DataCoordinate¶

class lsst.daf.butler.DataCoordinate¶

Bases: NamedKeyMapping[Dimension, int | str | None]

A validated data ID.

DataCoordinate guarantees that its key-value pairs identify at least all required dimensions in a DimensionGroup.

See also

Data IDs

Notes

DataCoordinate is an ABC, but it provides staticmethod factory functions for private concrete implementations that should be sufficient for most purposes. standardize is the most flexible and safe of these; the others (make_empty, from_required_values, and from_full_values) are more specialized and perform little or no checking of inputs.

Lookups for implied dimensions (those in self.dimensions.implied) are supported if and only if has_full_values is True. This also sets the keys of the mapping attribute. This means that DataCoordinate equality is not the same as testing for equality on the mapping attribute (instead, it is the same as testing for equality on the required attribute).

Attributes Summary

`dimensions`	Dimensions identified by this data ID (`DimensionGroup`).
`full`	Return mapping for all dimensions in `self.dimensions`.
`full_values`	The full values (only) of this data ID as a tuple.
`graph`	Dimensions identified by this data ID (`DimensionGraph`).
`mapping`	A mapping view of the data ID with keys for all dimensions it has values for.
`names`	Names of the required dimensions identified by this data ID.
`records`	A mapping that contains `DimensionRecord` objects for all elements identified by this data ID.
`region`	Spatial region associated with this data ID.
`required`	A mapping view of the data ID with keys for just its required dimensions.
`required_values`	The required values (only) of this data ID as a tuple.
`timespan`	Temporal interval associated with this data ID.
`universe`	Universe that defines all known compatible dimensions.

Methods Summary

`byName`()	Return a `Mapping` with names as keys and the `self` values.
`expanded`(records)	Return a `DataCoordinate` that holds the given records.
`fromFullValues`(graph, values)	Construct a `DataCoordinate` from all dimension values.
`fromRequiredValues`(graph, values)	Construct a `DataCoordinate` from required dimension values.
`from_full_values`(dimensions, values)	Construct a `DataCoordinate` from all dimension values.
`from_json`(json_str[, universe, registry])	Convert from JSON to a pydantic model.
`from_required_values`(dimensions, values)	Construct a `DataCoordinate` from required dimension values.
`from_simple`(simple[, universe, registry])	Construct a new object from the simplified form.
`get`(k[,d])
`hasFull`()	Whether this data ID contains implied and required values.
`hasRecords`()	Whether this data ID contains records.
`items`()
`keys`()	Deprecated since version v27.
`makeEmpty`(universe)	Return an empty `DataCoordinate`.
`make_empty`(universe)	Return an empty `DataCoordinate`.
`pack`()	Pack this data ID into an integer.
`standardize`([mapping, dimensions, graph, ...])	Standardize the supplied dataId.
`subset`(dimensions)	Return a `DataCoordinate` whose graph is a subset of `self.graph`.
`to_json`([minimal])	Convert this class to JSON assuming that the `to_simple()` returns a pydantic model.
`to_simple`([minimal])	Convert this class to a simple python type.
`union`(other)	Combine two data IDs.
`values`()
`values_tuple`()	Return the required values (only) of this data ID as a tuple.

Attributes Documentation

dimensions¶

Dimensions identified by this data ID (DimensionGroup).

Note that values are only required to be present for dimensions in self.dimensions.required; all others may be retrieved (from a Registry) given these.

full¶

Return mapping for all dimensions in self.dimensions.

The mapping includes key-value pairs for all dimensions in self.dimensions, including implied.

Accessing this attribute if hasFull returns False is a logic error that may raise an exception of unspecified type either immediately or when implied keys are accessed via the returned mapping, depending on the implementation and whether assertions are enabled.

Deprecated since version v27: DataCoordinate.full is deprecated in favor of .mapping, and will be dropped after v27.

full_values¶

The full values (only) of this data ID as a tuple.

Element order is consistent with DimensionGroup.data_coordinate_keys, i.e. all required dimensions followed by all implied dimensions.

graph¶

Dimensions identified by this data ID (DimensionGraph).

Note that values are only required to be present for dimensions in self.graph.required; all others may be retrieved (from a Registry) given these.

Deprecated since version v27: DataCoordinate.graph is deprecated in favor of .dimensions, and will be dropped after v27.

mapping¶: A mapping view of the data ID with keys for all dimensions it has values for.

names¶

Names of the required dimensions identified by this data ID.

They are returned in the same order as keys (collections.abc.Set [ str ]).

Deprecated since version v27: DataCoordinate.names is deprecated in favor of the .dimensions attribute, and will be dropped after v27.

records¶

A mapping that contains DimensionRecord objects for all elements identified by this data ID.

This mapping will become a regular Mapping with str keys after v27.

Notes

The values of this mapping may be None if and only if there is no record for that element with these dimensions in the database (which means some foreign key field must have a NULL value).

Accessing this attribute if hasRecords returns False is a logic error that may raise an exception of unspecified type either immediately or when the returned mapping is used, depending on the implementation and whether assertions are enabled.

region¶

Spatial region associated with this data ID.

(lsst.sphgeom.Region or None).

This is None if and only if self.dimensions.spatial is empty.

Accessing this attribute if hasRecords returns False is a logic error that may or may not raise an exception, depending on the implementation and whether assertions are enabled.

required¶: A mapping view of the data ID with keys for just its required dimensions.

required_values¶

The required values (only) of this data ID as a tuple.

Element order is consistent with required.

In contexts where all data IDs have the same dimensions, comparing and hashing these tuples can be much faster than comparing the original DataCoordinate instances.

timespan¶

Temporal interval associated with this data ID.

(Timespan or None).

This is None if and only if self.dimensions.temporal is empty.

Accessing this attribute if hasRecords returns False is a logic error that may or may not raise an exception, depending on the implementation and whether assertions are enabled.

universe¶

Universe that defines all known compatible dimensions.

The universe will be compatible with this coordinate (DimensionUniverse).

Methods Documentation

byName() → dict[str, +V_co]¶

Return a Mapping with names as keys and the self values.

Returns:

dictionarydict: A dictionary with the same values (and iteration order) as self, with str names as keys. This is always a new object, not a view.

abstract expanded(records: NamedKeyMapping[DimensionElement, DimensionRecord | None] | Mapping[str, DimensionRecord | None]) → DataCoordinate¶

Return a DataCoordinate that holds the given records.

Guarantees that hasRecords returns True.

This is a low-level interface with at most assertion-level checking of inputs. Most callers should use Registry.expandDataId instead.

Parameters:

recordsMapping [ str, DimensionRecord or None ]: A NamedKeyMapping with DimensionElement keys or a regular Mapping with str (DimensionElement name) keys and DimensionRecord values. Keys must cover all elements in self.graph.elements. Values may be None, but only to reflect actual NULL values in the database, not just records that have not been fetched. Passing a NamedKeyMapping is deprecated and will not be supported after v27.

static fromFullValues(graph: DimensionGraph, values: tuple[int | str | None, ...]) → DataCoordinate¶

Construct a DataCoordinate from all dimension values.

This method is deprecated in favor of from_full_values.

This is a low-level interface with at most assertion-level checking of inputs. Most callers should use standardize instead.

Parameters:

graphDimensionGraph: Dimensions this data ID will identify.
valuestuple [ int or str ]: Tuple of primary key values corresponding to itertools.chain(graph.required, graph.implied), in that order. Note that this is _not_ the same order as graph.dimensions, though these contain the same elements.

Returns:

dataIdDataCoordinate: A data ID object that identifies the given dimensions. dataId.hasFull() will always return True. dataId.hasRecords() will only return True if graph is empty.

Deprecated since version v27: fromFullValues is deprecated in favor of from_full_values, which takes a DimensionGroup instead of a DimensionGraph. It will be removed after v27.

static fromRequiredValues(graph: DimensionGraph, values: tuple[int | str | None, ...]) → DataCoordinate¶

Construct a DataCoordinate from required dimension values.

This method is deprecated in favor of from_required_values.

This is a low-level interface with at most assertion-level checking of inputs. Most callers should use standardize instead.

Parameters:

graphDimensionGraph: Dimensions this data ID will identify.
valuestuple [ int or str ]: Tuple of primary key values corresponding to graph.required, in that order.

Returns:

dataIdDataCoordinate: A data ID object that identifies the given dimensions. dataId.hasFull() will return True only if graph.implied is empty. dataId.hasRecords() will return True if and only if graph is empty.

Deprecated since version v27: fromRequiredValues is deprecated in favor of from_required_values, which takes a DimensionGroup instead of a DimensionGraph. It will be removed after v27.

static from_full_values(dimensions: DimensionGroup, values: tuple[int | str | None, ...]) → DataCoordinate¶

Construct a DataCoordinate from all dimension values.

This is a low-level interface with at most assertion-level checking of inputs. Most callers should use standardize instead.

Parameters:

dimensionsDimensionGroup: Dimensions this data ID will identify.
valuestuple [ int or str ]: Tuple of primary key values corresponding to itertools.chain(graph.required, graph.implied), in that order. Note that this is _not_ the same order as graph.dimensions, though these contain the same elements.

Returns:

data_idDataCoordinate: A data ID object that identifies the given dimensions. dataId.hasFull() will always return True. dataId.hasRecords() will only return True if dimensions is empty.

classmethod from_json(json_str: str, universe: DimensionUniverse | None = None, registry: Registry | None = None) → SupportsSimple¶: Convert from JSON to a pydantic model.

static from_required_values(dimensions: DimensionGroup, values: tuple[int | str | None, ...]) → DataCoordinate¶

Construct a DataCoordinate from required dimension values.

This is a low-level interface with at most assertion-level checking of inputs. Most callers should use standardize instead.

Parameters:

dimensionsDimensionGroup: Dimensions this data ID will identify.
valuestuple [ int or str ]: Tuple of primary key values corresponding to graph.required, in that order.

Returns:

data_idDataCoordinate: A data ID object that identifies the given dimensions. dataId.hasFull() will return True only if dimensions.implied is empty. dataId.hasRecords() will return True if and only if graph is empty.

classmethod from_simple(simple: SerializedDataCoordinate, universe: DimensionUniverse | None = None, registry: Registry | None = None) → DataCoordinate¶

Construct a new object from the simplified form.

The data is assumed to be of the form returned from the to_simple method.

Parameters:

simpledict of [str, Any]: The dict returned by to_simple().
universeDimensionUniverse: Object that manages all known dimensions.
registrylsst.daf.butler.Registry, optional: Registry from which a universe can be extracted. Can be None if universe is provided explicitly.

Returns:

dataIdDataCoordinate: Newly-constructed object.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

abstract hasFull() → bool¶

Whether this data ID contains implied and required values.

Returns:

statebool: If True, __getitem__, get, and __contains__ (but not keys!) will act as though the mapping includes key-value pairs for implied dimensions, and the full property may be used. If False, these operations only include key-value pairs for required dimensions, and accessing full is an error. Always True if there are no implied dimensions.

abstract hasRecords() → bool¶

Whether this data ID contains records.

These are the records for all of the dimension elements it identifies.

Returns:

statebool

If True, the following attributes may be accessed:

records

region

timespan

pack

If False, accessing any of these is considered a logic error.

items() → a set-like object providing a view on D's items¶

keys() → NamedValueAbstractSet[Dimension]¶: Deprecated since version v27: Using DataCoordinate as a Mapping is deprecated in favor of the .mapping and .required attributes, and will be dropped after v27.

static makeEmpty(universe: DimensionUniverse) → DataCoordinate¶

Return an empty DataCoordinate.

It identifies the null set of dimensions.

Parameters:

universeDimensionUniverse: Universe to which this null dimension set belongs.

Returns:

dataIdDataCoordinate: A data ID object that identifies no dimensions. hasFull and hasRecords are guaranteed to return True, because both full and records are just empty mappings.

static make_empty(universe: DimensionUniverse) → DataCoordinate¶

Return an empty DataCoordinate.

It identifies the null set of dimensions.

Parameters:

universeDimensionUniverse: Universe to which this null dimension set belongs.

Returns:

data_idDataCoordinate: A data ID object that identifies no dimensions. hasFull and hasRecords are guaranteed to return True, because both full and records are just empty mappings.

pack(name: str, *, returnMaxBits: Literal[True]) → tuple[int, int]¶

pack(name: str, *, returnMaxBits: Literal[False]) → int

Pack this data ID into an integer.

Parameters:

namestr: Name of the DimensionPacker algorithm (as defined in the dimension configuration).
returnMaxBitsbool, optional: If True (False is default), return the maximum number of nonzero bits in the returned integer across all data IDs.

Returns:

packedint: Integer ID. This ID is unique only across data IDs that have the same values for the packer’s “fixed” dimensions.
maxBitsint, optional: Maximum number of nonzero bits in packed. Not returned unless returnMaxBits is True.

Notes

Accessing this attribute if hasRecords returns False is a logic error that may or may not raise an exception, depending on the implementation and whether assertions are enabled.

Deprecated since version v26: Deprecated in favor of configurable dimension packers. Will be removed after v26.

Standardize the supplied dataId.

Adapts an arbitrary mapping and/or additional arguments into a true DataCoordinate, or augment an existing one.

Parameters:

mappingMapping, optional: An informal data ID that maps dimensions or dimension names to their primary key values (may also be a true DataCoordinate).
dimensionsIterable [ str ], DimensionGroup or DimensionGraph, optional: The dimensions to be identified by the new DataCoordinate. If not provided, will be inferred from the keys of mapping and **kwargs, and universe must be provided unless mapping is already a DataCoordinate.
graphDimensionGraph, optional: Like dimensions, but requires a DimensionGraph instance. Ignored if dimensions is provided. Deprecated and will be removed after v27.
universeDimensionUniverse: All known dimensions and their relationships; used to expand and validate dependencies when graph is not provided.
defaultsDataCoordinate, optional: Default dimension key-value pairs to use when needed. These are never used to infer graph, and are ignored if a different value is provided for the same key in mapping or **kwargs`.
**kwargs: Additional keyword arguments are treated like additional key-value pairs in mapping.

Returns:

coordinateDataCoordinate: A validated DataCoordinate instance.

Raises:

TypeError: Raised if the set of optional arguments provided is not supported.
KeyError: Raised if a key-value pair for a required dimension is missing.

abstract subset(dimensions: DimensionGraph | DimensionGroup | Iterable[str]) → DataCoordinate¶

Return a DataCoordinate whose graph is a subset of self.graph.

Parameters:

dimensionsDimensionGraph, DimensionGroup, or Iterable [ str ]: The dimensions identified by the returned DataCoordinate. Passing a DimensionGraph is deprecated and support will be dropped after v27.

Returns:

coordinateDataCoordinate: A DataCoordinate instance that identifies only the given dimensions. May be self if graph == self.graph.

Raises:

KeyError: Raised if the primary key value for one or more required dimensions is unknown. This may happen even if the required subset of the new dimensions are not a subset of the dimensions actually known by this data ID.. As an example, consider trying to go from a data ID with dimensions {instrument, physical_filter, band} to just {instrument, band}; band is implied by physical_filter and hence would have no value in the original data ID if self.hasFull() is False.

Notes

If hasFull and hasRecords return True on self, they will return True (respectively) on the returned DataCoordinate as well. The converse does not hold.

to_json(minimal: bool = False) → str¶: Convert this class to JSON assuming that the to_simple() returns a pydantic model.

to_simple(minimal: bool = False) → SerializedDataCoordinate¶

Convert this class to a simple python type.

This is suitable for serialization.

Parameters:

minimalbool, optional: Use minimal serialization. If set the records will not be attached.

Returns:

simpleSerializedDataCoordinate: The object converted to simple form.

abstract union(other: DataCoordinate) → DataCoordinate¶

Combine two data IDs.

Yields a new one that identifies all dimensions that either of them identify.

Parameters:

otherDataCoordinate: Data ID to combine with self.

Returns:

unionedDataCoordinate: A DataCoordinate instance that satisfies unioned.dimensions == self.dimensions.union(other.dimensions). Will preserve hasFull and hasRecords whenever possible.

Notes

No checking for consistency is performed on values for keys that self and other have in common, and which value is included in the returned data ID is not specified.

values() → an object providing a view on D's values¶

values_tuple() → tuple[int | str | None, ...]¶

Return the required values (only) of this data ID as a tuple.

In contexts where all data IDs have the same dimensions, comparing and hashing these tuples can be much faster than comparing the original DataCoordinate instances.

Deprecated since version v27: DataCoordinate.values_tuple() is deprecated in favor of .required_values, and will be dropped after v27.

Navigation

DataCoordinate¶