DimensionRecordSet¶
- final class lsst.daf.butler.DimensionRecordSet(element: DimensionElement | str, records: Iterable[DimensionRecord] = (), universe: DimensionUniverse | None = None, *, _by_required_values: dict[tuple[DataIdValue, ...], DimensionRecord] | None = None)¶
Bases:
Collection
[DimensionRecord
]A mutable set-like container specialized for
DimensionRecord
objects.- Parameters:
- element
DimensionElement
orstr
, optional The dimension element that defines the records held by this set. If not a
DimensionElement
instance,universe
must be provided.- records
Iterable
[DimensionRecord
], optional Dimension records to add to the set.
- universe
DimensionUniverse
, optional Object that defines all dimensions. Ignored if
element
is aDimensionElement
instance.
- element
Notes
DimensionRecordSet
maintains its insertion order (likedict
, and unlikeset
).DimensionRecordSet
implementscollections.abc.Collection
but notcollections.abc.Set
because the latter would require interoperability with all otherSet
implementations rather than justDimensionRecordSet
, and that adds a lot of complexity without much clear value. To help make this clear to type checkers it implements only the named-method versions of these operations (e.g.issubset
) rather than the operator special methods (e.g.__le__
).DimensionRecord
equality is defined in terms of a record’s data ID fields only, andDimensionRecordSet
does not generally specify which record “wins” when two records with the same data ID interact (e.g. inintersection
). Theadd
andupdate
methods are notable exceptions: they always replace the existing record with the new one.Dimension records can also be held by
DimensionRecordTable
, which provides column-oriented access and Arrow interoperability.Attributes Summary
Name of the dimension element these records correspond to.
Methods Summary
add
(value[, replace])Add a new record to the set.
difference
(other)Return a new set with only records that are in
self
and not inother
.discard
(value)Remove a record if it exists.
find
(data_id[, or_add])Return the record with the given data ID.
find_with_required_values
(required_values[, ...])Return the record whose data ID has the given required values.
intersection
(other)Return a new set with only records that are in both
self
andother
.isdisjoint
(other)Test whether the intersection of
self
andother
is empty.issubset
(other)Test whether all elements in
self
are inother
.issuperset
(other)Test whether all elements in
other
are inself
.pop
()Remove and return an arbitrary record.
remove
(value)Remove a record.
union
(other)Return a new set with all records that are either in
self
orother
.update
(values[, replace])Add new records to the set.
update_from_data_coordinates
(data_coordinates)Add records to the set by extracting and deduplicating them from data coordinates.
Attributes Documentation
- element¶
Name of the dimension element these records correspond to.
Methods Documentation
- add(value: DimensionRecord, replace: bool = True) None ¶
Add a new record to the set.
- Parameters:
- value
DimensionRecord
Record to add.
- replace
bool
, optional If
True
(default) replace any existing record with the same data ID. IfFalse
the existing record will be kept.
- value
- Raises:
- ValueError
Raised if
value.element != self.element
.
- difference(other: DimensionRecordSet) DimensionRecordSet ¶
Return a new set with only records that are in
self
and not inother
.- Parameters:
- other
DimensionRecordSet
Another record set with the same record type.
- other
- Returns:
- difference
DimensionRecordSet
A new record set with all elements
self
that are not inother
.
- difference
- discard(value: DimensionRecord | DataCoordinate) None ¶
Remove a record if it exists.
- Parameters:
- value
DimensionRecord
orDataCoordinate
Record to remove, or its data ID.
- value
- find(data_id: ~lsst.daf.butler.dimensions._coordinate.DataCoordinate, or_add: ~lsst.daf.butler.dimensions._record_set.DimensionRecordFactory = <function fail_record_lookup>) DimensionRecord ¶
Return the record with the given data ID.
- Parameters:
- data_id
DataCoordinate
Data ID to match.
- or_add
DimensionRecordFactory
Callback that is invoked if no existing record is found, to create a new record that is added to the set and returned. The return value of this callback is not checked to see if it is a valid dimension record with the right element and data ID.
- data_id
- Returns:
- record
DimensionRecord
Matching record.
- record
- Raises:
- KeyError
Raised if no record with this data ID was found.
- ValueError
Raised if the data ID did not have the right dimensions.
- find_with_required_values(required_values: tuple[int | str | None, ...], or_add: ~lsst.daf.butler.dimensions._record_set.DimensionRecordFactory = <function fail_record_lookup>) DimensionRecord ¶
Return the record whose data ID has the given required values.
- Parameters:
- required_values
tuple
[int
orstr
] Data ID values to match.
- or_add
DimensionRecordFactory
Callback that is invoked if no existing record is found, to create a new record that is added to the set and returned. The return value of this callback is not checked to see if it is a valid dimension record with the right element and data ID.
- required_values
- Returns:
- record
DimensionRecord
Matching record.
- record
- Raises:
- ValueError
Raised if the data ID did not have the right dimensions.
- intersection(other: DimensionRecordSet) DimensionRecordSet ¶
Return a new set with only records that are in both
self
andother
.- Parameters:
- other
DimensionRecordSet
Another record set with the same record type.
- other
- Returns:
- intersection
DimensionRecordSet
A new record set with all elements in both sets.
- intersection
- isdisjoint(other: DimensionRecordSet) bool ¶
Test whether the intersection of
self
andother
is empty.- Parameters:
- other
DimensionRecordSet
Another record set with the same record type.
- other
- Returns:
- isdisjoint ;
bool
Whether the intersection of
self
andother
is empty.
- isdisjoint ;
- issubset(other: DimensionRecordSet) bool ¶
Test whether all elements in
self
are inother
.- Parameters:
- other
DimensionRecordSet
Another record set with the same record type.
- other
- Returns:
- issubset ;
bool
Whether all elements in
self
are inother
.
- issubset ;
- issuperset(other: DimensionRecordSet) bool ¶
Test whether all elements in
other
are inself
.- Parameters:
- other
DimensionRecordSet
Another record set with the same record type.
- other
- Returns:
- issuperset ;
bool
Whether all elements in
other
are inself
.
- issuperset ;
- pop() DimensionRecord ¶
Remove and return an arbitrary record.
- remove(value: DimensionRecord | DataCoordinate) None ¶
Remove a record.
- Parameters:
- value
DimensionRecord
orDataCoordinate
Record to remove, or its data ID.
- value
- Raises:
- KeyError
Raised if there is no matching record.
- union(other: DimensionRecordSet) DimensionRecordSet ¶
Return a new set with all records that are either in
self
orother
.- Parameters:
- other
DimensionRecordSet
Another record set with the same record type.
- other
- Returns:
- intersection
DimensionRecordSet
A new record set with all elements in either set.
- intersection
- update(values: Iterable[DimensionRecord], replace: bool = True) None ¶
Add new records to the set.
- Parameters:
- values
Iterable
[DimensionRecord
] Records to add.
- replace
bool
, optional If
True
(default) replace any existing records with the same data IDs. IfFalse
the existing records will be kept.
- values
- Raises:
- ValueError
Raised if
value.element != self.element
.
- update_from_data_coordinates(data_coordinates: Iterable[DataCoordinate]) None ¶
Add records to the set by extracting and deduplicating them from data coordinates.
- Parameters:
- data_coordinates
Iterable
[DataCoordinate
] Data coordinates to extract from.
DataCoordinate.hasRecords
must beTrue
.
- data_coordinates