FGABOR (Apr2001) ftools.xte FGABOR (Apr2001)
NAME
fgabor -- Perform a Gabor transform on a lightcurve and return the
normalized power as a function of time and frequency.
USAGE
fgabor infile fmin fmax nfreq window outfile timeunits ratecol
extname maxgap winfrac sigma normalize quiet clobber
DESCRIPTION
The Gabor transform takes a function of one variable, time, and
maps it to a function of two variables, time and frequency:
f(t) -> G(t,k)
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.
PARAMETERS
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).
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).
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).
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.
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).
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.
(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.
(ratecol = RATE) [string - rate column name]
The name of the column in the input file containing the rate
information.
(extname = RATE) [string - lightcurve extension name]
The name of the extension (EXTNAME keyword) which contains the
lightcurve in the input FITS file.
(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.
(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.
(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.
(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.
(quiet = no) [boolean]
If set to "yes" all standard output will be supressed.
(clobber = no) [boolean]
Overwrite existing output file having the same name?
(mode = ql) [string]
FTOOLS internal -- users should not need to change.
EXAMPLES
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.
BUGS
Please report problems to xtehelp@athena.gsfc.nasa.gov.
SEE ALSO