# 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

uncertainty

float

scalar

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

uncertainty

float

scalar

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

uncertainty

float

scalar

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

uncertainty

float

scalar

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

uncertainty

float

scalar

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

uncertainty

float

scalar

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

uncertainty

float

scalar

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

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.

## 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 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

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