General Utilities

FITS Input/Output in fitsio

This section describes, in general terms, the FITS format and how it is used by tasks in the
fitsio package. The last part of this section (beginning on page 62) provides basic tutorial-type information about how to read and write FITS files and tapes using fitsio tasks.

The FITS Format

The standard format for exchange of astronomical data is the FITS (Flexible Image Transport System) format, which is defined in a series of papers published in Astron. Astrophys. Suppl., beginning in 1981.*1 FITS format is endorsed by the International Astronomical Union, and is being adopted as a NASA standard. The NASA Astrophysics Division, through the NASA Office of Standards and Technology (NOST), has adopted FITS "as a standard for the distribution of processed astronomical data from NASA Astrophysics missions and archives managed by or for the NASA Astrophysics Division."

The relationship between STSDAS image data, STSDAS tables, and the corresponding FITS data structures, is discussed in Chapter 3 on page 37.

[FITS] - Jump to the FITS Home Page

FITS Capabilities in STSDAS/TABLES

The fitsio package in STSDAS or TABLES is used to convert STSDAS (and IRAF) images to and from FITS format.*2 It also converts ASCII or STSDAS binary tables to and from FITS format. The stwfits task lets you create one or more FITS files from a GEIS file, retaining the information in all groups together with the group parameter block. In stwfits there is a parameter called gftoxdim which, when set, converts the multigroup file to a FITS file that has an extra dimension to accomodate multiple groups; it appends a FITS TABLE extension that contains the group parameter block. In general, stwfits lets you create FITS extensions like TABLE, BINTABLE, and IMAGE.

It is also possible to produce a separate FITS file for every group in the multigroup GEIS source file. In this case, no table is appended; instead, group information is contained in the FITS header. If you want a separate FITS file for every group, then set the parameter gftoxdim = no.

A new way to produce a FITS file from a GEIS file is to use the extension parameter. This will produce one FITS file with an IMAGE extension from multiple input images. For more details, see the online help by typing help stwfits.

The strfits task can be used to convert a FITS file to a multigroup GEIS file, while retaining its group structure. If the parameter xdimtogf is set to no, then two files will be created: an image file having an extra dimension for the groups, and a table containing the group parameter block. This requires that you have a FITS file created with stwfits and the parameter gftoxdim = yes. To recreate the original multigroup GEIS file, set the parameter xdimtogf = yes.

The default group parameter block (GPB), which is located at the end of each group in the GEIS data file, contains the information shown in Table 4.1. These values are taken from the header file which, for each parameter (n), contains the keywords PTYPEn, PDTYPEn, and PSIZEn. PTYPEn is the parameter name, PDTYPEn is its data type, and PSIZEn is its size in bits.

FITS Default Group Parameter Block

If the FITS file does not follow the default standard, then a template file with the group parameter structure is needed to convert the FITS file to a GEIS file. The template file is a GEIS header file containing the keywords PTYPEn, PDTYPEn, and PSIZEn for each group parameter, plus the keywords PCOUNT and PSIZE. The file name of this image header can be passed to the strfits task using the template parameter.

The stwfits task offers the following capabilities:

strfits offers the following capabilities:

Scaling Data

The original FITS output standard calls for all floating point data types to be converted to 32-bit integer data. Scaling is done by stwfits when setting the parameter scale=yes and is automatic when autoscale=yes, i.e., the values of bscale and bzero are determined by the program. For data having a large dynamic range, this scaling loses precision when FITS files are recovered to disk images. However, the IEEE FITS standard allows both single and double precision data to be stored in floating-point format so that no precision is lost. To use the new IEEE FITS standard, set the ieee parameter to "yes" in the stwfits task.

Tutorial: Reading and Writing FITS Files

This section describes basic techniques for handling FITS-format data tapes, especially those with HST image data. Topics in this section include:

Using Tape Drives

Before reading or writing a tape, you must:

  1. Find out what the IRAF alias is for the tape drive you want to use (use the devices task).

  2. Physically mount (load) the data tape on the tape drive.

  3. Allocate the tape drive.

The IRAF devices command will list the available tape drives on your system along with their IRAF aliases. You can then use the devstatus command to see if somebody else is using the tape drive. Once you know the IRAF name of an available drive, you should mount your tape on the drive and then allocate it using the allocate command. When you are finished using the tape drive, you should release it using the deallocate command. Figure 4.1 shows an example of how to use these three commands.

Finding and Allocating a Tape Drive

If you are not actually working from the host console to which the tape drive is attached, you must use the IRAF networking syntax, for example, ra!mta to indicate that the drive is attached to host ra.

Reading FITS Tapes and Files

To read an HST FITS-format data tape, you must:

  1. Allocate a drive and mount your tape as described above.

  2. Set the imtype environment variable which defines the type of image that you will be using.

  3. Set the strfits parameters.

  4. Read the tape using strfits.

  5. Dismount and deallocate the tape drive.

The imtype environment variable specifies the type of image that you are reading from tape, you will usually set this to "hhh", which specifies multigroup GEIS format.*3 For example:

fi> set imtype="hhh"

Always use the STSDAS strfits task when reading HST data sets. The STScI pipeline uses a special convention for mapping GEIS files to FITS format. While other FITS readers may be able to read some of the data, they are unlikely to properly reconstruct the entire data file.

Type epar strfits to edit the strfits parameters as shown in Figure
4.2. The parameters you should verify and set (if needed) are:

Setting strfits Parameters

Reconstructing GEIS Images From Multiple FITS Files

If you requested that your data be shipped to you with each group of the multigroup GEIS files written to separate files, you can reconstruct the original GEIS image and use it with the STSDAS calibration and analysis tools. To reconstruct the image, you must:

  1. Set the imtype environment variable to "hhh".

  2. Find an appropriate template file containing the correct group parameters for the instrument.

  3. Run the strfits task to reconstruct the first group of the image, defining the number of groups and the template file to use. (See the example in Figure 4.3).

  4. Run the strfits task once for each additional group in the file.

Reconstructing a Multigroup GEIS File

Writing FITS Tapes and Files

If you wish to write HST data sets to a FITS tape, you must:

  1. Allocate a tape drive and mount your tape as described on page 63.

  2. Set the stwfits parameters (type epar stwfits).

  3. Write the files to tape by typing stwfits.

Figure 4.4 shows an example of setting the stwfits parameters using the epar parameter editor. If you are writing your data to a new tape, there are three parameters you must set:

If you are using an Exabyte tape drive, you should also set blocking = 10. Setting the blocking factor to 10 may be useful for other tape devices as well--you could save a lot of tape if you're using a 9-track tape at 6250 bpi.

Setting stwfits Parameters

Once your parameters are set, run the stwfits task to write the files to tape and then dismount the tape and use the deallocate command to release the drive.

You can use stwfits to convert your multigroup GEIS files to FITS format so that you can work with the files using third-party software. In this case, you will write the files to disk rather than to a tape. To do this:

  1. Use epar to set the stwfits parameters. You need to set iraf_file to the name(s) of your GEIS files and set fits_file to the name(s) of the converted FITS-format file.

  2. Run stwfits as before.

For more information about using the fitsio tasks, see the two online help discussions for FITS examples and the GEIS format. Type help fits_exampl and help geis.

For more information about the fitsio package, see the online help files. Also, type help fits_exampl and help geis.

The FITS Format
FITS Capabilities in STSDAS/TABLES
Scaling Data
Tutorial: Reading and Writing FITS Files
Using Tape Drives
Reading FITS Tapes and Files
Reconstructing GEIS Images From Multiple FITS Files
Writing FITS Tapes and Files

Generated with WebMaker