Spec2D Output

Overview

During the data-reduction process, PypeIt creates a series of 2D spectral images prior to extraction of 1D spectra. And, of course, several of these 2D images may have greater value for analysis than the 1D spectra. For the extracted 1D spectra, see Spec1D Output.

For each on-source exposure, PypeIt outputs a series of these images in a single, multi-extension fits file, separated by detector; see Current Spec2DObj Data Model.

Naming

The 2D spectra files have names like:

spec2d_b27-J1217p3905_KASTb_2015May20T045733.560.fits

See here for a description of the naming convention.

Inspecting

You can open this image in ds9 and play around. But we highly recommend using the pypeit_show_2dspec script which interfaces with ginga.

pypeit_show_2dspec

This script displays the sky-subtracted 2D image for a single detector in a ginga RC viewer. It also overlays the slits and any objects extracted. It should be called from the reduction directory, i.e. above the Science/ folder where the spec2d image is located.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_show_2dspec -h
usage: pypeit_show_2dspec [-h] [--list] [--det DET] [--spat_id SPAT_ID]
                          [--maskID MASKID] [--showmask [SHOWMASK ...]]
                          [--removetrace] [--embed] [--ignore_extract_mask]
                          [--channels CHANNELS] [--prefix PREFIX] [--no_clear]
                          [-v VERBOSITY] [--try_old]
                          file

Display sky subtracted, spec2d image in a ginga viewer.

positional arguments:
  file                  Path to a PypeIt spec2d file

options:
  -h, --help            show this help message and exit
  --list                List the extensions only? (default: False)
  --det DET             Detector name or number. If a number, the name is
                        constructed assuming the reduction is for a single
                        detector. If a string, it must match the name of the
                        detector object (e.g., DET01 for a detector, MSC01 for a
                        mosaic). (default: 1)
  --spat_id SPAT_ID     Restrict plotting to this slit (PypeIt ID notation)
                        (default: None)
  --maskID MASKID       Restrict plotting to this maskID (default: None)
  --showmask [SHOWMASK ...]
                        Include a channel showing the mask. If no arguments are
                        provided, the mask bit values are provided directly. You
                        can also specify one or more mask flags used to
                        construct an image identifying which pixels are flagged
                        by any of these issues. E.g., to show pixels flagged by
                        the instrument specific bad-pixel mask or cosmic arrays,
                        use --showmask BPM CR . See
                        https://pypeit.readthedocs.io/en/release/out_masks.html
                        for the list of flags. (default: None)
  --removetrace         Do not overplot traces in the skysub, sky_resid, and
                        resid channels (default: False)
  --embed               Upon completion embed in ipython shell (default: False)
  --ignore_extract_mask
                        Ignore the extraction mask (default: False)
  --channels CHANNELS   Only show a subset of the channels (0-indexed), e.g. 1,3
                        (default: None)
  --prefix PREFIX       Channel name prefix [lets you display more than one set]
                        (default: )
  --no_clear            Do *not* clear all existing tabs (default: True)
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all] (default:
                        1)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

Here is a typical call:

pypeit_show_2dspec Science/spec2d_c17_60L._LRISb_2017Mar20T055336.211.fits

This opens 4 tabs in the ginga display, one for each of the following:

  • Procesed image (sciimg-det##)

  • Sky subtracted image (skysub-det##)

  • Sky residual image (sky_resid-det##)

  • Full residual image which removes the object too (resid-det##)

Red/green lines indicate slit edges. Orange lines (if present) indicate traces for detected objects. Light blue lines (if present) indicate traces for manually extracted objects.

As you mouse around, the x-values shown at the bottom indicate the wavelength.

Warning

If you get an obscure error when executing the above command, it may be that you’re trying to view a file created by a previous version of PypeIt. As the code develops, we sometimes change the datamodel of different output files, which are often not backwards compatible. If you run into this error, try reverting to the relevant PypeIt version (the version used to create the file is typically written to the VERSPYP header keyword) or re-reduce the data with the new PypeIt version.

pypeit_parse_slits

This script prints to the screen a short summary of the slit information, detector by detector.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_parse_slits -h
usage: pypeit_parse_slits [-h] [--try_old] input_file

Print info on slits from a input file

positional arguments:
  input_file  Either a spec2D or Slits filename

options:
  -h, --help  show this help message and exit
  --try_old   Attempt to load old datamodel versions. A crash may ensue..
              (default: False)

See pypeit_parse_slits for more info.

pypeit_chk_wavecalib

This script prints to the screen a set of simple wavelength calibration diagnostics per each slit, detector by detector.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_wavecalib -h
usage: pypeit_chk_wavecalib [-h] [--try_old] input_file [input_file ...]

Print QA on Wavelength Calib to the screen

positional arguments:
  input_file  One or more PypeIt WaveCalib file [e.g. WaveCalib_A_1_DET01.fits]
              or spec2d file

options:
  -h, --help  show this help message and exit
  --try_old   Attempt to load old datamodel versions. A crash may ensue..
              (default: False)

See pypeit_chk_wavecalib for more info.

Identifying Slits

If you need to generate an image describing the location of each slit/order for a given detector here is the recommended approach:

from pypeit import spec2dobj
spec2DObj = spec2dobj.Spec2DObj.from_file('spec2d_b170320_2083-c17_60L._LRISb_2017Mar20T055336.211.fits', det=2)
slitmask = spec2DObj.slits.slit_img(flexure=spec2DObj.sci_spat_flexure)

If no flexure correction was applied, it will be ignored. This generates an image with pixel values:

  • -1 for a pixel not in any slit/order

  • SPAT_ID for each pixel in the slit identified by SPAT_ID

Current Spec2DObj Data Model

Internally, the image is held in AllSpec2DObj, which holds the full set of Spec2DObj objects.

All wavelengths are in vacuum.

The data model for the latter is:

Version: 1.1.0

Obj Key

Obj Type

Array Type

Description

bpmmask

ImageBitMaskArray

2D bad-pixel mask for the image

det

int

Detector index

detector

DetectorContainer, Mosaic

Detector or Mosaic metadata

ivarmodel

ndarray

floating

2D ivar model image (float32)

ivarraw

ndarray

floating

2D processed inverse variance image (float32)

maskdef_designtab

Table

Table with slitmask design and object info

med_chis

ndarray

floating

Median of the chi image for each slit/order

objmodel

ndarray

floating

2D object model image (float32)

scaleimg

ndarray

floating

2D multiplicative scale image [or a single scalar as an array] that has been applied to the science image (float32)

sci_spat_flexure

float

Shift, in spatial pixels, between this image and SlitTrace

sci_spec_flexure

Table

Global shift of the spectrum to correct for spectralflexure (pixels). This is based on the sky spectrum atthe center of each slit

sciimg

ndarray

floating

2D processed science image (float32)

skymodel

ndarray

floating

2D sky model image (float32)

slits

SlitTraceSet

SlitTraceSet defining the slits

std_chis

ndarray

floating

std of the chi image for each slit/order

tilts

ndarray

floating

2D tilts image (float64)

vel_corr

float

Relativistic velocity correction for wavelengths

vel_type

str

Type of reference frame correction (if any). Options are listed in the routine: WavelengthSolutionPar.valid_reference_frames() Current list: observed, heliocentric, barycentric

waveimg

ndarray

floating

2D wavelength image in vacuum (float64)

wavesol

Table

Table with WaveCalib diagnostic info

Each array and the associated DetectorContainer is written as a separate HDU prefixed by the detector number, DET01-.

For a description of how to use the bitmasks (i.e., the *BPMMASK extensions), see our description of the Output Bitmasks.