pypeit.calibframe module

Implements the calibration frame base class.

class pypeit.calibframe.CalibFrame(d=None)[source]

Bases: DataContainer

An abstract class for calibration frames. The primary purpose of the class is to set the naming scheme for all processed calibration files.

_base_header(hdr=None)[source]

Override the base class method to add useful/identifying internals to the header.

Parameters:: hdr (astropy.io.fits.Header, optional) – Header object to update. The provided object is not edited, only copied.
Returns:: The new/edited fits header.
Return type:: astropy.io.fits.Header

_validate()[source]

Validation method that is executed every time a CalibFrame is instantiated.

Ensures:

calib_type and datamodel are defined, and

any members of datamodel of the base class are also members of the derived class.

calib_file_format = 'fits': The extension and file format of the output file. Should be 'fits' or 'fits.gz' (for gzipped output).

calib_keys_from_header(hdr)[source]

(Attempt to) Fill the calibration keys based on the provided hdr.

If successful, this sets the values for the calibration internals.

Parameters:: hdr (astropy.io.fits.Header) – Header to parse

calib_type = None: The type of the calibration frame, primarily used to set the name of the output file.

static construct_calib_id(calib_id, ingested=False)[source]

Use the calibration ID to construct a unique identifying string included in output file names.

Parameters:

calib_id (str, list, int) – Identifiers for one or more calibration groups for this calibration frame. Strings (either as individually entered or as elements of a provided list) can be single or comma-separated integers. Otherwise, all strings must be convertible to integers; the only exception is the string ‘all’.
ingested (bool, optional) – Indicates that the calib_id object has already been “ingested” (see ingest_calib_id()). If True, this will skip the ingestion step.

Returns:

A string identifier to include in output file names.

Return type:

str

static construct_calib_key(setup, calib_id, detname)[source]

Construct the identifier used for a given set of calibrations.

The identifier is the combination of the configuration, the calibration group(s), and the detector. The configuration ID is the same as included in the configuration column (A, B, C, etc), the calibration group is a dash-separated list of the calibration group identifiers or “all”, and the detector/mosaic identifier (e.g., DET01, MSC02) is set by the detector number or mosaic tuple (see get_det_name()).

Parameters:

setup (str) – The string identifier for the instrument setup/configuration; see unique_configurations().
calib_id (str, list, int) – Identifiers for one or more calibration groups for this calibration frame. See ingest_calib_id().
detname (str) – The identifier used for the detector or detector mosaic for the relevant instrument; see get_det_name().

Returns:

Calibration identifier.

Return type:

str

classmethod construct_file_name(calib_key, calib_dir=None)[source]

Generate a calibration frame filename.

Parameters:

calib_key (str) – String identifier of the calibration group. See construct_calib_key().
calib_dir (str, Path, optional) – If provided, return the full path to the file given this directory.

Returns:

File path if calib_dir is provided, otherwise the file name

Return type:

str, Path

copy_calib_internals(other)[source]

Copy the internals from another CalibFrame to this one.

Parameters:: other (CalibFrame) – Object to copy from.

datamodel = {'PYP_SPEC': {'descr': 'PypeIt spectrograph name', 'otype': <class 'str'>}}

Default datamodel for any CalibFrame. Derived classes should instantiate their datamodels by first inheriting from the base class. E.g.:

class ArcFrame(CalibFrame):
    datamodel = {**CalibFrame.datamodel, ...}

classmethod from_hdu(hdu, chk_version=True, **kwargs)[source]

Instantiate the object from an HDU extension.

Parameters:

hdu (astropy.io.fits.HDUList, astropy.io.fits.ImageHDU, astropy.io.fits.BinTableHDU) – The HDU(s) with the data to use for instantiation.
chk_version (bool, optional) – If True, raise an error if the datamodel version or type check failed. If False, throw a warning only.
**kwargs – Passed directly to _parse().

get_path()[source]

Return the path to the output file.

This is a simple wrapper for the construct_file_name() classmethod that uses the existing values of calib_key and :attr`calib_dir`.

Returns:: File path or file name. This is always the full path if calib_dir is defined.
Return type:: str, Path

classmethod glob(calib_dir, setup, calib_id, detname=None)[source]

Search for calibration files.

Parameters:

calib_dir (str, Path) – Directory to search
setup (str) – The setup/configuration identifier (e.g., A, B, C, …) of the calibrations
calib_id (str, int) – The single calibration group of the calibrations
detname (str, optional) – The identifier of the detector/mosaic of the calibrations. If None, any relevant calibrations are returned.

Returns:

List of paths to applicable calibration files. If no relevant files are found or if calib_dir is not an existing directory, None is returned.

Return type:

list

static ingest_calib_id(calib_id)[source]

Ingest the calibration group IDs, converting the input into a list of strings.

Parameters:: calib_id (str, list, int) – Identifiers for one or more calibration groups for this calibration frame. Strings (either as individually entered or as elements of a provided list) can be single or comma-separated integers. Otherwise, all strings must be convertible to integers; the only exception is the string ‘all’.
Returns:: List of string representations of single calibration group integer identifiers.
Return type:: list

Examples

>>> CalibFrame.ingest_calib_id('all')
['all']
>>> CalibFrame.ingest_calib_id(['all', 1])
[WARNING] :: Calibration groups set to ['1' 'all'], resetting to simply "all".
['all']
>>> CalibFrame.ingest_calib_id('1,2')
['1', '2']
>>> CalibFrame.ingest_calib_id(['1,2', '5,8', '3'])
['1', '2', '3', '5', '8']
>>> CalibFrame.ingest_calib_id([2, 1, 2])
['1', '2']

internals = ['calib_id', 'calib_key', 'calib_dir']

Base class internals. The internals of any derived class should also include these. E.g.:

class ArcFrame(CalibFrame):
    internals = CalibFrame.internals + ['arc_specific_internal']

static parse_calib_id(calib_id_name)[source]

Parse the calibration ID(s) from the unique string identifier used in file naming. I.e., this is the inverse of construct_calib_id().

Parameters:: calib_id_name (str) – The string identifier used in file naming constructed from a list of calibration IDs using construct_calib_id().
Returns:: List of string representations of single calibration group integer identifiers.
Return type:: list

static parse_calib_key(calib_key)[source]

Given the calibration key identifier, parse its different components.

To see how the key is constructed, see construct_calib_key().

Parameters:: calib_key (str) – The calibration key identifier to parse.
Returns:: The three components of the calibration key.
Return type:: tuple

static parse_key_dir(inp, from_filename=False)[source]

Grab the identifying key and directory by parsing the input.

Parameters:

inp (str, astropy.io.fits.Header) – Either a filename or a Header of a FITS file
from_filename (bool, optional) – If True, inp must be a string providing the calibration file name, which must follow the expected naming convention. If False, inp must be an astropy.io.fits.Header or a file from which a header can be read.

Returns:

Two strings with the identifying key and directory of the processed calibration frame.

Return type:

tuple

set_paths(odir, setup, calib_id, detname)[source]

Set the internals necessary to construct the IO path for the calibration file.

Nothing is returned; this function is used to set calib_dir, calib_id, and calib_key.

Parameters:

odir (str, Path) – Output directory for the processed calibration frames
setup (str) – The string identifier for the instrument setup/configuration; see unique_configurations().
calib_id (str, list, int) – Identifiers for one or more calibration groups for this calibration frame. Strings (either as individually entered or as elements of a provided list) can be single or comma-separated integers. Otherwise, all strings must be convertible to integers; the only exception is the string ‘all’.
detname (str) – The identifier used for the detector or detector mosaic for the relevant instrument; see get_det_name().

to_file(file_path=None, overwrite=True, **kwargs)[source]

Overrides the base-class function, forcing the naming convention.

Parameters:

file_path (str, Path, optional) – Full path for the file to be written. This should be used very rarely. The whole point of the CalibFrame is to follow a deterministic I/O naming structure, and use of this option circumvents that. You should instead typically use set_paths() so that the file path is defined automatically.
overwrite (bool, optional) – Flag to overwrite any existing files. This overrides the default of the base class, meaning that anytime a calibration frame is written to disk it will overwrite any existing files by default!
**kwargs (optional) – Passed directly to to_file().