DimensionGraph

class lsst.daf.butler.DimensionGraph

Bases: object

An immutable, dependency-complete collection of dimensions.

DimensionGraph behaves in many respects like a set of Dimension instances that maintains several special subsets and supersets of related DimensionElement instances. It does not fully implement the collections.abc.Set interface, as its automatic expansion of dependencies would make set difference and XOR operations behave surprisingly.

It also provides dict-like lookup of DimensionElement instances from their names.

Parameters:

universe : DimensionUniverse

The special graph of all known dimensions of which this graph will be a subset.

dimensions : iterable of Dimension, optional

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

names : iterable of str, optional

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

conform : bool, 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 primarily for internal use.

Notes

DimensionGraph should be used instead of other collections in any context where a collection of dimensions is required and a DimensionUniverse is available.

While DimensionUniverse inherits from DimensionGraph, it should otherwise not be used as a base class.

Attributes Summary

names	A set of the names of all dimensions in the graph (KeysView).
primaryKeyTraversalOrder	Return a tuple of all elements in an order allows records to be found given their primary keys, starting from only the primary keys of required dimensions (tuple [ DimensionRecord ]).

Methods Summary

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

primaryKeyTraversalOrder

Return a tuple of all elements in an order allows records to be found given their primary keys, starting from only the primary keys of required dimensions (tuple [ DimensionRecord ]).

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

Methods Documentation

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.

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.