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

Attributes Summary

names	Set of the names of all dimensions in the graph (KeysView).
primaryKeyTraversalOrder	Return a tuple of all elements in specific order.
spatial	Families represented by the spatial elements in this graph.
temporal	Families represented by the temporal elements in this graph.

Methods Summary

from_json(json_str, universe, registry)	Return new class from JSON string.
from_simple(names, universe, registry)	Construct a new object from the simplified form.
get(name, default)	Return the element with the given name.
intersection(*others)	Construct a new graph with 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.
to_json(minimal)	Convert this class to JSON form.
to_simple(minimal)	Convert this class to a simple python type.
union(*others)	Construct a new graph with all dimensions in any of the operands.

Attributes Documentation

names

Set of the names of all dimensions in the graph (KeysView).

primaryKeyTraversalOrder

Return a tuple of all elements in specific order.

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

spatial

Families represented by the spatial elements in this graph.

temporal

Families represented by the temporal elements in this graph.

Methods Documentation

classmethod from_json(json_str: str, universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = None) → SupportsSimple

Return new class from JSON string.

Converts a JSON string created by to_json and return something of the supplied class.

Parameters:

json_str : str

Representation of the dimensions in JSON format as created by to_json().

universe : DimensionUniverse, optional

The special graph of all known dimensions. Passed directly to from_simple().

registry : lsst.daf.butler.Registry, optional

Registry to use to convert simple name of a DatasetType to a full DatasetType. Passed directly to from_simple().

Returns:

constructed : Any

Newly-constructed object.

classmethod from_simple(names: List[str], universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = None) → DimensionGraph

Construct a new object from the simplified form.

This is assumed to support data data returned from the to_simple method.

Parameters:

names : list of str

The names of the dimensions.

universe : DimensionUniverse

The special graph of all known dimensions of which this graph will be a subset. Can be None if Registry is provided.

registry : lsst.daf.butler.Registry, optional

Registry from which a universe can be extracted. Can be None if universe is provided explicitly.

Returns:

graph : DimensionGraph

Newly-constructed object.

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

intersection(*others) → lsst.daf.butler.core.dimensions._graph.DimensionGraph

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

See also union.

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.

to_json(minimal: bool = False) → str

Convert this class to JSON form.

The class type is not recorded in the JSON so the JSON decoder must know which class is represented.

Parameters:

minimal : bool, optional

Use minimal serialization. Requires Registry to convert back to a full type.

Returns:

json : str

The class in JSON string format.

to_simple(minimal: bool = False) → List[str]

Convert this class to a simple python type.

This type is suitable for serialization.

Parameters:

minimal : bool, optional

Use minimal serialization. Has no effect on for this class.

Returns:

names : list

The names of the dimensions.

union(*others) → lsst.daf.butler.core.dimensions._graph.DimensionGraph

Construct a new graph with 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.