Frfread Manual for Versions 4.0 and Later

Introduction

Frfread is the official program which converts ASCA telemetry into FITS format event lists and HK files. It was originally written at Pennsylvania State University, and distributed by that institution, but as of the Fall of 1998 is now maintained by the ASCA Data Processing Team at GSFC. All questions, comments, and bug reports should be sent to ascahelp@athena.gsfc.nasa.gov.

Note that the Processing Team has made significant changes to the code in version 4.0. You should read this document even if you a familiar with earlier versions of frfread. The changes in version 4.0 are detailed in the file changes4.html.

Obtaining Frfread

Source code for frfread is available here. The current (and probably final) version is 4.5.

Compiling and Installing Frfread

The frfread source code is contained in the src directory. We do not currently provide pre-compiled binaries, so you will have to compile the code yourself.

Requirements

You will need an ANSI C compiler, such as gcc. You will also need an up-to-date installation of the FTOOLS. This last requirement should not be burdensome since any in-depth ASCA data analysis requires the FTOOLS.

Compiling

Before compiling you need to edit the Makefile in the src directory as described below. Comments in that file should help you do this.

First, set CC to choose your C compiler. We recommend gcc, but any ANSI-compliant compiler should work.

Then set FTOOLS to the machine-dependant directory of your FTOOLS installation. If your FTOOLS are correctly installed and initialized, then this will be the value of your FTOOLS environment variable. The basic FTOOLS libraries needed are the FITS I/O routines in CFITSIO and the parameter (.par) file I/O routines in xanlib. Xanlib in turn needs a number of other FTOOLS libraries and FORTRAN system libraries.

Next, choose a set of platform-dependant compilation options. By setting MACHINE, FTOOLSLIB, and FTOOLSINC. We have tested frfread under Sun/Solaris and Dec Alpha/OSF, and have provided FTOOLSLIB definitions which should work for these. If you want to compile on some other platform you may need to be a bit more creative with the FTOOLSLIB definition.

If installing under Solaris, you may need to modify -L/opt/SUNWspro/SC3.0 to point to the correct directory for your compiler version. You can get the correct directory name from ls -d /opt/SUNWspro/SC*.

Finally, if you are using an old (before FTOOLS 4.1 ) version of the FTOOLS, then you will need to uncomment the definition:
FTOOLS4_0=-DOLD_FITSIO.
This is to accomodate older versions of CFITSIO which do not have the fits_report_error function.

After making these modifications the program should compile simply by typing make.

Installing

Before installing you need to set the Makefile BIN variable to the directory where you want to install frfread. The installer must be able to create files in this directory.

We recommend that you set BIN to the FTOOLS bin directory. This is the simplest option for users who are correctly configured to run the FTOOLS. The reason is that frfread checks the SYSPFILES and PFILES environment variables in order to find its .par file. With a normal FTOOLS setup, these environment variables point to the FTOOLS bin directory.

Another option would be to install frfread elsewhere, but then copy frfread4.par to the FTOOLS bin directory. If this is not possible, we provide a borne shell script run_frfread in the frfread bin directory This script resets the environment variables before running frfread, without affecting the calling shell.

After setting the installation directory, type make install.

Running Frfread

The name of the frfread executable is "frfread4". Before version 4.0 it was possible to build either a GUI version of frfread, "frfread", or a command-line driven non-GUI version "frfreadng". With frfread versions 4.0 and later, the GUI is no longer available and "frfread4" behaves most like "frfreadng". The name of the executable was changed to emphasize the differences between frfread4 and frfreadng and to avoid confusion with the older frfread.par.

Parameters

Frfread4 uses the same XPI parameter file interface library as the FTOOLS. Therefore, parameters may be supplied on the command line or when prompted using the same syntax as the FTOOLS. Previous versions of frfread used an FTOOLS/IRAF-style parameter file but did not employ the full XPI interface.

The following parameters are available:

FITS Output

Frfread produces five Housekeeping (HK) files - one for each instrument and one common HK file. These files are typically used as input to the mkfilter2 FTOOL to create the filter (.mkf) file used to screen the data. The GIS HK files may also be used by the ghkcurve FTOOL to produce monitor count light curves.

Frfread also creates a large number of FITS event files. Each time a minor mode changes for one of the instruments, frfread closes the current file and opens a new one. Since minor modes tend to change a few times per orbit (~6 kiloseconds), it is not uncommon for frfread to produce over a hundred event files for a single observation. The standard processing done at GSFC combines event files with identical modes to produce a more manageable set of unfiltered (.unf) files. The FTOOL script ascascreen -e fits will also conveniently handle the large number of files created by frfread . Note frfread does not fill the PI, DETX, DETY, X, or Y columns. The ascalin FTOOL must be used to do that. For more on ASCA data analysis see the ASCA Data Reduction (ABC) Guide at http://heasarc.gsfc.nasa.gov/docs/asca/abc/abc.html.

The file names for HK files have the following form: [base name][inst]HK.fits, where

For example, the common HK file created from frf file ft940408_1555.1729 is ft940408_1555_1729CMHK.fits.

Event file names have the form [base name][inst][index][mode][bitrate].fits, where

For example the second SIS 1 event file generated from FRF file ft940408_1555.1729, with BRIGHT mode and HIGH bit rate would be called ft940408_1555_1729S100202H.fits

Terminal Output

Frfread 4.0 and later is considerably more verbose than earlier versions. You may wish to
redirect stdout to a log file. In general, messages written to stdout do not indicate serious problems, and messages to stderr, indicate errors which may affect the data.

Telemetry Corruption and Dropouts
ASCA telemetry is often garbled or lost in transmission to the ground. The telemetry format does not include a checksum, so there is no foolproof way to detect corrupted sequences. Instead, frfread checks a number of telemetry bytes with predictable values. If any of these bytes is corrupted, the entire super frame is ignored. Typically less than 1% of all super frames in a given FRF file are rejected this way.

The following messages to stdout report instances of telemetry corruption. Most indicate that a super frame has been ignored.

Dropped Events
The method described above removes the most seriously corrupted super frames, but leaves some corrupted data. Frfread also removes individual events which appear to be corrupted. Nearly all of these are null events which have had one or more of their zero bits switched to 1.

All dropped events are reported to stdout with one of the following messages:

Other Messages to stdout
There are a number of other messages which may appear on stdout: Error Messages to stderr
The following error messages are rare and probably indicate a significant problem which could affect the data integrity. You can send questions about these messages or report their occurance to ascahelp@athena.gsfc.nasa.gov.

A Note About Date Formats

Frfread 4.0 (and later versions) writes DATE-OBS and DATE-END keywords in "yyyy-mm-dd" format. However, some of the FTOOLS before FTOOLS version 4.2 may not be able to handle this format. If possible, we strongly recommend installing the latest version of the FTOOLS. However, since beta versions of frfread 4.0 may be available before the release of FTOOLS 4.2, we have provided a script old_style_dates which will convert the dates in all the event and HK files to the older dd/mm/yy format. This script is installed in the frfread bin directory. To run, simply invoke it in the directory containing the frfread output. The script requires the FTOOLS to work.

Note that the FITS standard requires that software be backwards compatible with the old style dates. However, it also specifies that the old style dates can only be used to represent dates between 1900 and 1999. Using old_style_dates on post 2000 data will give incorrect results.

This manual was last revised 1998-10-15 by Edward A. Pier of the ASCA Data Processing Team. Minor revisions 2003-06-13.