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:

Processed 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.1

Obj Key	Obj Type	Array Type	Description
`bkg_redux_skymodel`	ndarray	floating	2D sky model image without the background subtraction (float32)
`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.