.help ghkcurve May97 ftools.asca
.ih
NAME

ghkcurve - Extract light curve from ASCA GIS housekeeping file.
.ih
USAGE

ghkcurve infile outfile gtifile+ext irate [monitor=L1]
.ih
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.
.ih
PARAMETERS
.ls infile [filename]
The name of the input GIS housekeeping (HK) file (usually "*GnHK.fits",
n=2 or 3).
.le
.ls 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.
.le
.ls 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).
.le
.ls 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.
.le
.ls 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.)
.le
.ih
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':
.nf

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

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

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

.fi
.ih
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.

.ih
SEE ALSO

For further explanation of the GIS monitor counts, please see
http://heasarc.gsfc.nasa.gov/docs/asca/monitor.html.

.endhelp
