Reference Files

The refpix step uses a REFPIX reference file, but only when processing NIRSpec exposures that have been acquired using an IRS2 readout pattern. No other instruments or exposure modes require a reference file for this step.

REFPIX Reference File

REFTYPE:

REFPIX

Data model:

IRS2Model

The REFPIX reference file contains the complex coefficients for the correction.

Reference Selection Keywords for REFPIX

CRDS selects appropriate REFPIX references based on the following keywords. REFPIX is not applicable for instruments not in the table. All keywords used for file selection are required.

Instrument	Keywords
NIRSpec	INSTRUME, DETECTOR, READPATT, 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 REFPIX

In addition to the standard reference file keywords listed above, the following keywords are required in REFPIX reference files, because they are used as CRDS selectors (see Reference Selection Keywords for REFPIX):

Keyword	Data Model Name
DETECTOR	model.meta.instrument.detector
READPATT	model.meta.exposure.readpatt

Reference File Format

REFPIX reference files are FITS format, with two BINTABLE extensions. The FITS primary HDU does not contain a data array. The first BINTABLE extension is labeled with EXTNAME = “IRS2” and has the following column characteristics:

Column	Data type
alpha_0	float32
alpha_1	float32
alpha_2	float32
alpha_3	float32
beta_0	float32
beta_1	float32
beta_2	float32
beta_3	float32

The “alpha” arrays contain correction multipliers to the reference output, and the “beta” arrays contain correction multipliers to the interleaved reference pixels. Both arrays have 4 components, one for each sector (amplifier output). These are applied to (i.e. multiplied by) the Fourier transform of the interleaved reference pixel data. The coefficients are intrinsically complex values, but have their real and imaginary parts stored in alternating table rows, i.e. row 1 contains the real components of all coefficients and row 2 contains the corresponding imaginary components for each. This storage scheme results in a total of 2916352 (2048 * 712 * 2) rows in the table.

The second BINTABLE extension is labeled with EXTNAME = “DQ” and has the following column characteristics:

Column	Data type
output	int16
odd_even	int16
mask	uint32

This table has eight rows. The “output” column contains the amplifier output numbers: 1, 1, 2, 2, 3, 3, 4, 4. The “odd_even” column contains values 1 or 2, indicating that either the first or second pair of reference pixel reads respectively should be regarded as bad. The “mask” column contains 32-bit unsigned integer values. The interpretation of these values was described in the ESA CDP3 document as follows:

“There is also a DQ extension that holds a binary table with three columns (OUTPUT, ODD_EVEN, and MASK) and eight rows. In the current IRS2 implementation, one jumps 32 times to odd and 32 times to even reference pixels, which are then read twice consecutively. Therefore, the masks are 32 bit unsigned integers that encode bad interleaved reference pixels/columns from left to right (increasing column index) in the native detector frame. When a bit is set, the corresponding reference data should not be used for the correction.”

We assume that “native detector frame” in the above description referred to the order that the data and interleaved reference pixels were read out from the detector, not the physical locations of the pixels on the detector. The difference is that the readout direction changes when going from one amplifier output to the next; that is, the pixels are read out from left to right for the first and third outputs, and they are read out from right to left for the second and fourth outputs. Furthermore, we assume that for the first amplifier output, it is the least significant bit in the value from the MASK column that corresponds to the first set of four reads of interleaved reference pixel values (reading pixels from left to right).