DataCoordinate¶

class lsst.daf.butler.DataCoordinate¶

Bases: lsst.daf.butler.NamedKeyMapping

An immutable data ID dictionary that guarantees that its key-value pairs identify at least all required dimensions in a DimensionGraph.

DataCoordinateSet itself is an ABC, but 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 (makeEmpty, fromRequiredValues, and fromFullValues) are more specialized and perform little or no checking of inputs.

Notes

Like any data ID class, DataCoordinate behaves like a dictionary, but with some subtleties:

Both Dimension instances and str names thereof may be used as keys in lookup operations, but iteration (and keys) will yield Dimension instances. The names property can be used to obtain the corresponding str names.

Lookups for implied dimensions (those in self.graph.implied) are supported if and only if hasFull returns True, and are never included in iteration or keys. The full property may be used to obtain a mapping whose keys do include implied dimensions.

Equality comparison with other mappings is supported, but it always considers only required dimensions (as well as requiring both operands to identify the same dimensions). This is not quite consistent with the way mappings usually work - normally differing keys imply unequal mappings - but it makes sense in this context because data IDs with the same values for required dimensions but different values for implied dimensions represent a serious problem with the data that DataCoordinate cannot generally recognize on its own, and a data ID that knows implied dimension values should still be able to compare as equal to one that does not. This is of course not the way comparisons between simple dict data IDs work, and hence using a DataCoordinate instance for at least one operand in any data ID comparison is strongly recommended.

Attributes Summary

`full`	A mapping that includes key-value pairs for all dimensions in `self.graph`, including implied (`NamedKeyMapping`).
`graph`	The dimensions identified by this data ID (`DimensionGraph`).
`names`	The names of the required dimensions identified by this data ID, in the same order as `keys` (`collections.abc.Set` [ `str` ]).
`records`	A mapping that contains `DimensionRecord` objects for all elements identified by this data ID (`NamedKeyMapping`).
`region`	The spatial region associated with this data ID (`lsst.sphgeom.Region` or `None`).
`timespan`	The temporal interval associated with this data ID (`Timespan` or `None`).
`universe`	The universe that defines all known dimensions compatible with this coordinate (`DimensionUniverse`).

Methods Summary

`byName`()	Return a `Mapping` with names as keys and the same values as `self`.
`expanded`(records, …)	Return a `DataCoordinate` that holds the given records and guarantees that `hasRecords` returns `True`.
`fromFullValues`(graph, values, int, None], …])	Construct a `DataCoordinate` from a tuple of dimension values that identify all dimensions.
`fromRequiredValues`(graph, values, int, …)	Construct a `DataCoordinate` from a tuple of dimension values that identify only required dimensions.
`from_json`(json_str, universe, registry)	Convert a JSON string created by `to_json` and return something of the supplied class.
`from_simple`(simple, Any], universe, registry)	Construct a new object from the data returned from the `to_simple` method.
`get`(k[,d])
`hasFull`()	Whether this data ID contains values for implied as well as required dimensions.
`hasRecords`()	Whether this data ID contains records for all of the dimension elements it identifies.
`items`()
`keys`()
`makeEmpty`(universe)	Return an empty `DataCoordinate` that identifies the null set of dimensions.
`pack`(name, *, returnMaxBits)	Pack this data ID into an integer.
`standardize`(mapping, DataIdValue]] = None, …)	Adapt an arbitrary mapping and/or additional arguments into a true `DataCoordinate`, or augment an existing one.
`subset`(graph)	Return a `DataCoordinate` whose graph is a subset of `self.graph`.
`to_json`(minimal)	Convert this class to JSON form.
`to_simple`(minimal)	Convert this class to a simple python type suitable for serialization.
`union`(other)	Combine two data IDs, yielding a new one that identifies all dimensions that either of them identify.
`values`()

Attributes Documentation

full¶

A mapping that includes key-value pairs for all dimensions in self.graph, including implied (NamedKeyMapping).

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.

graph¶

The 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.

names¶: The names of the required dimensions identified by this data ID, in the same order as keys (collections.abc.Set [ str ]).

records¶

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

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¶

The spatial region associated with this data ID (lsst.sphgeom.Region or None).

This is None if and only if self.graph.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.

timespan¶

The temporal interval associated with this data ID (Timespan or None).

This is None if and only if self.graph.timespan 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¶: The universe that defines all known dimensions compatible with this coordinate (DimensionUniverse).

Methods Documentation

byName() → Dict[str, V_co]¶

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

Returns:	dictionary : `dict` 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.

expanded(records: Union[lsst.daf.butler.core.named.NamedKeyMapping[lsst.daf.butler.core.dimensions._elements.DimensionElement, typing.Union[lsst.daf.butler.core.dimensions._records.DimensionRecord, NoneType]][lsst.daf.butler.core.dimensions._elements.DimensionElement, Optional[lsst.daf.butler.core.dimensions._records.DimensionRecord]], Mapping[str, Optional[lsst.daf.butler.core.dimensions._records.DimensionRecord]]]) → lsst.daf.butler.core.dimensions._coordinate.DataCoordinate¶

Return a DataCoordinate that holds the given records and 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:	records : `Mapping` [ `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.

static fromFullValues(graph: lsst.daf.butler.core.dimensions._graph.DimensionGraph, values: Tuple[Union[str, int, None], ...]) → lsst.daf.butler.core.dimensions._coordinate.DataCoordinate¶

Construct a DataCoordinate from a tuple of dimension values that identify all dimensions.

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

Parameters:	graph : `DimensionGraph` Dimensions this data ID will identify. values : `tuple` [ `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:	dataId : `DataCoordinate` A data ID object that identifies the given dimensions. `dataId.hasFull()` will return `True` if and only if `graph.implied` is empty, and `dataId.hasRecords()` will never return `True`.

static fromRequiredValues(graph: lsst.daf.butler.core.dimensions._graph.DimensionGraph, values: Tuple[Union[str, int, None], ...]) → lsst.daf.butler.core.dimensions._coordinate.DataCoordinate¶

Construct a DataCoordinate from a tuple of dimension values that identify only required dimensions.

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

Parameters:	graph : `DimensionGraph` Dimensions this data ID will identify. values : `tuple` [ `int` or `str` ] Tuple of primary key values corresponding to `graph.required`, in that order.
Returns:	dataId : `DataCoordinate` A data ID object that identifies the given dimensions. `dataId.hasFull()` will return `True` if and only if `graph.implied` is empty, and `dataId.hasRecords()` will never return `True`.

classmethod from_json(json_str: str, universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = None) → SupportsSimple¶

Convert a JSON string created by to_json and return something of the supplied class.

Parameters:	json_str : `str` Representation of the dimensions in JSON format as created by `to_json()`. universe : `DimensionUniverse`, optional The special graph of all known dimensions. Passed directly to `from_simple()`. registry : `lsst.daf.butler.Registry`, optional Registry to use to convert simple name of a DatasetType to a full `DatasetType`. Passed directly to `from_simple()`.
Returns:	constructed : Any Newly-constructed object.

classmethod from_simple(simple: Dict[str, Any], universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = None) → DataCoordinate¶

Construct a new object from the data returned from the to_simple method.

Parameters:	simple : `dict` of [`str`, `Any`] The `dict` returned by `to_simple()`. universe : `DimensionUniverse` The special graph of all known dimensions. registry : `lsst.daf.butler.Registry`, optional Registry from which a universe can be extracted. Can be `None` if universe is provided explicitly.
Returns:	dataId : `DataCoordinate` Newly-constructed object.

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

hasFull() → bool¶

Whether this data ID contains values for implied as well as required dimensions.

Returns:	state : `bool` 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.

hasRecords() → bool¶

Whether this data ID contains records for all of the dimension elements it identifies.

Returns:	state : `bool` 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() → a set-like object providing a view on D's keys¶

static makeEmpty(universe: DimensionUniverse) → DataCoordinate¶

Return an empty DataCoordinate that identifies the null set of dimensions.

Parameters:	universe : `DimensionUniverse` Universe to which this null dimension set belongs.
Returns:	dataId : `DataCoordinate` 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: bool = False) → Union[Tuple[int, int], int]¶

Pack this data ID into an integer.

Parameters:	name : `str` Name of the `DimensionPacker` algorithm (as defined in the dimension configuration). returnMaxBits : `bool`, optional If `True` (`False` is default), return the maximum number of nonzero bits in the returned integer across all data IDs.
Returns:	packed : `int` Integer ID. This ID is unique only across data IDs that have the same values for the packer’s “fixed” dimensions. maxBits : `int`, 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.

static standardize(mapping: Optional[NameLookupMapping[Dimension, DataIdValue]] = None, *, graph: Optional[DimensionGraph] = None, universe: Optional[DimensionUniverse] = None, defaults: Optional[DataCoordinate] = None, **kwargs) → DataCoordinate¶

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

Parameters:	mapping : `Mapping`, optional An informal data ID that maps dimensions or dimension names to their primary key values (may also be a true `DataCoordinate`). graph : `DimensionGraph` 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`. universe : `DimensionUniverse` All known dimensions and their relationships; used to expand and validate dependencies when `graph` is not provided. defaults : `DataCoordinate`, 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:	coordinate : `DataCoordinate` 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.

subset(graph: lsst.daf.butler.core.dimensions._graph.DimensionGraph) → lsst.daf.butler.core.dimensions._coordinate.DataCoordinate¶

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

Parameters:	graph : `DimensionGraph` The dimensions identified by the returned `DataCoordinate`.
Returns:	coordinate : `DataCoordinate` 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 if `graph.issubset(self.graph)` is `False`, or even if `graph.issubset(self.graph)` is `True`, if `self.hasFull()` is `False` and `graph.required.issubset(self.graph.required)` is `False`. As an example of the latter case, 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 form.

The class type is not recorded in the JSON so the JSON decoder must know which class is represented.

Parameters:	minimal : `bool`, optional Use minimal serialization. Requires Registry to convert back to a full type.
Returns:	json : `str` The class in JSON string format.

to_simple(minimal: bool = False) → Dict[KT, VT]¶

Convert this class to a simple python type suitable for serialization.

Parameters:	minimal : `bool`, optional Use minimal serialization. Has no effect on for this class.
Returns:	as_dict : `dict` The object converted to a dictionary.

union(other: lsst.daf.butler.core.dimensions._coordinate.DataCoordinate) → lsst.daf.butler.core.dimensions._coordinate.DataCoordinate¶

Combine two data IDs, yielding a new one that identifies all dimensions that either of them identify.

Parameters:	other : `DataCoordinate` Data ID to combine with `self`.
Returns:	unioned : `DataCoordinate` A `DataCoordinate` instance that satisfies `unioned.graph == self.graph.union(other.graph)`. 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¶

Navigation

DataCoordinate¶