DimensionGroup

class lsst.daf.butler.DimensionGroup(universe: DimensionUniverse, names: Iterable[str] | DimensionGroup = frozenset({}), _conform: bool = True)

Bases: object

An immutable, dependency-complete collection of dimensions.

DimensionGroup behaves in many respects like a set of str dimension names that maintains several special subsets and supersets of related dimension elements. It does not fully implement the collections.abc.Set interface, because it defines a few different iteration orders and does not privilege any one of them by implementing __iter__.

Parameters:

universeDimensionUniverse

Object that manages all known dimensions.

namesiterable of str, optional

An iterable of the names of dimensions that must be included in the group. All (recursive) dependencies of these dimensions will also be included. At most one of dimensions and names must be provided.

_conformbool, optional

If True (default), expand to include dependencies. False should only be used for callers that can guarantee that other arguments are already correctly expanded, and is for internal use only.

Notes

DimensionGroup should be used instead of other collections in most contexts where a collection of dimensions is required and a DimensionUniverse is available. Exceptions include cases where order matters (and is different from the consistent ordering defined by the DimensionUniverse), or complete Set semantics are required.

This class is not a Pydantic model, but it implements the __get_pydantic_core_schema__ special method and hence can be used as a field in Pydantic models or [de]serialized directly via pydantic.TypeAdapter, but validation requires a DimensionUniverse to be passed as the “universe” key in the Pydantic validation context. The pydantic_utils.DeferredValidation class can be used to defer validation of this object or other types that use it until that context is available.

Attributes Summary

data_coordinate_keys	A set of dimensions ordered like DataCoordinate.mapping.
lookup_order	A tuple of all elements in the order needed to find their records.
spatial	Families represented by the spatial elements in this graph.
temporal	Families represented by the temporal elements in this graph.

Methods Summary

as_group()	Return self.
from_simple(data, universe)	Create an instance of this class from serialized data.
intersection(*others)	Construct a new group with only dimensions in all of the operands.
isdisjoint(other)	Test whether the intersection of two groups 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.
to_simple()	Convert this class to a simple data format suitable for serialization.
union(*others)	Construct a new group with all dimensions in any of the operands.

Attributes Documentation

data_coordinate_keys

A set of dimensions ordered like DataCoordinate.mapping.

This order is defined as all required dimensions followed by all implied dimensions.

lookup_order

A tuple of all elements in the order needed to find their records.

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

spatial

Families represented by the spatial elements in this graph.

temporal

Families represented by the temporal elements in this graph.

Methods Documentation

as_group() → DimensionGroup

Return self.

Returns:

groupDimensionGroup

Returns itself.

Notes

This is a backwards-compatibility API that allowed both the old DimensionGraph class and DimensionGroup to be coerced to the latter.

Deprecated since version v28: Deprecated as no longer necessary (this method always returns ‘self’). Will be removed after v28.

classmethod from_simple(data: SerializedDimensionGroup, universe: DimensionUniverse) → DimensionGroup

Create an instance of this class from serialized data.

Parameters:

dataSerializedDimensionGroup

Serialized data from a previous call to to_simple.

universeDimensionUniverse

Dimension universe in which this dimension group will be defined.

intersection(*others: DimensionGroup) → DimensionGroup

Construct a new group with only dimensions in all of the operands.

Parameters:

*othersDimensionGroup

Other groups to compare with.

Returns:

interDimensionGroup

Intersection of all the groups.

Notes

See also union.

isdisjoint(other: DimensionGroup) → bool

Test whether the intersection of two groups is empty.

Parameters:

otherDimensionGroup

Other group to compare with.

Returns:

is_disjoinbool

Returns True if either operand is the empty.

issubset(other: DimensionGroup) → bool

Test whether all dimensions in self are also in other.

Parameters:

otherDimensionGroup

Other group to compare with.

Returns:

is_subsetbool

Returns True if self is empty.

issuperset(other: DimensionGroup) → bool

Test whether all dimensions in other are also in self.

Parameters:

otherDimensionGroup

Other group to compare with.

Returns:

is_supersetbool

Returns True if other is empty.

to_simple() → list[str]

Convert this class to a simple data format suitable for serialization.

union(*others: DimensionGroup) → DimensionGroup

Construct a new group with all dimensions in any of the operands.

Parameters:

*othersDimensionGroup

Other groups to join with.

Returns:

unionDimensionGroup

Union of all the groups.

Notes

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