Frame Types

Overview

Every raw data file ingested by PypeIt must be given a frame type. This identifies how the frame should be treated and included in the data reduction.

Frame typing can be done automatically by running pypeit_setup, which is a simple wrapper for PypeItSetup. The type of frame for each data file is automatically identified as one or more of the types listed in the table below; any files that could not be identified are given a frame type set to None.

The robustness of the automated typing of calibration frames varies with some Spectrographs being much more robust than others. Automated typing of science versus standard frames is generally not robust for any instrument. Always inspect your PypeIt Reduction File to ensure the frame typing is correct!

Definitions

The possible frame types defined by PypeIt and a brief description can be listed as follows:

from pypeit.core.framematch import FrameTypeBitMask
FrameTypeBitMask().info()

More detailed descriptions are given in the table below.

Frame Type	Description
`align`	Used to align spatial positions in multiple slits. This frame is particularly useful for slit-based IFU, such as Keck KCWI.
`arc`	Spectrum of one or more calibration arc lamps
`bias`	Bias frame; typically a 0s exposure with the shutter closed
`dark`	Dark frame; typically a >0s exposure to assess dark current (shutter closed)
`illumflat`	Spectrum taken to correct illumination profile of the slit(s). This is often the same as the trace flat (below).
`lampoffflats`	Spectrum taken to remove persistence from lamp on flat exposures and/or thermal emission from the telescope and dome. Usually this is an exposure using a flat with lamps OFF
`pinhole`	Spectrum taken through a pinhole slit (i.e. a very short slit length), and is used to define the centre if a slit (currently, this frame is only used for echelle data reduction). Often this is an exposure using a flat lamp, but one can in principle use a standard star frame too (or a science frame if the spectrum is uniform).
`pixelflat`	Spectrum taken to correct for pixel-to-pixel detector variations. Often an exposure using a dome (recommended) or internal flat lamp, but for observations in the very blue, this may be on-sky
`slitless_pixflat`	Spectrum taken without a slitmask or longslit to correct for pixel-to-pixel detector variations. This is often an exposure taken on-sky
`science`	Spectrum of one or more science targets
`standard`	Spectrum of spectrophotometric standard star PypeIt includes a list of pre-defined standards
`trace`	Spectrum taken to define the slit edges. Often this is an exposure using a flat lamp, but for observations in the very blue, this may be on-sky. The slit length of a trace frame should be the same as the science slit.
`tilt`	Exposure used to trace the tilt in the wavelength solution. Often the same file(s) as the arc.
`sky`	On-sky observation of the sky used for background subtraction
`None`	File could not be automatically identified by PypeIt

It is possible (and even common for arc and flats images) that a frame can be assigned more than one frame type.

Warning

Any execution of run_pypeit will crash if your PypeIt Reduction File includes entries with None frame types defined. You must either remove or edit those entries in the pypeit file by-hand after running pypeit_setup.

Automated Typing

Automated typing of files is performed by pypeit_setup.

In detail, PypeItSetup builds a table of metadata for all files found using the search key provided to its from_file_root() method. The metadata itself is gathered and maintained by PypeItMetaData based on a set of header keywords that are defined for each supported spectrograph. For example, the metadata keywords for Keck DEIMOS reductions are:

Metadata Key   Header Card
------------   -----------
          ra            RA
         dec           DEC
      target      TARGNAME
      decker      SLMSKNAM
     binning          None
         mjd          None
     exptime      ELAPTIME
     airmass       AIRMASS
    dispname      GRATENAM
       hatch      HATCHPOS
   dispangle          None
      idname       OBSTYPE
  lampstat01         LAMPS
     dateobs      DATE-OBS
         utc           UTC
        mode       MOSMODE
         amp       AMPMODE
      object        OBJECT
     filter1      DWFILNAM
     frameno       FRAMENO
  instrument      INSTRUME

which can be obtained by executing

pypeit_obslog keck_deimos -k

See pypeit_obslog.

The method get_frame_types() uses the metadata to try to identify each frame type. With a couple exceptions, however, this method is largely a wrapper for the check_frame_type method of each spectrograph; e.g., see check_frame_type() for DEIMOS. The relevant exposure time for each frame can be refined using parameters in the pypeit file. For example, to edit the exposure time for pixelflat images to be between 15 and 30 seconds, you can include the following lines in your PypeIt Reduction File:

[calibrations]
    [[pixelflatframe]]
        exprng = 15, 30

Note that you can set either (or both) of the limits to None such that it is undefined. I.e.:

from pypeit.spectrographs.keck_deimos import KeckDEIMOSSpectrograph
KeckDEIMOSSpectrograph().default_pypeit_par()['calibrations']['pixelflatframe']['exprng']

shows the default exposure-time range for pixel flats is [None, 30], meaning there is no lower limit on the exposure time for the pixel-flats. At the moment, only the exposure time can be altered programmatically for the frame type determination; all other conditions are hard-coded.