Common Keywords to All Reference Files

At present, most JWST science and reference files are FITS files with image or table extensions. The FITS primary data unit is always empty. The primary header contains all keywords not specific to individual extensions. Keywords specific to a particular extension are contained in the header of that extension.

The required Keywords Documenting Contents of Reference Files are:

Keyword Comment
REFTYPE Required values are listed in the discussion of each pipeline step.
DESCRIP Summary of file content and/or reason for delivery
AUTHOR Person(s) who created the file
USEAFTER YYYY-MM-DDThh:mm:ss Date and time after the reference files will be used.
The T is required. Time string may NOT be omitted; use T00:00:00 if no
meaningful value is available.
PEDIGREE Options are
‘SIMULATION’ or ‘MODEL’
‘GROUND’
‘DUMMY’
‘INFLIGHT YYYY-MM-DD YYYY-MM-DD’
HISTORY Information that will help user to determine:
HISTORY 1- how the file was created
HISTORY 2- Date of modification
HISTORY 3- DOCUMENT: Name of document describing the strategy and algorithms used
HISTORY to create the file
HISTORY 4- SOFTWARE: Description, version number, location of software used to
HISTORY create the file.
HISTORY 5- DATA USED: Data used to create file
HISTORY 6- DIFFERENCES: How is this version different from the one that it
HISTORY replaces?
HISTORY 7- If your text spills over to the next line, begin it with another
HISTORY HISTORY keyword, as in this example.

A pipeline module may require separate reference files for each instrument, detector, filter, observation date, etc. The values of these parameters must be included in the reference file header. The observing-mode keyword values are vital to the process of ingesting reference files into CRDS, as they are used to establish the mapping between observing modes and specific reference files. Some observing-mode keywords are also used in the pipeline processing steps. If an observing-mode keyword is irrelevant to a particular observing mode (such as GRATING for the MIRI imager mode or the NIRCam and NIRISS instruments), then it may be omitted from the file header. The Keywords Documenting the Observing Mode are:

Keyword Sample Value Comment
TELESCOP JWST  
INSTRUME MIRI Instrument name. Allowed values: FGS, NIRCAM, NIRISS, NIRSPEC, MIRI
PUPIL NRM Pupil wheel element. Required only for NIRCam and NIRISS. NIRCam allowed values: CLEAR, F162M, F164N, F323N, F405N, F466N, F470N, GRISMV2, GRISMV3 NIRISS allowed values: CLEARP, F090W, F115W, F140M, F150W, F158M, F200W, GR700XD, NRM
FILTER F2100W Filter wheel element. Allowed values: too many to list here
GRATING G395M

Required only for NIRSpec.

NIRSpec allowed values: G140M, G235M, G395M, G140H, G235H, G395H, PRISM, MIRROR

EXP_TYPE MIR_MRS

Exposure type.

FGS allowed values: FGS_IMAGE, FGS_FOCUS, FGS_SKYFLAT, FGS_INTFLAT, FGS_DARK

MIRI allowed values: MIR_IMAGE, MIR_TACQ, MIR_LYOT, MIR_4QPM, MIR_LRS-FIXEDSLIT, MIR_LRS-SLITLESS, MIR_MRS, MIR_DARK, MIR_FLATIMAGE, MIR_FLATMRS, MIR_CORONCAL

NIRCam allowed values: NRC_IMAGE, NRC_GRISM, NRC_TACQ, NRC_TACONFIRM, NRC_CORON, NRC_TSIMAGE, NRC_TSGRISM, NRC_FOCUS, NRC_DARK, NRC_FLAT, NRC_LED

NIRISS allowed values: NIS_IMAGE, NIS_TACQ, NIS_TACONFIRM, NIS_WFSS, NIS_SOSS, NIS_AMI, NIS_FOCUS, NIS_DARK, NIS_LAMP

NIRSpec allowed values: NRS_TASLIT, NRS_TACQ, NRS_TACONFIRM, NRS_CONFIRM, NRS_FIXEDSLIT, NRS_AUTOWAVE, NRS_IFU, NRS_MSASPEC, NRS_AUTOFLAT, NRS_IMAGE, NRS_FOCUS, NRS_DARK, NRS_LAMP, NRS_BOTA, NRS_BRIGHTOBJ, NRS_MIMF

DETECTOR MIRIFULONG

Allowed values: GUIDER1, GUIDER2

NIS

NRCA1, NRCA2, NRCA3, NRCA4, NRCB1, NRCB2, NRCB3, NRCB4, NRCALONG, NRCBLONG

NRS1, NRS2

MIRIFULONG, MIRIFUSHORT, MIRIMAGE

CHANNEL 12 MIRI MRS (IFU) channel. Allowed values: 1, 2, 3, 4, 12, 34 SHORT NIRCam channel. Allowed values: SHORT, LONG
BAND MEDIUM IFU band. Required only for MIRI. Allowed values are SHORT, MEDIUM, LONG, and N/A, as well as any allowable combination of two values (SHORT-MEDIUM, LONG-SHORT, etc.). (Also used as a header keyword for selection of all MIRI Flat files, Imager included.)
READPATT FAST

Name of the readout pattern used for the exposure. Each pattern represents a particular combination of parameters like nframes and groups. For MIRI, FAST and SLOW refer to the rate at which the detector is read.

MIRI allowed values: SLOW, FAST, FASTGRPAVG, FASTINTAVG

NIRCam allowed values: DEEP8, DEEP2, MEDIUM8, MEDIUM2, SHALLOW4, SHALLOW2, BRIGHT2, BRIGHT1, RAPID

NIRSpec allowed values: NRSRAPID, NRS, NRSN16R4, NRSIRS2RAPID

NIRISS allowed values: NIS, NISRAPID

FGS allowed values: ID, ACQ1, ACQ2, TRACK, FINEGUIDE, FGS60, FGS840, FGS7850, FGSRAPID, FGS

NRS_NORM 16 Required only for NIRSpec.
NRS_REF 4 Required only for NIRSpec.
SUBARRAY FULL MIRI allowed values: FULL, GENERIC, MASK1140, MASK1550, MASK1065, MASKLYOT, BRIGHTSKY, SUB256, SUB128, SUB64, SLITLESSPRISM
P_XXXXXX P_READPA pattern keywords used by CRDS for JWST to describe the intended uses of a reference file using or’ed combinations of values. Only a subset of P_pattern keywords are supported.
SUBSTRT1 1 Starting pixel index along axis 1 (1-indexed)
SUBSIZE1 2048 Size of subarray along axis 1
SUBSTRT2 1 Starting pixel index along axis 2 (1-indexed)
SUBSIZE2 2048 Size of subarray along axis 2
FASTAXIS 1 Fast readout direction relative to image axes for Amplifier #1 (1 = +x axis, 2 = +y axis, -1 = -x axis, -2 = -y axis) SEE NOTE BELOW.
SLOWAXIS 2
Slow readout direction relative to image axes for all amplifiers (1 = +x axis, 2 = +y axis,
-1 = -x axis, -2 = -y axis)

Note: For the NIR detectors, the fast readout direction changes sign from one amplifier to the next. It is +1, -1, +1, and -1, for amps 1, 2, 3, and 4, respectively. The keyword FASTAXIS refers specifically to amp 1. That way, it is entirely correct for single-amp readouts and correct at the origin for 4-amp readouts. For MIRI, FASTAXIS is always +1.

Tracking Pipeline Progress

As each pipeline step is applied to a science data product, it will record a status indicator in a header keyword of the science data product. The current list of step status keyword names is given in the following table. These status keywords may be included in the primary header of reference files, in order to maintain a history of the data that went into creating the reference file. Allowed values for the status keywords are ‘COMPLETE’ and ‘SKIPPED’. Absence of a particular keyword is understood to mean that step was not even attempted.

Table 3. Keywords Documenting Which Pipeline Steps Have Been Performed

S_IPC IPC correction
S_RESET MIRI reset correction
S_SUPERB Superbias subtraction
S_IMPRNT NIRSpec MSA imprint subtraction
S_MSAFLG NIRSpec MSA failed shutter flagging
S_EXTR1D 1-D spectral extraction
S_LASTFR MIRI last frame correction
S_DQINIT DQ initialization
S_REFPIX Reference pixel correction
S_ERRINI ERR initialization
S_DARK Dark subtraction
S_SATURA Saturation check
S_LINEAR Linearity correction
S_JUMP Jump detection
S_RAMP Ramp fitting
S_WCS WCS assignment
S_FLAT Flat-fielding
S_FRINGE Fringe correction
S_PERSIS Persistence correction
S_STRAY Straylight correction
S_TELEMI Telescope emission
S_PHOTOM Photometric (absolute flux) calibration
S_EXTR1D 1-D extraction
S_EXTR2D 2-D spectral extraction
S_RESAMP Image resampling
S_BKDSUB Background subtraction
S_SLOSS Slit-loss correction

Orientation of Detector Image

All steps in the pipeline assume the data are in the DMS (science) orientation, not the native readout orientation. The pipeline does NOT check or correct for the orientation of the reference data. It assumes that all files ingested into CRDS have been put into the science orientation. All header keywords documenting the observing mode (Table 2) should likewise be transformed into the DMS orientation. For square data array dimensions it’s not possible to infer the actual orientation directly so reference file authors must manage orientation carefully.

Correct values for FASTAXIS and SLOWAXIS for each detector are:
DETECTOR FASTAXIS SLOWAXIS
MIRIMAGE 1 2
MIRIFULONG 1 2
MIRIFUSHORT 1 2
NRCA1 -1 2
NRCA2 1 -2
NRCA3 -1 2
NRCA4 1 -2
NRCALONG -1 2
NRCB1 1 -2
NRCB2 -1 2
NRCB3 1 -2
NRCB4 -1 2
NRCBLONG 1 -2
NRS1 2 1
NRS2 -2 -1
NIS -2 -1
GUIDER1 -2 -1
GUIDER2 2 -1

Differing values for these keywords will be taken as an indicator that neither the keyword value nor the array orientation are correct.