DimensionGraph

class lsst.daf.butler.DimensionGraph(universe, dimensions=(), joins=(), implied=False)

Bases: object

An automatically-expanded collection of both Dimensions and DimensionJoins.

Parameters:
universe : DimensionGraph

The ultimate graph the new graph should be a subset of.

dimensions : iterable of Dimension or str

Dimension objects that should be included in the graph, or their string names. Note that the new graph will in general return more than these dimensions, due to expansion to include dependenies.

joins : iterable of DimensionJoin or str.

DimensionJoin objects that should be included in the graph, or their string names.

implied : bool

If True, expand the graph to (recursively) include implied dependencies as well as required dependencies.

Notes

A DimensionGraph behaves much like a DimensionSet containing only Dimension objects, with a few key differences:

  • A DimensionGraph always contains all of the required dependencies of any of its elements. That means some standard set operations (namely symmetric_difference/^ and difference/-) can’t behave the way one would expect, and hence aren’t available (that’s why DimensionGraph doesn’t inherit from collections.abc.Set while DimensionSet does).
  • Any DimensionJoins whose dependencies are present in the graph are accessible via the joins() method (which is why we consider this graph - it contains the relationships as well as the elements of a system of dimensions).

Unlike most other dimension classes, DimensionGraph objects can be constructed directly, but only after a special “universe” DimensionGraph is constructed via a call to fromConfig. A “universe” graph contains all dimension elements, and all other DimensionGraphs or DimensionSets constructed from that universe are subsets of it.

Attributes Summary

elements A set containing both Dimension and DimensionJoin objects (DimensionSet).
leaves Dimensions that are not required or implied dependencies of any other dimension in the graph (DimensionSet).
names The names of all elements (set-like, immutable).
universe The graph of all dimensions compatible with self (DimensionGraph).

Methods Summary

extract(elements[, implied]) Return a new graph containing the given elements.
findIf(predicate[, default]) Return the element in self that matches the given predicate.
fromConfig([config]) Construct a “universe” DimensionGraph from configuration.
get(key[, default]) Return the element with the given name, or default if it does not exist.
getRegionHolder() Return the Dimension that provides the spatial region for this combination of dimensions.
implied([only]) Return the (recursive) implied dependencies of the dimensions in this graph.
intersection(*others[, implied]) Return a new graph containing all elements that are in both self
isdisjoint(other) Return True if there are no dimensions in both self and other, and False otherwise.
issubset(other) Return True if all dimensions in self are also in other.
issuperset(other) Return True if all dimensions in other are also in self, and False otherwise.
joins([summaries]) Return the DimensionJoin objects held by this graph.
links() Return the names of all fields that uniquely identify these dimensions in a data ID dict.
toSet() Return a DimensionSet with the same dimensions as self.
union(*others[, implied]) Return a new graph containing all elements that are in self or any of the other given graphs.
withLink(link) Return the set of Dimension and DimensionJoin objects that have the given link name in their primary or foreign keys.

Attributes Documentation

elements

A set containing both Dimension and DimensionJoin objects (DimensionSet).

leaves

Dimensions that are not required or implied dependencies of any other dimension in the graph (DimensionSet).

names

The names of all elements (set-like, immutable).

The order of the names is consistent with the iteration order of the DimensionSet itself.

universe

The graph of all dimensions compatible with self (DimensionGraph).

The universe of a DimensionGraph that is itself a universe is self.

Methods Documentation

extract(elements, implied=False)

Return a new graph containing the given elements.

Parameters:
elements : iterable of DimensionElement or str

Dimensions, DimensionJoins, or names thereof. These must be in self or self.joins().

implied : bool

If True, expand the result to include implied dependencies as well as required dependencies.
Returns:
subgraph : DimensionGraph

A new graph containing at least the elements and their dependencies.
findIf(predicate, default=None)

Return the element in self that matches the given predicate.

Parameters:
predicate : callable

Callable that takes a single DimensionElement argument and returns a bool, indicating whether the given value should be returned.

default : DimensionElement, optional

Object to return if no matching elements are found.
Returns:
matching : DimensionElement

Element matching the given predicate.
Raises:
ValueError

Raised if multiple elements match the given predicate.
static fromConfig(config=None)

Construct a “universe” DimensionGraph from configuration.

Parameters:
config : DimensionConfig, implied

Configuration specifying the elements and their relationships. If not provided, will be loaded from the default search path (see ConfigSubset).
Returns:
universe : DimensionGraph

A self-contained DimensionGraph containing all of the elements defined in the given configuration.
get(key, default=None)

Return the element with the given name, or default if it does not exist.

key may also be a Dimension, in which case an equivalent object will be returned.

getRegionHolder()

Return the Dimension that provides the spatial region for this combination of dimensions.

Returns:
holder : DimensionElement, or None.

Dimension or DimensionJoin that provides a unique region for this graph, or None if there is no region or multiple regions. holder.hasRegion is guaranteed to be True if holder is not None.
implied(only=True)

Return the (recursive) implied dependencies of the dimensions in this graph.

Parameters:
only : bool

If True (default), do not include dimensions in self.
Returns:
set : DimensionSet

A set containing dimensions that are implied dependencies of those in the graph, possibly (if only is False) along with those in the graph.
intersection(*others, implied=False)
Return a new graph containing all elements that are in both self
and all of the other given graphs.
Parameters:
*others : iterable over Dimension or str.

Other sets whose elements may be included in the result.
Returns:
result : DimensionGraph

Graph containing all elements in all of the inputs.
isdisjoint(other)

Return True if there are no dimensions in both self and other, and False otherwise.

All graphs (including the empty graph) are disjoint with the empty graph.

issubset(other)

Return True if all dimensions in self are also in other.

The empty graph is a subset of all graphs (including the empty graph).

issuperset(other)

Return True if all dimensions in other are also in self, and False otherwise.

All graphs (including the empty graph) are supersets of the empty graph.

joins(summaries=True)

Return the DimensionJoin objects held by this graph.

Parameters:
summaries : bool

If False, filter out joins that summarize any other joins being returned (in most cases only the most precise join between a group of dimensions is needed).
Returns:
joins : DimensionSet

The joins held by this graph, possibly filtered.

Return the names of all fields that uniquely identify these dimensions in a data ID dict.

Returns:
links : frozenset of str
toSet()

Return a DimensionSet with the same dimensions as self.

union(*others, implied=False)

Return a new graph containing all elements that are in self or any of the other given graphs.

Parameters:
*others : iterable over Dimension or str.

Other sets whose elements should be included in the result.
Returns:
result : DimensionGraph

Graph containing any elements in any of the inputs.

Return the set of Dimension and DimensionJoin objects that have the given link name in their primary or foreign keys.

Unlike most other DimensionGraph operations, this method does not limit its results to the elements included in self.

Parameters:
link : str

Key field name.
Returns:
dimensions : DimensionSet

Set potentially containing both Dimension and DimensionJoin elements.