.help fgabor Apr2001 ftools.xte
.ih
NAME
fgabor --  Perform a Gabor transform on a lightcurve and return the
normalized power as a function of time and frequency.
.ih
USAGE
fgabor infile fmin fmax nfreq window outfile timeunits ratecol extname maxgap 
winfrac sigma normalize quiet clobber
.ih
DESCRIPTION
The Gabor transform takes a function of one variable, time, and maps it to 
a function of two variables, time and frequency:    
.nf
                       f(t) -> G(t,k)
.fi
For each frequency k, the function of time only G(*,k) is the result of
convolving the function f with a kernel which is the product of a fixed
Gaussian window and the complex exponential of frequency k.  So 
of G(*,k) is a filtered version of the original function (or signal) f. 
.ih
PARAMETERS
.ls infile [string - file name]
The name of the input FITS file containing the lightcurve to be analyzed.
Any OGIP-compliant lightcurve should work, though you may need to set
the ratecol and/or extname parameters appropriately (see below).
.le
.ls fmin [real - minimum frequency]
The minimum frequency to be considered in the transform. Should be greater
than ndata/window. Measured in either Hertz or cycles per dataset, depending
on the setting of the timeunits parameter (see below).
.le
.ls fmax [real - maximum frequency]
The maximum frequency to be considered in the transform. Should be less than
than the Nyquist frequency. Measured in either Hertz or cycles per dataset, 
depending on the setting of the timeunits parameter (see below).
.le
.ls nfreq [integer - number of frequencies]
The number of frequencies to use between fmin and fmax. Must be at least
two. Too high a value will result in a very large output file and will
consume proportionally more system resources during the computation.
.le
.ls window = INDEF [real - window size]
The size (+/- 3 sigma) of the Gaussian window to use in the transform.
Should be specified in either number of timesteps or in seconds, depending
on the setting of the timeunits parameter (see below, also fmin and fmax).
is used. If set to INDEF, the tool will choose a window size based on the
size of the dataset and the winfrac parameter (see below).
.le
.ls outfile = gaborpwr.fits [string - filename]
The name for the output FITS file containing the normalized power array
and a table of frequencies. Use the clobber parameter to allow the tool
to overwrite a preexisting file.
.le
.ls (timeunits = yes) [boolean - use time units]
If "yes" then the fmin, fmax and window parameters will be interpreted as
units of Hz and seconds, respectively. If "no" then they will be taken to
be in cycles per dataset and number of rows instead.
.le
.ls (ratecol = RATE) [string - rate column name]
The name of the column in the input file containing the rate information.
.le
.ls (extname = RATE) [string - lightcurve extension name]
The name of the extension (EXTNAME keyword) which contains the lightcurve
in the input FITS file.
.le
.ls (maxgap = 0.10) [real - maximum gapsize]
Defines the maximum number of consecutive rows which are missing or which
contain NULL rates (as a fraction of the total size of the dataset).
Up to this limit rows which contain NULL rate values or are missing
will be replaced by random Gaussian noise prior to performing the Gabor
transform.
.le
.ls (winfrac = 0.20) [real - default INDEF window]
Default window size (as a fraction of the total size of the dataset)
used when the window parameter (see above) is set to INDEF.
.le
.ls (sigma = INDEF) [real - Standard deviation for random noise]
When set to INDEF (the default) the Gaussian used to fill NULL
and/or missing values will be defined by the computed standard deviation
of the existing rate values. This parameter allows users to instead set
this standard deviation explicitly.
.le
.ls (normalize = yes) [boolean - Normalize output power?]
The default behavior is to normalize the output power to 1.
If this parameter is set to "no" the normalization will not
be done.
.le
.ls (quiet = no) [boolean]
If set to "yes" all standard output will be supressed.
.le
.ls (clobber = no) [boolean]
Overwrite existing output file having the same name?
.le
.ls (mode = ql) [string]
FTOOLS internal -- users should not need to change.
.le
.ih
EXAMPLES
.ih    
NOTES:
The output FITS file will include three data units. The first (primary
array) will contain the result of the Gabor transform: a FITS image with
dimensions of nfreq x nrows. The second data unit (first extension)
is a binary table listing the frequencies used in the tranform, in
units of either Hz or cycles per dataset, depending on the setting of
the timeunits parameter.  The third data unit (second extension) is a
binary table which contains a copy of the data on which the transform
was actually performed, ie with the mean value subtracted and with time
gaps and NULL values filled with random, Gaussian-distributed noise.
.le
.ih
BUGS
.le
.ls Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
.endhelp

