Instrument

class lsst.obs.base.Instrument

Bases: object

Base class for instrument-specific logic for the Gen3 Butler.

Concrete instrument subclasses should be directly constructable with no arguments.

Attributes Summary

additionalCuratedDatasetTypes	Curated dataset types specific to this particular instrument that do not follow the standard organization found in obs data packages.
configPaths	Paths to config files to read for specific Tasks.
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.

Methods Summary

applyConfigOverrides(name, config)	Apply instrument-specific overrides for a task config.
fromName(name, registry)	Given an instrument name and a butler, retrieve a corresponding instantiated instrument object.
getCamera()	Retrieve the cameraGeom representation of this instrument.
getCuratedCalibrationNames()	Return the names of all the curated calibration dataset types.
getName()	Return the short (dimension) name for this instrument.
getObsDataPackageDir()	The root of the obs data package that provides specializations for this instrument.
getRawFormatter(dataId)	Return the Formatter class that should be used to read a particular raw file.
importAll(registry)	Import all the instruments known to this registry.
makeCollectionName(label)	Get the instrument-specific collection string to use as derived from the supplied label.
makeDataIdTranslatorFactory()	Return a factory for creating Gen2->Gen3 data ID translators, specialized for this instrument.
makeDefaultRawIngestRunName()	Make the default instrument-specific run collection string for raw data ingest.
register(registry)	Insert instrument, physical_filter, and detector entries into a Registry.
writeAdditionalCuratedCalibrations(butler[, run])	Write additional curated calibrations that might be instrument specific and are not part of the standard set.
writeCameraGeom(butler[, run])	Write the default camera geometry to the butler repository with an infinite validity range.
writeCuratedCalibrations(butler[, run])	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 = 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)

configPaths = ()

Paths to config files to read for specific Tasks.

The paths in this list should contain files of the form task.py, for each of the Tasks that requires special configuration.

filterDefinitions

FilterDefinitionCollection, defining the filters for this instrument.

obsDataPackage = 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 = None

Instrument specific name to use when locating a policy or configuration file in the file system.

standardCuratedDatasetTypes = frozenset({'defects', 'crosstalk', 'qe_curve'})

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)

Methods Documentation

applyConfigOverrides(name, config)

Apply instrument-specific overrides for a task config.

Parameters:

name : str

Name of the object being configured; typically the _DefaultName of a Task.

config : lsst.pex.config.Config

Config instance to which overrides should be applied.

static fromName(name: str, registry: Registry) → Instrument

Given an instrument name and a butler, retrieve a corresponding instantiated instrument object.

Parameters:

name : str

Name of the instrument (must match the return value of getName).

registry : lsst.daf.butler.Registry

Butler registry to query to find the information.

Returns:

instrument : Instrument

An instance of the relevant Instrument.

Raises:

LookupError

Raised if the instrument is not known to the supplied registry.

ModuleNotFoundError

Raised if the class could not be imported. This could mean that the relevant obs package has not been setup.

TypeError

Raised if the class name retrieved is not a string.

Notes

The instrument must be registered in the corresponding butler.

getCamera()

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() → Set[str]

Return the names of all the curated calibration dataset types.

Returns:

names : set 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 getName()

Return the short (dimension) name for this instrument.

This is not (in general) the same as the class name - it’s what is used as the value of the “instrument” field in data IDs, and is usually an abbreviation of the full name.

classmethod getObsDataPackageDir()

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

Returns:

dir : str

The root of the relevat obs data package.

getRawFormatter(dataId)

Return the Formatter class that should be used to read a particular raw file.

Parameters:

dataId : DataCoordinate

Dimension-based ID for the raw file or files being ingested.

Returns:

formatter : Formatter class

Class to be used that reads the file into an lsst.afw.image.Exposure instance.

static importAll(registry: Registry) → None

Import all the instruments known to this registry.

This will ensure that all metadata translators have been registered.

Parameters:

registry : lsst.daf.butler.Registry

Butler registry to query to find the information.

Notes

It is allowed for a particular instrument class to fail on import. This might simply indicate that a particular obs package has not been setup.

classmethod makeCollectionName(label: str) → str

Get the instrument-specific collection string to use as derived from the supplied label.

Parameters:

label : str

String to be combined with the instrument name to form a collection name.

Returns:

name : str

Collection name to use that includes the instrument name.

makeDataIdTranslatorFactory() → TranslatorFactory

Return a factory for creating Gen2->Gen3 data ID translators, specialized for this instrument.

Derived class implementations should generally call TranslatorFactory.addGenericInstrumentRules with appropriate arguments, but are not required to (and may not be able to if their Gen2 raw data IDs are sufficiently different from the HSC/DECam/CFHT norm).

Returns:

factory : TranslatorFactory.

Factory for Translator objects.

classmethod makeDefaultRawIngestRunName() → str

Make the default instrument-specific run collection string for raw data ingest.

Returns:

coll : str

Run collection name to be used as the default for ingestion of raws.

register(registry)

Insert instrument, physical_filter, and detector entries into a Registry.

writeAdditionalCuratedCalibrations(butler, run=None)

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

Default implementation does nothing.

Parameters:

butler : lsst.daf.butler.Butler

Butler to use to store these calibrations.

run : str, optional

Name of the run to use to override the default run associated with this Butler.

writeCameraGeom(butler, run=None)

Write the default camera geometry to the butler repository with an infinite validity range.

Parameters:

butler : lsst.daf.butler.Butler

Butler to receive these calibration datasets.

run : str, optional

Name of the run to use to override the default run associated with this Butler.

writeCuratedCalibrations(butler, run=None)

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

Parameters:

butler : lsst.daf.butler.Butler

Butler to use to store these calibrations.

run : str

Run to use for this collection of calibrations. If None the collection name is worked out automatically from the instrument name and other metadata.

Notes

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

writeStandardTextCuratedCalibrations(butler, run=None)

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

Parameters:

butler : lsst.daf.butler.Butler

Butler to receive these calibration datasets.

run : str, optional

Name of the run to use to override the default run associated with this Butler.