# Section 8. Near Infrared Camera and Multi-Object Spectrometer¶

The Near Infrared Camera and Multi-Object Spectrometer (NICMOS) data that an observer receives are calibrated in the pipeline by the following STSDAS calibration routines: CalTempFromBias, calnica, calnicb and runcalsaa. These routines perform different operations:

CalTempFromBias: This routine calculates the temperature of the detector from the measured bias levels. It runs only on the MULTIACCUM observations and runs on the *_raw.fits files.

calnica: This routine removes the instrumental signature from the science data. It is the first calibration step, and is applied to all NICMOS datasets individually. Calnica operates on the raw science data files.

calnicb: This routine operates on associations: it co-adds datasets obtained from multi images at individual pattern position, identify sources in the imge and remove the backgroun signal. It creates a mosaic image from all the pattern positions. Calnicb is applied to the calibrated science data files (usually the output from calnica), and requires association tables (*_asn.fits) and the telemetry and engineering data files (*_spt.fits).

uuncalsaa: This routine in the pipeline comprises of two PyRAF tasks, saaclean and nic_rem_persist which are available in the stsdas.hst_calib.nicmos package.

SAACLEAN - Removing SAA Persistence from NICMOS Images

This task is run on post-SAA NICMOS images to identify the amount of charge in each pixel that can be attributed to persistent flux from SAA cosmic rays, and apply a correction based on an SAA persistence model to remove this flux from the data. Saaclean runs on a single science image (i.e. not on all the separate readouts of a NICMOS MULTIACCUM file). If applicable it operates on the [SCI,1] extension of cal.fits files that are the final product of the “calnica” calibration pipeline. It is run only when the SAA_DARK and FLATFILE keywords are populated in the raw file header.

By default, saaclean will produce an image of the SAA persistence signal by scaling and combining the two SAA exposures associated with the science image as specified in the SAADARK related keywords in the header file. In this case, the associated images and their _asn file must be present in the directory with the science image. Alternatively, a pre-existing SAA persistence image can be specified by the user.

NIC_REM_PERSIST: Removing Bright Earth Persistence from NICMOS images

NICMOS detectors may be exposed to another type of persistence, Bright Earth Persistence (BEP, This occurs in rare instances when HST is pointed towards the bright earth and one or more of the NICMOS filter wheels are not yet in the blank position.

A stored BEP persistence image is scaled to the measured persistence and subtracted from the science image.The task nic_rem_persist uses persistence model file given by the keyword PMODFILE, and persistence mask file given by the keyword PMSKFILE. Both these reference files are specific for each camera. Calibration indicator BEPDONE indicates whether the BEP correction was applied or not. Bright Earth Persistence keyword BEPSCALE shows the level of persistence calculated, a default value of BEPVALLO=0.5 shows minimum allowed value of the persistence to apply, a default value of BEPUSELO=0.5 shows minimum allowed fraction of pixels used and BEPFRAC gives the fraction of pixels used to calculate persistence.

The CalTempFromBias, calnica, and calnicb tasks are available in STSDAS in the hst_calib.nicmos package. The runcalsaa routine in the pipeline comprises of two PyRAF tasks, saaclean and nic_rem_persist which are also available in the hst_calib.nicmos package.

Section 8.1 defines the format and structure of the reference files and tables. Section 8.2 describes the file name extensions and keyword requirements. Sections 8.3 and 8.4 detail the reference files and tables, respectively. Section 8.5 presents the rules for calibration switches currently used by OPUS. Section 8.6 documents the current NICMOS generic science image header.

The following reference files and tables are used by calnica.

Read Noise Files: The noise file contains the readout noise for each pixel as the 1 standard deviation noise level in electrons.

Dark Files: Dark current reference files.

Temperature Dependent Darks: Temperature dependent dark reference files. It takes into account the temperature dependence of the dark signal.

Linearity Correction Files: This file is used for correcting the integrated counts in the science image for the non-linear response of the detectors and it also contains the saturation limits for each pixel in the array.

Temperature Dependent Flat Fields Temperature dependent flatfield reference files. The TDFFILE file contains five imsets, each with a flat-field image valid for a particular temperature range.

Flat Field Files: Static flatfield reference files.

Photometric Calibration Tables: These are binary tables containing the photometry parameters for all observation modes.

## 8.1 File Formats¶

The NICMOS calibration reference files (hereafter, reference files) share the same format and structure as all the NICMOS image datasets. This has been defined in detail in Instrument Science Report (ISR) NICMOS-002 (J.W. MacKenty, H. Bushouse, and C. Skinner: STScI, July 1995). The major points are summarized below.

### 8.1.1 NICMOS¶

NICMOS images are in FITS format using image extensions. The primary header contains all keywords not specific to individual extensions. All image data resides in the image extensions. The primary data unit in NICMOS files is always empty, as indicated by the NAXIS = 0 keyword setting in the primary header.

### 8.1.2 NICMOS Observation Datasets¶

All NICMOS observation datasets contain sets of five image extensions (hereafter referred to as an “imsets”) namely SCI, ERR, DQ, SAMP, and TIME. The name of the extension is stored in the keyword EXTNAME. A science data file can contain one or more imsets. The order of the images in the FITS files is listed in the table below. For example, an individual NICMOS exposure obtained with the ACCUM mode will generate a *_raw.fits file with one imset; an individual MULTIACCUM exposure with n readouts will generate a *_raw.fits file (and, after calibration, an *_ima.fits file) containing n + 1 imsets, including the zeroth readout. The *_cal.fits and *_mos.fits files always contain one imset.

All reference files (with the exception of the linearity file) follow this structure. All NICMOS science and reference file images have dimensions of 256 by 256 pixels; thus reference data are always applied to the science data in pixel space.

Header-Data Unit Extension Name imset Contents Data Type
Primary (Extension 0) (N/A) (N/A) Global keywords; no data. (N/A)
Extension 1 SCI 1 Science image raw: 16-bit int; calibrated: float
Extension 2 ERR 1 Error (sigma) image float
Extension 3 DQ 1 Data Quality image 16-bit int
Extension 4 SAMP 1 Number of Samples image 16-bit int
Extension 5 TIME 1 Integration Time image float
Extension 6 SCI 2 Science image raw: 16-bit int; calibrated: float
Extension 7 ERR 2 Error (sigma) image float
Extension 8 DQ 2 Data Quality image 16-bit int
Extension 9 SAMP 2 Number of Samples image 16-bit int
Extension 10 TIME 2 Integration Time image float

Local STScI conventions allow for images containing a constant value in all pixels to be stored as an empty FITS data array, indicated by NAXIS = 0 in the image extension header. In these cases the dimensions of the constant array are stored in the NPIX1 and NPIX2 image extension header keywords, set to values of 256 for NICMOS data, and the constant pixel value is stored in the PIXVALUE keyword of the extension header. The contents and purpose of each of the five image extensions that comprise a NICMOS imset are as follows:

Science Image (SCI): This image contains the data from the detector readout. In ACCUM and BRIGHTOBJ modes the image received from the instrument is the result of subtracting the initial from the final readouts of the exposure. In MULTIACCUM mode the images received are the raw (unsubtracted) data corresponding to each detector readout. In raw datasets the science array is an integer (16-bit) image in units of DNs (counts). In calibrated datasets it is a floating-point image in units of DNs per second (count rates).

Error Array (ERR): The error image is a floating-point array containing an estimate of the statistical uncertainty associated with each corresponding science image pixel. This image is computed in the ground calibration pipeline task calnica as a combination of detector read noise and Poisson noise in the accumulated science image counts (see Chapter 3) and corresponds to 1 sigma uncertainties. For calibrated MULTIACCUM images (i.e., *_cal.fits files), the values of the error array are computed uncertainties in the count rates derived from the linear fit to counts vs. exposure time from the intermediate readouts.

Data Quality Array (DQ): This integer (unsigned 16-bit) array contains bit-encoded data quality flags indicating various status and problem conditions associated with corresponding pixels in the science image. Because the flag values are bit-encoded, a total of 16 simultaneous conditions can be associated witheach pixel. The current list of NICMOS data quality flags is given in Section 8.1.3.

Samples Array (SAMP): The SAMP image is an integer (16-bit) array containing the total number of data samples that were used to compute the corresponding pixel values in the science image. For ACCUM and BRIGHTOBJ modes, the number of samples contributing to each pixel always has a value of 1 in the raw data file. For MULTIACCUM mode the sample values in the raw and intermediate data files are set to the number of readouts that contributed to the corresponding science image.

Integration Time Array (TIME): The TIME image is a floating-point array containing the effective integration time associated with each corresponding science image pixel value. These data are always computed in the ground calibration pipeline for recording in the raw data file.

### 8.1.3 NICMOS Data Quality Flags¶

The data quality flags for each pixel in a NICMOS dataset are defined below. Their use with individual reference files is discussed in Section 8.3. User flags should be used by application software and will not be used in the delivered datasets in the future. Each flag occupies one bit in a 16-bit short integer word, where bit 0 is the least significant bit:

Bit Condition
0 No known problems
1 Reed-Solomon error
2 Poor or uncertain linearity correction
4 Poor or uncertain dark correction
8 Poor or uncertain flat field correction
16 Pixel affected by grot on the detector
32 Defective (hot or cold) pixel
64 Saturated pixel
128 Missing data in telemetry
256 Bad pixel determined during calibration
512 Pixel contains cosmic ray
1024 Pixel contains source
2048 Pixel has signal on 0th read
4096 Cosmic ray detected by MultiDrizzle
8192 User flag
16384 Curvature in detector response

## 8.2 Calibration Reference File and Table Names and Keywords¶

### 8.2.1 Reference File Naming Convention¶

The calibration reference files and tables use the formats defined in Section 8.1. Their file names are constructed from the standard CDBS unique name, an underscore, a three-letter suffix, and the extension .FITS. Each operational reference file past or present has a unique name. The file name root has the format YMDHHMMSI where:

Y  denotes the year (1->Z, 1981=1)
M  denotes the month (1->C, January = 1)
D  denotes the day of the month (1->V)
HH denotes the hour (00->23)
MM denotes the minutes (00->59)
S  denotes seconds/2 (0->T)
I  denotes the instrument
(j=ACS, n=NICMOS, u=WFPC2, o=STIS, f=FGS, l=COS, i=WFC3
v=HSP, w=WFPC, x=FOC, y=FOS, z=GHRS, m=multiple)

The file name extension which is defined by file type is appended to the unique root.

### 8.2.2 Reference File Keyword Conventions¶

The headers of the reference files follow the generic NICMOS science data file format as described in Section 8.6 and defined in STScI ICD-19. While a valid reference file may omit some or all of the keywords marked with a leading asterisk (*), general practice should be to keep the header keywords identical to the present output of OPUS generic conversion. Appropriate null values may optionally be inserted for keywords marked with an asterisk. All keywords not marked with an asterisk must be included. The reasoning behind the retention of a broad set of keywords (e.g., pointing information) is so that generic software (e.g., display tasks) will be able to use these files without generating exceptions for missing keywords. To that end, the inclusion of benign values in these keywords within reference data is strongly encouraged.

To support the operation of calnica* and calnicb , some reference files require additional keywords. These keywords, along with the essential selection and control keywords, are defined in Section 8.3.

Also, history header records documenting the sources of the calibration data at a level that (generally) would make it possible to recreate the reference file are required.

### 8.2.3 Reference Table Keyword Conventions¶

The headers of the reference tables are much shorter than the headers of the reference files. They are fully specified in Section 8.4.

Also, history header records documenting the sources of the calibration data at a level that (generally) would make it possible to recreate the reference table are required.

## 8.3 Calibration Reference Files for CALNICA¶

This contains a flag array for known bad (hot or cold) pixels with flag value DQ = 32. There is one MASKFILE for each detector. Besides the truly “defective” bad pixels included in the MASKFILE reference images there are other bad pixels, for example, pixels affected by “grot”. In the MASKFILE, pixels affected by “grot” have a flag value DQ =16.

Format: Flag values from the static bad pixel mask file are added to the DQ image. Pixels that are not flagged contain the value of 0.

Flags and Indicators: Selected by the keyword CAMERA (which can be 1, 2, or 3)

Restrictions: It is legitimate for the image extensions other than SCI and DQ to be null arrays (i.e., NAXIS = 0, following the STScI convention).

CAMERA =            / camera in use (1, 2, or 3)            I2
PEDIGREE=           / reference file pedigree i             C68
DESCRIP =           / reference file description i          C68

### 8.3.2 Noise File (NOI): <unique name>_NOI.FITS¶

The noise file contains the noise model for each of the NICMOS detectors. Currently the noise model is a simple combination of detector read noise and Poisson noise in the signal, such that:

where \sigma_{rd} is the read noise in units of electrons, adcgain is the analog-to-digital conversion gain factor in electrons per DN (given by header keyword ADCGAIN). Noise is computed in units of electrons, but the result is converted to units of DNs for storage in the error image. The detector read noise is read pixel-by-pixel from the *_noi.fits image. The data quality flags set in the DQ image of the *_noi.fits file are propagated into the DQ images of all image sets (imsets) being processed.

Reference files for both FAST and SLOW readout modes are supported. Multiple readouts do not produce a simple NREAD reduction in readout noise and therefore NOI reference files for various NREAD values are required. If there is not a NOI reference file corresponding to a particular NREAD value for a science observation, the closest match will be used.

Format: The floating-point noise values, in units of electrons, are stored in the SCI array. When appropriate, data quality flags are included in the DQ array and are propagated forward by calnica. The ERR array may contain uncertainty estimates for the noise values but are not required or used by calnica at this time.

Flags and Indicators: Selected by the keywords CAMERA (which can be 1, 2, or 3), READOUT (FAST or SLOW), and NREAD (1-25).

Restrictions: It is legitimate for the image extensions other than SCI and DQ to be null arrays (i.e., NAXIS = 0, following the STScI convention).

CAMERA =                / camera in use (1, 2, or 3)                    I2
NREAD =                 / ACCUM - number of initial and final readouts  I2
PEDIGREE=               / reference file pedigree                       C68
DESCRIP =               / reference file description                    C68

### 8.3.3 Dark Current File (DRK): <unique name>_DRK.FITS and Temperature Dependent dark file :<unique name>_TDD.FITS¶

The dark current file contains the measured dark current for each of a set of exposure times; optimal removal is accomplished by the subtraction of a dark image of equivalent exposure time. Since the number of achievable exposure times is prohibitively large, data obtained with exposure times not in the calibrateduset will be corrected by interpolated dark current values.

Dark reference files do not include any temperature dependence of the dark signal. To also include this, new temperature dependent TEMPFILE reference files have been created.

Images taken in Cycles 7 and 7N that are retrieved after March 2002 have the TEMPFILE keyword set. This is also the case for images in Cycle 11 and later if retrieved after September 2002. However, for the latter images, the full temperature dependence of all components was not implemented until May 2009. If both the DARKFILE and TEMPFILE keywords are set in the header of the *_raw.fits file, then calnica uses the TEMPFILE in the DARKCORR step. For images retrieved before the dates given above, where only the DARKFILE exists, observers may want to consider using the OTFR to download their images again to include the temperature dependence of the dark signal in the image calibration.

For more details please refer to DARKCORR step in Section 3.2.2 of NICMOS Data Handbook (http://www.stsci.edu/hst/nicmos/documents/handbooks/DataHandbookv8/nic_ch3.7.4.html#392648)

For BRIGHTOBJ mode data, dark subtraction is skipped by default in calnica, since short exposure times result in insignificant dark current relative to the object signal.

Format: The dark current file follows the generic NICMOS format with one imset for each dark exposure time. The calnica DARKCORR step subtracts the dark reference images, readout-by-readout for MULTIACCUM observations, from the science data. Error estimates of the dark current, stored in the ERR images of the DARKFILE, are propagated in quadrature into the ERR images of all processed science imsets. Data quality (DQ) flags set in the DARKFILE are also propagated into the DQ images of all processed imsets.

The primary header of the dark current file will contain special keywords indicating the total number of dark current images (imsets) in the file and a list of the exposure times corresponding to each image. These keywords are necessary for calnica to know what exposure times are available in the reference file.

The keywords are as follows:

NUMEXPOS: Integer keyword indicating the number of exposures in the file
EXPOS_n: Floating-point exposure time for image <n>, where <n> is a value from 1 to
NUMEXPOS (maximum of 99), with no leading zero for values of < 10

Flags and Indicators: The dark current file is selected by CAMERA (which can be 1, 2, or 3), NREAD (1-25), READOUT (FAST or SLOW), and SAMP_SEQ (NONE, SCAMRR, MCAMRR, STEP1, STEP2, STEP8, STEP16, STEP32, STEP64, STEP128, STEP256, MIF512, MIF1024, MIF2048, MIF3072, SPARS64, or SPARS256).

The Temperature Dependent Dark file is selected by CAMERA (which can be 1, 2, or 3) and TEMPKEY (NDWTMP11, NDWTMP13)

Restrictions: It is legitimate for the image extensions other than SCI, ERR, and DQ to be null arrays (i.e., NAXIS = 0, following the STScI convention).

Required and Additional Keywords for Dark current file:

CAMERA  =                   / camera in use (1, 2, or 3)                            I2
NREAD   =                   / ACCUM - number of initial and final readouts          I2
SAMP_SEQ=                   / MultiAccum exposure time sequence name               C08
PEDIGREE=                   / reference file pedigree                              C68
DESCRIP =                   / reference file description                           C68
NUMEXPOS=                   / number of dark exposures in file                      I2
EXPOS_n =                   / exposure time of nth dark in file                     R4

Required and Additional Keywords for Temperature Dependent Dark file:

TFBHIGH =                          / upper limit for temperature                    R4
CAMERA  =                          / camera in use (1, 2, or 3)                     I2
TMPSETS =                          /set temperature when TFBTEMP is invalid         R4
DARKMETH= "TEMPERATURE-DEPENDENT"  /Dark calculation method                         C68
TEMPKEY =                          /Temperature key                                 C68
PEDIGREE=                          / reference file pedigree                        C68
DESCRIP =                          / reference file description                     C68

### 8.3.4 Linearity Correction File (LIN): <unique name>_LIN.FITS¶

The linearity correction file contains a set of coefficients for each pixel that generate a linear correction over the nonlinear range of the NICMOS detectors. The observed response of the detectors can conveniently be represented by two regimes.

At low and intermediate signal levels the detector response deviates from the incident flux in a way that is correctable using the following expression:

F_c = (c_1 + c_2 F + c_3 F^2) F

where c_1, c_2, and c_3 are the correction coefficients, F is the uncorrected flux (in DN) and F_c is the corrected flux. In practice the coefficient c_1 is set to 1, so that the total correction factor starts at a value of 1 at the zero signal level.

At high signal levels —as saturation sets in— the response becomes highly non-linear and is not correctable to a scientifically useful degree; the saturation levels are about 21,500 DN (NIC1), 22,500 DN (NIC2), and 26,200 DN (NIC3).

The linearity correction file consists of a set of images containing the c_1, c_2, and c_3 correction coefficients and their variances at each pixel. The [NODE,2] extension of the LIN file sets the saturation value for each pixel. Error estimates on the correction applied to non-saturated pixels are propagated into the ERR images of all imsets processed. Data quality flags set in the LIN file are also propagated into the processed DQ images. There is one LIN file per detector.

Format: This file departs from the standard format described in Section 8.1.2. The linearity coefficients are stored in floating-point image extensions with EXTNAME = COEF and EXTVER values 1 and 2. The variance, or error, values are stored in three floating-point image extensions with EXTNAME = ERR and EXTVER values 1-3. The DQ flags are stored, as usual, in a shortinteger image extension with EXTNAME = DQ and EXTVER = 1. The threshold values (in units of DN) are stored in two floating-point image extensions with EXTNAME = NODE and EXTVER values of 1 and 2.

In addition to the above data, the LIN file also contains two floating-point image extensions which store a “super zero read” image and its associated statistical errors. These image extensions are designated by EXTNAME = ZSCI and ZERR, and EXTVER = 1. The “super zero read” image is the average of a large number of MultiAccum mode zeroth read images and is used by calnica to estimate the amount of signal that may be present in the zeroth read of an observation being calibrated.

A typical file organization is as follows:

Ext. No EXTNAME EXTVER BITPIX Contents
Contents 10 ZERR 1 -32
0 N/A N/A 8 Primary header with null data array
1 COEF 1 -32 Linearity coefficient c1
2 COEF 2 -32 Linearity coefficient c2
3 COEF 2 -32 Linearity coefficient c3
4 NODE 1 -32 Threshold 1
5 NODE 2 -32 Threshold 2
6 DQ 1 16 Data quality flags
7 ERR 1 -32 Variance e1
8 ERR 2 -32 Variance e2
9 ERR 3 -32 Covariance e12
10 ERR 4 -32 Error of the intercept
11 ERR 5 -32 Error of the intercept
12 ERR 6 -32 Error of the intercept
13 ZSCI 1 -32 Super zero read science image
14 ZERR 1 -32 Super zero read error image

Flags and Indicators: Selected by the keyword CAMERA (which can be 1, 2, or 3).

Restrictions: None.

CAMERA  =                   / camera in use (1, 2, or 3)          I2
PEDIGREE=                   / reference file pedigree             C68
DESCRIP =                   / reference file description          C68

### 8.3.5 Flat Field File (FLT): < unique name>_FLT.FITS and Temperature dependent Flat Field File (TDF)¶

The science data are corrected for variations in Detector Quantum Efficiency (DQE) between pixels by multiplying by an (inverse) flat-field reference image. This step is skipped for observations using a grism because the flat-field corrections are wavelength dependent.

Starting with calnica version 4.4, this step uses the TDFFILE reference file, which contains the flat-field image for a given detector and filter (or polarizer) combination. Each flat-field image (*_tdf.fits) consists of five individual images (imsets) each having five extensions: SCI, ERR, DQ, SAMP, and TIME. The *_tdf.fits images therefore consist of 25 extensions with the SCI images, i.e., the temperature dependent flat-fields, in extensions 1, 6, 11, 16, and 21. Keywords TFBLOW and TFBHIGH show the temperature range for each extension. The full temperature range covered by all five bins is given by the TFBLOW and TFBHIGH keyword in the primary header (EXT=0).

The extension for which TFBLOW < TFBTEMP < TFBHIGH, where TFBTEMP is the temperature from science data header, is used for the flat-fielding. Having a set of temperature dependent flat-fields makes it possible to correct for some of the temperature dependent pixel-to-pixel DQE variations seen in the NICMOS detectors. In the FLATCORR step, calnica reads the detector temperature from the TFBTEMP keyword and selects the appropriate imset from the TDFFILE to use. The particular imset used is written to the TDFGROUP keyword in the header of the calibrated *_cal.fits files. The temperature dependent flat-fields were delivered to the Archive on November 19, 2008 for Cycle 11 and later observations and on January 23, 2009 for data taken during Cycles 7 and 7N. For data retrieved prior to these dates there is no TDFFILE listed in the header. In this case, the FLATFILE reference file is used instead. This consists of a single static (non-temperature dependent) flat-field image. FLATFILE is used instead of TDFFILE in the cases where TFBTEMP keyword is missing or TFBTEMP lies outside the range given by TFBHIGH and TFBLOW keywords in the primary header.

Format: Error estimates and DQ flags contained in the TDFFILE/FLATFILE are propagated into the processed images.

Flags and Indicators:

For FLATFILE - Selected by CAMERA (which can be 1, 2, or 3) and FILTER.

For TDFFILE - Selected by *CAMERA (which can be 1, 2, or 3), *FILTER, TFBLOW and TFBHIGH.

Restrictions: It is legitimate for the image extensions other than SCI, ERR, and DQ to be null arrays (i.e., NAXIS = 0, following the STScI convention).

CAMERA  =                   / camera in use (1, 2, or 3)                            I2
FILTER  =                   / filter wheel element in beam during   observation    C07
PEDIGREE=                   / reference file pedigree                              C68
DESCRIP =                   / reference file description                           C68

### 8.3.6 Background Illumination Pattern File (ILM): <unique name>_ILM.FITS¶

The background illumination pattern file contains the spatial variation in observed background count rates relative to a common mean of all non-DQ-flagged pixels of 0.0. Thus the illumination correction is accomplished by subtracting the illumination file from data that has already had the constant background level removed.

Format: Data quality flags are included in the DQ array and errors in the ERR array and are propagated forward by calnicb. DQ will be flagged with either the defective pixel flag (bit 5 - decimal 32) or the poor background correction flag (bit 4 - decimal 16), as appropriate.

Flags and Indicators: Selected by CAMERA (which can be 1, 2, or 3) and FILTER.

Restrictions: It is legitimate for the image extensions other than SCI, ERR, and DQ to be null arrays (i.e., NAXIS = 0, following the STScI convention).

CAMERA  =                   / camera in use (1, 2, or 3)                            I2
FILTER  =                   / filter wheel element in beam during                   C07
observation
PEDIGREE=                   / reference file pedigree                               C68
DESCRIP =                   / reference file description                            C68

## 8.4 Calibration Tables¶

### 8.4.1 Photometric Calibration Table (PHT): < unique name>_PHT.FITS¶

The NICMOS photometry parameters file contains data used to populate the photometry keywords, PHOTMODE, PHOTFLAM, PHOTFNU, PHOTZPT, PHOTPLAM, and PHOTBW in NICMOS science file headers according to the camera and filter combination used for the observation. Science image count rates (DN/sec) can be multiplied by the values of keywords PHOTFLAM or PHOTFNU to obtain absolute source fluxes in units of ergs/sec/cm2/ Å or Janskys, respectively. PHT tables associated with NICMOS images retrieved after 23 January 2009 also include coefficients for correcting for the temperature dependence of the photometry caused by the temperature dependence of the DQE. Calnica (version 4.4 and later) reads the detector temperature from the TFBTEMP keyword and uses the coefficients to calculate a scaling factor that is stored in the ZPSCALE keyword of the *_cal.fits files. The output science image is then multiplied by this scaling factor to account for the temperature dependence of the DQE. The coefficients for Cycle 7 and 7N data are included in the PHT tables starting January, 23 2009. For i Cycle 11 and later, the coefficients were updated in May 2009.

Format: The photometry parameters file is a FITS-format file consisting of a primary header- data unit with a null data array (designated by the NAXIS = 0 specification in the primary header), followed by a FITS binary table (BINTABLE) extension. The binary table is composed of eight fields or columns containing values of the PHOTMODE string, the five floating-point (4-byte) photometry parameters PHOTFLAM, PHOTFNU, PHOTPLAM, PHOTBW, and PHOTZPT, as well as PEDIGREE and DESCRIP strings. Records of photometry parameters are organized by the PHOTMODE string. The PHOTMODE string is a comma-separated list of the instrument name, the camera number, the filter or grating name, and the DN designator (e.g., NICMOS,1,F110W,DN). There is one PHOTMODE entry for each available NICMOS observing mode (camera/filter combination).

Flags and Indicators: Records are selected on the basis of an exact match to the PHOTMODE string.

Restrictions: None. Table 8-1 describes the column definitions.

Table 8-1. Photometric Calibration Table (PHT), <unique name> _PHT.FITS

Column Name Data Type Units Description
PHOTMODE CH*19 Instrument observation mode
PHOTFLAM R ergs/cm2/ Å /DN Inverse sensitivity
PHOTFNU R Jy*sec/DN Inverse sensitivity
PHOTPLAM R Å Pivot wavelength
PHOTBW R Å Band width
PHOTZPT R mag Zero point
PEDIGREE CH*40 Reference data pedigree
DESCRIP CH*40 Reference data description

TFBHIGH =                          / upper limit for temperature                    R4
TFBLOW  =                          / lower limit for temperature                    R4
PEDIGREE=                          / reference file pedigree                        C68
DESCRIP =                          / reference file description                     C68

## 8.5 OPUS Calibration Switch Rules¶

### 8.5.1 Calnica Matrix¶

Keyword         Value          Rule
-------             -----          ----
ZSIGCORR            OMIT           default
PERFORM        if OBSMODE = MULTIACCUM
ZOFFCORR            OMIT           default
PERFORM        if OBSMODE = MULTIACCUM
BIASCORR            PERFORM        default
NOISCALC            PERFORM        default
DARKCORR            PERFORM        default
OMIT           if OBSMODE = BRIGHTOBJ
OMIT           if FILTER = BLANK
NLINCORR            PERFORM        default
OMIT           if DARKCORR = OMIT
FLATCORR          PERFORM        default
OMIT           if FILTER = G096, G141, or G206
OMIT           if DARKCORR = OMIT
OMIT           if IMAGETYP = FLAT
UNITCORR          PERFORM        default
OMIT           if DARKCORR = OMIT
OMIT           if FLATCORR = OMIT
PHOTCALC            PERFORM        default
CRIDCALC            PERFORM        default
BACKCALC            PERFORM        default
WARNCALC            PERFORM        default

### 8.5.2 Calnicb Matrix¶

Keyword             Value          Rule
-------             -----          ----
ILLMCORR            PERFORM        default
OMIT           if FILTER = BLANK
OMIT           if IMAGETYP = DARK or FLAT

## 8.6 Generic NICMOS Science Image Header¶

The following listing shows a standard header used by all NICMOS reference files.

SIMPLE  =                    T / Fits standard
BITPIX  =                   16 / Bits per pixel
NAXIS   =                    0 / Number of axes
EXTEND  =                    T / File may contain extensions
ORIGIN  = 'NOAO-IRAF FITS Image Kernel July 2003' / FITS file originator
IRAF-TLM= '                    / Time of last modification
NEXTEND =                    5 / Number of standard extensions
DATE    =                      / date this file was written (yyyy-mm-dd)
FILENAME=                      / name of file
FILETYPE= 'SCI      '          / type of data found in data file
TELESCOP= 'HST'                / telescope used to acquire data
INSTRUME= 'NICMOS'             / identifier for instrument used to acquire data
EQUINOX =               2000.0 / equinox of celestial coord. system

/ DATA DESCRIPTION KEYWORDS

ROOTNAME=                      / rootname of the observation set
IMAGETYP= 'EXT               ' / type of exposure identifier
PRIMESI = 'NICMOS'             / instrument designated as prime

/ TARGET INFORMATION

TARGNAME=                      / proposer's target name
RA_TARG =                      / right ascension of the target (deg) (J2000)
DEC_TARG=                      / declination of the target (deg) (J2000)
ECL_LONG=                      / ecliptic longitude of the target (deg) (J2000)
ECL_LAT =                      / ecliptic latitude of the target (deg) (J2000)
GAL_LONG=                      / galactic longitude of the target (deg) (J2000)
GAL_LAT =                      / galactic latitude of the target (deg) (J2000)

/ OTHER COORDINATE SYSTEM INFORMATION

APER_REF=            '         / aperture used for reference position
ELON_REF=                      / ecliptic longitude at reference position (deg)
ELAT_REF=                      / ecliptic latitude at reference position (deg)
GLON_REF=                      / galactic longitude at reference position (deg)
GLAT_REF=                      / galactic latitude at reference position (deg)

/ PROPOSAL INFORMATION

PROPOSID=                      / PEP proposal identifier
LINENUM =                      / proposal logsheet line number
PR_INV_L=                      / last name of principal investigator
PR_INV_F=                      / first name of principal investigator
PR_INV_M=                      / middle name / initial of principal investigat

/ EXPOSURE INFORMATION

ORIENTAT=                      / position angle of image y axis (deg. e of n)
SUNANGLE=                      / angle between sun and V1 axis
MOONANGL=                      / angle between moon and V1 axis
SUN_ALT =                      / altitude of the sun above Earth's limb
FGSLOCK =                      / commanded FGS lock (FINE,COARSE,GYROS,UNKNOWN)
GYROMODE=                      / number of gyros scheduled for observation
REFFRAME=                      / guide star catalog version

DATE-OBS=                      / UT date of start of observation (yyyy-mm-dd)
TIME-OBS=                      / UT time of start of observation (hh:mm:ss)
EXPSTART=                      / exposure start time (Modified Julian Date)
EXPEND  =                      / exposure end time (Modified Julian Date)
EXPTIME =                      / exposure duration (seconds)--calculated
EXPFLAG =                      / Exposure interruption indicator
QUALCOM1=                                                 '
QUALCOM2=                                                 '
QUALCOM3=                                                 '
QUALITY =                                                 '

/ INSTRUMENT CONFIGURATION INFORMATION

CAMERA  =                      / Camera in use (1, 2, or 3)
PRIMECAM=                      / Primary camera for internal parallels
FOCUS   =                      / In-focus camera for this observation
APERTURE=                      / aperture in use (NICi,NICi-FIX,NIC2-CORON/ACQ)
OBSMODE =                      / array readout mode (ACCUM, MULTIACCUM, etc.)
FILTER  =                      / filter wheel element in beam during observation
NUMITER =                      / number of exposure iterations
NSAMP   =                      / RAMP, MULTI-ACCUM - number of samples
SAMP_SEQ=                      / MultiAccum exposure time sequence name
CR_ELIM =                      / RAMP - onboard cosmic ray detection used
SAT_ELIM=                      / RAMP - on-board saturation detection used
CRTHRESH=                      / RAMP - on-board cosmic ray detect threshold
SATHRESH=                      / RAMP - on-board saturation threshold
VARSCALE=                      / RAMP - on-board scale factor for variance
FOMXPOS =                      / X offset of FOV using NICMOS FOM (arcsec)
FOMYPOS =                      / Y offset of FOV using NICMOS FOM (arcsec)
NFXTILTP=                      / Fom X TILT Position (arcsec)
NFYTILTP=                      / Fom Y TILT Position (arcsec)
NPXTILTP=                      / PAM X TILT Position (steps)
NPYTILTP=                      / PAM Y TILT Position (steps)
NPFOCUSP=                      / Pam FOCUS Position (mm)
TIMEPATT=                      / timing pattern id
SAMPZERO=                      / sample time of the zeroth read (sec)
HCLKRATE=                      / horizontal clock rate (microseconds)
VIDEO_BW=                      / readout video bandwidth (kHz)
ADCGAIN =                      / analog-digital conversion gain (electrons/DN)

/ POINTING INFORMATION

PA_V3   =           198.371597 / position angle of V3-axis of HST (deg)

/ BACKGROUND KEYWORDS

BACKEST1=                      / background estimate number 1
BACKEST2=                      / background estimate number 2
BACKEST3=                      / background estimate number 3

/ PHOTOMETRY KEYWORDS

PHOTMODE=                      /
PHOTFLAM=                      / inverse sensitivity (ergs/cm**2/Angstrom/DN)
PHOTFNU =                      / inverse sensitivity (JY*sec/DN)
PHOTZPT =                      / ST magnitude system zero point (mag)
ZPSCALE =                      / temp dependent photometric 0-pt scale factor
PHOTFERR=                      / relat err: temp dependent photometric zero-pt
PHOTPLAM=                      / pivot wavelength of the photmode (Angstroms)
PHOTBW  =                      / RMS bandwidth of the photmode (Angstroms)

/ BIAS-DERIVED TEMPERATURE INFORMATION

TFBDATE =                      / Date that CalTempFromBias was run
TFBERR  =                      / Error (degK) for temperature derived from bias
TFBMETH =                      / CalTempFromBias algorithm type used
TFBTEMP =                      / Temperature (degK) derived from bias
TFBVER  =                      / Version of CalTempFromBias run

/ BIAS-DERIVED TEMPERATURE CALIBRATION SWITCHES

TFBCALC =                      / CalTempFromBias calc: PERFORM, OMIT, COMPLETE

/ BIAS-DERIVED TEMPERATURE CALIBRATION INDICATORS

TFBDONE =                      / CalTempFromBias calc: PERFORM, OMIT, SKIPPED

/ CALNICA CALIBRATION REFERENCE FILES

MASKFILE=                      / static data quality file
NOISFILE=                      / detector read noise file
NLINFILE=                      / detector nonlinearities file
DARKFILE=                      / dark current file
TEMPFILE=                      / temperature-dependent dark file
LINSCALE=                      / scaling factor for linear dark image
AMPSCALE=                      / scaling factor for ampglow image
FLATFILE=                      / flat field file
TDFFILE =                      / temperature-dependent flat field
TDFGROUP=                      / imset from TDFFILE applied by CALNICA
PHOTTAB =                      / photometric calibration table
BACKTAB =                      / background model parameters table

IDCTAB  =                      / Image Distortion Correction table

/ CALNICA CALIBRATION REFERENCE FILE PEDIGREE

MASKPDGR=                      / static data quality file
NOISPDGR=                      / detector read noise file
NLINPDGR=                      / detector nonlinearities f
DARKPDGR=                      / dark current file pedigre
FLATPDGR=                      / flat field file pedigree
PHOTPDGR=                      / photometric calibration t
BACKPDGR=                      / background model paramete

/ CALNICA CALIBRATION SWITCHES: perform,omit

BIASCORR=                      / subtract ADC bias level
ZSIGCORR=                      / Zero read signal correction
ZOFFCORR=                      / subtract MULTIACCUM zero read
NOISCALC=                      / calculate statistic errors
NLINCORR=                      / correct for detector nonlinearities
DARKCORR=                      / dark correction
BARSCORR=                      / bars correction
FLATCORR=                      / flat field correction
UNITCORR=                      / convert to count rates
PHOTCALC=                      / calculate photometric keywords
CRIDCALC=                      / identify cosmic ray hits
BACKCALC=                      / calculate background estimates
WARNCALC=                      / generate user warnings

/ CALNICA CALIBRATION INDICATORS: performed, skipped, omitted

BIASDONE=                      / subtract ADC bias level
ZSIGDONE=                      / Zero read signal correction
ZOFFDONE=                      / subtract MULTI-ACCUM zero read
NOISDONE=                      / calculate statistic errors
NLINDONE=                      / correct for detector nonlinearities
DARKDONE=                      / dark correction
BARSDONE=                      / bars correction
FLATDONE=                      / flat field correction
UNITDONE=                      / convert to count rates
PHOTDONE=                      / calculate photometric keywords
CRIDDONE=                      / identify cosmic ray hits
BACKDONE=                      / calculate background estimates
WARNDONE=                      / generate user warnings

CALSTAGE=                      / state of calibration
CAL_VER =                      / CALNIC code version
PROCTIME=                      / Pipeline processing time (MJD)
OPUS_VER=                      / OPUS software system version number

/ POST-SAA DARK KEYWORDS

SAA_EXIT=                      / time of last exit from SAA contour level 23
SAA_TIME=                      / seconds since last exit from SAA contour 23
SAA_DARK=                      / association name for post-SAA dark exposures
SAACRMAP=                      / SAA cosmic ray map file

/ BRIGHT EARTH PERSISTENCE KEYWORDS

BEPSCALE=                      / level of persistence calculated
BEPVALLO=                      / minimum allowed value of the persistence to app
BEPUSELO=                      / minimum allowed fraction of pixels used
BEPFRAC =                      / fraction of pixels used to calculate persistenc

/ RUNCALSAA CALIBRATION REFERENCE FILES

SAADFILE=                      / SAA dark reference image file
SAADPDGR=                      / SAA dark ref file pedigre
SAACNTAB=                      / saaclean reference table
SAACPDGR=                      / pedigree of saaclean refe
PEDSBTAB=                      / pedsub reference table
PDSBPDGR=                      / pedigree of pedsub refere
PMODFILE=                      / persistence model file

/ RUNCALSAA CALIBRATION SWITCHES

SAACORR =                      / correct for SAA signature
BEPCORR =                      / Calculate and apply bright earth persistence

/ RUNCALSAA CALIBRATION INDICATORS

SAADONE =                      / correct for SAA signature
BEPDONE =                      / Calculate and apply bright earth persistence

/ SAA_CLEAN output keywords

SAAPERS =                      / SAA persistence image
SCNPSCL =                      / scale factor used to construct persistence img
SCNPMDN =                      / median used in flatfielding persistence image
SCNTHRSH=                      / Threshold dividing high & low signal domains
SCNHNPIX=                      / Number of pixels in high signal domain (HSD)
SCNLNPIX=                      / Number of pixels in low signal domain (LSD)
SCNHCHI2=                      / HSD chi squared for parabola fit
SCNHSCL =                      / HSD scale factor for min noise
SCNHEFFN=                      / HSD effective noise at SCNGAIN
SCNHNRED=                      / HSD noise reduction (percent)
SCNLCHI2=                      / LSD chi squared for parabola fit
SCNLSCL =                      / LSD scale factor for min noise
SCNLEFFN=                      / LSD effective noise at SCNGAIN
SCNLNRED=                      / LSD noise reduction (percent)
SCNAPPLD=                      / to which domains was SAA

/ RLINCOR CALIBRATION REFERENCE FILES

ZPRATTAB=                      / nonlincor zeropoint scaling table
RNLCORTB=                      / nonlincor nonlinearity power law table

/ CALNICB CALIBRATION INFORMATION

ILLMCORR=                      / background illumination pattern subtraction
ILLMDONE=                      / background illumination pattern subtraction
ILLMFILE=                      / background illumination pattern file name
ILLMPDGR=                      / background illumination pattern
MEAN_BKG=                      / mean background level (DN/sec)

/ OTFR KEYWORDS

T_SGSTAR=                      / OMS calculated guide star control

/ PATTERN KEYWORDS

PATTERN1=                      / primary pattern type
P1_SHAPE=                      / primary pattern shape
P1_PURPS=                      / primary pattern purpose
P1_NPTS =                      / number of points in primary pattern
P1_PSPAC=                      / point spacing for primary pattern (arc-sec)
P1_LSPAC=                      / line spacing for primary pattern (arc-sec)
P1_ANGLE=                      / angle between sides of parallelogram patt (deg)
P1_FRAME=                      / coordinate frame of primary pattern
P1_ORINT=                      / orientation of pattern to coordinate frame (deg
P1_CENTR=                      / center pattern relative to pointing (yes/no)
BKG_OFF =                      / pattern offset method (SAM or FOM)
PATTSTEP=                      / position number of this point in the pattern
PATT_OFF=                      / pattern offset method (SAM, FOM, etc.)
PATTERN =                      / pattern type
PORIENT =                      / orientation of pattern on sky (deg)
NUMPOS  =                      / number of positions in pattern
DITHSIZE=                      / size of dither steps (arc seconds)
PATT_POS=                      / position number in pattern sequence

/ Target Acquisition Keywords

NCHKBOXX=                      / CHecKBOX location X
NCHKBOXY=                      / CHecKBOX location Y
NTABOXSZ=                      / TA checkBOX SiZe
NXCENT  =                      / X pos CENTroid (steps)
NYCENT  =                      / Y pos CENTroid (steps)
NXCENTP =                      / X pos CENTroid (pixels)
NYCENTP =                      / Y pos CENTroid (pixels)
NBOXSUM =                      / checkBoX  SUM
NOFFSETX=                      / OFFSET maneuver X (steps)
NOFFSETY=                      / OFFSET maneuver Y (steps)
NOFFSTXP=                      / OFFSeT maneuver X (pixels)
NOFFSTYP=                      / OFFSeT maneuver Y (pixels)
NSLEWCON=                      / SLEW CONfirmation (Clear,Set)

/ ASSOCIATION KEYWORDS

ASN_ID  =                      / unique identifier assigned to association
ASN_TAB =                      / name of the association table
ASN_MTYP=                      / Role of the Member in the Association
END
[Listing Version Jun 2012]