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 providesstaticmethod
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
, andfromFullValues
) 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 andstr
names thereof may be used as keys in lookup operations, but iteration (andkeys
) will yieldDimension
instances. Thenames
property can be used to obtain the correspondingstr
names. - Lookups for implied dimensions (those in
self.graph.implied
) are supported if and only ifhasFull
returnsTrue
, and are never included in iteration orkeys
. Thefull
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 simpledict
data IDs work, and hence using aDataCoordinate
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
orNone
).timespan
The temporal interval associated with this data ID ( Timespan
orNone
).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 asself
.expanded
(records, …)Return a DataCoordinate
that holds the given records and guarantees thathasRecords
returnsTrue
.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.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 ofself.graph
.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
returnsFalse
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 aRegistry
) 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
returnsFalse
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
orNone
).This is
None
if and only ifself.graph.spatial
is empty.Accessing this attribute if
hasRecords
returnsFalse
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
orNone
).This is
None
if and only ifself.graph.timespan
is empty.Accessing this attribute if
hasRecords
returnsFalse
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 asself
.Returns:
-
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 thathasRecords
returnsTrue
.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
orNone
] A
NamedKeyMapping
withDimensionElement
keys or a regularMapping
withstr
(DimensionElement
name) keys andDimensionRecord
values. Keys must cover all elements inself.graph.elements
. Values may beNone
, but only to reflect actual NULL values in the database, not just records that have not been fetched.
- records :
-
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
orstr
] Tuple of primary key values corresponding to
itertools.chain(graph.required, graph.implied)
, in that order. Note that this is _not_ the same order asgraph.dimensions
, though these contain the same elements.
Returns: - dataId :
DataCoordinate
A data ID object that identifies the given dimensions.
dataId.hasFull()
will returnTrue
if and only ifgraph.implied
is empty, anddataId.hasRecords()
will never returnTrue
.
- graph :
-
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
orstr
] 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 returnTrue
if and only ifgraph.implied
is empty, anddataId.hasRecords()
will never returnTrue
.
- graph :
-
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 notkeys
!) will act as though the mapping includes key-value pairs for implied dimensions, and thefull
property may be used. IfFalse
, these operations only include key-value pairs for required dimensions, and accessingfull
is an error. AlwaysTrue
if there are no implied dimensions.
- state :
-
hasRecords
() → bool¶ Whether this data ID contains records for all of the dimension elements it identifies.
Returns:
-
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
andhasRecords
are guaranteed to returnTrue
, because bothfull
andrecords
are just empty mappings.
- universe :
-
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: Notes
Accessing this attribute if
hasRecords
returnsFalse
is a logic error that may or may not raise an exception, depending on the implementation and whether assertions are enabled.- name :
-
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 ofmapping
and**kwargs
, anduniverse
must be provided unlessmapping
is already aDataCoordinate
.- 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 inmapping
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.
- mapping :
-
subset
(graph: lsst.daf.butler.core.dimensions._graph.DimensionGraph) → lsst.daf.butler.core.dimensions._coordinate.DataCoordinate¶ Return a
DataCoordinate
whose graph is a subset ofself.graph
.Parameters: - graph :
DimensionGraph
The dimensions identified by the returned
DataCoordinate
.
Returns: - coordinate :
DataCoordinate
A
DataCoordinate
instance that identifies only the given dimensions. May beself
ifgraph == 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)
isFalse
, or even ifgraph.issubset(self.graph)
isTrue
, ifself.hasFull()
isFalse
andgraph.required.issubset(self.graph.required)
isFalse
. 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 ifself.hasFull()
isFalse
.
Notes
If
hasFull
andhasRecords
returnTrue
onself
, they will returnTrue
(respectively) on the returnedDataCoordinate
as well. The converse does not hold.- graph :
-
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 satisfiesunioned.graph == self.graph.union(other.graph)
. Will preservehasFull
andhasRecords
whenever possible.
Notes
No checking for consistency is performed on values for keys that
self
andother
have in common, and which value is included in the returned data ID is not specified.- other :
-
values
() → an object providing a view on D's values¶
- Both