[Top] [Prev] [Next] [Bottom]

2.3 GEIS File Format

The HST-specific Generic Edited Information Set (GEIS) format1 is the standard format for reducing data from FOC, FOS, FGS, GHRS, HSP, WF/PC-1, and WFPC2. All HST images in GEIS format consist of two components: a header file and a separate binary data file, both of which should reside in the same directory. GEIS header files, whose suffixes end in "h" (e.g., w0lo0105t.c1h), consist entirely of ASCII text in fixed-length records of 80 bytes. These records contain header keywords that specify the properties of the image itself and the parameters used in executing the observation and processing the data. GEIS binary data files, whose suffixes end in "d" (e.g., w0lo0105t.c1d), contain one or more groups of binary data. Each group comprises a data array followed by an associated block of binary parameters called the Group Parameter Block (GPB). The sizes and datatypes of the data arrays and group parameters in each group of a GEIS file are identical. Figure 2.3 depicts the structure of a GEIS data file graphically.

The binary content of GEIS files is machine dependent. Copying GEIS files directly from one platform to another (e.g., from a VAX to a Sun) may result in unreadable data.

Figure 2.3: GEIS File Structure

2.3.1 Converting FITS to GEIS

The STScI archive stores and distributes datasets from FOC, FOS, FGS, GHRS, HSP, WF/PC-1, and WFPC2 in a special archival FITS format. We highly recommend that users convert these datasets back into their native GEIS format before working with them. Your data must be in GEIS format for you to use many of the STSDAS software tools developed specifically for analysis of these data. It is important to use the strfits task found in stsdas.fitsio or in tables.fitsio to perform the conversion from archival FITS format to the GEIS format because the data-processing pipeline employs a special convention for mapping GEIS files to FITS format. While other FITS readers may be able to read portions of the data correctly, they are unlikely to reconstruct the entire data file properly.

To recreate the original multigroup GEIS file using strfits, you must first type:

cl> set imtype=hhh 

This command tells IRAF to write output files in GEIS format. You then need to set the strfits parameters xdimtogf and oldirafname both to "yes". For example, after you have set imtype = hhh, you can convert the FITS file *_hhf.fits into the GEIS format files *.hhh and *.hhd by typing:

cl> strfits *_hhf.fits iraf_fil="" xdim=yes oldiraf=yes

2.3.2 GEIS Data Groups

One of the original advantages of GEIS format noted in Section 2.1 was that it could accommodate multiple images within a single file. This feature is useful because a single HST observation often produces multiple images or spectra. For example, a single WF/PC-1 or WFPC2 exposure generates four simultaneous images, one for each CCD chip. Likewise, the FOS and GHRS obtain data in a time-resolved fashion so that a single FOS or GHRS dataset comprises many spectra-one corresponding to each readout. The data corresponding to each sub-image (for the WF/PC-1 or WFPC2) or each sub-integration (for the FOS or GHRS) are stored sequentially in the groups of a single GEIS binary data file. The header file corresponding to this data file contains the information that applies to the observation as a whole (i.e., to all the groups in the image), and the group-specific keyword information is stored in the group parameter block of each data group in the binary data file.

The number of groups produced by a given observation depends upon the instrument configuration, the observing mode, and the observing parameters. Table 2.1 lists the contents and the number of groups in the final calibrated image for the most commonly-used modes of each instrument.

Groups in Calibrated Images, by Instrument and Mode



Number of Groups





FGS data are not reduced with IRAF and STSDAS. Therefore, FGS groups have different meaning than for the other instruments.




All FOC images have only a single group.




Group n contains accumulated counts from groups (subintegrations) 1, 2, ... n. The last group is the full exposure.



Each group is an independent subintegration with exposure time given by group parameter EXPOSURE.




HSP datasets always have only a single group that represents either digital star (.d0h, .c0h), digital sky (.d1h, .c1h), analog star (.d2h, .c2h), or analog sky (.d3h, .c3h).




Each group is an independent subintegration with exposure time given by group parameter EXPOSURE. If FP-SPLIT mode was used, the groups will be shifted in wavelength space. The independent subintegrations should be coadded prior to analysis.



Each group is a separate subintegration with exposure time given by group parameter EXPOSURE.




Group n represents CCD chip n, e.g., group 1 is chip 1 (unless not all chips were used). Group parameter DETECTOR always gives chip used.



Group n is chip n + 4, e.g., group 1 is chip 5. If not all chips were used, see the DETECTOR parameter which always gives the chip used.




Planetary chip is group 1, detector 1. Wide Field chips are groups 2-4 for detectors 2-4. If all chips were not used, see the DETECTOR keyword.

2.3.3 Working with GEIS Files

This section briefly explains how to work with information in GEIS header and data files.

GEIS Headers

Header keyword information relevant to each group of a GEIS file resides in two places, the header file itself and the parameter block associated with the group. Because GEIS header files are composed solely of ASCII text, they are easy to print using standard Unix or VMS text-handling facilities. However, the group parameters are stored in the binary data file. To access them you need to use a task such as imheader, as shown on page 2-13.

You can use the IRAF hedit task to edit the keywords in GEIS headers. While it it possible to edit GEIS header files using standard Unix and VMS text editors, you must maintain their standard 80-character line length. The hedit task automatically preserves this line length. If you need to add or delete group parameters, you can use the STSDAS groupmod task in the stsdas.hst_calib.ctools package. The STSDAS chcalpar task, described in more detail in the Calibration chapters for each instrument, is useful for updating header keywords containing calibration switches and calibration reference files.

Always edit headers using tasks like hedit, eheader, and chcalpar. Editing headers with a standard text editor may corrupt the files by creating incorrect line lengths.

GEIS Data Files

Numerous IRAF/STSDAS tasks exist for working with GEIS images (see Chapter 3). Most of these tasks operate on only one image at a time, so you usually need to specify which group of a GEIS file is to be processed. If you do not specify a group, your task will choose the first group by default.

Specifying a Group

To specify a particular group in a GEIS file, append the desired group number in square brackets to the file name (e.g., z2bd010ft.d0h[10]). For example, to apply the imarith task to group 10 of a GEIS image, type the following:

cl> imarith indata.hhh[10] + 77.0 outdata.hhh

This command will add 77.0 to the data in group 10 of the file indata.hhh, and will write the output to a new single-group file called outdata.hhh. Any operation performed on a single group of a multigroup GEIS file results in an output file containing a single group.

Specifying an Image Section

If you wish to process only a portion of an image, you can specify the image section after the group specification in the following manner:

cl> imarith indata.hhh[2][100:199,200:399] * 32.0 outdata.hhh

This command extracts a 100 by 200 pixel subsection of the image in the second group of the file indata.hhh, multiplies this data by a factor of 32.0, and stores the result in a new output file, outdata.hhh, which is a 100 by 200 pixel single group GEIS file.

Printing Header Information

As discussed in the previous section, the task imheader extracts and prints information about the GEIS image. This task reports the image name, dimensions (including the number of groups), pixel type, and title of the image when it is run in default mode. For example:

cl> imhead indata.hhh 
indata.hhh[1/64][500][real]: INDATA[1/64]
The output line indicates that indata.hhh is a multigroup GEIS file which contains 64 groups of images, each consisting of a spectral array 500 pixels in length. The data type of the values is real (floating point). Note that since no group designation was provided, the task defaulted to the first group. To reveal more information regarding group 10, you can type:

cl> imhead indata.hhh[10] long+ | page

which will generate a long listing of both the ASCII header parameters in the *.hhh file and the specific GPB parameters for group 10 from the *.hhd file.

Other Group-Related Tasks

Currently, IRAF or STSDAS tasks cannot process all the groups in an input image and write the results to corresponding groups in an output image. However, there are several STSDAS tasks, particularly in the toolbox.imgtools and hst_calib.ctools packages, that simplify working with group format data. Please refer to the STSDAS User's Guide for more details about working with GEIS images.

[Top] [Prev] [Next] [Bottom]

1 GEIS files are also commonly referred to as STSDAS images.

Copyright © 1997, Association of Universities for Research in Astronomy. All rights reserved. Last updated: 07/01/98 08:36:06