Instrument#

class lsst.obs.base.Instrument(collection_prefix: str | None = None)#

Bases: Instrument

Rubin-specified base for instrument-specific logic for the Gen3 Butler.

Parameters#

collection_prefixstr, optional: Prefix for collection names to use instead of the instrument’s own name. This is primarily for use in simulated-data repositories, where the instrument name may not be necessary and/or sufficient to distinguish between collections.

Notes#

Concrete instrument subclasses must have the same construction signature as the base class.

Attributes Summary

`additionalCuratedDatasetTypes`	Curated dataset types specific to this particular instrument that do not follow the standard organization found in obs data packages.
`filterDefinitions`	`FilterDefinitionCollection`, defining the filters for this instrument.
`obsDataPackage`	Name of the package containing the text curated calibration files.
`policyName`	Instrument specific name to use when locating a policy or configuration file in the file system.
`standardCuratedDatasetTypes`	The dataset types expected to be obtained from the obsDataPackage.
`translatorClass`	Class to use when extracting information from metadata.

Methods Summary

`getCamera`()	Retrieve the cameraGeom representation of this instrument.
`getCuratedCalibrationNames`()	Return the names of all the curated calibration dataset types.
`getObsDataPackageDir`()	Return the root of the obs data package that provides specializations for this instrument.
`get_curated_calibration_labels`()	Return appropriate labels (pieces of a collection name) for a collection populated by `writeCuratedCalibrations`.
`group_name_to_group_id`(group_name)	Translate the exposure group name to an integer.
`writeAdditionalCuratedCalibrations`(butler[, ...])	Write additional curated calibrations that might be instrument specific and are not part of the standard set.
`writeCameraGeom`(butler[, collection, labels])	Write the default camera geometry to the butler repository and associate it with the appropriate validity range in a calibration collection.
`writeCuratedCalibrations`(butler[, ...])	Write human-curated calibration Datasets to the given Butler with the appropriate validity ranges.
`writeStandardTextCuratedCalibrations`(butler)	Write the set of standardized curated text calibrations to the repository.

Attributes Documentation

additionalCuratedDatasetTypes: Set[str] = frozenset({})#

Curated dataset types specific to this particular instrument that do not follow the standard organization found in obs data packages.

These are the instrument-specific dataset types written by writeAdditionalCuratedCalibrations in addition to the calibrations found in obs data packages that follow the standard scheme. (set of str)

filterDefinitions#: FilterDefinitionCollection, defining the filters for this instrument.

obsDataPackage: str | None = None#: Name of the package containing the text curated calibration files. Usually a obs _data package. If None no curated calibration files will be read. (str)

policyName: str | None = None#: Instrument specific name to use when locating a policy or configuration file in the file system.

standardCuratedDatasetTypes: Set[str] = frozenset({'bfk', 'crosstalk', 'defects', 'linearizer', 'manual_defects', 'qe_curve', 'transmission_atmosphere', 'transmission_filter', 'transmission_filter_detector', 'transmission_optics', 'transmission_sensor', 'transmission_system'})#

The dataset types expected to be obtained from the obsDataPackage.

These dataset types are all required to have standard definitions and must be known to the base class. Clearing this list will prevent any of these calibrations from being stored. If a dataset type is not known to a specific instrument it can still be included in this list since the data package is the source of truth. (set of str)

translatorClass: MetadataTranslator | None = None#: Class to use when extracting information from metadata. If None the metadata extraction system will determine the translator class itself. This class can also be used to calculate the observing day offset in some scenarios.

Methods Documentation

abstract getCamera() → Camera#

Retrieve the cameraGeom representation of this instrument.

This is a temporary API that should go away once obs packages have a standardized approach to writing versioned cameras to a Gen3 repo.

classmethod getCuratedCalibrationNames() → frozenset[str]#

Return the names of all the curated calibration dataset types.

Returns#

namesfrozenset of str: The dataset type names of all curated calibrations. This will include the standard curated calibrations even if the particular instrument does not support them.

Notes#

The returned list does not indicate whether a particular dataset is present in the Butler repository, simply that these are the dataset types that are handled by writeCuratedCalibrations.

classmethod getObsDataPackageDir() → str | None#

Return the root of the obs data package that provides specializations for this instrument.

Returns#

dirstr or None: The root of the relevant obs data package, or None if this instrument does not have one.

get_curated_calibration_labels() → list[str]#

Return appropriate labels (pieces of a collection name) for a collection populated by writeCuratedCalibrations.

If this returns an empty list (as the default implementation does), the user will be required to provide a label.

classmethod group_name_to_group_id(group_name: str) → int#

Translate the exposure group name to an integer.

Parameters#

group_namestr: The name of the exposure group.

Returns#

idint: The exposure group name in integer form. This integer might be used as an ID to uniquely identify the group in contexts where a string can not be used.

Notes#

The default implementation removes all non numeric characters and casts to an integer.

writeAdditionalCuratedCalibrations(butler: Butler, collection: str | None = None, labels: Sequence[str] = ()) → None#

Write additional curated calibrations that might be instrument specific and are not part of the standard set.

Default implementation does nothing.

Parameters#

butlerlsst.daf.butler.Butler: Butler to use to store these calibrations.
collectionstr, optional: Name to use for the calibration collection that associates all datasets with a validity range. If this collection already exists, it must be a CALIBRATION collection, and it must not have any datasets that would conflict with those inserted by this method. If None, a collection name is worked out automatically from the instrument name and other metadata by calling makeCalibrationCollectionName, but this default name may not work well for long-lived repositories unless labels is also provided (and changed every time curated calibrations are ingested).
labelsSequence [ str ], optional: Extra strings to include in collection names, after concatenating them with the standard collection name delimiter. If provided, these are inserted into the names of the RUN collections that datasets are inserted directly into, as well the CALIBRATION collection if it is generated automatically (i.e. if collection is None). Usually this is just the name of the ticket on which the calibration collection is being created.

writeCameraGeom(butler: Butler, collection: str | None = None, labels: Sequence[str] = ()) → None#

Write the default camera geometry to the butler repository and associate it with the appropriate validity range in a calibration collection.

Parameters#

butlerlsst.daf.butler.Butler: Butler to use to store these calibrations.
collectionstr, optional: Name to use for the calibration collection that associates all datasets with a validity range. If this collection already exists, it must be a CALIBRATION collection, and it must not have any datasets that would conflict with those inserted by this method. If None, a collection name is worked out automatically from the instrument name and other metadata by calling makeCalibrationCollectionName, but this default name may not work well for long-lived repositories unless labels is also provided (and changed every time curated calibrations are ingested).
labelsSequence [ str ], optional: Extra strings to include in collection names, after concatenating them with the standard collection name delimiter. If provided, these are inserted into the names of the RUN collections that datasets are inserted directly into, as well the CALIBRATION collection if it is generated automatically (i.e. if collection is None). Usually this is just the name of the ticket on which the calibration collection is being created.

writeCuratedCalibrations(butler: Butler, collection: str | None = None, labels: Sequence[str] = ()) → None#

Write human-curated calibration Datasets to the given Butler with the appropriate validity ranges.

Parameters#

butlerlsst.daf.butler.Butler: Butler to use to store these calibrations.
collectionstr, optional: Name to use for the calibration collection that associates all datasets with a validity range. If this collection already exists, it must be a CALIBRATION collection, and it must not have any datasets that would conflict with those inserted by this method. If None, a collection name is worked out automatically from the instrument name and other metadata by calling makeCalibrationCollectionName, but this default name may not work well for long-lived repositories unless labels is also provided (and changed every time curated calibrations are ingested).
labelsSequence [ str ], optional: Extra strings to include in collection names, after concatenating them with the standard collection name delimiter. If provided, these are inserted into the names of the RUN collections that datasets are inserted directly into, as well the CALIBRATION collection if it is generated automatically (i.e. if collection is None). Usually this is just the name of the ticket on which the calibration collection is being created.

Notes#

Expected to be called from subclasses. The base method calls writeCameraGeom, writeStandardTextCuratedCalibrations, and writeAdditionalCuratedCalibrations.

writeStandardTextCuratedCalibrations(butler: Butler, collection: str | None = None, labels: Sequence[str] = ()) → None#

Write the set of standardized curated text calibrations to the repository.

Parameters#

butlerlsst.daf.butler.Butler: Butler to receive these calibration datasets.
collectionstr, optional: Name to use for the calibration collection that associates all datasets with a validity range. If this collection already exists, it must be a CALIBRATION collection, and it must not have any datasets that would conflict with those inserted by this method. If None, a collection name is worked out automatically from the instrument name and other metadata by calling makeCalibrationCollectionName, but this default name may not work well for long-lived repositories unless labels is also provided (and changed every time curated calibrations are ingested).
labelsSequence [ str ], optional: Extra strings to include in collection names, after concatenating them with the standard collection name delimiter. If provided, these are inserted into the names of the RUN collections that datasets are inserted directly into, as well the CALIBRATION collection if it is generated automatically (i.e. if collection is None). Usually this is just the name of the ticket on which the calibration collection is being created.