Algorithms for calwebb_spec2, which is stage 2 of the JWST Science Calibration Pipeline for spectroscopic data are used to process data from uncalibrated slope images to calibrated slope images. 

On this page

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

The calwebb_spec2 module is stage 2 of the JWST Science Calibration Pipeline for all spectroscopic observations. The input to this stage is the uncalibrated slope images (calwebb_detector1 output) and the output is calibrated slope images. An association (ASN) file is required to run this step on multiple slope images, or if an associated source catalog is specified for spectral extraction as in the case of WFSS modes. The steps are listed in Figure 1 with the flow from the top to the bottom.

Unless otherwise stated, the algorithms described are the baseline version.

Figure 1. calwebb_spec2


Graphical representation of all the steps in the calwebb_spec2 module. Checkmarks indicate which steps are applicable to which modes, for NIR and MIR observations. Note that the Imprint Subtraction step  is available/applied to both IFU and MSA observations (but could be turned off for either mode, if needed). Note that the steps indicated for time-series observations (TSO) data will process these data in accordance with the specific modes used to obtain the TSO observations. Note also that, while NIRISS SOSS data has most of its steps in common with other TSO data, it includes additional steps of background subtraction and path-loss correction, while TSO data on the other hand includes a flat field correction step; these differences are driven by the unique instrumental characteristics of the NIRISS SOSS mode. Finally, note that the order of the flat field correction step, subwindow extraction step, and point vs extended decision step depend on the observing mode.

Steps for both NIR and MIR data

WCS information

Software documentation outside JDox: Assign WCS 

The information to transfer the pixel coordinates to astronomical coordinates (e.g., RA, Dec, and wavelength) is added to the data with this step. The needed information is described in the World Coordinate System (WCS) format. The WCS information and distortion model are provided by instrument and detector-specific calibration reference files (all) and an instrument model (NIRSpec only). The data itself is not modified by this step.

Background subtraction

Software documentation outside JDox: Background Image Subtraction 

An observed or modeled background image is subtracted from the target exposure. 

If an APT-specified background target was observed, a combined background image constructed from all exposures of that target is subtracted from the science target exposure.

For NIRISS WFSS, NIRISS SOSS, and NIRCam WFSS, a master version of the dispersed background is used, scaled to match the background in the science target exposure.

For NIRSpec MSA, NIRSpec IFU, NIRSpec Fixed Slit, and MIRI LRS, if observations were taken at 2 or more nod positions, the associated nod position or sum of nod positions is subtracted.

Flat field correction

Software documentation outside JDox: Flat field correction 

The flat field corrects for the pixel-to-pixel variations and large scale variations in the instrument+telescope responsivity. The flat field image is taken from instrument and detector specific calibration reference files. For NIRSpec, the flat field is created on-the-fly from reference files and the instrument model.

Point vs extended decision

Software documentation outside JDox: Source Type 

Some of the calibration pipeline steps rely on knowing if the target is a point or extended source (e.g., spectral extraction). The determination of a source as point or extended can be informed by setting the extended tag in APT (see APT Targets), from simultaneous imaging (NIRISS and NIRCam WFSS), from the NIRSpec MSA tool output, or if no other information is available, by using defaults by instrument mode. The default is to assume a point source except for NIRSpec MSA backgrounds and MIRI IFU observations. This decision is attached to the data and used by later steps in the JWST Science Calibration Pipeline. When manually rerunning the JWST Science Calibration Pipeline, this step can be set by the user.

Path-loss correction

Software documentation outside JDox: Pathloss Correction 

The loss of signal in the path is corrected here. The causes of signal loss include the slit (NIRSpec, MIRI), the diffracted slit image being larger than the gratings (NIRSpec), the MSA bar shadow (NIRSpec MSA), and cases where the PSF wings may extend beyond the subarray size in the cross-dispersion direction (NIRISS SOSS). The correction values are provided by instrument- and mode-specific calibration reference files.

Flux calibration

Software documentation outside JDox: Photometric Calibration 

The multiplicative conversion factor between counts/s and MJy/sr as a function of wavelength is attached to the data. A second conversion factor between counts/s and micro-Jy/sq arcsec as a function of wavelength is also attached. Basically, these are FITS keywords. The pixel area reference file will be attached to the data allowing conversion between surface brightness and flux density for each pixel. Details of the calculation of these calibration factors can be found in the JWST Data Absolute Flux Calibration article.

For MIRI MRS, the pixel array values are multiplied by a reference array to convert the detector image to units of MJy/sr.

For NIRSpec data, the conversion factor is applied as part of the F-flat correction in the flat field step. The photom step will be used to apply a residual correction for systematic differences among standard stars, once multiple standards are observed and analyzed in Cycle 1.

Rectified 2-D/3-D product

Software documentation outside JDox: Resampling 

As a product for the Archive, rectified 2-D (all except IFUs) or 3-D (IFUs) products are created using the attached WCS information. These rectified 2-D/3-D products are not used in the calibration pipeline itself (other than to create 1-D extracted spectra from IFU data for later use in the calwebb_spec3 master_background step) and are created as they are useful for visual browsing of the data.

Spectral Extraction

       Software documentation outside JDox: Extract 2D Spectra and Extract 1D Spectra 

The extracted spectrum for every targeted source is the primary output of the spectroscopic observations. The spectrum is extracted by summing the signal in an aperture centered on the sky coordinates (RA & Dec) of the targets. When the extractions are done from individual unrectified images, the WCS information is used to map the projected aperture from the sky to detector coordinates. If the extraction is done from a cube created from multiple rectified images, the apertures are directly taken from the sky coordinates.

NIR-specific steps

Imprint subtraction

Software documentation outside JDox: Imprint Subtraction 

The MSA shutters are not completely dark allowing a small amount of light to leak through causing an imprint. When there is a dedicated imprint exposure taken (all MSA shutters closed and IFU closed), this will be subtracted from the target exposure.

MSA failed open flagging

Software documentation outside JDox: MSA Flag Open Correction 

The MSA failed open shutters will result in an elevated level of light to fall on the detectors. This step flags the pixels that are affected by these failed open shutters. This step uses the list of failed open shutters and the NIRSpec instrument model to flag the affected pixels.

Subwindow extraction

Software documentation outside JDox: Extract 2D 

The region of interest for each source is extracted for NIRISS/NIRCam WFSSNIRISS SOSS, and NIRSpec MSA/fixed slit data. The location of the sources for the WFSS observations is provided using the direct imaging observations taken as part of the observations. The NIRSpec MSA configuration file provides the location of the sources for this MOS mode. The other modes have fixed locations for sources. This subwindow extraction assumes that sources are isolated and not confused with other sources (such confused sources will need to be extracted with a post-pipeline tool). The main impact of this step is to provide single sources to the rest of the calibration pipeline providing a uniform treatment of all spectra from the observation modes listed.

MSA Bar Shadow correction

Software documentation outside JDox: MSA Bar Shadow Correction 

For NIRSpec MSA observations, there are losses in the case of extended sources arising from the imperfect profile of the shutter. The shadow bar correction is derived from the instrumental mode for the target shutter and adjacent shutters, and is applied to the 2-D cutouts.

WFSS Contamination Removal

Software documentation outside JDox: WFSS Contamination Removal 

This step is applied to WFSS observations (NIRISS and NIRCam) to correct effects due to contamination resulting from overlapping spectral traces from objects that are near the source of interest. This can happen, for example, in observations of crowded fields. In this step, source fluxes from a direct image of the field are used to simulate the WFSS spectra for each of the overlapping nearby objects. Each spectrum of the source of interest is then corrected by subtracting the simulated spectra of these nearby contaminating objects.

MIR-specific steps

Stray light subtraction

Software documentation outside JDox: Stray Light Correction 

As discussed on the MIRI Features & Caveats page, the MIRI detectors exhibit scattering inside the detector substrate that produces a cruciform-shaped artifact around bright sources. In the MRS the interleaving of the slices on the detector means that this cross artifact is non-local in sky coordinates and can produce banding in the rectified 3-D data cubes. This step estimates the cross-artifact signal via convolution of the data with a model cruciform kernel and subtracts it from the MIRI MRS data. Likewise, it subtracts any pedestal residual count rate due to variations in the dark current over time using regions of the detector that do not directly see light from the sky.

Fringing removal

Software documentation outside JDox: Fringe Correction and Residual Fringe Correction

There are significant fringes in the MIRI IFU data. These fringes are removed to first order by dividing the exposures by a static fringe flat contained within the detector-specific calibration reference file. This fringe flat only performs well for uniform extended sources however, and leaves significant residual fringes remaining for point sources or sources with complex spatial structure. The residual_fringe step of the pipeline can correct for many of these residual fringe features using a periodogram-based analysis of the data; this step is not run by default but can be enabled by users in offline reprocessing (see JWST MIRI MRS Pipeline Caveats).

NIRSpec-specific steps

Master background subtraction

Software documentation outside JDox: Master Background Subtraction 

Master background subtraction for NIRSpec MOS comes from designated background MSA slitlets contained with the same exposure as the science targets or are supplied by the user. Processing for MOS mode is done within the calwebb_spec2 pipeline when processing individual MOS exposures, resulting in background-subtracted and fully calibrated 2-D cutouts and extracted 1D spectra.

Wavelength assignments

Software documentation outside JDox: Wavelength Assignments 

This step updates the wavelength assignments for NIRSpec fixed slit (FS) and MOS point sources that are known to be off-center (in the dispersion direction) in their slit. For NIRSpec MOS observations, wavelength assignments are initially created assuming that the source is perfectly centered in a slitlet. Most sources, however, are not perfectly centered in every slitlet in a real observation, therefore this step carries out a computation aimed at providing a more accurate determination of the source position in the slitlet, which is then used for the subsequent steps in the pipeline.

Latest updates

    Added information about the steps for WFSS contamination removal and wavelength assignments
    Added a statement about NIRSpec data in the flux calibration step

  • Added Master Background Subtraction step for NIRSpec MOS observations.


Originally published