Reference Files

The photom step uses PHOTOM and pixel AREA reference files. The AREA reference file is only used when processing imaging and NIRSpec IFU observations.

PHOTOM Reference File

REFTYPE:

PHOTOM

The PHOTOM reference file contains conversion factors for putting pixel values into physical units.

Reference Selection Keywords for PHOTOM

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

Instrument	Keywords
FGS	INSTRUME, DETECTOR, DATE-OBS, TIME-OBS
MIRI	INSTRUME, DETECTOR, BAND, DATE-OBS, TIME-OBS
NIRCam	INSTRUME, DETECTOR, DATE-OBS, TIME-OBS
NIRISS	INSTRUME, DETECTOR, 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 PHOTOM

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

Keyword	Data Model Name	Instruments
DETECTOR	model.meta.instrument.detector	FGS, MIRI, NIRCam, NIRISS
EXP_TYPE	model.meta.exposure.type	All
BAND	model.meta.instrument.band	MIRI

Tabular PHOTOM Reference File Format

PHOTOM reference files are FITS format. For all modes except MIRI MRS, the PHOTOM file contains tabular data in a BINTABLE extension with EXTNAME = ‘PHOTOM’. The FITS primary HDU does not contain a data array. The contents of the table extension vary a bit for different instrument modes, as shown in the tables below.

Data model:

FgsImgPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
FGS	Image	photmjsr	float	scalar	MJy/steradian/(DN/sec)
		uncertainty	float	scalar	MJy/steradian/(DN/sec)

Data model:

MirImgPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
MIRI	Image	filter	string	12	N/A
		subarray	string	15	N/A
		photmjsr	float	scalar	MJy/steradian/(DN/sec)
		uncertainty	float	scalar	MJy/steradian/(DN/sec)

The MIRI Imager PHOTOM reference file can contain an optional BINTABLE extension named “TIMECOEFF”, containing coefficients for an time-dependent correction. The format of this additional table extension is as follows:

EXTNAME	XTENSION	NAXIS	Dimensions	Data type
TIMECOEFF	BINTABLE	2	TFIELDS = 3	float32

Data model:

MirLrsPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
MIRI	LRS	filter	string	12	N/A
		subarray	string	15	N/A
		photmjsr	float	scalar	MJy/steradian/(DN/sec)
		uncertainty	float	scalar	MJy/steradian/(DN/sec)
		nelem	integer	scalar	N/A
		wavelength	float	array	microns
		relresponse	float	array	unitless
		reluncertainty	float	array	unitless

Data model:

NrcImgPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
NIRCam	Image	filter	string	12	N/A
		pupil	string	12	N/A
		photmjsr	float	scalar	MJy/steradian/(DN/sec)
		uncertainty	float	scalar	MJy/steradian/(DN/sec)

Data model:

NrcWfssPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
NIRCam	WFSS	filter	string	12	N/A
		pupil	string	15	N/A
		order	integer	scalar	N/A
		photmjsr	float	scalar	MJy/steradian/(DN/sec)
		uncertainty	float	scalar	MJy/steradian/(DN/sec)
		nelem	integer	scalar	N/A
		wavelength	float	array	microns
		relresponse	float	array	unitless
		reluncertainty	float	array	unitless

Data model:

NisImgPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
NIRISS	Image	filter	string	12	N/A
		pupil	string	12	N/A
		photmjsr	float	scalar	MJy/steradian/(DN/sec)
		uncertainty	float	scalar	MJy/steradian/(DN/sec)

Data model:

NisSossPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
NIRISS	SOSS	filter	string	12	N/A
		pupil	string	15	N/A
		order	integer	scalar	N/A
		photmj	float	scalar	MJy/(DN/sec)
		uncertainty	float	scalar	MJy/(DN/sec)
		nelem	integer	scalar	N/A
		wavelength	float	array	microns
		relresponse	float	array	unitless
		reluncertainty	float	array	unitless

Data model:

NisWfssPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
NIRISS	WFSS	filter	string	12	N/A
		pupil	string	15	N/A
		order	integer	scalar	N/A
		photmjsr	float	scalar	MJy/steradian/(DN/sec)
		uncertainty	float	scalar	MJy/steradian/(DN/sec)
		nelem	integer	scalar	N/A
		wavelength	float	array	microns
		relresponse	float	array	unitless
		reluncertainty	float	array	unitless

Data model:

NrsFsPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
NIRSpec	Fixed Slit	filter	string	12	N/A
		grating	string	15	N/A
		slit	string	15	N/A
		photmj	float	scalar	MJy/(DN/sec)
		uncertainty	float	scalar	MJy/(DN/sec)
		nelem	integer	scalar	N/A
		wavelength	float	array	microns
		relresponse	float	array	unitless
		reluncertainty	float	array	unitless

Data model:

NrsMosPhotomModel

Instrument	Mode	Column name	Data type	Dimensions	Units
NIRSpec	MOS and IFU	filter	string	12	N/A
		grating	string	15	N/A
		photmj	float	scalar	MJy/(DN/sec)
		uncertainty	float	scalar	MJy/(DN/sec)
		nelem	integer	scalar	N/A
		wavelength	float	array	microns
		relresponse	float	array	unitless
		reluncertainty	float	array	unitless

Row Selection

A row of data within the table is selected by the photom step based on the optical elements in use for the exposure. The selection attributes are always contained in the first few columns of the table. The remaining columns contain the data needed for photometric conversion. The row selection criteria for each instrument/mode are:

• FGS:

  • No selection criteria (table contains a single row)

• MIRI:

  • Imager and LRS: Filter and Subarray

  • MRS: Does not use table-based reference file (see below)

• NIRCam:

  • All: Filter and Pupil

• NIRISS:

  • Imaging: Filter and Pupil

  • Spectroscopic: Filter, Pupil, and Order number

• NIRSpec:

  • IFU and MOS: Filter and Grating

  • Fixed Slits: Filter, Grating, and Slit name

Note: For spectroscopic data the Nelem column should be present. Its value must be greater than 0, and Nelem entries are read from each of the Wavelength and Relresponse arrays. Nelem is not used for imaging data because there are no columns containing arrays.

The primary header of the tabular PHOTOM reference files contains the keywords PIXAR_SR and PIXAR_A2, which give the average pixel area in units of steradians and square arcseconds, respectively.

MIRI MRS Photom Reference File Format

Data model:

MirMrsPhotomModel

For MIRI MRS, the PHOTOM file contains 2-D arrays of conversion factors in IMAGE extensions. The FITS primary HDU does not contain a data array. The format and content of the MIRI MRS PHOTOM reference file is as follows:

EXTNAME	XTENSION	NAXIS	Dimensions	Data type
SCI	IMAGE	2	1032 x 1024	float
ERR	IMAGE	2	1032 x 1024	float
DQ	IMAGE	2	1032 x 1024	integer
PIXSIZ	IMAGE	2	1032 x 1024	float
DQ_DEF	BINTABLE	2	TFIELDS = 4	N/A
TIMECOEFF_CH1 [1]	BINTABLE	2	TFIELDS = 5	N/A
TIMECOEFF_CH2 [1]	BINTABLE	2	TFIELDS = 5	N/A
TIMECOEFF_CH3 [1]	BINTABLE	2	TFIELDS = 5	N/A
TIMECOEFF_CH4 [1]	BINTABLE	2	TFIELDS = 5	N/A

Footnotes

[1] (1,2,3,4)

Optional extension. If present, the MRS time-dependent throughput correction can be applied.

The SCI extension contains a 2D array of inverse sensitivity factors corresponding to each pixel in a 2D MRS slice image. The sensitivity factors are in units of (MJy/pixel)/(DN/sec). The ERR extension contains a 2D array of uncertainties for the SCI values, in the same units. The DQ extension contains a 2D array of bit-encoded data quality flags for the SCI values. The DQ_DEF extension contains a table listing the definitions of the values used in the DQ array. The PIXSIZ extension contains a 2D array of pixel sizes (i.e. solid angles), in units of square-arcsec.

The SCI and PIXSIZ array values are both divided into the science product SCI and ERR arrays, yielding surface brightness in units of mJy/sq-arcsec.

Scalar PHOTMJSR and PHOTUJA2 values are stored in primary header keywords in the MIRI MRS PHOTOM reference files and are copied into the science product header by the photom step.

The TIMECOEFF_CH tables contain the parameters to correct the MRS time-dependent throughput loss. If these tables do not exist in the reference file, then the MIRI MRS time-dependent correction is skipped.

Constructing a PHOTOM Reference File

The most straight-forward way to construct a tabular PHOTOM reference file is to populate a data model within python and then save the data model to a FITS file. Each instrument mode has its own photom data model, as listed above, which contains the columns of information unique to that instrument.

A NIRCam WFSS photom reference file, for example, could be constructed as follows from within the python environment:

>>> import numpy as np
>>> from stdatamodels.jwst import datamodels
>>> filter = np.array(['GR150C', 'GR150R'])
>>> pupil = np.array(['F140M', 'F200W'])
>>> order = np.array([1, 1], dtype=np.int16)
>>> photf = np.array([1.e-15, 3.e-15], dtype=np.float32)
>>> uncer = np.array([1.e-17, 3.e-17], dtype=np.float32)
>>> nrows = len(filter)
>>> nx = 437
>>> nelem = np.zeros(nrows, dtype=np.int16) + nx
>>> temp_wl = np.linspace(1.0, 5.0, nx, dtype=np.float32).reshape(1, nx)
>>> wave = np.zeros((nrows, nx), np.float32)
>>> wave[:] = temp_wl.copy()
>>> resp = np.ones((nrows, nx), dtype=np.float32)
>>> resp_unc = np.zeros((nrows, nx), dtype=np.float32)
>>> data_list = [(filter[i], pupil[i], order[i], photf[i], uncer[i], nelem[i],
...               wave[i], resp[i], resp_unc[i]) for i in range(nrows)]
>>> data = np.array(data_list,
...                 dtype=[('filter', 'S12'),
...                        ('pupil', 'S15'),
...                        ('order', '<i2'),
...                        ('photmjsr', '<f4'),
...                        ('uncertainty', '<f4'),
...                        ('nelem', '<i2'),
...                        ('wavelength', '<f4', (nx,)),
...                        ('relresponse', '<f4', (nx,)),
...                        ('reluncertainty', '<f4', (nx,))])
>>> output = datamodels.NrcWfssPhotomModel(phot_table=data)
>>> output.save('nircam_photom_0001.fits')
'nircam_photom_0001.fits'

AREA Reference File

REFTYPE:

AREA

The AREA reference file contains pixel area information for a given instrument mode.

Reference Selection Keywords for AREA

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

Instrument	Keywords
FGS	INSTRUME, DETECTOR, DATE-OBS, TIME-OBS
MIRI	INSTRUME, DETECTOR, FILTER, EXP_TYPE, DATE-OBS, TIME-OBS
NIRCam	INSTRUME, DETECTOR, FILTER, PUPIL, EXP_TYPE, DATE-OBS, TIME-OBS
NIRISS	INSTRUME, DETECTOR, FILTER, PUPIL, EXP_TYPE, DATE-OBS, TIME-OBS
NIRSpec	INSTRUME, DETECTOR, FILTER, GRATING, 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 AREA

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

Keyword	Data Model Name	Instrument
DETECTOR	model.meta.instrument.detector	All
EXP_TYPE	model.meta.exposure.type	MIRI, NIRCam, NIRISS, NIRSpec
FILTER	model.meta.instrument.filter	MIRI, NIRCam, NIRISS, NIRSpec
PUPIL	model.meta.instrument.pupil	NIRCam, NIRISS
GRATING	model.meta.instrument.grating	NIRSpec

Reference File Format

AREA reference files are FITS format. For imaging modes (FGS, MIRI, NIRCam, and NIRISS) the AREA reference files contain 1 IMAGE extension, while reference files for NIRSpec spectroscopic modes contain 1 BINTABLE extension. The FITS primary HDU does not contain a data array.

Imaging Modes

Data model:

PixelAreaModel

The format of imaging mode AREA reference files is as follows:

EXTNAME	XTENSION	NAXIS	Dimensions	Data type
SCI	IMAGE	2	ncols x nrows	float

The SCI extension data array contains a 2-D pixel-by-pixel map of relative pixel areas, normalized to a value of 1.0. The absolute value of the nominal pixel area is given in the primary header keywords PIXAR_SR and PIXAR_A2, in units of steradians and square arcseconds, respectively. These keywords should have the same values as the PIXAR_SR and PIXAR_A2 keywords in the header of the corresponding PHOTOM reference file.

NIRSpec Fixed-Slit Mode

Data model:

NirspecSlitAreaModel

The BINTABLE extension has EXTNAME=’AREA’ and has column characteristics shown below. There is one row for each of the 5 fixed slits, with slit_id values of “S200A1”, “S200A2”, “S400A1”, “S200B1”, and “S1600A1”. The pixel area values are in units of square arcseconds and represent the nominal area of any pixel illuminated by the slit.

Column name	Data type
slit_id	char*15
pixarea	float

NIRSpec MOS Mode

Data model:

NirspecMosAreaModel

The BINTABLE extension has EXTNAME=’AREA’ and has column characteristics shown below. There is one row for each shutter in each MSA quadrant. The quadrant and shutter values are 1-indexed. The pixel area values are in units of square arcseconds and represent the nominal area of any pixel illuminated by a given MSA shutter.

Column name	Data type
quadrant	integer
shutter_x	integer
shutter_y	integer
pixarea	float

NIRSpec IFU Mode

Data model:

NirspecIfuAreaModel

The BINTABLE extension has EXTNAME=’AREA’ and has column characteristics shown below. There is one row for each of the 30 IFU slices, with the slice_id values being 0-indexed (i.e. range from 0 to 29). The pixel area values are in units of square arcseconds and represent the nominal area of any pixel illuminated by a given IFU slice.

Column name	Data type
slice_id	integer
pixarea	float