DataCoordinateSet

class lsst.daf.butler.DataCoordinateSet(dataIds: AbstractSet[DataCoordinate], graph: DimensionGraph, *, hasFull: Optional[bool] = None, hasRecords: Optional[bool] = None, check: bool = True)

Bases: _DataCoordinateCollectionBase

Iterable iteration that is set-like.

A DataCoordinateIterable implementation that adds some set-like functionality, and is backed by a true set-like object.

Parameters:

dataIdscollections.abc.Set [ DataCoordinate ]

A set of DataCoordinate instances, with dimensions equal to graph. If this is a mutable object, the caller must be able to guarantee that it will not be modified by any other holders.

graphDimensionGraph

Dimensions identified by all data IDs in the set.

hasFullbool, optional

If True, the caller guarantees that DataCoordinate.hasFull returns True for all given data IDs. If False, no such guarantee is made, and DataCoordinateSet.hasFull will always return False. If None (default), DataCoordinateSet.hasFull will be computed from the given data IDs, immediately if check is True, or on first use if check is False.

hasRecordsbool, optional

If True, the caller guarantees that DataCoordinate.hasRecords returns True for all given data IDs. If False, no such guarantee is made and DataCoordinateSet.hasRecords will always return False. If None (default), DataCoordinateSet.hasRecords will be computed from the given data IDs, immediately if check is True, or on first use if check is False.

check: `bool`, optional

If True (default) check that all data IDs are consistent with the given graph and state flags at construction. If False, no checking will occur.

Notes

DataCoordinateSet does not formally implement the collections.abc.Set interface, because that requires many binary operations to accept any set-like object as the other argument (regardless of what its elements might be), and it’s much easier to ensure those operations never behave surprisingly if we restrict them to DataCoordinateSet or (sometimes) DataCoordinateIterable, and in most cases restrict that they identify the same dimensions. In particular:

• a DataCoordinateSet will compare as not equal to any object that is not a DataCoordinateSet, even native Python sets containing the exact same elements;

• subset/superset comparison _operators_ (<, >, <=, >=) require both operands to be DataCoordinateSet instances that have the same dimensions (i.e. graph attribute);

• issubset, issuperset, and isdisjoint require the other argument to be a DataCoordinateIterable with the same dimensions;

• operators that create new sets (&, |, ^, -) require both operands to be DataCoordinateSet instances that have the same dimensions _and_ the same dtype;

• named methods that create new sets (intersection, union, symmetric_difference, difference) require the other operand to be a DataCoordinateIterable with the same dimensions _and_ the same dtype.

In addition, when the two operands differ in the return values of hasFull and/or hasRecords, we make no guarantees about what those methods will return on the new DataCoordinateSet (other than that they will accurately reflect what elements are in the new set - we just don’t control which elements are contributed by each operand).

Attributes Summary

graph	Dimensions identified by these data IDs (DimensionGraph).
universe	Universe that defines all known compatible dimensions.

Methods Summary

constrain(query, columns)	Constrain a SQL query to include or relate to only known data IDs.
difference(other)	Return a new set with all data IDs in this that are not in other.
fromScalar(dataId)	Return a DataCoordinateIterable containing the single data ID.
hasFull()	Indicate if all data IDs in this iterable identify all dimensions.
hasRecords()	Return whether all data IDs in this iterable contain records.
intersection(other)	Return a new set that contains all data IDs from parameters.
isdisjoint(other)	Test whether there are no data IDs in both self and other.
issubset(other)	Test whether self contains all data IDs in other.
issuperset(other)	Test whether other contains all data IDs in self.
subset(graph)	Return a set whose data IDs identify a subset.
symmetric_difference(other)	Return a new set with all data IDs in either parameters, not both.
toSequence()	Transform this iterable into a DataCoordinateSequence.
toSet()	Transform this iterable into a DataCoordinateSet.
union(other)	Return a new set that contains all data IDs in either parameters.

Attributes Documentation

graph

universe

Universe that defines all known compatible dimensions.

(DimensionUniverse).

Methods Documentation

constrain(query: SimpleQuery, columns: Callable[[str], ColumnElement]) → None

Constrain a SQL query to include or relate to only known data IDs.

Parameters:

querySimpleQuery

Struct that represents the SQL query to constrain, either by appending to its WHERE clause, joining a new table or subquery, or both.

columnsCallable

A callable that accepts str dimension names and returns SQLAlchemy objects representing a column for that dimension’s primary key value in the query.

difference(other: DataCoordinateIterable) → DataCoordinateSet

Return a new set with all data IDs in this that are not in other.

Parameters:

otherDataCoordinateIterable

An iterable of data IDs with other.graph == self.graph.

Returns:

intersectionDataCoordinateSet

A new DataCoordinateSet instance.

static fromScalar(dataId: DataCoordinate) → _ScalarDataCoordinateIterable

Return a DataCoordinateIterable containing the single data ID.

Parameters:

dataIdDataCoordinate

Data ID to adapt. Must be a true DataCoordinate instance, not an arbitrary mapping. No runtime checking is performed.

Returns:

iterableDataCoordinateIterable

A DataCoordinateIterable instance of unspecified (i.e. implementation-detail) subclass. Guaranteed to implement the collections.abc.Sized (i.e. __len__) and collections.abc.Container (i.e. __contains__) interfaces as well as that of DataCoordinateIterable.

hasFull() → bool

Indicate if all data IDs in this iterable identify all dimensions.

Not just required dimensions.

Returns:

statebool

If True, all(d.hasFull() for d in iterable) is guaranteed. If False, no guarantees are made.

hasRecords() → bool

Return whether all data IDs in this iterable contain records.

Returns:

statebool

If True, all(d.hasRecords() for d in iterable) is guaranteed. If False, no guarantees are made.

intersection(other: DataCoordinateIterable) → DataCoordinateSet

Return a new set that contains all data IDs from parameters.

Parameters:

otherDataCoordinateIterable

An iterable of data IDs with other.graph == self.graph.

Returns:

intersectionDataCoordinateSet

A new DataCoordinateSet instance.

isdisjoint(other: DataCoordinateIterable) → bool

Test whether there are no data IDs in both self and other.

Parameters:

otherDataCoordinateIterable

An iterable of data IDs with other.graph == self.graph.

Returns:

isdisjointbool

True if there are no data IDs in both self and other, and False otherwise.

issubset(other: DataCoordinateIterable) → bool

Test whether self contains all data IDs in other.

Parameters:

otherDataCoordinateIterable

An iterable of data IDs with other.graph == self.graph.

Returns:

issubsetbool

True if all data IDs in self are also in other, and False otherwise.

issuperset(other: DataCoordinateIterable) → bool

Test whether other contains all data IDs in self.

Parameters:

otherDataCoordinateIterable

An iterable of data IDs with other.graph == self.graph.

Returns:

issupersetbool

True if all data IDs in other are also in self, and False otherwise.

subset(graph: DimensionGraph) → DataCoordinateSet

Return a set whose data IDs identify a subset.

Parameters:

graphDimensionGraph

Dimensions to be identified by the data IDs in the returned iterable. Must be a subset of self.graph.

Returns:

setDataCoordinateSet

A DataCoordinateSet with set.graph == graph. Will be self if graph == self.graph. Elements are equivalent to those that would be created by calling DataCoordinate.subset on all elements in self, with deduplication but and in arbitrary order.

symmetric_difference(other: DataCoordinateIterable) → DataCoordinateSet

Return a new set with all data IDs in either parameters, not both.

Parameters:

otherDataCoordinateIterable

An iterable of data IDs with other.graph == self.graph.

Returns:

intersectionDataCoordinateSet

A new DataCoordinateSet instance.

toSequence() → DataCoordinateSequence

Transform this iterable into a DataCoordinateSequence.

Returns:

seqDataCoordinateSequence

A new DatasetCoordinateSequence with the same elements as self, in the same order. May be self if it is already a DataCoordinateSequence.

toSet() → DataCoordinateSet

Transform this iterable into a DataCoordinateSet.

Returns:

setDataCoordinateSet

A DatasetCoordinateSet instance with the same elements as self, after removing any duplicates. May be self if it is already a DataCoordinateSet.

union(other: DataCoordinateIterable) → DataCoordinateSet

Return a new set that contains all data IDs in either parameters.

Parameters:

otherDataCoordinateIterable

An iterable of data IDs with other.graph == self.graph.

Returns:

intersectionDataCoordinateSet

A new DataCoordinateSet instance.