LsstCamPhoSim¶
- class lsst.obs.lsst.LsstCamPhoSim(collection_prefix: str | None = None)¶
Bases:
LsstCam
Gen3 Butler specialization for Phosim simulations.
Attributes Summary
Curated dataset types specific to this particular instrument that do not follow the standard organization found in obs data packages.
Built-in immutable sequence.
Name of the package containing the text curated calibration files.
Instrument specific name to use when locating a policy or configuration file in the file system.
Dataset type definition to use for "raw" datasets.
The dataset types expected to be obtained from the obsDataPackage.
Methods Summary
applyConfigOverrides
(name, config)Apply instrument-specific overrides for a task config.
extractDetectorRecord
(camGeomDetector)Create a Gen3 Detector entry dict from a cameraGeom.Detector.
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_data_id
(data_id[, collection_prefix])Instantiate an
Instrument
object from a fully-expanded data ID.from_string
(name[, registry, collection_prefix])Return an instance from the short name or class name.
Retrieve the cameraGeom representation of this instrument.
Return the names of all the curated calibration dataset types.
getName
()Return the short (dimension) name for this instrument.
Return 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.
group_name_to_group_id
(group_name)Translate the exposure group name to an integer.
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.
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.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.
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.
make_default_dimension_packer
(data_id[, ...])Return the default dimension packer for the given data ID.
Make an
lsst.pex.config.Field
that can be used to configure how data IDs for this instrument are packed.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.
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
ofstr
)
- 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>¶
- instrument = 'LSSTCam-PhoSim'¶
- obsDataPackage: str | None = 'obs_lsst_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 = 'phosim'¶
Instrument specific name to use when locating a policy or configuration file in the file system.
- raw_definition: tuple[str, tuple[str, ...], str] | None = None¶
Dataset type definition to use for “raw” datasets. This is a tuple of the dataset type name, a tuple of dimension names, and the storage class name. If
None
the ingest system will use its default definition.
- standardCuratedDatasetTypes: Set[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
ofstr
)
- visitSystem = 0¶
Methods Documentation
- applyConfigOverrides(name: str, config: Config) None ¶
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.
- name
- extractDetectorRecord(camGeomDetector)¶
Create a Gen3 Detector entry dict from a cameraGeom.Detector.
- static formatCollectionTimestamp(timestamp: str | datetime) str ¶
Format a timestamp for use in a collection name.
- Parameters:
- timestamp
str
ordatetime.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-awaredatetime.datetime
instance (converted to UTC). This is intended to cover all forms that stringCALIBDATE
metadata values have taken in the past, as well as the format this method itself writes out (to enable round-tripping).
- timestamp
- Returns:
- formatted
str
Standardized string form for the timestamp.
- formatted
- classmethod fromName(name: str, registry: Registry, collection_prefix: str | None = None) Self ¶
Given an instrument name and a butler registry, 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.
- collection_prefix
str
, 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.
- name
- Returns:
- instrument
Instrument
An instance of the relevant
Instrument
.
- 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.
- classmethod from_data_id(data_id: DataCoordinate, collection_prefix: str | None = None) Self ¶
Instantiate an
Instrument
object from a fully-expanded data ID.- Parameters:
- data_id
DataCoordinate
Expanded data ID that includes the instrument dimension.
- collection_prefix
str
, 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.
- data_id
- Returns:
- instrument
Instrument
An instance of the relevant
Instrument
.
- instrument
- Raises:
- TypeError
Raised if the class name retrieved is not a string or the imported symbol is not an
Instrument
subclass.
- classmethod from_string(name: str, registry: Registry | None = None, collection_prefix: str | None = None) Self ¶
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:
- name
str
The name or fully-qualified class name of an instrument.
- registry
lsst.daf.butler.Registry
, optional Butler registry to query to find information about the instrument, by default
None
.- collection_prefix
str
, 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.
- name
- Returns:
- instrument
Instrument
The instantiated instrument.
- 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
Constructing Instrument from a name.
- classmethod 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:
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 ¶
Return 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.
- Parameters:
- dataId
DataId
Dimension-based ID for the raw file or files being ingested.
- dataId
- Returns:
- formatter
lsst.daf.butler.Formatter
class Class to be used that reads the file into the correct Python object for the raw data.
- formatter
- classmethod group_name_to_group_id(group_name: str) int ¶
Translate the exposure group name to an integer.
- Parameters:
- group_name
str
The name of the exposure group.
- group_name
- Returns:
- id
int
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.
- id
Notes
If given a group name that can be directly cast to an integer it returns the integer. If the group name looks like an ISO date the ID returned is seconds since an arbitrary recent epoch. Otherwise the group name is hashed and the first 14 digits of the hash is returned along with the length of the group name.
- 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.
- registry
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.
- makeCollectionName(*labels: str) str ¶
Get the instrument-specific collection string to use as derived from the supplied labels.
- static makeCollectionTimestamp() str ¶
Create a timestamp string for use in a collection name from the current time.
- Returns:
- formatted
str
Standardized string form of the current time.
- formatted
- makeCuratedCalibrationRunName(calibDate: str, *labels: str) str ¶
Make a RUN collection name appropriate for inserting curated calibration datasets with the given
CALIBDATE
metadata value.- Parameters:
- Returns:
- name
str
Run collection name.
- name
- 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.
- coll
- 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:
- *labels
str
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.
- *labels
- Returns:
- name
str
Collection name.
- name
Notes
This is a
staticmethod
, not aclassmethod
, 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:
- name
str
Name for the umbrella collection.
- name
- makeUnboundedCalibrationRunName(*labels: str) str ¶
Make a RUN collection name appropriate for inserting calibration datasets whose validity ranges are unbounded.
- static make_default_dimension_packer(data_id: DataCoordinate, is_exposure: bool | None = None) DimensionPacker ¶
Return the default dimension packer for the given data ID.
- Parameters:
- data_id
lsst.daf.butler.DataCoordinate
Data ID that identifies at least the
instrument
dimension. Must have dimension records attached.- is_exposure
bool
, optional If
False
, construct a packer for visit+detector data IDs. IfTrue
, construct a packer for exposure+detector data IDs. IfNone
, this is determined based on whethervisit
orexposure
is present indata_id
, withvisit
checked first and hence used if both are present.
- data_id
- Returns:
- packer
lsst.daf.butler.DimensionPacker
Object that packs {visit, detector} or {exposure, detector} data IDs into integers.
- packer
Notes
When using a dimension packer in task code, using
make_dimension_packer_config_field
to make the packing algorithm configurable is preferred over this method.When obtaining a dimension packer to unpack IDs that were packed by task code, it is similarly preferable to load the configuration for that task and the existing packer configuration field there, to ensure any config overrides are respected. That is sometimes quite difficult, however, and since config overrides for dimension packers are expected to be exceedingly rare, using this simpler method will almost always work.
- static make_dimension_packer_config_field(doc: str = 'How to pack visit+detector or exposure+detector data IDs into integers. The default (None) is to delegate to the Instrument class for which registered implementation to use (but still use the nested configuration for that implementation).') RegistryField ¶
Make an
lsst.pex.config.Field
that can be used to configure how data IDs for this instrument are packed.- Parameters:
- doc
str
, optional Documentation for the config field.
- doc
- Returns:
- field
lsst.pex.config.RegistryField
A config field for which calling
apply
on the instance attribute constructs anlsst.daf.butler.DimensionPacker
that defaults to the appropriate one for this instrument.
- field
Notes
This method is expected to be used whenever code requires a single integer that represents the combination of a detector and either a visit or exposure, but in most cases the
lsst.meas.base.IdGenerator
class and its helper configs provide a simpler high-level interface that should be used instead of calling this method directly.This system is designed to work best when the configuration for the ID packer is not overridden at all, allowing the appropriate instrument class to determine the behavior for each data ID encountered. When the configuration does need to be modified (most often when the scheme for packing an instrument’s data IDs is undergoing an upgrade), it is important to ensure the overrides are only applied to data IDs with the desired instrument value.
Unit tests of code that use a field produced by this method will often want to explicitly set the packer to “observation” and manually set its
n_detectors
andn_observations
fields; this will make it unnecessary for tests to provide expanded data IDs.
- register(registry, update=False)¶
Insert instrument, and other relevant records into
Registry
.- Parameters:
- registry
lsst.daf.butler.Registry
Registry client for the data repository to modify.
- update
bool
, optional If
True
(False
is default), update existing records if they differ from the new ones.
- registry
- 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:
- butler
lsst.daf.butler.Butler
Butler to use to store these calibrations.
- collection
str
, 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. IfNone
, a collection name is worked out automatically from the instrument name and other metadata by callingmakeCalibrationCollectionName
, but this default name may not work well for long-lived repositories unlesslabels
is also provided (and changed every time curated calibrations are ingested).- labels
Sequence
[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 theCALIBRATION
collection if it is generated automatically (i.e. ifcollection is None
). Usually this is just the name of the ticket on which the calibration collection is being created.
- butler
- 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:
- butler
lsst.daf.butler.Butler
Butler to use to store these calibrations.
- collection
str
, 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. IfNone
, a collection name is worked out automatically from the instrument name and other metadata by callingmakeCalibrationCollectionName
, but this default name may not work well for long-lived repositories unlesslabels
is also provided (and changed every time curated calibrations are ingested).- labels
Sequence
[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 theCALIBRATION
collection if it is generated automatically (i.e. ifcollection is None
). Usually this is just the name of the ticket on which the calibration collection is being created.
- butler
- 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:
- butler
lsst.daf.butler.Butler
Butler to use to store these calibrations.
- collection
str
, 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. IfNone
, a collection name is worked out automatically from the instrument name and other metadata by callingmakeCalibrationCollectionName
, but this default name may not work well for long-lived repositories unlesslabels
is also provided (and changed every time curated calibrations are ingested).- labels
Sequence
[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 theCALIBRATION
collection if it is generated automatically (i.e. ifcollection is None
). Usually this is just the name of the ticket on which the calibration collection is being created.
- butler
Notes
Expected to be called from subclasses. The base method calls
writeCameraGeom
,writeStandardTextCuratedCalibrations
, andwriteAdditionalCuratedCalibrations
.
- writeStandardTextCuratedCalibrations(butler: Butler, collection: str | None = None, labels: Sequence[str] = ()) None ¶
Write the set of standardized curated text calibrations to the repository.
- Parameters:
- butler
lsst.daf.butler.Butler
Butler to receive these calibration datasets.
- collection
str
, 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. IfNone
, a collection name is worked out automatically from the instrument name and other metadata by callingmakeCalibrationCollectionName
, but this default name may not work well for long-lived repositories unlesslabels
is also provided (and changed every time curated calibrations are ingested).- labels
Sequence
[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 theCALIBRATION
collection if it is generated automatically (i.e. ifcollection is None
). Usually this is just the name of the ticket on which the calibration collection is being created.
- butler