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).

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 element with the given name.
getSpatial(*, independent, prefer) Return the elements that are associated with spatial regions, possibly with some filtering.
getTemporal(*, independent, prefer) Return the elements that are associated with a timespan, possibly with some filtering.
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.
makeSchemaSpec() Create a database-agnostic schema specification for all dimensions.
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).

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: Any = None) → DimensionElement

Return the element with the given name.

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

getSpatial(*, independent: bool = True, prefer: Optional[Iterable[DimensionElement]] = None) → NamedValueSet[DimensionElement]

Return the elements that are associated with spatial regions, possibly with some filtering.

Parameters:
independent : bool

If True (default) ensure that all returned elements are independent of each other, by resolving any dependencies between spatial elements in favor of the dependent one (which is the one with the smaller, more precise region). A graph that includes both “tract” and “patch”, for example, would have only “patch” returned here if independent is True. If False, all spatial elements are returned.

prefer : iterable of DimensionElement

Elements that should be returned instead of their dependents when independent is True (ignored if independent is False). For example, passing prefer=[tract] to a graph with both “tract” and “patch” would result in only “tract” being returned.
Returns:
spatial : NamedValueSet of DimensionElement

Elements that have DimensionElement.spatial True, filtered as specified by the arguments.
getTemporal(*, independent: bool = True, prefer: Optional[Iterable[DimensionElement]] = None) → NamedValueSet[DimensionElement]

Return the elements that are associated with a timespan, possibly with some filtering.

Parameters:
independent : bool

If True (default) ensure that all returned elements are independent of each other, by resolving any dependencies between spatial elements in favor of the dependent one (which is the one with the smaller, more precise timespans).

prefer : iterable of DimensionElement

Elements that should be returned instead of their dependents when independent is True (ignored if independent is False).
Returns:
temporal : NamedValueSet of DimensionElement

Elements that have DimensionElement.temporal True, filtered as specified by the arguments.
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).
makeSchemaSpec() → Dict[str, lsst.daf.butler.core.ddl.TableSpec]

Create a database-agnostic schema specification for all dimensions.

Returns:
spec : dict

Mapping from str logical table name to ddl.TableSpec. Callers may use other names for actual database tables, but should use the keys in this dictionary when calling setupDimensionStorage.
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.