ghkcurve HEADAS help file

NAME

ghkcurve - Extract light curve from ASCA GIS housekeeping file.

USAGE

        ghkcurve infile outfile gtifile+ext irate [monitor=L1]

DESCRIPTION

This program constructs a light curve file from a specified monitor count in the ASCA GIS housekeeping files. A monitor count is a simple running count, modulo 256, of the received photons that fall between the pulse-height and rise-time discriminators (and are therefore included in the GIS PH mode data). The light curve may be constructed from high-rate (0.125 sec) or medium-rate (1.0 sec) data, or from both (integrated into 1.0 sec bins). For the LDHIT monitor count, the rates are .0625 and 0.5 sec.

PARAMETERS

infile [filename]

The name of the input GIS housekeeping (HK) file (usually "*GnHK.fits", n=2 or 3).

outfile [filename]

The name of the output light curve file. The light curve is in a FITS binary table extension called `RATE', which contains an 8-byte double-precision-real column `TIME' and a 4-byte integer column `COUNTS'. In addition, a GTI table is written which is the intersection of the table specified by the gtifile parameter and the housekeeping file's ALLGTI extension, if any, sorted and with overlaps and zero-length intervals removed. The GTI table is not written if gtifile=`NONE' and there is no ALLGTI.

gtifile [filename+ext or filename[ext], default=NONE]

The name of the input file containing a Good Time Interval table, including the extension number of the table, or `NONE'.

NOTE: If the input housekeeping file has an ALLGTI extension, it will be automatically intersected with the user's input GTI; ie, an entry will be counted only if it falls within intervals from both the gtifile and ALLGTI lists. If gtifile=`NONE', only the ALLGTI will be applied, if found. If gtifile=`NONE' and there is no ALLGTI, all counts will be accepted. When using older HK files without an ALLGTI, the GTI extension should be taken from screened event or science-product files, not from mkf files (see BUGS).

irate [string]

The integration rate, HIGH (0.125 sec), MEDIUM (1.0 sec), or HI+MED (uses data at both rates, integrated into 1.0 sec bins). Points at other bit rates will be rejected. If monitor=LDHIT, the rates are 0.0625 and 0.5 sec.

monitor [string, hidden, default=L1]

The monitor count to read: L1, LDHIT, etc. L1 (the default) counts events between the rise-time and pulse-height discriminators, which enter the GIS PH mode data. LDHIT includes all events which exceed the lower pulse-height discriminator. Specify as in the HK file, except for the instrument prefix (`G2_' or `G3_') which is added automatically. (For more information, please see http://heasarc.gsfc.nasa.gov/docs/asca/monitor.html.)

EXAMPLES

1) Make a FITS light curve file `GX5_1.lcurve' with 0.125 sec time resolution from the GIS3 housekeeping file `ft931009_0333_1601G3HK.fits' using the GTI table in the second extension of the cleaned event file `ad10001000g30017h.evt':

     ghkcurve ft931009_0333_1601G3HK.fit GX5_1.lcurve ad10001000g30017h.evt+2 high

2) Make a curve of the all the LDHIT counts, with 0.5-second integration, using no GTI table:

     ghkcurve ft931009_0333_1601G3HK.fit GX5_1.ldhit none high+med monitor=ldhit

BUGS

When using housekeeping files that lack an ALLGTI extension, it is recommended that GTI inputs be taken from screened event or science product files, rather than using a GTI extension made only from the mkf file. This is because short telemetry gaps or corruptions, which are excluded from the science-file GTIs, may not be excluded in the mkf file if they are smaller than one mkf file bin length. Such telemetry gaps cause sudden jumps in the HK parameters that appear as spikes in the light curve, since GHKCURVE assumes that data gaps within a GTI are periods when no detections occured. Although GHKCURVE monitors the SF_LOST HK parameter, this does not catch all the telemetry gaps. The ALLGTI extension properly accounts for all telemetry gaps.

ASCA time is assumed. In particular, the MJDREF, TIMEREF, TIMESYS, and TIMEUNIT header keywords in gtifile are NOT compared with those in infile. TIMEZERO keywords are properly applied, however.

In previous versions, the TSTART and TSTOP header values were taken from the GTI table. This is now fixed: TSTART and TSTOP are the times of the first and last counts that went into the output light curve.

Also in the headers, DATE-OBS, TIME-OBS, DATE-END, TIME-END, and MJD-OBS are all copied from the input file, and so may not agree with TSTART and TSTOP.

This version of ghkcurve resets the basis of the timesteps after a bitrate change, after a telemetry loss flag, or when starting a new GTI, so the lightcurve entries won't always be separated by a multiple of the integration rate.