Space Telescope Science Institute
Intro to HST Data Handbooks 8.0 May 2011
Table of Contents Previous Next Index Print

Introduction to the HST Data Handbooks > Chapter 2: HST File Formats > 2.3 GEIS File Format

GEIS format1 is the standard format for reducing data from FGS, FOC, FOS, GHRS, HSP, WF/PC-1, and WFPC2. Data from these instruments are distributed by the HDA in waivered FITS files and must be converted to GEIS format. Note that WFPC2 data is now available from the HDA in waivered FITS and MEF format files2.
All HST images in GEIS format consist of two components: a header file (with suffix ending in “h”), and a separate binary data file (with suffix ending in “d”). Both files must reside in the same directory for processing.
GEIS header files (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, (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). Each group of a GEIS file has identical array sizes, data types, and group parameters. Figure 2.2 depicts the structure of a GEIS data file graphically.
The three-letter identifier (e.g., d0h) that follows the rootname of a GEIS format HST data file (see Chapter 5 for more on HST file names) has often been called an “extension” in the past. However, because of the potential for confusion with FITS extensions, this handbook will refer to these three-letter identifiers as “suffixes.”
The binary content of GEIS files is machine dependent. Copying GEIS files directly from one platform to another (e.g., from a Mac to a Sun) may result in unreadable data. The task STRFITS can be used to convert GEIS to waivered FITS format before transferring.
Figure 2.2: GEIS File Structure
The HDA stores and distributes datasets from FGS, FOC, FOS, GHRS, HSP, WF/PC-1, and WFPC2 in waivered FITS format.
We highly recommend that users convert waivered FITS datasets back into their native GEIS format before processing them.
Your data must be in GEIS format for you to use 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 waivered FITS format to the GEIS format. A special convention is used to map GEIS format to waivered 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 multi-group GEIS file using strfits, you must first type:
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:
As another example, the waivered FITS WFPC2 dataset u6n20101m_clf.fits can be converted using strfits to created two GEIS files: u6n20101m.clh (a header file) and u6n20101m.cld (a data file).
One of the original advantages of GEIS format 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, a single FOS or GHRS dataset may comprise many spectra. The data corresponding to each CCD (for WF/PC-1 or WFPC2), or each readout (FOS) or bin (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.4 lists the contents and the number of groups in the final calibrated image for the most commonly-used modes of each instrument that uses the GEIS data format.
Table 2.4: Groups in Calibrated Images by Instrument and Mode for instruments using GEIS format.
Number of Groups
FGS data are not reduced with IRAF and STSDAS. Therefore, FGS groups have different meaning than for the other instruments.
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 data (.d0h, .c0h), digital sky data (.d1h, .c1h), analog star data (.d2h, .c2h), or analog sky data (.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 not all chips were used, see the DETECTOR keyword.
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 primary header file and the parameter block associated with a group. Because GEIS header files are composed solely of ASCII text, they are easy to view or print using standard Unix text-handling facilities. However, the group parameters are stored in the binary data file. To access them you need to use an IRAF task such as imheader, as shown in the section titled “Printing Header Information”.
You can use the IRAF hedit task to edit the keywords in GEIS headers. While it is possible to edit GEIS header files using standard Unix 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 is useful for updating header keywords containing calibration switches and calibration reference files.
Always edit headers using tasks like hedit, eheader, groupmod, or 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. Most of these tasks operate on only one image at a time, so you usually need to specify the GEIS file group to be processed. If you do not specify a group, the task will operate on 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:
(Always refer to a GEIS file by its header file name, with suffix ending in “h”, even though mathematically you are operating on the data portion.)
The command above 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 multi-group GEIS file results in an output file containing a single group.
Specifying an Image Section
If you wish to process only part of an image, you can specify the image section after the group specification in the following manner:
This command extracts a 100 by 200 pixel subsection of the image in the second group of the file indata.hhh, multiplies it 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.
An image section of one group of a GEIS image may be overwritten or operated upon, leaving the rest of the image intact. For example, the following two commands will first create outdata.hhh and then overwrite a section of it:
Printing Header Information
As for MEF files, the task imheader extracts and prints information about a GEIS image. This task prints 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 multi-group GEIS file which contains 64 groups of data, each consisting of an 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:
This will generate a long listing of both the ASCII header parameters in the *.hhh file and the specific group parameters for group 10 of the *.hhd file.
Other Group-Related Tasks
Currently, IRAF tasks and many STSDAS tasks cannot simultaneously process all the groups in an input image and write the results to corresponding groups in an output image in one step. However, there are several STSDAS tasks, particularly in the toolbox.imgtools and hst_calib.ctools packages, written to support group format data. Please refer to the STSDAS User’s Guide for more details about working with GEIS images.
File formats for the first and second generation HST instruments (FGS, FOC, FOS, HSP, WF/PC-1, GHRS, and WFPC2) were developed before the standardization of MEF format. The waivered FITS format was developed in response to the need for a machine independent storage format for these data and was based on the idea of stacking multi-group GEIS data as a new dimension in a FITS image.
For example, a WFPC2 science data GEIS file with four groups has four 800x800 pixel images in its data file. When this GEIS file is converted to a waivered FITS file (using the IRAF task stwfits), the resulting FITS file has the dimensions of 800x800x4 (a three-dimensional image!) in its primary HDU. Similarly, an FOS GEIS file may have 40 groups, each group being a one-dimensional image (spectrum) that is 2064 pixels in length. The waivered FITS file equivalent of this FOS GEIS file has one 2D image of the size 2064x40 as its primary HDU.
In the case of a 4-group WFPC2 image, the first extension of the waivered FITS file is a table containing four rows. Each row represents a group. Each column in the table will correspond to a group keyword. Each element in the table contains keyword values for a specific group. This can be viewed using the tread command:
You can also display the values of specific keywords using a command like tdump, which in the example below, writes the values to a file called “params.txt”:
st> tdump u2eo030ft_c0f.fits[1] columns="PHOTMODE, CRVAL1,\ CRVAL2, BIASEVEN, BIASODD" datafile=params.txt
The data component of a multi-group GEIS file, when converted to waivered FITS, is stored in the primary HDU of the waivered FITS image as a multi-dimensional image. The task display can be used to view one group image at a time. For instance, to view group 2 of a 4-group waivered FITS WFPC2 image, type:
The display task reads the image from the primary HDU, and specifies the image using three-dimensional syntax, where the “*” represents all pixels in x and y.
If you want to view the central 400x400 section of the WFPC2 image, you can use the following command:
It is STRONGLY recommended that all waivered FITS files be converted back to GEIS format, by using the task strfits, before further processing and analysis with IRAF/STSDAS tasks.

GEIS files are also commonly referred to as STSDAS images.

Table of Contents Previous Next Index Print