LsstComCamTranslator

class lsst.obs.lsst.translators.LsstComCamTranslator(header, filename=None)

Bases: lsst.obs.lsst.translators.LsstCamTranslator

Metadata translation for the LSST Commissioning Camera.

Attributes Summary

DETECTOR_MAX	Maximum number of detectors to use when calculating the detector_exposure_id.
cameraPolicyFile	Path to policy file relative to obs_lsst root.
default_resource_package	Module name to use to locate the correction resources.
default_resource_root	Default package resource path root to use to locate header correction files within the default_resource_package package.
default_search_path	Default search path to use to locate header correction files.
detectorMapping	Mapping of detector name to detector number and serial.
detectorSerials	Mapping of detector serial number to raft, number, and name.
name	Name of this translation class
supported_instrument	Supports the lsstCam instrument.
translators	All registered metadata translation classes.

Methods Summary

are_keys_ok(keywords)	Are the supplied keys all present and defined?
can_translate(header[, filename])	Indicate whether this translation class can translate the supplied header.
can_translate_with_options(header, options)	Helper method for can_translate allowing options.
cards_used()	Cards used during metadata extraction.
compute_detector_exposure_id(exposure_id, …)	Compute the detector exposure ID from detector number and exposure ID.
compute_detector_info_from_serial(…)	Helper method to return the detector information from the serial.
compute_detector_num_from_name(…)	Helper method to return the detector number from the name.
compute_exposure_id(dayobs, seqnum[, controller])	Helper method to calculate the exposure_id.
defined_in_this_class(name)	Report if the specified class attribute is defined specifically in this class.
detector_mapping()	Returns the mapping of full name to detector ID and serial.
detector_serials()	Obtain the mapping of detector serial to detector group, name, and number.
determine_translatable_headers(filename[, …])	Given a file return all the headers usable for metadata translation.
determine_translator(header[, filename])	Determine a translation class by examining the header
fix_header(header, instrument, obsid[, filename])	Fix ComCam headers.
is_key_ok(keyword)	Return True if the value associated with the named keyword is present in this header and defined.
is_keyword_defined(header, keyword)	Return True if the value associated with the named keyword is present in the supplied header and defined.
is_on_sky()	Determine if this is an on-sky observation.
max_detector_exposure_id()	The maximum detector exposure ID expected to be generated by this instrument.
max_exposure_id()	The maximum exposure ID expected from this instrument.
quantity_from_card(keywords, unit[, …])	Calculate a Astropy Quantity from a header card and a unit.
resource_root()	Package resource to use to locate correction resources within an installed package.
search_paths()	Search paths to use for LSST data when looking for header correction files.
to_altaz_begin()	Telescope boresight azimuth and elevation at start of observation.
to_boresight_airmass()	Calculate airmass at boresight at start of observation.
to_boresight_rotation_angle()	Angle of the instrument in boresight_rotation_coord frame.
to_boresight_rotation_coord()	Boresight rotation angle.
to_dark_time()	Calculate the dark time.
to_datetime_begin()	Calculate start time of observation.
to_datetime_end()	Calculate end time of observation.
to_detector_exposure_id()	Return value of detector_exposure_id from headers.
to_detector_group()	Collection name of which this detector is a part.
to_detector_name()	Name of the detector within the instrument (might not be unique if there are detector groups).
to_detector_num()	Return value of detector_num from headers.
to_detector_serial()	Serial number/string associated with this detector.
to_detector_unique_name()	Return a unique name for the detector.
to_exposure_group()	Calculate the exposure group string.
to_exposure_id()	Generate a unique exposure ID number
to_exposure_time()	Duration of the exposure with shutter open (seconds).
to_instrument()	The instrument used to observe the exposure.
to_location()	Calculate the observatory location.
to_object()	Object of interest or field name.
to_observation_counter()	Return the sequence number within the observing day.
to_observation_id()	Label uniquely identifying this observation (can be related to ‘exposure_id’).
to_observation_reason()	Return the reason this observation was taken.
to_observation_type()	Return value of observation_type from headers.
to_observing_day()	Return the day of observation as YYYYMMDD integer.
to_physical_filter()	Calculate the physical filter name.
to_pressure()	Atmospheric pressure outside the dome.
to_relative_humidity()	Relative humidity outside the dome.
to_science_program()	Observing program (survey or proposal) identifier.
to_telescope()	Full name of the telescope.
to_temperature()	Temperature outside the dome.
to_tracking_radec()	Return value of tracking_radec from headers.
to_visit_id()	Calculate the visit associated with this exposure.
translator_version()	Return the version string for this translator class.
validate_value(value, default[, minimum, …])	Validate the supplied value, returning a new value if out of range

Attributes Documentation

DETECTOR_MAX = 1000

Maximum number of detectors to use when calculating the detector_exposure_id.

Note that because this is the maximum number of detectors, for zero-based detector_num values this is one greater than the maximum detector_num. It is also often rounded up to the nearest power of 10 anyway, to allow detector_exposure_id values to be easily decoded by humans.

cameraPolicyFile = 'policy/comCam.yaml'

Path to policy file relative to obs_lsst root.

default_resource_package = 'astro_metadata_translator'

Module name to use to locate the correction resources.

default_resource_root = None

Default package resource path root to use to locate header correction files within the default_resource_package package.

default_search_path = None

Default search path to use to locate header correction files.

detectorMapping = None

Mapping of detector name to detector number and serial.

detectorSerials = None

Mapping of detector serial number to raft, number, and name.

name = 'LSSTComCam'

Name of this translation class

supported_instrument = 'LSSTCam'

Supports the lsstCam instrument.

translators = {'DECam': <class 'astro_metadata_translator.translators.decam.DecamTranslator'>, 'HSC': <class 'astro_metadata_translator.translators.hsc.HscTranslator'>, 'LSST-TS3': <class 'lsst.obs.lsst.translators.ts3.LsstTS3Translator'>, 'LSST-TS8': <class 'lsst.obs.lsst.translators.ts8.LsstTS8Translator'>, 'LSST-UCDCam': <class 'lsst.obs.lsst.translators.lsst_ucdcam.LsstUCDCamTranslator'>, 'LSSTCam': <class 'lsst.obs.lsst.translators.lsstCam.LsstCamTranslator'>, 'LSSTCam-PhoSim': <class 'lsst.obs.lsst.translators.phosim.LsstCamPhoSimTranslator'>, 'LSSTCam-imSim': <class 'lsst.obs.lsst.translators.imsim.LsstCamImSimTranslator'>, 'LSSTComCam': <class 'lsst.obs.lsst.translators.comCam.LsstComCamTranslator'>, 'LSST_LATISS': <class 'lsst.obs.lsst.translators.latiss.LatissTranslator'>, 'MegaPrime': <class 'astro_metadata_translator.translators.megaprime.MegaPrimeTranslator'>, 'SDSS': <class 'astro_metadata_translator.translators.sdss.SdssTranslator'>, 'SuprimeCam': <class 'astro_metadata_translator.translators.suprimecam.SuprimeCamTranslator'>}

All registered metadata translation classes.

Methods Documentation

are_keys_ok(keywords)

Are the supplied keys all present and defined?

Parameters

keywordsiterable of str

Keywords to test.

Returns

all_okbool

True if all supplied keys are present and defined.

classmethod can_translate(header, filename=None)

Indicate whether this translation class can translate the supplied header.

Looks for “COMCAM” instrument in case-insensitive manner but must be on LSST telescope. This avoids confusion with other telescopes using commissioning cameras.

Parameters

headerdict-like

Header to convert to standardized form.

filenamestr, optional

Name of file being translated.

Returns

canbool

True if the header is recognized by this class. False otherwise.

classmethod can_translate_with_options(header, options, filename=None)

Helper method for can_translate allowing options.

Parameters

headerdict-like

Header to convert to standardized form.

optionsdict

Headers to try to determine whether this header can be translated by this class. If a card is found it will be compared with the expected value and will return that comparison. Each card will be tried in turn until one is found.

filenamestr, optional

Name of file being translated.

Returns

canbool

True if the header is recognized by this class. False otherwise.

Notes

Intended to be used from within can_translate implementations for specific translators. Is not intended to be called directly from determine_translator.

cards_used()

Cards used during metadata extraction.

Returns

usedfrozenset of str

Cards used when extracting metadata.

classmethod compute_detector_exposure_id(exposure_id, detector_num)

Compute the detector exposure ID from detector number and exposure ID.

This is a helper method to allow code working outside the translator infrastructure to use the same algorithm.

Parameters

exposure_idint

Unique exposure ID.

detector_numint

Detector number.

Returns

detector_exposure_idint

The calculated ID.

classmethod compute_detector_info_from_serial(detector_serial)

Helper method to return the detector information from the serial.

Parameters

detector_serialstr

Detector serial ID.

Returns

infotuple of (str, str, int)

Detector group, name, and number.

classmethod compute_detector_num_from_name(detector_group, detector_name)

Helper method to return the detector number from the name.

Parameters

detector_groupstr

Name of the detector grouping. This is generally the raft name.

detector_namestr

Detector name.

Returns

numint

Detector number.

static compute_exposure_id(dayobs, seqnum, controller=None)

Helper method to calculate the exposure_id.

Parameters

dayobsstr

Day of observation in either YYYYMMDD or YYYY-MM-DD format. If the string looks like ISO format it will be truncated before the T before being handled.

seqnumint or str

Sequence number.

controllerstr, optional

Controller to use. If this is “O”, no change is made to the exposure ID. If it is “C” a 1000 is added to the year component of the exposure ID. If it is “H” a 2000 is added to the year component. None indicates that the controller is not relevant to the exposure ID calculation (generally this is the case for test stand data).

Returns

exposure_idint

Exposure ID in form YYYYMMDDnnnnn form.

classmethod defined_in_this_class(name)

Report if the specified class attribute is defined specifically in this class.

Parameters

namestr

Name of the attribute to test.

Returns

in_classbool

True if there is a attribute of that name defined in this specific subclass. False if the method is not defined in this specific subclass but is defined in a parent class. Returns None if the attribute is not defined anywhere in the class hierarchy (which can happen if translators have typos in their mapping tables).

Notes

Retrieves the attribute associated with the given name. Then looks in all the parent classes to determine whether that attribute comes from a parent class or from the current class. Attributes are compared using id().

classmethod detector_mapping()

Returns the mapping of full name to detector ID and serial.

Returns

mappingdict of str:tuple

Returns the mapping of full detector name (group+detector) to detector number and serial.

Raises

ValueError

Raised if no camera policy file has been registered with this translation class.

Notes

Will construct the mapping if none has previously been constructed.

classmethod detector_serials()

Obtain the mapping of detector serial to detector group, name, and number.

Returns

infodict of tuple of (str, str, int)

A dict with the serial numbers as keys and values of detector group, name, and number.

classmethod determine_translatable_headers(filename, primary=None)

Given a file return all the headers usable for metadata translation.

This method can optionally be given a header from the file. This header will generally be the primary header or a merge of the first two headers.

In the base class implementation it is assumed that this supplied header is the only useful header for metadata translation and it will be returned unchanged if given. This can avoid unnecesarily re-opening the file and re-reading the header when the content is already known.

If no header is supplied, a header will be read from the supplied file using read_basic_metadata_from_file, allowing it to merge the primary and secondary header of a multi-extension FITS file. Subclasses can read the header from the data file using whatever technique is best for that instrument.

Subclasses can return multiple headers and ignore the externally supplied header. They can also merge it with another header and return a new derived header if that is required by the particular data file. There is no requirement for the supplied header to be used.

Parameters

filenamestr

Path to a file in a format understood by this translator.

primarydict-like, optional

The primary header obtained by the caller. This is sometimes already known, for example if a system is trying to bootstrap without already knowing what data is in the file. For many instruments where the primary header is the only relevant header, the primary header will be returned with no further action.

Yields

headersiterator of dict-like

A header usable for metadata translation. For this base implementation it will be either the supplied primary header or a header read from the file. This implementation will only ever yield a single header.

Notes

Each translator class can have code specifically tailored to its own file format. It is important not to call this method with an incorrect translator class. The normal paradigm is for the caller to have read the first header and then called determine_translator() on the result to work out which translator class to then call to obtain the real headers to be used for translation.

classmethod determine_translator(header, filename=None)

Determine a translation class by examining the header

Parameters

headerdict-like

Representation of a header.

filenamestr, optional

Name of file being translated.

Returns

translatorMetadataTranslator

Translation class that knows how to extract metadata from the supplied header.

Raises

ValueError

None of the registered translation classes understood the supplied header.

classmethod fix_header(header, instrument, obsid, filename=None)

Fix ComCam headers.

Notes

Fixes the following issues:

• If LSST_NUM is missing it is filled in by looking at the CCDSLOT value and assuming that the ComCam detectors are fixed.

Corrections are reported as debug level log messages.

See fix_header for details of the general process.

is_key_ok(keyword)

Return True if the value associated with the named keyword is present in this header and defined.

Parameters

keywordstr

Keyword to check against header.

Returns

is_okbool

True if the header is present and not-None. False otherwise.

static is_keyword_defined(header, keyword)

Return True if the value associated with the named keyword is present in the supplied header and defined.

Parameters

headerdict-lik

Header to use as reference.

keywordstr

Keyword to check against header.

Returns

is_definedbool

True if the header is present and not-None. False otherwise.

is_on_sky()

Determine if this is an on-sky observation.

Returns

is_on_skybool

Returns True if this is a observation on sky on the summit.

classmethod max_detector_exposure_id()

The maximum detector exposure ID expected to be generated by this instrument.

Returns

max_idint

The maximum value.

classmethod max_exposure_id()

The maximum exposure ID expected from this instrument.

Returns

max_exposure_idint

The maximum value.

quantity_from_card(keywords, unit, default=None, minimum=None, maximum=None, checker=None)

Calculate a Astropy Quantity from a header card and a unit.

Parameters

keywordsstr or list of str

Keyword to use from header. If a list each keyword will be tried in turn until one matches.

unitastropy.units.UnitBase

Unit of the item in the header.

defaultfloat, optional

Default value to use if the header value is invalid. Assumed to be in the same units as the value expected in the header. If None, no default value is used.

minimumfloat, optional

Minimum possible valid value, optional. If the calculated value is below this value, the default value will be used.

maximumfloat, optional

Maximum possible valid value, optional. If the calculated value is above this value, the default value will be used.

checkerfunction, optional

Callback function to be used by the translator method in case the keyword is not present. Function will be executed as if it is a method of the translator class. Running without raising an exception will allow the default to be used. Should usually raise KeyError.

Returns

qastropy.units.Quantity

Quantity representing the header value.

Raises

KeyError

The supplied header key is not present.

resource_root()

Package resource to use to locate correction resources within an installed package.

Returns

resource_packagestr

Package resource name. None if no package resource are to be used.

resource_rootstr

The name of the resource root. None if no package resources are to be used.

search_paths()

Search paths to use for LSST data when looking for header correction files.

Returns

pathlist

List with a single element containing the full path to the corrections directory within the obs_lsst package.

to_altaz_begin()

Telescope boresight azimuth and elevation at start of observation.

Returns

translationastropy.coordinates.AltAz

Translated property.

to_boresight_airmass()

Calculate airmass at boresight at start of observation.

Notes

Early data are missing AMSTART header so we fall back to calculating it from ELSTART.

to_boresight_rotation_angle()

Angle of the instrument in boresight_rotation_coord frame.

Returns

translationastropy.coordinates.Angle

Translated value derived from the header.

to_boresight_rotation_coord()

Boresight rotation angle.

Only relevant for science observations.

to_dark_time()

Calculate the dark time.

If a DARKTIME header is not found, the value is assumed to be identical to the exposure time.

Returns

darkastropy.units.Quantity

The dark time in seconds.

to_datetime_begin()

Calculate start time of observation.

Uses FITS standard MJD-OBS or DATE-OBS, in conjunction with the TIMESYS header.

Returns

start_timeastropy.time.Time

Time corresponding to the start of the observation.

to_datetime_end()

Calculate end time of observation.

Uses FITS standard MJD-END or DATE-END, in conjunction with the TIMESYS header.

Returns

start_timeastropy.time.Time

Time corresponding to the end of the observation.

to_detector_exposure_id()

Return value of detector_exposure_id from headers.

Unique integer identifier for this detector in this exposure.

Returns

detector_exposure_idint

The translated property.

to_detector_group()

Collection name of which this detector is a part. Can be None if there are no detector groupings.

Returns

translationstr

Translated value derived from the header.

to_detector_name()

Name of the detector within the instrument (might not be unique if there are detector groups).

Returns

translationstr

Translated value derived from the header.

to_detector_num()

Return value of detector_num from headers.

Unique (for instrument) integer identifier for the sensor.

Returns

detector_numint

The translated property.

to_detector_serial()

Serial number/string associated with this detector.

Returns

translationstr

Translated value derived from the header.

to_detector_unique_name()

Return a unique name for the detector.

Base class implementation attempts to combine detector_name with detector_group. Group is only used if not None.

Can be over-ridden by specialist translator class.

Returns

namestr

detector_group``_``detector_name if detector_group is defined, else the detector_name is assumed to be unique. If neither return a valid value an exception is raised.

Raises

NotImplementedError

Raised if neither detector_name nor detector_group is defined.

to_exposure_group()

Calculate the exposure group string.

For LSSTCam and LATISS this is read from the GROUPID header. If that header is missing the exposure_id is returned instead as a string.

to_exposure_id()

Generate a unique exposure ID number

This is a combination of DAYOBS and SEQNUM, and optionally CONTRLLR.

Returns

exposure_idint

Unique exposure number.

to_exposure_time()

Duration of the exposure with shutter open (seconds).

Returns

translationastropy.units.Quantity

Translated value derived from the header.

to_instrument()

The instrument used to observe the exposure.

Returns

translationstr

Translated property.

to_location()

Calculate the observatory location.

Uses FITS standard OBSGEO- headers.

Returns

locationastropy.coordinates.EarthLocation

An object representing the location of the telescope.

to_object()

Object of interest or field name.

Returns

translationstr

Translated property.

to_observation_counter()

Return the sequence number within the observing day.

Returns

counterint

The sequence number for this day.

to_observation_id()

Label uniquely identifying this observation (can be related to ‘exposure_id’).

Returns

translationstr

Translated value derived from the header.

to_observation_reason()

Return the reason this observation was taken.

Base class implementation returns the science if the observation_type is science, else unknown. A subclass may do something different.

Returns

namestr

The reason for this observation.

to_observation_type()

Return value of observation_type from headers.

Type of observation (currently: science, dark, flat, bias, focus).

Returns

observation_typestr

The translated property.

to_observing_day()

Return the day of observation as YYYYMMDD integer.

For LSSTCam and other compliant instruments this is the value of the DAYOBS header.

Returns

obs_dayint

The day of observation.

to_physical_filter()

Calculate the physical filter name.

Returns

filterstr

Name of filter. Can be a combination of FILTER and FILTER2 headers joined by a “~” if FILTER2 is set and not empty. Returns “UNKNOWN” if no filter is declared.

to_pressure()

Atmospheric pressure outside the dome.

Returns

translationastropy.units.Quantity

Translated property.

to_relative_humidity()

Relative humidity outside the dome.

Returns

translationfloat

Translated property.

to_science_program()

Observing program (survey or proposal) identifier.

Returns

translationstr

Translated value derived from the header.

to_telescope()

Full name of the telescope.

Returns

translationstr

Translated property.

to_temperature()

Temperature outside the dome.

Returns

translationastropy.units.Quantity

Translated property.

to_tracking_radec()

Return value of tracking_radec from headers.

Requested RA/Dec to track.

Returns

tracking_radecastropy.coordinates.SkyCoord

The translated property.

to_visit_id()

Calculate the visit associated with this exposure.

Notes

For LATISS and LSSTCam the default visit is derived from the exposure group. For other instruments we return the exposure_id.

classmethod translator_version()

Return the version string for this translator class.

Returns

versionstr

String identifying the version of this translator.

Notes

Assumes that the version is available from the __version__ variable in the parent module. If this is not the case a translator should subclass this method.

static validate_value(value, default, minimum=None, maximum=None)

Validate the supplied value, returning a new value if out of range

Parameters

valuefloat

Value to be validated.

defaultfloat

Default value to use if supplied value is invalid or out of range. Assumed to be in the same units as the value expected in the header.

minimumfloat

Minimum possible valid value, optional. If the calculated value is below this value, the default value will be used.

maximumfloat

Maximum possible valid value, optional. If the calculated value is above this value, the default value will be used.

Returns

valuefloat

Either the supplied value, or a default value.