DimensionSet¶

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

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

links()¶

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

Navigation

DimensionSet¶