DataCoordinate

class lsst.daf.butler.DataCoordinate

Bases: lsst.daf.butler.core.utils.IndexedTupleDict

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

DataCoordinate instances should usually be constructed via the standardize class method; the constructor is reserved for callers that can guarantee that the values tuple has exactly the right elements.

Parameters:

graph : DimensionGraph

The dimensions identified by this instance.

values : tuple

Tuple of primary key values for the given dimensions.

Notes

Like any data ID class, DataCoordinate behaves like a dictionary, mostly via methods inherited from IndexedTupleDict. Like NamedKeyDict, both Dimension instances and str names thereof may be used as keys in lookup operations.

Subclasses are permitted to support lookup for any dimension in self.graph.dimensions, but the base class only supports lookup for those in self.graph.required, which is the minimal set needed to identify all others in a Registry. Both the base class and subclasses define comparisons, iterators, and the keys, values, and items views to just the self.graph.required subset in order to guarantee true (i.e. Liskov) substitutability.

Attributes Summary

graph	The dimensions identified by this data ID (DimensionGraph).
universe	The universe that defines all known dimensions compatible with this coordinate (DimensionUniverse).

Methods Summary

byName()	Return a true dict keyed by str dimension name and the same values as self.
fingerprint(update)	Update a secure hash function with the values in this data ID.
get(k[,d])
items()
keys()
matches(other)	Test whether the values of all keys in both coordinates are equal.
standardize(mapping, Any]] = None, *, graph, …)	Adapt an arbitrary mapping and/or additional arguments into a true DataCoordinate, or augment an existing one.
subset(graph)	Return a new DataCoordinate whose graph is a subset of self.graph.
values()

Attributes Documentation

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.

universe

The universe that defines all known dimensions compatible with this coordinate (DimensionUniverse).

Methods Documentation

byName() → Dict[str, Any]

Return a true dict keyed by str dimension name and the same values as self.

fingerprint(update)

Update a secure hash function with the values in this data ID.

Parameters:

update : Callable

Callable that accepts a single bytes argument to update the hash; usually the update method of an instance from the hashlib module.

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

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

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

matches(other: lsst.daf.butler.core.dimensions.coordinate.DataCoordinate) → bool

Test whether the values of all keys in both coordinates are equal.

Parameters:

other : DataCoordinate

The other coordinate to compare to.

Returns:

consistent : bool

True if all keys that are in in both other and self are associated with the same values, and False otherwise. True if there are no keys in common.

static standardize(mapping: Optional[Mapping[str, Any]] = None, *, graph: Optional[DimensionGraph] = None, universe: Optional[DimensionUniverse] = None, **kwds) → 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 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 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.

kwds

Additional keyword arguments are treated like additional key-value pairs in mapping.

Returns:

coordinate : DataCoordinate

A validated DataCoordinate instance. May be a subclass instance if and only if mapping is a subclass instance and graph is a subset of mapping.graph.

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.

Notes

Because DataCoordinate stores only values for required dimensions, key-value pairs for other related dimensions will be ignored and excluded from the result. This means that a DataCoordinate may contain fewer key-value pairs than the informal data ID dictionary it was constructed from.

subset(graph: lsst.daf.butler.core.dimensions.graph.DimensionGraph) → lsst.daf.butler.core.dimensions.coordinate.DataCoordinate

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

Subclasses may override this method to return a subclass instance.

Parameters:

graph : DimensionGraph

The dimensions identified by the returned DataCoordinate.

Returns:

coordinate : DataCoordinate

A DataCoordinate instance that identifies only the given dimensions.

Raises:

KeyError

Raised if graph is not a subset of self.graph, and hence one or more dimensions has no associated primary key value.

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