Part II: NICMOS Data Handbook

5.1 STSDAS Software

---

Software tools for NICMOS FITS files available in the STSDAS packages toolbox.imgtools.mstools and hst_calib.nicmos have been designed to maintain compatibility with pre-existing analysis software. The tools have either been written in ANSI-C or are IRAF CL scripts interfacing with pre-existing IRAF/STSDAS tasks. Some of the new tools accept a variety of data formats such as OIF and GEIS, as well as STIS and NICMOS FITS files, and will in time replace the STSDAS tasks they render obsolete.

Tasks fall into two major categories:

1. General-purpose utilities. These tasks include tools for mathematical and statistical operations on science images and for analysis and display of reduced and raw data. In most cases, the utilities extend existing routines to include error and data quality propagation. These are the utilities of greatest interest to the user community. Under this category are several tasks described in Chapter 3 of the HST Introduction, msarith, mscombine, msstatistics, msjoin and mssplit, along with a few other tasks we describe below, ndisplay, markdq, mosdisplay, pstack, pstats, sampinfo, nicpipe, biaseq, pedsky, pedsub, sampdiff and sampcum. The first five are found in the package toolbox.imgtools.mstools; the remaining ones reside in the package hst_calib.nicmos.
2. Calibration-oriented utilities. These tasks generate reference files, such as read noise arrays, dark files, flatfields, non-linearity correction arrays, and bad pixel arrays, to feed the calibration database and to support the calibration pipelines. The tasks are designed specifically for the calibration of NICMOS and are not particularly useful for the general observer. The tools are mstreakflat, msbadpix, ndark, nlincorr, and msreadnoise. All are located in the calibration package hst_calib.nicmos.

The tasks in the toolbox.imgtools.mstools package are particularly useful for working with individual STIS and NICMOS imsets. See "Working with STIS and NICMOS Imsets" in Chapter 3 of the HST Introduction if you are not familiar with these tasks. Below we describe a few tasks of specific interest to NICMOS observers. For additional details and examples of these and other tools, please refer to the online help.

Occasionally, the STScI NICMOS group introduces new software tasks outside the time frame of major new STSDAS releases. These are made available as a separate, add-on package called nicproto, and are usually announced in the STScI Analysis News (STAN) which is periodically distributed by e-mail (for more information, see Section 1.1). This package can be obtained from the STSDAS or STScI NICMOS group WWW sites. Tasks in nicproto are generally somewhat experimental, and final versions migrate into the hst_calib.nicmos package in the next major STSDAS release. All routines described in this edition of the handbook are now available in the most recent STSDAS distribution, v3.0.

ndisplay and markdq

The markdq task reads the data quality (DQ) array from a NICMOS image and marks the DQ flags on the displayed image. Each flag value can be set independently to a different color or can be turned off. The ndisplay task combines the capabilities of the IRAF task display and the task markdq: it displays a NICMOS image and overlays the DQ flags according to a user-specified color-code. Both tasks are useful for locating specific DQ values, for example, the cosmic rays rejected by calnica in a MULTIACCUM image.

mosdisplay

The mosdisplay task provides a convenient way to display images from all IMSETS of a NICMOS MULTIACCUM image together as a mosaic in a single ximtool or saoimage window. The user may select which extension (e.g., SCI, ERR, TIME, SAMP, or DQ) to display, and can control the display threshold parameters or leave them to be automatically determined.

pstack and pstats

The pstack and pstats tasks plot all the samples of a specified pixel or image section, respectively, from a NICMOS MULTIACCUM image as a function of time. These tasks can be used to track the time behavior of an image on a pixel-by-pixel basis. For example, the temporal positions of cosmic ray hits or the onset of saturation during the course of an exposure can be located for a defined set of pixels. The pstats task can be particularly useful for identifying anomalous data behavior such as drifting bias levels or scattered light which may cause the background level to vary substantially during the course of an exposure.

sampinfo

The sampinfo task offers a convenient way to get readout-by-readout information about a NICMOS MULTIACCUM image. It provides information about the overall readout sequence (SAMP_SEQ, NEXTEND, NSAMP, and EXPTIME), and then for each imset of the multi-extension fits file it lists the corresponding SAMPNUM, SAMPTIME and DELTATIME values. These can be useful bits of information when using non-standard processing techniques, such as the biaseq routine. An example of the use of sampinfo and its output is given in Section 4.1.4.

nicpipe, biaseq, pedsky and pedsub

The nicpipe task provides a shortcut for partially processing NICMOS images through some but not all stages of calnica. Normally, this is meant for use in preparing images for "bias equalization" using the biaseq task (see Chapter 4). Setting stage=biaseq takes the processing through the steps ZSIGCORR, ZOFFCORR, MASKCORR, BIASCORR, NOISCALC, DARKCORR, NLINCORR, and BARSCORR. Setting stage=final completes the processing. This can also be done by hand using chcalpar or hedit to change the processing control switches in the image headers (see Section 3.5.2) and running calnica directly. Occasionally nicpipe can come in handy at other times besides biaseq processing: one example is given below.

The tasks biaseq, pedsky, and pedsub provide methods for dealing with the floating quadrant bias or "pedestal" effect in some (not all) data sets, and are described in Section 4.1.4.

sampdiff and sampcum

The sampdiff task provides a convenient way to convert a MULTIACCUM image into a set of independent "first differences." Normally, each IMSET (readout) of a MULTIACCUM image is the cumulative sum of the total exposure time prior to that readout. As such, the [sci,*] images are not statistically independent. When analyzing NICMOS images, it is sometimes helpful to look at the data which was collected during each readout interval independent of that which was accumulated previously, i.e. by taking the difference of successive readouts. In this way, you can isolate readouts with problems (e.g., major cosmic ray hits or moving objects, sudden changes in bias, scattered light, etc.). The sampdiff task automates this process. Note that, in general, this is only really a sensible thing to do if the image has not been converted from counts to count rate by the UNITCORR step of calnica! The sampcum task inverts this process, re-accumulating the first differences.

Using These Tasks: An Example.

As an example, you might want to inspect NICMOS data for anomalies which occur during individual readouts during a MULTIACCUM using a procedure like this:

ni> nicpipe n4xj13jwq_raw.fits "" stage=biaseq ni> sampdiff n4xj13jwq_ima.fits n4xj13jwq_fdiff.fits ni> mosdisplay n4xj13jwq_fdiff.fits 1 extname=sci number+ ni> pstats n4xj13jwq_fdiff.fits[1:128,1:128]\ >>> extname=sci units=rate stat=midpt

 

In this example, the raw image is first partially processed through calnica using nicpipe. By setting stage=biaseq, the pipeline processing stops before flatfielding, conversion to count rate, and CRIDCALC cosmic ray processing. You then take first differences with sampdiff, displays them as a mosaic with mosdisplay to look for bars, bias jumps, monster cosmic rays, or other oddities in individual readouts, and then use pstats to plot the median count rate (units=rate) per sample time in the image quadrant [1:128,1:128].

Having satisfied yourself that the data is fine, you might then complete processing using the biaseq and pedsky tasks in the following manner:

ni> biaseq n4xj13jwq_ima.fits n4xj13jwq_beq.fits \ >>> skysamps=1-13 fitbias+ fitjump+ ni> nicpipe n4xj13jwq_beq.fits "" stage=final ni> pedsky n4xj13jwq_beq_cal.fits n4xj13jwq_ped.fits \ >>> salgorithm=auto interactive+ rmedian-

 

In this case, you have corrected readout-to-readout bias drifts with biaseq, also fitting for bias jumps in the process, and then carried out the final "pedestal" correction with pedsky, solving for the background level and pedestal interactively. Please see Section 4.1.4 of this manual and the on-line help files for biaseq and pedsky for a detailed explanation of the parameters. The resulting end product image will be n4xj13jwq_ped.fits.