C Interface
int HDgti_init(struct gti_struct *gti)
int HDgti_free(struct gti_struct *gti)
int HDgti_copy(struct gti_struct *dest, struct gti_struct *src, int *status)
int HDgti_grow(struct gti_struct *gti, int new, int *status)
int HDgti_merge(int mode, struct gti_struct *gti,
struct gti_struct *agti, struct gti_struct *bgti,
int *status)
int HDgti_clean(struct gti_struct *gti, struct gti_struct *ogti,
int *status)
double HDgti_exp(double t1, double t2, struct gti_struct *gti, int *status)
int HDgti_where(struct gti_struct *gti, int ntimes,
double *times, int *segs, int *status)
int HDgti_read(fitsfile *fptr, struct gti_struct *gti,
char *extname, char *start, char *stop,
int *status)
int HDgti_readfile(char *filename, struct gti_struct *gti,
char *extname, char *start, char *stop,
int *status)
int HDgti_write(fitsfile *fptr, struct gti_struct *gti,
char *extname, char *start, char *stop,
int *status)
double HDget_frac_time(fitsfile *fileptr, char *key,
double *vali, double *valf,
int *status)
int HDput_frac_time(fitsfile *fileptr, char *key,
double vali, double valf,
int force, char *comment,
int *status);
Perl Interface
use HEACORE:HEAUTILS; HDgti_empty(); HDgti_read($fits,$extname,$startcolname,$stopcolname,$status); HDgti_write($fits,$gti,$extname,$startcolname,$stopcolname,$status); HDget_frac_time($fits,$keyname,$vali,$valf,$status); HDput_frac_time($fits,$keyname,$vali,$valf,$force,$comment,$status); HDgti_merge($mode,$agti,$bgti,$status);
This module contains routines which are used to create, manipulate, read and write "good time intervals" or GTIs. A GTI contains information about a set of time intervals, which are typically useful for astronomy data processing. For example, a GTI usually contains information about exposure start and stop times. This module has routines which interface with standard FITS-format GTI files.
The primary data structure used by this module is the gti_struct structure, which is defined here:
struct gti_struct {
double mjdref; /* MJD Reference time of GTI */
double timezero; /* Timezero time offset of GTI */
int ngti; /* Number of occupied time values */
int maxgti; /* Maximum amount of time values */
double *start, *stop;/* Pointer to start[] and stop[] arrays */
void *dptr; /* Raw data storage pointer */
};
Most of these fields correspond to time-specific keywords within
FITS GTI files.
In perl, GTIs a represented as hash references. The hash structure is
{ mjdrefi => 0,
mjdreff => 0.0,
timezero => 0.0,
start => [],
stop => [] }
Here start and stop are perl array references. Some of the book-keeping
elements found in the C structure are not required, since Perl can dynamically
allocate the needed arrays. Thus, ngti is not needed because start and stop
can be sized directly.
In C, the user is responsible for allocating a gti_struct structure using malloc or some other suitable means. There are two ways to initialze the data structure. The function HDgti_init() can be used to initialize a structure to a consistent empty state. An initialized structure begins life empty with no internal storage. Alternatively, the HDgti_copy() function can be used to duplicate an existing GTI structure into an uninitialized destination data structure.
In Perl, a blank GTI can be constructed by using HDgti_empty(), which returns a blank hash reference. In Perl, no explicit deallocations are required.
The function HDgti_free() is used to deallocate any internal storage and must be called by the user before de-allocating the gti structure itself.
A GTI may be enlarged using HDgti_grow(), where the user specifies the new maximum amount of storage. Thus, the standard life-cylce for a GTI will be something like this:
{
struct gti_struct gti; /* or allocate with malloc() */
HDgti_init(>i); /* initialize structure */
HDgti_grow(>i, ngti, &status); /* grow to desired size */
/* ..... process with GTI ..... */
HDgti_free(>i);
/* de-allocate "gti" with free() if appropriate */
}
In Perl, HDgti_grow() is not required because the start and stop
array references can be sized as needed.
The function HDgti_read() is used to initialize a GTI structure using the contents of existing FITS GTI extension. The file should be formatted according to the OGIP/93-003 memo, "The Proposed Timing FITS File Format for High Energy Astrophysics Data." The MJDREF and TIMEZERO keywords should be present in the requested extension. If they are not present, the default value is assumed to be zero. The variant HDgti_readfile() can be used to open a GTI file by name, whereas the HDgti_read() variant is used for a GTI file already opened by the CFITSIO library for reading.
The function HDgti_write() is used to write a GTI structure as a new FITS extension. The file must exist and be open for writing.
The utility routine HDget_frac_time() can be used to read keyword that can potentially be stored either as the complete value or as integer and fractional components. For example the reference time value can either be stored as MJDREF (complete numerical result) or two keywords, MJDREFI and MJDREFF, representing the integer and fractional components. HDget_frac_time() attempts both alternatives and returns the results.
The equivalent routine HDput_frac_time() can be used to write the needed integer/fractional time keywords. Some capability is provided to allow the user to write either the integer/fractional or total value, depending on the existing contents of the output file.
This module also supports manipulation and tabulation capabilities for GTI structures.
The HDgti_exp() function calculates the overlap exposure time between a requested start and stop time and a given GTI structure.
The HDgti_where() function computes which GTI time interval a requested event falls into, or -1 if the event time does not fall into any interval.
The HDgti_merge() function performs a merging function between two GTI structures. The merge can either be an "intersection" (GTI_AND) operation, which represents the overlapping intervals that occur in both GTI structures; or a "union" (GTI_OR) operation, which represents the intervals which occur in either one GTI structure or the other.
The HDgti_clean() function takes as input a GTI structure and performs sanity check operations. After "cleaning" the GTI structure will be in time order with duplicate and overlapping time intervals removed. I.e. there will be no redundant intervals and two overlapping intervals will be joined into one.
HDgti_init - initialize GTI structure (C only) Intializes an already-existing GTI structure. It is assumed that no memory needs to be deallocated. struct gti_struct *gti - pointer to existing GTI structure. RETURNS: status code
HDgti_empty - initialize GTI structure (Perl only) Returns an empty GTI structure as a hashref. The structure of the hash is described above. RETURNS: hashref
HDgti_free - deallocate memory associated with GTI structure (C only) Deallocates memory pointed to by GTI structure. The structure itself is not deallocated, but any time intervals are. The structure is then initialized to zeroes. struct gti_struct *gti - pointer to existing GTI structure. RETURNS: status code
HDgti_copy - deep copy GTI from one structure to another (C only) Perform deep copy of GTI from source to destination structures. The structures must already have been allocated; the contents are then transferred. struct gti_struct *dest - pointer to existing GTI structure, dest of copy struct gti_struct *src - pointer to existing GTI structure, source of copy int *status - pointer to status variable RETURNS: status code
HDget_frac_time - get (potentially) fractional time keyword from FITS header
Some OGIP FITS timing values are allowed to be specified either as
a single keyword, or a pair of keywords which gives integer and
fractional values which are to be added. This allows maximum time
precision. For example, for the observation starting time, it can
either be found by:
RETURNS *vali *valf
TSTART - single value TSTART TSTART 0
TSTARTI - integer value TSTARTI+F TSTARTI TSTARTF
TSTARTF - fractional value
This routine read a FITS timing keyword(s). The returned values
are given above. If the user passes null values for vali and/or
valf, then HDget_frac_time will gracefully skip storing those values.
fitsfile *fileptr - open FITS file pointer, open to HDU where
keywords are to be found
char *key - keyword name, "TSTART", "TIMEZERO", etc.
double *vali - upon return, and if vali is not null, then the whole
number of seconds is stored in *vali.
double *valf - upon return, and if valf is not null, then the fractional
number of seconds is stored in *valf.
int *status - pointer to status variable
RETURNS: (TSTART) or (TSTARTI+TSTARTF)
The Perl calling signature is similar)
HDget_frac_time($fits,$keyname,$vali,$valf,$status)
$fits - CFITSIO handle opened by Astro::FITS::CFITSIO
$keyname - name of keyword to get
$vali/$valf - upon return, values of integer & fractional part
$status - input/output, CFITSIO status variable
RETURNS: (TSTART) or (TSTARTI+TSTARTF)
HDput_frac_time - put fractional time keyword
Some OGIP FITS timing values are allowed to be specified either as
a single keyword, or a pair of keywords which gives integer and
fractional values which are to be added. This allows maximum time
precision. For example, for the observation starting time, it can
either be found by:
RETURNS *vali *valf
TSTART - single value TSTART TSTART 0
TSTARTI - integer value TSTARTI+F TSTARTI TSTARTF
TSTARTF - fractional value
In the documentation that follows, we use the notation KEYI and KEYF
for the integer and fractional versions of the keyword, and KEY for
the combined version of the keyword.
This routine writes FITS timing keyword(s). The returned values
are given above. If the user passes null values for vali and/or
valf, then HDget_frac_time will gracefully skip storing those values.
The subroutine will write the requested keywords and make sure that
the equivalent keywords of the other type are deleted. For
example, if one requests to write the KEYI/KEYF keywords with
force=1, then the KEY keyword will be deleted if it exists.
If one requests the full keyword KEY be written with force=2, then
the KEYI and KEYF keywords are deleted if requested. In that case,
the sum of vali+valf is written to the KEY keyword, so it is not
necessary for the caller to break the value into integer and
fractional parts.
fitsfile *fileptr - open FITS file pointer, open to HDU where
keywords are to be found
char *key - keyword name, "TSTART", "TIMEZERO", etc.
double vali - the requested time to be written (integer).
double valf - the requested time to be written (fractional).
int force - force writing of specific style of keyword
0 = don't care (will use existing KEY/KEYI/KEYF if found)
1 = force use of KEYI/KEYF (will delete KEY)
2 = force use of KEY (will delete KEYI/KEYF)
int *status - pointer to status variable
RETURNS: 0 upon success
CFITSIO error status upon failure
The Perl calling signature is similar)
HDput_frac_time($fits,$keyname,$vali,$valf,$force,$comment,$status)
$fits - CFITSIO handle opened by Astro::FITS::CFITSIO
$keyname - name of keyword to get
$vali/$valf - upon return, values of integer & fractional part
$force - force parameter as described above
$status - input/output, CFITSIO status variable
RETURNS: status code
HDgti_grow - enlarge the storage of an existing GTI structure (C only)
Takes an existing GTI structure, and enlarges it to a new size,
i.e., increases the maximum number of GTI rows that can be stored
in the structure.
The storage can never shrink. Thus, users can call this function
whenever they anticipate needing a certain number of GTI rows. The
existing values will be preserved.
HDgti_grow() handles the case where the GTI structure has been
initialized and has no allocated storage associated with it, yet.
struct gti_struct *gti - pointer to existing GTI structure, to be
enlarged.
int new - new maximum number of rows of storage which gti should contain.
int *status - pointer to status variable
RETURNS: status code
HDgti_read - read a GTI extension from a FITS file
HDgti_read reads a GTI extension from a FITS file, which has already
been opened for reading by the CFITSIO library. Upon completion, the
file is left open at the GTI HDU.
The HDgti_readfile variant opens a file by name and reads the
specified extension. Upon completion, the file is closed.
Both variants will search for the first extension matching the extname
parameter, in the case of HDgti_read() starting at the currently open
HDU, and proceeding to the end of the file. Set extname="*" to
match the first extension of the open file, or "(current)" to use the
currently open extension.
The user can choose the column names to read. The user can also
provide a reference GTI.
char *filename - name of FITS file to read (HDgti_readfile)
fitsfile *fptr - already opened FITS file (HDgti_read)
struct gti_struct *gti - pointer to existing GTI structure, to be
filled with data from FITS file.
char *extname - name of extension, or 0 for default of "GTI"
(set extname="*" to use first open table extension)
char *start - name of START column, or 0 for default of "*START*"
char *stop - name of STOP column, or 0 for default of "*STOP*"
int *status - pointer to status variable
RETURNS: status code
The Perl signature is similar
HDgti_read($fits,$extname,$startcolname,$stopcolname,$status)
The FITS file is required to be open via Astro::FITS::CFITSIO,
therefore there are no separate parameters for file name and file
handle. The value is returned directly instead of via pointer.
$fits - open CFITSIO file handle via Astro::FITS::CFITSIO
$extname - as described above
$startcolname/$stopcolname - as described above
$status - input/output, CFITSIO status
RETURNS: GTI hashref
HDgti_write - create a GTI extension and write it Writes a GTI extension to a FITS file. A binary table is created and populated with the gti "gti". Basic OGIP GTI keywords are written. The file is left open upon return so that users may manipulate the header afterwards. The units are assumed to be seconds. The user can choose the extname, and column names to write. When a GTI is empty, HDgti_write writes a special GTI that has one row but no actual exposure (i.e. START == STOP). This aids downstream software such as the mgtime task and some extractors when it comes to interpreting a truly empty GTI, rather than just ignoring the GTI file in that case. The START and STOP value for that one row need to come from somewhere, which is the tdefault value. Typically tdefault should be an in-bounds time value, such as the first time value in the input file. A value of zero is an acceptable value. If tdefault is negative, then no rows are written to the output. fitsfile *fptr - already-open FITS file, open for writing struct gti_struct *gti - populated GTI structure, to be written to fptr char *extname - name of extension, or 0 for default of "STDGTI" char *start - name of START column, or 0 for default of "START" char *stop - name of STOP column, or 0 for default of "STOP" double tdefault - default value for empty GTIs (see above) int *status - pointer to status variable RETURNS: status code The Perl signature is similar HDgti_write($fits,$gti,$extname,$startcolname,$stopcolname,$tdefault,$status) $fits - open CFITSIO file handle via Astro::FITS::CFITSIO $gti - GTI hashref to be written $extname - as described above $startcolname/$stopcolname - as described above $tdefault - as described above $status - input/output, CFITSIO status RETURNS: status code
HDgti_merge - merge two GTIs either using intersection or union Merges two different good time interval lists. If the mode is GTI_AND, then the intersection between the two lists is determined. If the mode is GTI_OR, then the union between the two lists is found. This routine is based heavily on the fortran version, taken from the HEASARC extractor (gtilib.f). The metadata such as MJDREF and TIMEZERO are taken from the "A" GTI, unless the values are zero, in which case the values are taken from the "B" GTI. int mode - merging mode, either GTI_AND or GTI_OR struct gti_struct *gti - pointer to existing GTI structure, result of merge struct gti_struct *agti - pointer to existing GTI structure, 1st input GTI struct gti_struct *bgti - pointer to existing GTI structure, 2nd input GTI int *status - pointer to status variable RETURNS: status code The Perl signature is similar HDgti_merge($mode,$agti,$bgti,$status) However, the resulting merged GTI is returned directly rather than by pointer. $mode - either "OR" or "AND" $agti - first input GTI (hashref) $bgti - second input GTI (hashref) $status - input/output, status code RETURNS: resulting GTI hashref
HDgti_clean - clean a GTI by sorting, removing duplicates, overlaps (C only) HDgti_clean: Sort a gti list and remove invalid and overlapping intervals by calling HDgti_merge to OR it with nothing. This routine is based heavily on the fortran version, taken from the HEASARC extractor. struct gti_struct *gti - pointer to existing GTI structure, result of clean struct gti_struct *ogti - pointer to existing GTI structure, to be cleaned int *status - pointer to status variable RETURNS: status code
HDgti_exp - compute overlap exposure of a time bin with GTI (C only)
Exposure: What part of the time interval (t1, t2) is contained
within the Good Time Intervals? (For the fractional exposure, just
divide gtiexp by (t2-t1).)
NOTE: It is *VITAL* that the GTI list be ordered and
contain no overlaps! If in doubt, call HDgti_clean first.
also, we assume that t1, t2, and the gti list are all
in the same units.
One difference from the FORTRAN version is that if there are no
good time intervals (i.e. gti->ngti == 0), then zero is returned
here. In the FORTRAN version, the whole exposure is returned.
double t1 - start of time bin.
double t2 - stop of time bin. (note: t1 < t2)
struct gti_struct *gti - pointer to existing GTI structure, whose
overlap with the time bin is to be computed.
int *status - pointer to status variable
RETURNS: overlap exposure
HDgti_where - which good time intervals a set of times falls into HDgti_where examines an array of times, and determines which good time intervals the times fall into. This routine is most highly optimized for times which are sorted in time order. An interval of -1 indicates a time that does not fall into a good time interval. struct gti_struct *gti - pointer to existing GTI structure. int ntimes - size of times array. double *times - an ntimes-element array, times to be examined. int *segs - an ntimes-element array. Upon return, the values give which good time interval the time falls into: (times[i] >= gti->start[segs[i]]) && (times[i] < gti->stop[segs[i]]) or, if segs[i] is -1, the time does not fall into a GTI int *status - pointer to status variable RETURNS: status code