STScI Logo

Hubble Space Telescope
Space Telescope Imaging Spectrograph

GO Primer

Getting your data
First things first--Paper Products
Matching the file name with exposures
Looking at your data headers
Displaying your data
Plotting your data
Extracting and plotting your spectrum
Further Information
A Very Small IRAF Cheat Sheet

Getting your data

We recommend that you use the HST Data Archive to retrieve your data prior to your visit so that you can look at it. If you have received a data tape and wish to read your data off of it, use the STSDAS command "strfits"; you will need to set the image type to fits. This will copy the FITS files from the tape onto the specified disk; to keep the original file names, set the "Use old IRAF name" to "yes". As an example:

set imtype = fits

strfits mta 1-3 oldiraf=yes

This will copy the first 3 files from the IRAF device named mta to the current working directory with the original file name used.. Alternately, if the tape was written as a UNIX tar, the FITS files can be accessed directly by:

tar xvf /dev/rmtx

which will dump the contents of the tape to the present directory. Note that as STIS datasets are quite large (over 2MB mimimum a piece), directories should be chosen appropriately.

Data on your tape includes: raw, calibrated, data quality,and OMS files. Note that the first file on the tape is a log file giving the tape contents.

NOTE:As of August 1, 2000 the archive will no longer automatically generate tapes for any proposal. This extends the policy now in place for cycle 9 to all older proposals. Tapes will only be made available by making a specific request to archive@stsci.edu.

First things first--Paper Products:

The fastest and easiest way to look at your data is to look at the paper products. These were carefully designed to help you get a quick look at your data and assess it. You can generate the paper products using the HST PDF Products Page. Or produce them yourself using the following steps in IRAF:

1. Place all of your data in one directory

2. Load the IRAF packages, stsdas, hst_calib and paperprod

(simply by typing them).

3. Run the task pp_dads type: pp_dads *.fits

Matching the file name with exposures:

The easiest way to learn about your exposures is to use an IRAF task called infostis.

Simply type:

infostis o3ura2060_raw.fits

and a table of keywords will be displayed for you; among them, Exposure ID which will tell you the visit and exposure number that you can then match to your proposal if you wish. For example, an exposure ID of 2.018 translates to visit 2, exposure 18.

---------------------------------------------------------------
                          S  T  I  S
---------------------------------------------------------------

         Rootname: O3URA2060              Detector: CCD
      Proposal ID: 7075                   Obs Type: IMAGING
      Exposure ID: 2.018                  Obs Mode: ACCUM
                                              Lamp: NONE
      Target Name: G191B2B                Aperture: F28X50OII
  Rigth Ascension:  05:05:30.6              Filter: OII
      Declination: +52:49:52.8         Opt Element: MIRVIS
          Equinox: 2000.0                  CCD amp: D
                                              Gain: 4
   Axis 1 binning: 1                      CR-split: 2
   Axis 2 binning: 1
         Subarray: no

  Total Exp. Time: 24.0 sec
 Number of imsets: 2
An alternative method is to read the instrument parameters from the header (see below) to determine the instrument configuration.

Looking at your data headers:

To work with your data you're going to need the proper software. You'll need the latest version of IRAF (version 2.11.3) that contains the new "fits kernel". You will also want to download the latest version of the STSDAS (version 2.2) STIS package, as calstis and the accompanying tools are evolving rapidly. (Please note that these programs are available only for Sun/OS and Solaris 2.5 platforms).

Once you have the proper software, start by looking at your data headers. The format of STIS data is very different from other HST data you may have had experience with. It's in a type of fits format, either fits with image extensions for two-dimentional data or 3-D binary tables for extracted spectra and time-tag series. Go into IRAF and run the task, catfits, on one of your datasets, e.g.:

catfits o3ura2060_raw.fits long-

EXT#  FITSNAME      FILENAME     EXTVE DIMENS     BITPI OBJECT

0     o3ura2060_raw                               16
1       IMAGE       SCI          1     1062x1044  16
2       IMAGE       ERR          1                16
3       IMAGE       DQ           1                16
4       IMAGE       SCI          2     1062x1044  16
5       IMAGE       ERR          2                16
6       IMAGE       DQ           2                16
You'll note there are 3 types of extensions: SCI, ERR, and DQ. SCI stands for "science" and contains the actual data. ERR stands for "error" and contains statistical errors. DQ stands for "data quality" and contains data quality values which flag suspect pixels. Details about data format can be found in the Data Handbook.

You may want to look at the header of your calibrated data. To do this use the IRAF task imheader:

imhead o42701010_sx2.fits[1] long+

This will give you the long version of the primary header of your 2-D calibrated extracted spectra. Naturally, what mode you used to take your data will determine what the final, calibrated image will contain (see Table 1). A complete description of file naming conventions and various suffixes (Table 2) is available.

Some useful keywords found in the header include:

PROPOSID, TDATEOBS, TARGNAME, TEXPTIME, OBSTYPE, OBSMODE, DETECTOR, CCDGAIN, SCLAMP, OPT_ELEM, APERTURE, FILTER, APER_FOV, MIRROR.

For an explanation of what each of these means in detail please refer to the Data Handbook.


Table 1: Typical STIS Output Products by Observation Type*

--------------------------------------------------------------------
Observation Type               Uncalibrated Files   Calibrated
                                                      Files+
--------------------------------------------------------------------
ACQ, ACQ/PEAK                  _raw                 none
IMAGING                        _raw, _spt, _asn     _flt, _crj (CCD),
   (CR-SPLIT or repeatobs)                          _sfl(MAMA)
IMAGING (single exposure)      _raw, _spt, _asn     _flt
FIRST ORDER SPECTROSCOPY       _raw, _wav, _asn     _flt, _crj (CCD),
   (CR-SPLIT or repeatobs)     _spt, _wsp           _sx1 (CCD), _sx2
FIRST ORDER SPECTROSCOPY       _raw, _wav, _asn     _flt, _x2d
   (single exposure)                                _spt, _wsp
ECHELLE SPECTROSCOPY           _raw, _wav, _asn     _flt, _x1d
   (single or repeatobs)                            _spt, _wsp
---------------------------------------------------------------------
* for ACCUM mode. The file names are the same for TIME-TAG with the addition of the uncalibrated _tag file.
+ the file in boldface is the most processed file


Table 2: Data File Naming Conventions

---------------------------------------------------------------
Product       Suffix  Type   Contents
---------------------------------------------------------------
Uncalibrated  _raw    image  Raw sciencea
              _tag    table  Timetag event list
              _spt    image  Support file (header)
              _wav    image  Associate wavecal exposure
              _wsp    image  Wavecal support file
              _asn    table  Association file
              _trl    table  Trailer file (input)
              _lrc    image  Local rate check image
              _lsp    text   LRC support file (header)
              _jit           See Chapter 2
              _jif    image  See Chapter 2
              _pdq    table  See Chapter 2
Calibrated    _flt    image  Flat-fielded science
              _crj    image  CR-rejected, flat-fielded science
              _sfl    image  Summed flat-fielded science
              _x1d    table  1-D extracted spectra
              _x2d    image  2-D extracted spectra or
                             geometrically corrected images
              _sx1    table  Summed 1-D extracted spectra
              _sx2    image  Summed 2-D extracted spectra
              _trl    table  Trailer file (output)
---------------------------------------------------------------
a Raw data from isolated wavecals, biases, darks, and flats, as well as from ACQs and ACQ/Peaks, have the _raw suffix.

For information on various modes see the STIS Instrument Handbook:

CCD ACCUM mode

MAMA ACCUM mode

MAMA TIMETAG mode

TARGET ACQ mode

Displaying your data:

Detailed information on how to look at your data is contained in the HST Data Handbook in section 3.5.2 COS and STIS Spectra. Below we give some short examples.

Before attempting to display or plot your data you may find it useful to run catfits on it. For example:

catfits file_sx2.fits

EXT#  FITSNAME    FILENAME       EXTVE  DIMENS   BITPI OBJECT
0     file_sx2    file_sx2.fits                        16
1     IMAGE       SCI              1    1201x1201     -32
2     IMAGE       ERR              1    1201x1201     -32
3     IMAGE       DQ               1    1201x1201      16

catfits file_x1d.fits

EXT#  FITSNAME    FILENAME       EXTVE  DIMENS   BITPI OBJECT
0     file_x1d    file_x1d.fits                       16
1     BINTABLE    SCI              1    9Fx1R
You can display any data that is an IMAGE, but you will have to plot such things as binary tables, (BINTABLE), or use tprint to read the table. Tprint can also be used to read fits tables (TABLE).

To display your data bring up your favorite display tool (saoimage or ximtool). Then simply use the IRAF task display:

display yourfile.fits[1] 1

You can display any image data (see table above).

Plotting your data:

You can plot any image data or binary table data with sgraph. In many cases only a small portion of your image will contain the data you wish to look at. You should display your two-dimensional spectra to determine the pixel range you wish to plot. An example of plotting a range of data is:

sgraph data_x2d.fits[1][*,100:1000]

This will plot the science extension of your dataset for the entire x range, but only pixel 100 through 1000 averaged together for the y range.

Extracting and plotting your spectrum:

To extract a 1-dimensional spectrum from your 2-dimensional image, you need to determine the AXIS2 (Y) position of the object. Use the IRAF task implot:

implot data_crj.fits[1] (CCD observations)

implot data_flt.fits[1] (MAMA observations)

This will give you a line plot through your data. Issue the command:

:c 512

to get a column plot through your data, which should show a peak at the Y location of your spectrum. Expand the plot around your line (place the cursor to the left of the line, hit "e", then the right of the line, and hit "e" again), and measure the middle of the line by placing the cursor on the peak and hitting the spacebar. You will also need to measure the width of your spectrum by placing the cursor at the edges of the profile. You can then use the STSDAS task x1d (part of the calstis pipeline) to extract a 1-dimension spectrum:

x1d data_crj.fits output=data_x1d.fits a2center=MIDDLE extrsize=WIDTH

where MIDDLE is a real value that provides the center of the search range for finding the spectrum, and WIDTH is a real value with the size of the extraction box, in reference pixels. Note that you must have the calibration reference files on-line, and have properly set the oref parameter (see section 3.5.1 in the Data Handbook). This spectrum is a FITS binary table. To convert this to an 1-dimensional image, use the STSDAS task tomultispec:
----------------------------
TOMULTISPEC work around for STIS Data

The IRAF task TOMULTISPEC does not currently work on STIS Data. While this problem is being resolved, please use the following work around:

In the pyraf command line type the following three commands:

TPRINT takes the x1d fits file as an input and outputs a text file. RSPEC takes the text file output by TPRINT as an input and outputs a fits file. Set the RSPEC parameter dtype to nonlinear so that SPLOT will plot wavelengths instead of pixel numbers.


----------------------------
You can now use the standard IRAF 1-dimensional tasks (such as splot) to plot and analyze your spectrum. If you have echelle spectra, echplot is an excellent task for plotting extracted spectral orders (see section 23.1 in the Data Handbook).

You can now use the standard IRAF 1-dimensional tasks (such as splot) to plot and analyze your spectrum. If you have echelle spectra, echplot is an excellent task for plotting extracted spectral orders (see section 23.1 in the Data Handbook).

Note that the STIS pipeline automatically extracts a one-dimensional spectrum for you. To determine the position of the extracted spectrum on the crj (CCD) or flt (MAMA) image, look at the trl file with the tread command for the x1d analysis section:

tread data_trl.fits

or alternately (to create an ascii file which is searchable):

strfits data_trl.fits "" data.trl

grep "spectrum extracted" data.trl

Further Information: We recommend reading sections of the STIS Instrument Handbook and/or the STIS Web Site that are relevant to your data to familiarize yourself with how your data was taken:

CCD Details
MAMA Details
Target Acquisitions
Data Taking
Binning & Subarrays
Exposure Sequences
Some particularly relevant sections of the Data Handbook include:
Instrument Capabilities and Design
Data Structure and naming conventions
Output products
Headers keywords
Paper Products
Calibration switches
Calstis structure
Pipeline flowchart
Recalibration
Error Sources
Analysis Tools
Time Tag data
Target Acquisitions
There is also an "anomalies" page on the STIS web site that you may find interesting/ useful when looking at your data.

A Very Small IRAF Cheat Sheet:

There are just a handful of IRAF and UNIX tasks that you need to get started looking at your data.

-------------------------------------------------------------
Command       Meaning
-------------------------------------------------------------
lpr filename  To print a file
cd            To change directories,
                 e.g.- cd /where/you/want/to/go
ls            To list files in that directory
apropos       To find tasks relating to what you want to do,
                 e.g.- apropos
plot          will give you many plotting package options
display       To display an image
splot         To plot a spectra
epar          To edit a task parameter file
lpar          To look at a task parameter file
imhead        To look at a data header
catfits       To list the header extensions in a .fits file
implot        Plot lines and columns of images
sgraph        To plot spectra
                 (in either image form or binary tables)
echplot       Generate plots of STIS extracted spectral orders
x1d           Extract a colelction of 1-D spectra from a
                 calibrated 2-D ACCUM image
tomultispec   Converts spectra from rows of a FITS 2-D
                 binary table to an IRAF multispec image
infostis      To get information about your dataset
help          To get help on a task, e.g.- help splot
-------------------------------------------------------------