DimensionUniverse

class lsst.daf.butler.DimensionUniverse

Bases: lsst.daf.butler.DimensionGraph

A special DimensionGraph that constructs and manages a complete set of compatible dimensions.

DimensionUniverse is not a class-level singleton, but all instances are tracked in a singleton map keyed by the version number in the configuration they were loaded from. Because these universes are solely responsible for constructing DimensionElement instances, these are also indirectly tracked by that singleton as well.

Parameters:
config : Config, optional

Configuration describing the dimensions and their relationships. If not provided, default configuration (from daf_butler/config/dimensions.yaml) wil be loaded.

Attributes Summary

names A set of the names of all dimensions in the graph (KeysView).
primaryKeyTraversalOrder Return a tuple of all elements in an order allows records to be found given their primary keys, starting from only the primary keys of required dimensions (tuple [ DimensionRecord ]).

Methods Summary

decode(encoded, *, universe) Construct a DimensionGraph from its encoded representation.
encode() Encode a DimensionGraph into a byte string.
extract(iterable, str]]) Construct a DimensionGraph from a possibly-heterogenous iterable of Dimension instances and string names thereof.
get(name, default) Return the element with the given name.
getEncodeLength() Return the size (in bytes) of the encoded size of DimensionGraph instances in this universe.
intersection(*others) Construct a new graph containing only dimensions in all of the operands.
isdisjoint(other) Test whether the intersection of two graphs is empty.
issubset(other) Test whether all dimensions in self are also in other.
issuperset(other) Test whether all dimensions in other are also in self.
makePacker(name, dataId) Construct a DimensionPacker that can pack data ID dictionaries into unique integers.
sorted(elements, *[, reverse]) Return a sorted version of the given iterable of dimension elements.
union(*others) Construct a new graph containing all dimensions in any of the operands.

Attributes Documentation

names

A set of the names of all dimensions in the graph (KeysView).

primaryKeyTraversalOrder

Return a tuple of all elements in an order allows records to be found given their primary keys, starting from only the primary keys of required dimensions (tuple [ DimensionRecord ]).

Unlike the table definition/topological order (which is what DimensionUniverse.sorted gives you), when dimension A implies dimension B, dimension A appears first.

Methods Documentation

classmethod decode(encoded: bytes, *, universe: DimensionUniverse) → DimensionGraph

Construct a DimensionGraph from its encoded representation.

Parameters:
encoded : bytes

Byte string produced by DimensionGraph.encode.

universe : DimensionUniverse

Universe the new graph is a part of. Must have the same dimensions as the original universe.
Returns:
graph : DimensionGraph

A new (or possibly cached) DimensionGraph instance matching the given encoding.
encode() → bytes

Encode a DimensionGraph into a byte string.

Returns:
encoded : bytes

Encoded representation of the graph. Length is guaranteed to be equal to DimensionUniverse.getEncodeLength.
extract(iterable: Iterable[Union[lsst.daf.butler.core.dimensions.elements.Dimension, str]]) → lsst.daf.butler.core.dimensions.graph.DimensionGraph

Construct a DimensionGraph from a possibly-heterogenous iterable of Dimension instances and string names thereof.

Constructing DimensionGraph directly from names or dimension instances is slightly more efficient when it is known in advance that the iterable is not heterogenous.

Parameters:
iterable: iterable of `Dimension` or `str`

Dimensions that must be included in the returned graph (their dependencies will be as well).
Returns:
graph : DimensionGraph

A DimensionGraph instance containing all given dimensions.
get(name: str, default: Any = None) → DimensionElement

Return the element with the given name.

This lookup covers all DimensionElement instances in self.elements, not just true Dimension instances).

getEncodeLength() → int

Return the size (in bytes) of the encoded size of DimensionGraph instances in this universe.

See DimensionGraph.encode and DimensionGraph.decode for more information.

intersection(*others)

Construct a new graph containing only dimensions in all of the operands.

isdisjoint(other: lsst.daf.butler.core.dimensions.graph.DimensionGraph) → bool

Test whether the intersection of two graphs is empty.

Returns True if either operand is the empty.

issubset(other: lsst.daf.butler.core.dimensions.graph.DimensionGraph) → bool

Test whether all dimensions in self are also in other.

Returns True if self is empty.

issuperset(other: lsst.daf.butler.core.dimensions.graph.DimensionGraph) → bool

Test whether all dimensions in other are also in self.

Returns True if other is empty.

makePacker(name: str, dataId: ExpandedDataCoordinate) → DimensionPacker

Construct a DimensionPacker that can pack data ID dictionaries into unique integers.

Parameters:
name : str

Name of the packer, matching a key in the “packers” section of the dimension configuration.

dataId : ExpandedDataCoordinate

Fully-expanded data ID that identfies the at least the “fixed” dimensions of the packer (i.e. those that are assumed/given, setting the space over which packed integer IDs are unique).
sorted(elements: Iterable[lsst.daf.butler.core.dimensions.elements.DimensionElement], *, reverse=False) → List[lsst.daf.butler.core.dimensions.elements.DimensionElement]

Return a sorted version of the given iterable of dimension elements.

The universe’s sort order is topological (an element’s dependencies precede it), starting with skypix dimensions (which never have dependencies) and then sorting lexicographically to break ties.

Parameters:
elements : iterable of DimensionElement.

Elements to be sorted.

reverse : bool, optional

If True, sort in the opposite order.
Returns:
sorted : list of DimensionElement

A sorted list containing the same elements that were given.
union(*others)

Construct a new graph containing all dimensions in any of the operands.

The elements of the returned graph may exceed the naive union of their elements, as some DimensionElement instances are included in graphs whenever multiple dimensions are present, and those dependency dimensions could have been provided by different operands.