DataCoordinateSet

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

Bases: lsst.daf.butler.core.dimensions._dataCoordinateIterable._DataCoordinateCollectionBase

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

Parameters:

dataIds : collections.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.

graph : DimensionGraph

Dimensions identified by all data IDs in the set.

hasFull : bool, 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.

hasRecords : bool, 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	The dimensions identified by these data IDs (DimensionGraph).
universe	The universe that defines all known dimensions compatible with this iterable (DimensionUniverse).

Methods Summary

constrain(query, columns, …)	Constrain a SQL query to include or relate to only data IDs in this iterable.
difference(other)	Return a new set that contains all data IDs in self that are not in other.
fromScalar(dataId)	Return a DataCoordinateIterable containing the single data ID given.
hasFull()	Return whether all data IDs in this iterable identify all dimensions, not just required dimensions.
hasRecords()	Return whether all data IDs in this iterable contain DimensionRecord instances.
intersection(other)	Return a new set that contains all data IDs in both self and other.
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 of the dimensions that this one’s do.
symmetric_difference(other)	Return a new set that contains all data IDs in either self or other, but 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 self or other.

Attributes Documentation

graph

The dimensions identified by these data IDs (DimensionGraph).

universe

The universe that defines all known dimensions compatible with this iterable (DimensionUniverse).

Methods Documentation

constrain(query: lsst.daf.butler.core.simpleQuery.SimpleQuery, columns: Callable[[str], sqlalchemy.sql.elements.ColumnElement]) → None

Constrain a SQL query to include or relate to only data IDs in this iterable.

Parameters:

query : SimpleQuery

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

columns : Callable

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: lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateIterable) → lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateSet

Return a new set that contains all data IDs in self that are not in other.

Parameters:

other : DataCoordinateIterable

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

Returns:

intersection : DataCoordinateSet

A new DataCoordinateSet instance.

static fromScalar(dataId: lsst.daf.butler.core.dimensions.coordinate.DataCoordinate) → lsst.daf.butler.core.dimensions._dataCoordinateIterable._ScalarDataCoordinateIterable

Return a DataCoordinateIterable containing the single data ID given.

Parameters:

dataId : DataCoordinate

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

Returns:

iterable : DataCoordinateIterable

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

Return whether all data IDs in this iterable identify all dimensions, not just required dimensions.

Returns:

state : bool

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

Returns:

state : bool

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

intersection(other: lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateIterable) → lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateSet

Return a new set that contains all data IDs in both self and other.

Parameters:

other : DataCoordinateIterable

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

Returns:

intersection : DataCoordinateSet

A new DataCoordinateSet instance.

isdisjoint(other: lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateIterable) → bool

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

Parameters:

other : DataCoordinateIterable

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

Returns:

isdisjoint : bool

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

issubset(other: lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateIterable) → bool

Test whether self contains all data IDs in other.

Parameters:

other : DataCoordinateIterable

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

Returns:

issubset : bool

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

issuperset(other: lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateIterable) → bool

Test whether other contains all data IDs in self.

Parameters:

other : DataCoordinateIterable

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

Returns:

issuperset : bool

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

subset(graph: lsst.daf.butler.core.dimensions.graph.DimensionGraph) → lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateSet

Return a set whose data IDs identify a subset of the dimensions that this one’s do.

Parameters:

graph : DimensionGraph

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

Returns:

set : DataCoordinateSet

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: lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateIterable) → lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateSet

Return a new set that contains all data IDs in either self or other, but not both.

Parameters:

other : DataCoordinateIterable

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

Returns:

intersection : DataCoordinateSet

A new DataCoordinateSet instance.

toSequence() → lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateSequence

Transform this iterable into a DataCoordinateSequence.

Returns:

seq : DataCoordinateSequence

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

toSet() → lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateSet

Transform this iterable into a DataCoordinateSet.

Returns:

set : DataCoordinateSet

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

union(other: lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateIterable) → lsst.daf.butler.core.dimensions._dataCoordinateIterable.DataCoordinateSet

Return a new set that contains all data IDs in either self or other.

Parameters:

other : DataCoordinateIterable

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

Returns:

intersection : DataCoordinateSet

A new DataCoordinateSet instance.