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_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_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().