DimensionUniverse

class lsst.daf.butler.DimensionUniverse(config: Config | None = None, *, version: int | None = None, namespace: str | None = None, builder: DimensionConstructionBuilder | None = None)

Bases: object

Self-consistent set of dimensions.

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 and namespace 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:
configConfig, optional

Configuration object from which dimension definitions can be extracted. Ignored if builder is provided, or if version is provided and an instance with that version already exists.

versionint, optional

Integer version for this DimensionUniverse. If not provided, a version will be obtained from builder or config.

namespacestr, optional

Namespace of this DimensionUniverse, combined with the version to provide universe safety for registries that use different dimension definitions.

builderDimensionConstructionBuilder, optional

Builder object used to initialize a new instance. Ignored if version is provided and an instance with that version already exists. Should not have had finish called; this will be called if needed by DimensionUniverse.

Attributes Summary

database_elements

All dimension elements whose records are stored in the database, except governor dimensions.

dimensions

All dimensions defined in this universe.

elements

All dimension elements defined in this universe.

empty

The DimensionGraph that contains no dimensions.

governor_dimensions

All governor dimensions defined in this universe.

namespace

The namespace associated with this universe.

skypix

All skypix systems known to this universe.

skypix_dimensions

All skypix dimensions defined in this universe.

version

The version number of this universe.

Methods Summary

conform(dimensions, /)

Construct a dimension group from an iterable of dimension names.

expandDimensionNameSet(names)

Expand a set of dimension names in-place.

extract(iterable)

Construct graph from iterable.

get(name[, default])

Return the DimensionElement with the given name or a default.

getDatabaseElements()

Return set of all DatabaseDimensionElement instances in universe.

getDimensionIndex(name)

Return the position of the named dimension.

getElementIndex(name)

Return the position of the named dimension element.

getEncodeLength()

Return encoded size of graph.

getGovernorDimensions()

Return a set of all GovernorDimension 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.

get_elements_populated_by(dimension)

Return the set of DimensionElement objects whose populated_by attribute is the given dimension.

isCompatibleWith(other)

Check compatibility between this DimensionUniverse and another.

makePacker(name, dataId)

Make a dimension packer.

sorted()

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

Attributes Documentation

database_elements

All dimension elements whose records are stored in the database, except governor dimensions.

dimensions

All dimensions defined in this universe.

elements

All dimension elements defined in this universe.

empty

The DimensionGraph that contains no dimensions.

After v27 this will be a DimensionGroup.

governor_dimensions

All governor dimensions defined in this universe.

Governor dimensions serve as special required dependencies of other dimensions, with special handling in dimension query expressions and collection summaries. Governor dimension records are stored in the database but the set of such values is expected to be small enough for all values to be cached by all clients.

namespace

The namespace associated with this universe.

Returns:
namespacestr

The namespace. When combined with the version can uniquely define this universe.

skypix

All skypix systems known to this universe.

(NamedValueAbstractSet [ SkyPixSystem ]).

skypix_dimensions

All skypix dimensions defined in this universe.

Skypix dimension records are always generated on-the-fly rather than stored in the database, and they always represent a tiling of the sky with no overlaps.

version

The version number of this universe.

Returns:
versionint

An integer representing the version number of this universe. Uniquely defined when combined with the namespace.

Methods Documentation

conform(dimensions: Iterable[str | Dimension] | str | DimensionElement | DimensionGroup | DimensionGraph, /) DimensionGroup

Construct a dimension group from an iterable of dimension names.

Parameters:
dimensionsIterable [ str or Dimension ], str, DimensionElement, DimensionGroup, or DimensionGraph

Dimensions that must be included in the returned group; their dependencies will be as well. Support for Dimension, DimensionElement and DimensionGraph objects is deprecated and will be removed after v27. Passing DimensionGraph objects will not yield a deprecation warning to allow non-deprecated methods and properties that return DimensionGraph objects to be passed though, since these will be changed to return DimensionGroup in the future.

Returns:
groupDimensionGroup

A DimensionGroup instance containing all given dimensions.

expandDimensionNameSet(names: set[str]) None

Expand a set of dimension names in-place.

Includes recursive dependencies.

This is an advanced interface for cases where constructing a DimensionGraph (which also expands required dependencies) is impossible or undesirable.

Parameters:
namesset [ str ]

A true set of dimension names, to be expanded in-place.

.. deprecated:: v27

Deprecated in favor of DimensionUniverse.conform, and will be removed after v27.

extract(iterable: Iterable[Dimension | str]) DimensionGraph

Construct graph from iterable.

Constructs 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:
iterableiterable of Dimension or str

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

Returns:
graphDimensionGraph

A DimensionGraph instance containing all given dimensions.

Deprecated since version v27: DimensionUniverse.extract and DimensionGraph are deprecated in favor of DimensionUniverse.conform and DimensionGroup, and will be removed after v27.

get(name: str, default: DimensionElement | None = None) DimensionElement | None

Return the DimensionElement with the given name or a default.

Parameters:
namestr

Name of the element.

defaultDimensionElement, optional

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

Returns:
elementDimensionElement

The named element.

getDatabaseElements() NamedValueAbstractSet[DatabaseDimensionElement]

Return set of all DatabaseDimensionElement instances in universe.

This does not include GovernorDimension instances, which are backed by the database but do not inherit from DatabaseDimensionElement.

Returns:
elementsNamedValueAbstractSet [ DatabaseDimensionElement ]

A frozen set of DatabaseDimensionElement instances.

getDimensionIndex(name: str) int

Return the position of the named dimension.

This position is in this universe’s sorting of all dimensions.

Parameters:
namestr

Name of the dimension.

Returns:
indexint

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.

The position is in this universe’s sorting of all elements.

Parameters:
namestr

Name of the element.

Returns:
indexint

Sorting index for this element.

getEncodeLength() int

Return encoded size of graph.

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

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

getGovernorDimensions() NamedValueAbstractSet[GovernorDimension]

Return a set of all GovernorDimension instances in this universe.

Returns:
governorsNamedValueAbstractSet [ GovernorDimension ]

A frozen set of GovernorDimension instances.

getStaticDimensions() NamedValueAbstractSet[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:
dimensionsNamedValueAbstractSet [ Dimension ]

A frozen set of Dimension instances.

getStaticElements() NamedValueAbstractSet[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:
elementsNamedValueAbstractSet [ DimensionElement ]

A frozen set of DimensionElement instances.

get_elements_populated_by(dimension: Dimension) NamedValueAbstractSet[DimensionElement]

Return the set of DimensionElement objects whose populated_by attribute is the given dimension.

Parameters:
dimensionDimension

The dimension of interest.

Returns:
populated_byNamedValueAbstractSet [ DimensionElement ]

The set of elements who say they are populated by the given dimension.

isCompatibleWith(other: DimensionUniverse) bool

Check compatibility between this DimensionUniverse and another.

Parameters:
otherDimensionUniverse

The other DimensionUniverse to check for compatibility.

Returns:
resultsbool

If the other DimensionUniverse is compatible with this one return True, else False.

makePacker(name: str, dataId: DataCoordinate) DimensionPacker

Make a dimension packer.

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

Parameters:
namestr

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

dataIdDataCoordinate

Fully-expanded data ID that identifies 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.

.. deprecated:: v26

Deprecated in favor of configurable dimension packers. Will be removed after v26.

sorted(elements: Iterable[Dimension], *, reverse: bool = False) Sequence[Dimension]
sorted(elements: Iterable[DimensionElement | str], *, reverse: bool = False) Sequence[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), with an unspecified (but deterministic) approach to breaking ties.

Parameters:
elementsiterable of DimensionElement

Elements to be sorted.

reversebool, optional

If True, sort in the opposite order.

Returns:
sortedSequence [ Dimension or DimensionElement ]

A sorted sequence containing the same elements that were given.