DimensionSet

class lsst.daf.butler.DimensionSet(universe, elements, expand=False, implied=False)

Bases: lsst.daf.butler.core.dimensions.sets.DimensionSetBase, collections.abc.Set

A custom set/dict hybrid class for collections of DimensionElements.

DimensionSet objects implement the full (immutable) collections.abc.Set interface. In addition, like frozenset, they are immutable and hashable, and also provide named-method versions of most operators. Unlike Python sets, they are deterministically sorted.

Parameters:
universe : DimensionGraph

Ultimate-parent DimensionGraph that constructed the elements in this set.

elements : iterable of DimensionElement or str

Elements to include in the set, or names thereof.

expand : bool

If True, recursively expand the set to include dependencies.

implied : bool

If True, include implied dependencies in expansion. Ignored if expand is False.

Raises:
ValidationError

Raised if a Dimension is not part of the Universe.

Notes

DimensionSet comparison operators and named-method relation operations accept other set-like objects and iterables containing either DimensionElement instances or their string names; because DimensionElements cannot be directly constructed, APIs that accept them should generally accept a name as an alternative when the transformation to a DimensionElement can be done internally. Operators that return new sets (|, &, ^, and -) do require DimensionSet operands on both sides to avoid surprises in return types.

Because the DimensionElement objects they hold always have a name, DimensionSets also supports some dict-like operations: including regular square-bracket indexing (__getitem__), get, and the in operator (__contains__). Both names and DimensionElement objects can be passed to any of these. The names attribute can also be used to obtain a set-like object containing those names.

DimensionSet instances cannot be constructed directly; they can only be obtained (possibly indirectly) from a special “universe” DimensionGraph loaded from configuration.

Attributes Summary

names The names of all elements (set-like, immutable).
universe The graph of all dimensions compatible with self (DimensionGraph).

Methods Summary

difference(other) Return a new set containing all elements that are in self but not other.
expanded([implied]) Return a new DimensionSet that has been expanded to include dependencies.
findIf(predicate[, default]) Return the element in self that matches the given predicate.
get(key[, default]) Return the element with the given name, or default if it does not exist.
intersection(*others) Return a new set containing all elements that are in both self and all of the other given sets.
isdisjoint(other) Return True if there are no elements in both self and other, and False otherwise.
issubset(other) Return True if all elements in self are also in other.
issuperset(other) Return True if all elements in other are also in self, and False otherwise.
links() Return the names of all fields that uniquely identify these dimensions in a data ID dict.
symmetric_difference(other) Return a new set containing all elements that are in either self or other, but not both.
union(*others) Return a new set containing all elements that are in self or any of the other given sets.

Attributes Documentation

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

Methods Documentation

difference(other)

Return a new set containing all elements that are in self but not other.

Parameters:
other : iterable of DimensionElement or str.

The other set containing elements that should not be included in the result.

Returns:
result : DimensionNameSet or DimensionSet

A new set containing elements in self but not other. A full DimensionSet is returned if any argument is a full DimensionSet or DimensionGraph.

expanded(implied=False)

Return a new DimensionSet that has been expanded to include dependencies.

Parameters:
implied : bool

Whether to include implied as well as required 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.

get(key, default=None)

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

key may also be a DimensionElement, in which case an equivalent object will be returned if it is present in the set.

intersection(*others)

Return a new set containing all elements that are in both self and all of the other given sets.

Parameters:
others : iterable over DimensionElement or str.

Other sets whose elements may be included in the result.

Returns:
result : DimensionNameSet or DimensionSet

A new set containing any elements in all input sets. A full DimensionSet is returned if any argument is a full DimensionSet or DimensionGraph.

isdisjoint(other)

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

All sets (including the empty set) are disjoint with the empty set.

issubset(other)

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

The empty set is a subset of all sets (including the empty set).

issuperset(other)

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

All sets (including the empty set) are supersets of the empty set.

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

Returns:
links : frozenset of str
symmetric_difference(other)

Return a new set containing all elements that are in either self or other, but not both.

Parameters:
other : iterable of DimensionElement or str.

The other set from which to draw potential result elements.

Returns:
result : DimensionNameSet or DimensionSet

A new set containing elements self or other, but not both. A full DimensionSet is returned if any argument is a full DimensionSet or DimensionGraph.

union(*others)

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

Parameters:
*others : iterable over DimensionElement or str.

Other sets whose elements should be included in the result.

Returns:
result : DimensionNameSet or DimensionSet

A new set containing all elements in any input set. A full DimensionSet is returned if any argument is a full DimensionSet or DimensionGraph.