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:

elementDimensionElement or str, optional

The dimension element that defines the records held by this set. If not a DimensionElement instance, universe must be provided.

recordsIterable [ DimensionRecord ], optional

Dimension records to add to the set.

universeDimensionUniverse, optional

Object that defines all dimensions. Ignored if element is a DimensionElement instance.

Notes

DimensionRecordSet maintains its insertion order (like dict, and unlike set).

DimensionRecordSet implements collections.abc.Collection but not collections.abc.Set because the latter would require interoperability with all other Set implementations rather than just DimensionRecordSet, 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, and DimensionRecordSet does not generally specify which record “wins” when two records with the same data ID interact (e.g. in intersection). The add and update 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

element

Name of the dimension element these records correspond to.

Methods Summary

add(value[, replace])	Add a new record to the set.
deserialize_records(raw_records)	Deserialize records and add them to this set.
difference(other)	Return a new set with only records that are in self and not in other.
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 and other.
isdisjoint(other)	Test whether the intersection of self and other is empty.
issubset(other)	Test whether all elements in self are in other.
issuperset(other)	Test whether all elements in other are in self.
pop()	Remove and return an arbitrary record.
remove(value)	Remove a record.
serialize_records()	Serialize the records to a list.
union(other)	Return a new set with all records that are either in self or other.
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:

valueDimensionRecord

Record to add.

replacebool, optional

If True (default) replace any existing record with the same data ID. If False the existing record will be kept.

Raises:

ValueError

Raised if value.element != self.element.

deserialize_records(raw_records: Iterable[list[Any]]) → None

Deserialize records and add them to this set.

Parameters:

raw_recordsIterable [ list ]

Serialized records, as returned by serialize_records or repeated calls to DimensionRecord.serialize_key_value.

Notes

The caller is responsible for ensuring that the serialized records have the same dimension element as this set, as this cannot be checked. Mismatches will probably result in a (confusing) type-validation error, but are not guaranteed to.

difference(other: DimensionRecordSet) → DimensionRecordSet

Return a new set with only records that are in self and not in other.

Parameters:

otherDimensionRecordSet

Another record set with the same record type.

Returns:

differenceDimensionRecordSet

A new record set with all elements self that are not in other.

discard(value: DimensionRecord | DataCoordinate) → None

Remove a record if it exists.

Parameters:

valueDimensionRecord or DataCoordinate

Record to remove, or its data ID.

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_idDataCoordinate

Data ID to match.

or_addDimensionRecordFactory

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.

Returns:

recordDimensionRecord

Matching 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, ...], 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_valuestuple [ int or str ]

Data ID values to match.

or_addDimensionRecordFactory

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.

Returns:

recordDimensionRecord

Matching 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 and other.

Parameters:

otherDimensionRecordSet

Another record set with the same record type.

Returns:

intersectionDimensionRecordSet

A new record set with all elements in both sets.

isdisjoint(other: DimensionRecordSet) → bool

Test whether the intersection of self and other is empty.

Parameters:

otherDimensionRecordSet

Another record set with the same record type.

Returns:

isdisjoint ; bool

Whether the intersection of self and other is empty.

issubset(other: DimensionRecordSet) → bool

Test whether all elements in self are in other.

Parameters:

otherDimensionRecordSet

Another record set with the same record type.

Returns:

issubset ; bool

Whether all elements in self are in other.

issuperset(other: DimensionRecordSet) → bool

Test whether all elements in other are in self.

Parameters:

otherDimensionRecordSet

Another record set with the same record type.

Returns:

issuperset ; bool

Whether all elements in other are in self.

pop() → DimensionRecord

Remove and return an arbitrary record.

remove(value: DimensionRecord | DataCoordinate) → None

Remove a record.

Parameters:

valueDimensionRecord or DataCoordinate

Record to remove, or its data ID.

Raises:

KeyError

Raised if there is no matching record.

serialize_records() → list[list[Any]]

Serialize the records to a list.

Returns:

raw_recordslist [ list ]

Serialized records, in the form returned by DimensionRecord.serialize_key_value.

Notes

This does not include the dimension element shared by all of the records, on the assumption that this is usually more conveniently saved separately (e.g. as the key of a dictionary of which the list of records is a value).

union(other: DimensionRecordSet) → DimensionRecordSet

Return a new set with all records that are either in self or other.

Parameters:

otherDimensionRecordSet

Another record set with the same record type.

Returns:

intersectionDimensionRecordSet

A new record set with all elements in either set.

update(values: Iterable[DimensionRecord], replace: bool = True) → None

Add new records to the set.

Parameters:

valuesIterable [ DimensionRecord ]

Records to add.

replacebool, optional

If True (default) replace any existing records with the same data IDs. If False the existing records will be kept.

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_coordinatesIterable [ DataCoordinate ]

Data coordinates to extract from. DataCoordinate.hasRecords must be True.