Reading/Writing IUE FITS Data in IRAF/STSDAS

I. Introduction

The original IUESIPS-generated data were archived in the Guest Observer ("GO") format, based on an obsolete version of the VICAR format. This format is not compatible with file readers supported by IRAF and STSDAS, which means that IUE data generated by IUESIPS cannot be read by them unless they are first rewritten to FITS (or ASCII) by an external package. NEWSIPS-generated files were stored as FITS binary files and can be accessed by a variety of FITS readers. However, NEWSIPS-generated files were stored in two different FITS structures, summarized as follows:

SILO/SIHI, FES, RAW files: Stored as primary data FITS arrays, these may be read by rfits or STSDAS strfits Error-flag and cosmic-ray data are stored as image extensions in the SILO/SIHI files and can be read with strfits.
Extracted spectral files (MXLO/MXHI): Each order (1 for MXLO, about 60 for MXHI) is stored as a table row (which in turn store either 9 (MXLO) or 17 (MXHI) fields of string, integer, floating point, and vectors). These files may be read in IRAF only with the STSDAS package iuetools, as described in Section III.

II. Additional Documentation

The reader may wish to consult documentation contained in the following sources:

HST Data Handbook, Vol. 1., Chapter 2.2: "FITS File Format,",
Description of FITS primary, image & table extension arrays, and syntax for use in STSDAS/TABLES tasks.
IUEDAC User's Guide, Chapter 3 Working with various file formats.
NEWSIPS Image Processing Manual, Chapter 12 ("Final Data Products"). Complete description of data file structures and contents.
Web page pointing to various FITS i/o libraries: http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/fits_libraries.html
on line help page in iuetools of IRAF/STSDAS

III. The iuetools Package

In order to read MXLO/MXHI files, the user must have iuetools installed on his/her computer. This first requires IRAF version 2.11, STSDAS (version 2.0), and STSDAS/TABLES.

The iuetools package contains two tasks:

mxexpand: computes wavelength array from FITS header keywords and writes output file in form suitable for STSDAS and TABLES tasks.

mxtomultispec: extracts spectra in FITS binary tables created by mxexpand and outputs file in "multispec" (two-dimensional) format. This file can then be used in the onedspec package of IRAF/NOAO, such as splot.

Notes:

1. Wavelength arrays: wavelengths in the MXLO (MXHI) order(s) are contained implicitly as header keywords, and can be expanded (calculated) into arrays via a linear dispersion relation. This calculation is the primary function of "mxexpand" task. Note that all wavelengths in NEWSIPS- generated data are monotonic as they refer to vacuum wavelengths.

2. Concatenating spectral orders: IRAF/STSDAS does not support scripts to splice MXHI orders. (To do this requires wavelength arrays and a designation of splice points. There are, however, IUEDAC routines which perform this function.) We recommend caution in writing software to merge spectral orders with a constant wavelength spacing since this requires a resampling of fluxes to a new wavelength grid.

3. Alternative to iuetools: If the user does not have iuetools installed, it is possible to read NEWSIPS MXLO files in IRAF. In that case one would have to first run another program to convert the MXLO table array to a primary array. For example, if IDL is available, one may use the IUEDAC task mxcon for this FITS-to-FITS file conversion (see http://archive.stsci.edu/iue/iuedacfits.html).

IV. Examples of Use of iuetools Package for MXHI Files

1. Reconnoitering your MXHI file, e.g. swp56875.mxhi:

Evaluate the structure of the MXHI/MXLO file (after loading STSDAS & TABLES):

ta> catfits swp58675.mxhi
Output:

 
EXT#  FITSNAME       FILENAME   EXTVE DIMEN  BITPI OBJECT
 0    swp56875.mxhi                              8
 1    BINTABLE       MEHI       17Fx60R

Note that swp56875.mxhi is a 3-dimensional binary table with 60 rows and 17 fields. Each of these fields may be a scalar or a vector of a fixed length (from IUE image to image) and is described in the NEWSIPS NEWSIPS Image Processing Manual, Chapter 12.9 (or Chapter12.8 for the 9 fields of MXLO files). The length of the wavelength or (various) flux fields is 768. This can be verified by executing 'catfits' with the "long" keyword set to "yes" for the extension file:

ta> catfits swp58675.mxhi[1] long=yes

An extensive dump of the fits header is printed out. Keywords of the form TFORMxx, where xx denotes the number for the wavelength or flux fields gives the dimensionality, 768.

2. Using mxexpand for later work with STSDAS tasks:

Convert MXHI file to an expanded FITS table:
ta> mxexpand swp58675.mxhi
Output: Converted file swp56875.mxhi --> swp56875mxhi.fits
[Both input and output files are 3-dimensional binary tables.]
Evaluate the file produced by mxexpand:
ta> catfits swp56875mxhi.fits
Output:
```
EXT#  FITSNAME       FILENAME   EXTVE DIMEN  BITPI OBJECT
 0    swp56875mxhi                               8
 1    BINTABLE       MEHI       18Fx60R
```
[mxexpand has added a field of wavelength vectors; none of the old fields are deleted]
Create listing of header to look at column attributes
To display column names, data type, format, and units, invoke 'tlcol' in TABLES:
ta> tlcol swp56875mxhi.fits[1] nlist=4 ,
or to view labeled structure of table columns, load 'stsdas' and type:
st> tread swp56875mxhi.fits
To get out of the tread window, type "control-d" and "quit".
Having the column names from the last step, now make a simple plot:
cl> sgraph "swp56875mxhi.fits[r:order=100] wave_array abs_cal"
Note: [ ] syntax shows use of STSDAS selectors for FITS and TABLES files; for help go to http://stsdas.stsci.edu/bps/ovselector.html. For help on sgraph, click here.
Alternatively, one can plot scalars among all the orders, e.g. order vs. starting wavelength:
cl> sgraph "swp56875mxhi.fits order wavelength"

3. Use of the mxtomultispec task:

Convert output expanded file from MXEXPAND to multispec (.imh) format:
ta> mxtomultispec swp56875mxhi.fits swp56875ms
Output: The output file - swp56875ms.imh - has been written.
Note the result is necessarily an IRAF 2-dimensional image (imh) file. This can be checked with the command:
cl> imhead swp56875ms
Output:
swp56875ms[768,60][real]: SWP56875_ABS_CAL6958G_R0001[1/1]
This file may now be used with your favorite IRAF task, e.g.
on> splot swp56875ms[*,30]
Comments:
Note that the plot resulting from this simple command has defaulted to plotting the former columns wave_array (wavelength) vs. abs_cal (absolute flux) of order 30.
The user may select an arbitary set of orders for the output file, e.g.
mxtomultispec "swp56875mxhi.fits[r:order=(82:84,90)]" swp56875msabb selector syntax, including the use of quotes, (), [] symbols.)
Let's check the structure of the new file:
cl> imhead swp56875msabb"
Output:
swp56875msabb[768,4][real]: SWP56875_ABS_CAL6958O_R0036[1/1]
This result tells us that we have an image containing 768 columns and 4 rows.

Need help with acronyms? Click here