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

SEE ALSO

CATEGORY