WFC3 Data Handbook V. 4.0

help@stsci.edu

9.1	STSDAS and STSCI_PYTHON Software

Software tools for working with WFC3 FITS files are available in the stsdas and stsci_python package. Legacy tools from IRAF such as toolbox.imgtools.mstools 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 will be transitioned to the python wfc3tools package in a future release.

These tasks include tools for mathematical and statistical operations on science images and for analysis and display of raw and reduced 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 Introduction to the HST Data Handbooks, msarith, mscombine, msstatistics, msjoin and mssplit, along with a few other tasks we describe below, ndisplay, markdq, mosdisplay, pstack, pstats, sampinfo, sampdiff, and sampcum. The first five are found in the package toolbox.imgtools.mstools; the remaining ones reside in the hst.calib.wfc3 (now deprecated - all wfc3 calibration software maybe found in the wfc3tools and HSTCAL packages) and older IRAF hst.calib.nicmos package.

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

The following tasks are found in both the wfc3 and nicmos IRAF packages: mosdisplay, pstack, pstats, sampinfo. Found only in the nicmos packager are sampdiff, sampcum, ndisplay and markdq. THe latter twi can be used for any HST dataset using multi-extension FITS format to store SCI, ERR and DQ arrays.

ndisplay and markdq

The markdq task reads the data quality (DQ) array from a multi-extension image and marks the DQ flags on a previously displayed science 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 science image and overlays the DQ flags according to a user-specified color-code. Both tasks are useful for locating specific DQ values, such as pixels flagged as saturated or marked as cosmic ray hits.

mosdisplay

The mosdisplay task provides a convenient way to display images from all IMSETS of a WFC3/IR multiaccum image together as a mosaic in a single ximtool or saoimage/ds9 window. The user may select which extension (e.g., SCI, ERR, DQ, SAMP or TIME) 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 WFC3/IR multiaccum image as a function of sample 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 particular pixel or 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 WFC3/IR 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.

sampdiff and sampcum

The sampdiff task provides a convenient way to convert a WFC3/IR 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 multiaccum images, it is sometimes helpful to look at the data collected during each readout interval independently of that which was accumulated previously, i.e. by taking the difference of successive readouts. In this way, you can isolate readouts that have problems (e.g., major cosmic ray hits or moving objects, sudden changes in 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 calwf3! The sampcum task inverts this process, re-accumulating the first differences.

Using These Tasks: An Example.

As an example, you might want to inspect WFC3 data for anomalies occurring during individual readouts of an IR exposure using a procedure like this:

--> hedit ib3x01a1q_raw.fits[0] unitcorr=omit

--> calwf3 ib3x01a1q_raw.fits

--> sampdiff ib3x01a1q_ima.fits ib3x01a1q_fdiff.fits

--> mosdisplay ib3x01a1q_fdiff.fits 1 extname=sci number+

--> pstats ib3x01a1q_fdiff.fits[1:512,1:512]\

>>> extname=sci units=rate stat=midpt

In this example, the raw image is processed through calwf3 with the unitcorr step turned off so that the data in the _ima file readouts are left in units of accumulating counts rather than count rate. You then take first differences with sampdiff, display the individual SCI extensions as a mosaic with mosdisplay to look for monster cosmic rays or other oddities in the readouts, and then use pstats to plot the median count rate (units=rate) per sample time in the image quadrant [1:512,1:512].