FITS file structures and contents¶
Here we describe the structure and content of the most frequently used forms of FITS files for JWST science data products. Each type of FITS file is the result of serialization of a corresponding data model.
Common Features¶
All FITS science products have a few common features to their structure and organization:
- The primary Header-Data Unit (HDU) only contains header information, in the form of keyword records, with an empty data array, which is indicated by the occurence of NAXIS=0 in the primary header. Meta data that pertains to the entire product is stored in keywords in the primary header. Meta data related to specific extensions (see below) should be stored in keywords in the headers of those extensions.
- All data related to the product are contained in one or more FITS Image or Table extensions. The header of each extension may contain keywords that pertain uniquely to that extension.
Level-1 and Level-2 exposure-based products, which contain the data from an individual exposure on an individual detector, use the following file naming scheme:
jw{ppppp}{ooo}{vvv}_{gg}{s}{aa}_{eeeee}_{detector}_{suffix}.fits
where:
- ppppp: program ID number
- ooo: observation number
- vvv: visit number
- gg: visit group
- s: parallel sequence ID (1=prime, 2-5=parallel)
- aa: activity number (base 36)
- eeeee: exposure number
- detector: detector name (e.g. ‘nrca1’, ‘nrcblong’, ‘mirimage’)
- suffix: product type identifier (e.g. ‘uncal’, ‘rate’, ‘cal’)
An example Level-2a product FITS file name is:
jw93065002001_02101_00001_nrca1_rate.fits
Specific products¶
This section lists the organization and contents of each type of science product in FITS form.
Raw Level-1b (suffix = uncal
)¶
Exposure raw data (level-1b) products are designated with a file name suffix of “uncal.” These files usually contain only the raw pixel values from an exposure, with the addition of a table extension that contains some downlinked meta data pertaining to individual groups. Additional extensions can be included for certain instruments and readout types. If the zero-frame was requested to be downlinked, an additional image extension is included that contains those data. MIRI exposures also contain an additional image extension with the values from the reference output. The FITS file structure is as follows.
HDU | Content | EXTNAME | HDU Type | Data Type | Dimensions |
---|---|---|---|---|---|
0 | Primary header | N/A | N/A | N/A | N/A |
1 | Pixel values | SCI | IMAGE | uint16 | ncols x nrows x ngroups x nints |
2 | Group meta | GROUP | BINTABLE | N/A | variable |
3 | Zero frame images | ZEROFRAME | IMAGE | uint16 | ncols x nrows x nints |
4 | Reference output | REFOUT | IMAGE | uint16 | ncols x 256 x ngroups x nints |
The raw pixel values in the SCI extension are stored as a 4-D data array, having dimensions equal to the 2-D size of the detector readout, with the data from the multiple groups (ngroups) within each integration stored along the 3rd axis, and the multiple integrations (nints) stored along the 4th axis.
If zero-frame data are downlinked, there will be one zero-frame image for each integration, stored as a 3-D cube (each cube plane corresponds to an integration).
Level-2 ramp data (suffix = ramp
)¶
As soon as raw level-1b products are loaded into the calibration
pipeline the contents of the product is modified to include
additional data extensions, as well as converting the raw SCI
(and ZEROFRAME and REFOUT, if present) array values from integer to
floating-point data type. New data arrays that are added include an
ERR extension and two types of data quality flag extensions. There
is a 2-D PIXELDQ
extension that will contain flags that pertain
to all groups and all integrations, and there is also a 4-D
GROUPDQ
extension for containing flags that pertain to individual
groups within individual integrations. The FITS file layout is as
follows:
HDU | Content | EXTNAME | HDU Type | Data Type | Dimensions |
---|---|---|---|---|---|
0 | Primary header | N/A | N/A | N/A | N/A |
1 | Pixel values | SCI | IMAGE | float32 | ncols x nrows x ngroups x nints |
2 | 2-D data quality | PIXELDQ | IMAGE | uint32 | ncols x nrows |
3 | 4-D data quality | GROUPDQ | IMAGE | uint8 | ncols x nrows x ngroups x nints |
4 | Error values | ERR | IMAGE | float32 | ncols x nrows x ngroups x nints |
Any additional extensions that were present in the raw level-1b file (e.g. GROUP, ZEROFRAME, REFOUT) will be carried along and will also appear in the level-2 ramp product.
Level-2a countrate products (suffix = rate
and rateints
)¶
Countrate products are produced by applying ramp-fitting to the
integrations within an exposure, in order to compute count rates
from the original accumulating signal. For exposures that
contain multiple integrations (nints > 1) this is done in two ways,
which results in two separate products that are produced. First,
countrates are computed for each integration within the exposure,
the resuls of which are stored in a rateints
product. These
products will contain 3-D science data arrays, where each plane
of the data cube contains the countrate image for an integration.
The results for each integration are also averaged together to
form a single 2-D countrate image for the entire exposure. These
resuls are stored in a rate
product.
The FITS file structure for a rateints
product is as follows:
HDU | Content | EXTNAME | HDU Type | Data Type | Dimensions |
---|---|---|---|---|---|
0 | Primary header | N/A | N/A | N/A | N/A |
1 | Pixel values | SCI | IMAGE | float32 | ncols x nrows x nints |
2 | Data quality | DQ | IMAGE | uint32 | ncols x nrows x nints |
3 | Error values | ERR | IMAGE | float32 | ncols x nrows x nints |
The FITS file structure for a rate
product is as follows:
HDU | Content | EXTNAME | HDU Type | Data Type | Dimensions |
---|---|---|---|---|---|
0 | Primary header | N/A | N/A | N/A | N/A |
1 | Pixel values | SCI | IMAGE | float32 | ncols x nrows |
2 | Data quality | DQ | IMAGE | uint32 | ncols x nrows |
3 | Error values | ERR | IMAGE | float32 | ncols x nrows |
Note that the two separate forms of PIXELDQ and GROUPDQ flags from the previous types of products have been combined into a single DQ extension with the same dimensions as the SCI and ERR components.
Level-2b calibrated products (suffix = cal
and calints
)¶
Single exposure calibrated products duplicate the format and content of
level-2a products. As with level-2a, there are two different forms of
calibrated products: one containing results for individual integrations
(calints
) and one for exposure-wide results (cal
).
The FITS file structure for a calints
product is as follows:
HDU | Content | EXTNAME | HDU Type | Data Type | Dimensions |
---|---|---|---|---|---|
0 | Primary header | N/A | N/A | N/A | N/A |
1 | Pixel values | SCI | IMAGE | float32 | ncols x nrows x nints |
2 | Data quality | DQ | IMAGE | uint32 | ncols x nrows x nints |
3 | Error values | ERR | IMAGE | float32 | ncols x nrows x nints |
The FITS file structure for a cal
product is as follows:
HDU | Content | EXTNAME | HDU Type | Data Type | Dimensions |
---|---|---|---|---|---|
0 | Primary header | N/A | N/A | N/A | N/A |
1 | Pixel values | SCI | IMAGE | float32 | ncols x nrows |
2 | Data quality | DQ | IMAGE | uint32 | ncols x nrows |
3 | Error values | ERR | IMAGE | float32 | ncols x nrows |