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 constructingDimensionElement
instances, these are also indirectly tracked by that singleton as well.Parameters: - config :
Config
, optional Configuration object from which dimension definitions can be extracted. Ignored if
builder
is provided, or ifversion
is provided and an instance with that version already exists.- version :
int
, optional Integer version for this
DimensionUniverse
. If not provided, a version will be obtained frombuilder
orconfig
.- builder :
DimensionConstructionBuilder
, 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 hadfinish
called; this will be called if needed byDimensionUniverse
.
Attributes Summary
skypix
All skypix systems known to this universe ( NamedValueAbstractSet
[SkyPixSystem
]).Methods Summary
expandDimensionNameSet
(names)Expand a set of dimension names in-place to include recursive dependencies. extract
(iterable, str]])Construct a DimensionGraph
from a possibly-heterogenous iterable ofDimension
instances and string names thereof.get
(name, default)Return the DimensionElement
with the given name or a default.getDatabaseElements
()Return a set of all DatabaseDimensionElement
instances in this universe.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.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. 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. Attributes Documentation
-
skypix
¶ All skypix systems known to this universe (
NamedValueAbstractSet
[SkyPixSystem
]).
Methods Documentation
-
expandDimensionNameSet
(names: Set[str]) → None¶ Expand a set of dimension names in-place to include recursive dependencies.
This is an advanced interface for cases where constructing a
DimensionGraph
(which also expands required dependencies) is impossible or undesirable.Parameters:
-
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 ofDimension
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.
- name :
-
getDatabaseElements
() → lsst.daf.butler.core.named.NamedValueAbstractSet[lsst.daf.butler.core.dimensions._database.DatabaseDimensionElement][lsst.daf.butler.core.dimensions._database.DatabaseDimensionElement]¶ Return a set of all
DatabaseDimensionElement
instances in this universe.This does not include
GovernorDimension
instances, which are backed by the database but do not inherit fromDatabaseDimensionElement
.Returns: - elements :
NamedValueAbstractSet
[DatabaseDimensionElement
] A frozen set of
DatabaseDimensionElement
instances.
- elements :
-
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.
- name :
-
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.
- name :
-
getEncodeLength
() → int¶ Return the size (in bytes) of the encoded size of
DimensionGraph
instances in this universe.See
DimensionGraph.encode
andDimensionGraph.decode
for more information.
-
getGovernorDimensions
() → lsst.daf.butler.core.named.NamedValueAbstractSet[lsst.daf.butler.core.dimensions._governor.GovernorDimension][lsst.daf.butler.core.dimensions._governor.GovernorDimension]¶ Return a set of all
GovernorDimension
instances in this universe.Returns: - governors :
NamedValueAbstractSet
[GovernorDimension
] A frozen set of
GovernorDimension
instances.
- governors :
-
getStaticDimensions
() → lsst.daf.butler.core.named.NamedValueAbstractSet[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 :
NamedValueAbstractSet
[Dimension
] A frozen set of
Dimension
instances.
- dimensions :
-
getStaticElements
() → lsst.daf.butler.core.named.NamedValueAbstractSet[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 :
NamedValueAbstractSet
[DimensionElement
] A frozen set of
DimensionElement
instances.
- elements :
-
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 returnTrue
.
- name :
-
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
ofDimensionElement
A sorted list containing the same elements that were given.
- elements : iterable of
- config :