CollectionSummary#

class lsst.daf.butler.registry.CollectionSummary(dataset_types: ~lsst.daf.butler._named.NamedValueSet[~lsst.daf.butler._dataset_type.DatasetType] = <factory>, governors: dict[str, set[str]] = <factory>)#

Bases: object

A summary of the datasets that can be found in a collection.

Attributes Summary

`dataset_types`	Dataset types that may be present in the collection (`NamedValueSet` [ `DatasetType` ]).
`governors`	Governor data ID values that are present in the collection's dataset data IDs (`dict` [ `str`, `set` [ `str` ] ]).

Methods Summary

`add_data_ids`(dataset_type, data_ids)	Include the given dataset type and data IDs in the summary.
`add_data_ids_generator`(dataset_type, data_ids)	Include the given dataset type and data IDs in the summary, yielding them back as a generator.
`add_datasets`(refs)	Include the given datasets in the summary.
`add_datasets_generator`(refs)	Include the given datasets in the summary, yielding them back as a generator.
`copy`()	Return a deep copy of this object.
`from_simple`(simple, universe)
`is_compatible_with`(dataset_type, dimensions)	Test whether the collection summarized by this object should be queried for a given dataset type and governor dimension values.
`to_simple`()
`union`()	Construct a summary that contains all dataset types and governor dimension values in any of the inputs.
`update`(*args)	Update this summary with dataset types and governor dimension values from other summaries.

Attributes Documentation

dataset_types: NamedValueSet[DatasetType] = <dataclasses._MISSING_TYPE object>#

Dataset types that may be present in the collection (NamedValueSet [ DatasetType ]).

A dataset type not in this set is definitely not in the collection, but the converse is not necessarily true.

governors: dict[str, set[str]] = <dataclasses._MISSING_TYPE object>#

Governor data ID values that are present in the collection’s dataset data IDs (dict [ str, set [ str ] ]).

A data ID value not in this restriction is not necessarily inconsistent with a query in the collection; such a search may only involve dataset types that do not include one or more governor dimensions in their data IDs, and hence the values of those data IDs are unconstrained by this collection in the query.

Methods Documentation

add_data_ids(dataset_type: DatasetType, data_ids: Iterable[DataCoordinate]) → None#

Include the given dataset type and data IDs in the summary.

Parameters#

dataset_typeDatasetType: Dataset type to include.
data_idsIterable [ DataCoordinate ]: Data IDs to include.

add_data_ids_generator(dataset_type: DatasetType, data_ids: Iterable[DataCoordinate]) → Generator[DataCoordinate, None, None]#

Include the given dataset type and data IDs in the summary, yielding them back as a generator.

Parameters#

dataset_typeDatasetType: Dataset type to include.
data_idsIterable [ DataCoordinate ]: Data IDs to include.

Yields#

data_idDataCoordinate: The same data IDs originally passed in.

Notes#

As a generator, this method does nothing if its return iterator is not used. Call add_data_ids instead to avoid this; this method is intended for the case where the given iterable may be single-pass and a copy is not desired, but other processing needs to be done on its elements.

add_datasets(refs: Iterable[DatasetRef]) → None#

Include the given datasets in the summary.

Parameters#

refsIterable [ DatasetRef ]: Datasets to include.

add_datasets_generator(refs: Iterable[DatasetRef]) → Generator[DatasetRef, None, None]#

Include the given datasets in the summary, yielding them back as a generator.

Parameters#

refsIterable [ DatasetRef ]: Datasets to include.

Yields#

refDatasetRef: The same dataset references originally passed in.

Notes#

As a generator, this method does nothing if its return iterator is not used. Call add_datasets instead to avoid this; this method is intended for the case where the given iterable may be single-pass and a copy is not desired, but other processing needs to be done on its elements.

copy() → CollectionSummary#

Return a deep copy of this object.

Returns#

copyCollectionSummary: A copy of self that can be modified without modifying self at all.

static from_simple(simple: SerializedCollectionSummary, universe: DimensionUniverse) → CollectionSummary#

is_compatible_with(dataset_type: DatasetType, dimensions: Mapping[str, Set[str]], rejections: list[str] | None = None, name: str | None = None) → bool#

Test whether the collection summarized by this object should be queried for a given dataset type and governor dimension values.

Parameters#

dataset_typeDatasetType: Dataset type being queried. If this collection has no instances of this dataset type (or its parent dataset type, if it is a component), False will always be returned.
dimensionsMapping: Bounds on the values governor dimensions can take in the query, usually from a WHERE expression, as a mapping from dimension name to a set of str governor dimension values.
rejectionslist [ str ], optional: If provided, a list that will be populated with a log- or exception-friendly message explaining why this dataset is incompatible with this collection when False is returned.
namestr, optional: Name of the collection this object summarizes, for use in messages appended to rejections. Ignored if rejections is None.

Returns#

compatiblebool: True if the dataset query described by this summary and the given arguments might yield non-empty results; False if the result from such a query is definitely empty.

to_simple() → SerializedCollectionSummary#

union() → CollectionSummary#

Construct a summary that contains all dataset types and governor dimension values in any of the inputs.

Parameters#

*argsCollectionSummary: Summaries to combine.

Returns#

unionedCollectionSummary: New summary object that represents the union of the given ones.

update(*args: CollectionSummary) → None#

Update this summary with dataset types and governor dimension values from other summaries.

Parameters#

*argsCollectionSummary: Summaries to include in self.