DimensionUniverse

class lsst.daf.butler.DimensionUniverse

Bases: object

A parent class that represents a complete, self-consistent set of dimensions and their relationships.

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 dimensions.yaml in this package’s configs resource directory) will be loaded.

Methods Summary

extract(iterable, str]])	Construct a DimensionGraph from a possibly-heterogenous iterable of Dimension instances and string names thereof.
get(name, default)	Return the DimensionElement with the given name or a default.
getDimensionIndex(name)	Return the position of the named dimension in this universe’s sorting of all dimensions.
getElementIndex(name)	Return the position of the named dimension element in this universe’s sorting of all elements.
getEncodeLength()	Return the size (in bytes) of the encoded size of DimensionGraph instances in this universe.
getStaticDimensions()	Return a set of all static dimensions in this universe.
getStaticElements()	Return a set of all static elements in this universe.
makePacker(name, dataId)	Construct a DimensionPacker that can pack data ID dictionaries into unique integers.
sorted(elements, str]], *, reverse)	Return a sorted version of the given iterable of dimension elements.

Methods Documentation

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: Optional[lsst.daf.butler.core.dimensions.elements.DimensionElement] = None) → Optional[lsst.daf.butler.core.dimensions.elements.DimensionElement]

Return the DimensionElement with the given name or a default.

Parameters:

name : str

Name of the element.

default : DimensionElement, optional

Element to return if the named one does not exist. Defaults to None.

Returns:

element : DimensionElement

The named element.

getDimensionIndex(name: str) → int

Return the position of the named dimension in this universe’s sorting of all dimensions.

Parameters:

name : str

Name of the dimension.

Returns:

index : int

Sorting index for this dimension.

Notes

The dimension sort order for a universe is consistent with the element order (all dimensions are elements), and either can be used to sort dimensions if used consistently. But there are also some contexts in which contiguous dimension-only indices are necessary or at least desirable.

getElementIndex(name: str) → int

Return the position of the named dimension element in this universe’s sorting of all elements.

Parameters:

name : str

Name of the element.

Returns:

index : int

Sorting index for this element.

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.

getStaticDimensions() → lsst.daf.butler.core.named.NamedValueSet[lsst.daf.butler.core.dimensions.elements.Dimension][lsst.daf.butler.core.dimensions.elements.Dimension]

Return a set of all static dimensions in this universe.

Non-static dimensions that are created as needed may also exist, but these are guaranteed to have no direct relationships to other elements (though they may have spatial or temporal relationships).

Returns:

dimensions : NamedValueSet [ Dimension ]

A frozen set of Dimension instances.

getStaticElements() → lsst.daf.butler.core.named.NamedValueSet[lsst.daf.butler.core.dimensions.elements.DimensionElement][lsst.daf.butler.core.dimensions.elements.DimensionElement]

Return a set of all static elements in this universe.

Non-static elements that are created as needed may also exist, but these are guaranteed to have no direct relationships to other elements (though they may have spatial or temporal relationships).

Returns:

elements : NamedValueSet [ DimensionElement ]

A frozen set of DimensionElement instances.

makePacker(name: str, dataId: DataCoordinate) → 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 : DataCoordinate

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). dataId.hasRecords() must return True.

sorted(elements: Iterable[Union[E, str]], *, reverse: bool = False) → List[E]

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

The universe’s sort order is topological (an element’s dependencies precede it), with an unspecified (but deterministic) approach to breaking 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.