Reference Files¶
The background image subtraction step uses reference files only when processing Wide-Field Slitless Spectroscopy (WFSS) exposures. Two reference files are used for WFSS mode: WFSSBKG and WAVELENGTHRANGE. The WAVELENGTHRANGE reference file is used in the process of determining the locations of source spectra in the image, and conversely the image areas that contain only background signal.
WFSS Background reference file¶
- REFTYPE:
WFSSBKG
- Data model:
The WFSS background reference file contains a “master” image of the dispersed background produced by a particular filter+grism combination.
Reference Selection Keywords for WFSSBKG¶
CRDS selects appropriate WFSSBKG references based on the following keywords. WFSSBKG is not applicable for instruments not in the table.
Instrument |
Keywords |
|---|---|
NIRCam |
INSTRUME, EXP_TYPE, DETECTOR, FILTER, PUPIL, DATE-OBS, TIME-OBS |
NIRISS |
INSTRUME, EXP_TYPE, DETECTOR, FILTER, PUPIL, DATE-OBS, TIME-OBS |
Standard Keywords¶
The following table lists the keywords that are required to be present in all reference files. The first column gives the FITS keyword names. The second column gives the jwst data model name for each keyword, which is useful when using data models in creating and populating a new reference file. The third column gives the equivalent meta tag in ASDF reference file headers, which is the same as the name within the data model meta tree (second column).
FITS Keyword |
Data Model Name |
ASDF meta tag |
|---|---|---|
AUTHOR |
model.meta.author |
author |
DATAMODL |
model.meta.model_type |
model_type |
DATE |
model.meta.date |
date |
DESCRIP |
model.meta.description |
description |
FILENAME |
model.meta.filename |
N/A |
INSTRUME |
model.meta.instrument.name |
instrument: {name} |
PEDIGREE |
model.meta.pedigree |
pedigree |
REFTYPE |
model.meta.reftype |
reftype |
TELESCOP |
model.meta.telescope |
telescope |
USEAFTER |
model.meta.useafter |
useafter |
NOTE: More information on standard required keywords can be found here: Standard Required Keywords
Type Specific Keywords for WFSSBKG¶
In addition to the standard reference file keywords listed above, the following keywords are required in WFSSBKG reference files, because they are used as CRDS selectors (see Reference Selection Keywords for WFSSBKG):
Keyword |
Data Model Name |
|---|---|
DETECTOR |
model.meta.instrument.detector |
EXP_TYPE |
model.meta.exposure.type |
FILTER |
model.meta.instrument.filter |
PUPIL |
model.meta.instrument.pupil |
Reference File Format¶
WFSSBKG reference files are FITS files with 3 IMAGE extensions and 1 BINTABLE extension. The FITS primary HDU does not contain a data array. The characteristics of the FITS extensions are as follows:
EXTNAME |
XTENSION |
NAXIS |
Dimensions |
Data type |
|---|---|---|---|---|
SCI |
IMAGE |
2 |
ncols x nrows |
float |
ERR |
IMAGE |
2 |
ncols x nrows |
float |
DQ |
IMAGE |
2 |
ncols x nrows |
integer |
DQ_DEF |
BINTABLE |
2 |
TFIELDS = 4 |
N/A |
The DQ_DEF extension contains the bit assignments used in the DQ array. It contains the following 4 columns:
TTYPE |
TFORM |
Description |
|---|---|---|
BIT |
integer |
The bit number, starting at zero |
VALUE |
integer |
The equivalent base-10 value of BIT |
NAME |
string |
The mnemonic name of the data quality condition |
DESCRIPTION |
string |
A description of the data quality condition |
NOTE: For more information on standard bit definitions see: Data Quality Flags.
WAVELENGTHRANGE Reference File¶
- REFTYPE:
WAVELENGTHRANGE
- Data model:
The WAVELENGTHRANGE reference file contains information on the minimum and
maximum wavelengths of various spectroscopic modes, which can be
order-dependent. The reference data are used to construct bounding boxes
around the spectral traces produced by each object in the NIRCam and NIRISS
WFSS modes.
If a list of GrismObject is supplied, then no reference file is necessary.
Reference Selection Keywords for WAVELENGTHRANGE¶
CRDS selects appropriate WAVELENGTHRANGE references based on the following keywords. WAVELENGTHRANGE is not applicable for instruments not in the table. All keywords used for file selection are required.
Instrument |
Keywords |
|---|---|
MIRI |
INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS |
NIRCam |
INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS |
NIRISS |
INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS |
NIRSpec |
INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS |
Standard Keywords¶
The following table lists the keywords that are required to be present in all reference files. The first column gives the FITS keyword names. The second column gives the jwst data model name for each keyword, which is useful when using data models in creating and populating a new reference file. The third column gives the equivalent meta tag in ASDF reference file headers, which is the same as the name within the data model meta tree (second column).
FITS Keyword |
Data Model Name |
ASDF meta tag |
|---|---|---|
AUTHOR |
model.meta.author |
author |
DATAMODL |
model.meta.model_type |
model_type |
DATE |
model.meta.date |
date |
DESCRIP |
model.meta.description |
description |
FILENAME |
model.meta.filename |
N/A |
INSTRUME |
model.meta.instrument.name |
instrument: {name} |
PEDIGREE |
model.meta.pedigree |
pedigree |
REFTYPE |
model.meta.reftype |
reftype |
TELESCOP |
model.meta.telescope |
telescope |
USEAFTER |
model.meta.useafter |
useafter |
NOTE: More information on standard required keywords can be found here: Standard Required Keywords
Type Specific Keywords for WAVELENGTHRANGE¶
In addition to the standard reference file keywords listed above, the following keywords are required in WAVELENGTHRANGE reference files
Keyword |
Data Model Name |
|---|---|
EXP_TYPE |
model.meta.exposure.type |
These keywords are used as CRDS selectors
Reference Selection Keywords for WAVELENGTHRANGE¶
CRDS selects appropriate WAVELENGTHRANGE references based on the following keywords. WAVELENGTHRANGE is not applicable for instruments not in the table. All keywords used for file selection are required.
Instrument |
Keywords |
|---|---|
MIRI |
INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS |
NIRCam |
INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS |
NIRISS |
INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS |
NIRSpec |
INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS |
Reference File Format¶
WAVELENGTHRANGE reference files are in ASDF format, with the format and contents
specified by the WavelengthrangeModel data model schema.
The exact content varies a bit depending on instrument mode, as explained in the
following sections.
MIRI MRS¶
For MIRI MRS, the WAVELENGTHRANGE file consists of two fields that define the wavelength range for each combination of channel and band.
- channels:
An ordered list of all possible channel and band combinations for MIRI MRS, e.g. “1SHORT”.
- wavelengthrange:
An ordered list of (lambda_min, lambda_max) for each item in the list above
NIRSpec¶
For NIRSpec, the WAVELENGTHRANGE file is a dictionary storing information about default wavelength range and spectral order for each combination of filter and grating.
- filter_grating:
- order:
Default spectral order
- range:
Default wavelength range
NIRCam WFSS, NIRCam TSGRISM, NIRISS WFSS¶
For NIRCam WFSS and TSGRIM modes, as well as NIRISS WFSS mode, the WAVELENGTHRANGE reference file contains the wavelength limits to use when calculating the minimum and maximum dispersion extents on the detector. It also contains the default list of orders that should be extracted for each filter. To be consistent with other modes, and for convenience, it also lists the orders and filters that are valid with the file.
- order:
A list of orders this file covers
- wavelengthrange:
A list containing the list of [order, filter, wavelength min, wavelength max]
- waverange_selector:
The list of FILTER names available
- extract_orders:
A list containing the list of orders to extract for each filter