DarkEnergyCamera

class lsst.obs.decam.DarkEnergyCamera(**kwargs)

Bases: Instrument

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
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.
formatCollectionTimestamp(timestamp)	Format a timestamp for use in a collection name.
fromName(name, registry[, collection_prefix])	Given an instrument name and a butler registry, retrieve a corresponding instantiated instrument object.
from_string(name[, registry, collection_prefix])	Return an instance from the short name or class name.
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.
makeCalibrationCollectionName(*labels)	Make a CALIBRATION collection name appropriate for associating calibration datasets with validity ranges.
makeCollectionName(*labels)	Get the instrument-specific collection string to use as derived from the supplied labels.
makeCollectionTimestamp()	Create a timestamp string for use in a collection name from the current time.
makeCuratedCalibrationRunName(calibDate, *labels)	Make a RUN collection name appropriate for inserting curated calibration datasets with the given CALIBDATE metadata value.
makeDefaultRawIngestRunName()	Make the default instrument-specific run collection string for raw data ingest.
makeRefCatCollectionName(*labels)	Return a global (not instrument-specific) name for a collection that holds reference catalogs.
makeUmbrellaCollectionName()	Return the name of the umbrella CHAINED collection for this instrument that combines all standard recommended input collections.
makeUnboundedCalibrationRunName(*labels)	Make a RUN collection name appropriate for inserting calibration datasets whose validity ranges are unbounded.
register(registry[, update])	Insert instrument, and other relevant records into Registry.
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: AbstractSet[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)

configPaths: Sequence[str] = ()

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 = <lsst.obs.base.filters.FilterDefinitionCollection object>

obsDataPackage: str | None = 'obs_decam_data'

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 = 'decam'

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

standardCuratedDatasetTypes: AbstractSet[str] = frozenset({'bfk', 'crosstalk', 'defects', 'linearizer', 'qe_curve', 'transmission_atmosphere', 'transmission_filter', '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)

Methods Documentation

applyConfigOverrides(name: str, config: Config) → None

Apply instrument-specific overrides for a task config.

Parameters:

namestr

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

configlsst.pex.config.Config

Config instance to which overrides should be applied.

static formatCollectionTimestamp(timestamp: str | datetime) → str

Format a timestamp for use in a collection name.

Parameters:

timestampstr or datetime.datetime

Timestamp to format. May be a date or datetime string in extended ISO format (assumed UTC), with or without a timezone specifier, a datetime string in basic ISO format with a timezone specifier, a naive datetime.datetime instance (assumed UTC) or a timezone-aware datetime.datetime instance (converted to UTC). This is intended to cover all forms that string CALIBDATE metadata values have taken in the past, as well as the format this method itself writes out (to enable round-tripping).

Returns:

formattedstr

Standardized string form for the timestamp.

static fromName(name: str, registry: Registry, collection_prefix: str | None = None) → Instrument

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

Parameters:

namestr

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

registrylsst.daf.butler.Registry

Butler registry to query to find the information.

collection_prefixstr, optional

Prefix for collection names to use instead of the intrument’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.

Returns:

instrumentInstrument

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 or the imported symbol is not an Instrument subclass.

Notes

The instrument must be registered in the corresponding butler.

static from_string(name: str, registry: Registry | None = None, collection_prefix: str | None = None) → Instrument

Return an instance from the short name or class name.

If the instrument name is not qualified (does not contain a ‘.’) and a butler registry is provided, this will attempt to load the instrument using Instrument.fromName(). Otherwise the instrument will be imported and instantiated.

Parameters:

namestr

The name or fully-qualified class name of an instrument.

registrylsst.daf.butler.Registry, optional

Butler registry to query to find information about the instrument, by default None.

collection_prefixstr, optional

Prefix for collection names to use instead of the intrument’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.

Returns:

instrumentInstrument

The instantiated instrument.

Raises:

RuntimeError

Raised if the instrument can not be imported, instantiated, or obtained from the registry.

TypeError

Raised if the instrument is not a subclass of Instrument.

See also

Instrument.fromName

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() → 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 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() → str | None

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.

getRawFormatter(dataId)

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

Parameters:

dataIdDataId

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

Returns:

formatterlsst.daf.butler.Formatter class

Class to be used that reads the file into the correct Python object for the raw data.

static importAll(registry: Registry) → None

Import all the instruments known to this registry.

This will ensure that all metadata translators have been registered.

Parameters:

registrylsst.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.

makeCalibrationCollectionName(*labels: str) → str

Make a CALIBRATION collection name appropriate for associating calibration datasets with validity ranges.

Parameters:

*labelsstr

Strings to be appended to the base name, using the default delimiter for collection names. Usually this is the name of the ticket on which the calibration collection is being created.

Returns:

namestr

Calibration collection name.

makeCollectionName(*labels: str) → str

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

Parameters:

*labelsstr

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

Returns:

namestr

Collection name to use that includes the instrument’s recommended prefix.

static makeCollectionTimestamp() → str

Create a timestamp string for use in a collection name from the current time.

Returns:

formattedstr

Standardized string form of the current time.

makeCuratedCalibrationRunName(calibDate: str, *labels: str) → str

Make a RUN collection name appropriate for inserting curated calibration datasets with the given CALIBDATE metadata value.

Parameters:

calibDatestr

The CALIBDATE metadata value.

*labelsstr

Strings to be included in the collection name (before calibDate, but after all other terms), using the default delimiter for collection names. Usually this is the name of the ticket on which the calibration collection is being created.

Returns:

namestr

Run collection name.

makeDefaultRawIngestRunName() → str

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

Returns:

collstr

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

static makeRefCatCollectionName(*labels: str) → str

Return a global (not instrument-specific) name for a collection that holds reference catalogs.

With no arguments, this returns the name of the collection that holds all reference catalogs (usually a CHAINED collection, at least in long-lived repos that may contain more than one reference catalog).

Parameters:

*labelsstr

Strings to be added to the global collection name, in order to define a collection name for one or more reference catalogs being ingested at the same time.

Returns:

namestr

Collection name.

Notes

This is a staticmethod, not a classmethod, because it should be the same for all instruments.

makeUmbrellaCollectionName() → str

Return the name of the umbrella CHAINED collection for this instrument that combines all standard recommended input collections.

This method should almost never be overridden by derived classes.

Returns:

namestr

Name for the umbrella collection.

makeUnboundedCalibrationRunName(*labels: str) → str

Make a RUN collection name appropriate for inserting calibration datasets whose validity ranges are unbounded.

Parameters:

*labelsstr

Extra strings to be included in the base name, using the default delimiter for collection names. Usually this is the name of the ticket on which the calibration collection is being created.

Returns:

namestr

Run collection name.

register(registry, update=False)

Insert instrument, and other relevant records into Registry.

Parameters:

registrylsst.daf.butler.Registry

Registry client for the data repository to modify.

updatebool, optional

If True (False is default), update existing records if they differ from the new ones.

Raises:

lsst.daf.butler.registry.ConflictingDefinitionError

Raised if any existing record has the same key but a different definition as one being registered.

Notes

New records can always be added by calling this method multiple times, as long as no existing records have changed (if existing records have changed, update=True must be used). Old records can never be removed by this method.

Implementations should guarantee that registration is atomic (the registry should not be modified if any error occurs) and idempotent at the level of individual dimension entries; new detectors and filters should be added, but changes to any existing record should not be. This can generally be achieved via a block like

with registry.transaction():
    registry.syncDimensionData("instrument", ...)
    registry.syncDimensionData("detector", ...)
    self.registerFilters(registry)

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 delimeter. 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 delimeter. 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 delimeter. 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 writeAdditionalCuratdCalibrations.

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 delimeter. 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.