DimensionGraph

class lsst.daf.butler.DimensionGraph(*args, **kwargs)

Bases: object

An immutable, dependency-complete collection of dimensions.

DimensionGraph is deprecated in favor of DimensionGroup and will be removed after v27. The two types have very similar interfaces, but DimensionGroup does not support direct iteration and its set-like attributes are of dimension element names, not DimensionElement instances. DimensionGraph objects are still returned by certain non-deprecated methods and properties (most prominently DatasetType.dimensions), and to handle these cases deprecation warnings are only emitted for operations on DimensionGraph that are not supported by DimensionGroup as well.

Parameters:

universeDimensionUniverse

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

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

namesiterable of str, optional

An iterable of the names of dimensions 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.

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

Deprecated since version v27: DimensionGraph is deprecated in favor of DimensionGroup and will be removed after v27.

Attributes Summary

dimensions	A true Set of all true Dimension instances in the graph.
elements	A true Set of all DimensionElement instances in the graph; a superset of dimensions (NamedValueAbstractSet of DimensionElement).
governors	A true Set of all GovernorDimension instances in the graph.
implied	The subset of dimensions whose elements need not be directly identified via their primary keys in a data ID.
names	Set of the names of all dimensions in the graph.
primaryKeyTraversalOrder	A tuple of all elements in specific order.
required	The subset of dimensions whose elements must be directly identified via their primary keys in a data ID in order to identify the rest of the elements in the graph.
skypix	A true Set of all SkyPixDimension instances in the graph.
spatial	Families represented by the spatial elements in this graph.
temporal	Families represented by the temporal elements in this graph.
topology	Families of elements in this graph that can participate in topological relationships.
universe	Object that manages all known dimensions.

Methods Summary

as_group()	Return a DimensionGroup that represents the same set of dimensions.
from_json(json_str[, universe, registry])	Convert from JSON to a pydantic model.
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 assuming that the to_simple() returns a pydantic model.
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

dimensions

A true Set of all true Dimension instances in the graph.

Deprecated since version v27: DimensionGraph is deprecated in favor of DimensionGroup, which uses sets of str names instead of NamedValueAbstractSets of Dimension or DimensionElement instances. Support for the NamedValueAbstractSet interfaces on this object will be dropped after v27. Use ‘.names’ instead of ‘.dimensions’ or ‘.dimensions.names’.

elements

A true Set of all DimensionElement instances in the graph; a superset of dimensions (NamedValueAbstractSet of DimensionElement).

governors

A true Set of all GovernorDimension instances in the graph.

implied

The subset of dimensions whose elements need not be directly identified via their primary keys in a data ID.

names

Set of the names of all dimensions in the graph.

primaryKeyTraversalOrder

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.

Deprecated since version v27: DimensionGraph is deprecated in favor of DimensionGroup, which does not have this attribute; use .lookup_order. DimensionGraph will be removed after v27.

required

The subset of dimensions whose elements must be directly identified via their primary keys in a data ID in order to identify the rest of the elements in the graph.

skypix

A true Set of all SkyPixDimension instances in the graph.

spatial

Families represented by the spatial elements in this graph.

temporal

Families represented by the temporal elements in this graph.

topology

Families of elements in this graph that can participate in topological relationships.

Deprecated since version v27: DimensionGraph is deprecated in favor of DimensionGroup, which does not have this attribute; use .spatial or .temporal. DimensionGraph will be removed after v27.

universe

Object that manages all known dimensions.

Methods Documentation

as_group() → DimensionGroup

Return a DimensionGroup that represents the same set of dimensions.

Returns:

groupDimensionGroup

Group that represents the same set of dimensions.

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

Convert from JSON to a pydantic model.

Parameters:

cls_type of SupportsSimple

The Python type being created.

json_strstr

The JSON string representing this object.

universeDimensionUniverse or None, optional

The universe required to instantiate some models. Required if registry is None.

registryRegistry or None, optional

Registry from which to obtain the dimension universe if an explicit universe has not been given.

Returns:

modelSupportsSimple

Pydantic model constructed from JSON and validated.

classmethod from_simple(names: SerializedDimensionGraph, universe: DimensionUniverse | None = None, registry: Registry | None = None) → DimensionGraph

Construct a new object from the simplified form.

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

Parameters:

nameslist of str

The names of the dimensions.

universeDimensionUniverse

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

registrylsst.daf.butler.Registry, optional

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

Returns:

graphDimensionGraph

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

Parameters:

namestr

Name of element to return.

defaulttyping.Any or None

Default value if named element is not present.

Returns:

elementDimensionElement or None

The element found, or the default.

intersection(*others: DimensionGroup | DimensionGraph) → DimensionGraph

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

Parameters:

*othersDimensionGroup or DimensionGraph

Other graphs to use.

Returns:

interDimensionGraph

Intersection of all the graphs.

Notes

See also union.

isdisjoint(other: DimensionGroup | DimensionGraph) → bool

Test whether the intersection of two graphs is empty.

Parameters:

otherDimensionGroup or DimensionGraph

Other graph to compare with.

Returns:

is_disjointbool

Returns True if either operand is the empty.

issubset(other: DimensionGroup | DimensionGraph) → bool

Test whether all dimensions in self are also in other.

Parameters:

otherDimensionGroup or DimensionGraph

Other graph to compare with.

Returns:

is_subsetbool

Returns True if self is empty.

issuperset(other: DimensionGroup | DimensionGraph) → bool

Test whether all dimensions in other are also in self.

Parameters:

otherDimensionGroup or DimensionGraph

Other graph to compare with.

Returns:

is_supersetbool

Returns True if other is empty.

to_json(minimal: bool = False) → str

Convert this class to JSON assuming that the to_simple() returns a pydantic model.

Parameters:

minimalbool

Return minimal possible representation.

to_simple(minimal: bool = False) → SerializedDimensionGraph

Convert this class to a simple python type.

This type is suitable for serialization.

Parameters:

minimalbool, optional

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

Returns:

nameslist

The names of the dimensions.

union(*others: DimensionGroup | DimensionGraph) → DimensionGraph

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

Parameters:

*othersDimensionGroup or DimensionGraph

Other graphs to join with.

Returns:

unionDimensionGraph

The union of this graph wit hall the others.

Notes

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.