.help perdgrm Jul96 ftools.xte
.ih
NAME
perdgrm -- compute the periodogram (a discrete fourier analysis) on
light curves which are comprised of binned intensities at unevenly
spaced time intervals.  This routine uses the definition and
normalization of the periodogram given in Scargle, J. D.  1982, ApJ, 263, 835.  
.ih
USAGE
perdgrm infile outfile times rms  
.ih
DESCRIPTION
This task performs fourier analysis using the algorithm and
normalization given by Scargle, J. D.  1982, ApJ, 163, 835.  The
algorithm works with any binned time series, but is particularly
useful for series in which the bins are unevenly spaced in time.
Rather than fill data gaps with the mean intensity, the algorithm uses
a periodogram technique for determining the strength of sinusoidal
variations present in the time series.  The algorithm utilizes a 
normalization which allows for the computation of "false alarm
probabilities" of observed peaks in the power spectrum.

This task computes the power spectrum and false alarm probabilities
for an input light curve.  The light curve may be broken up into
intervals, and the intervals separately  analyzed.  Because in
general the frequency sampling of the intervals may differ, averaging
the power spectra from different intervals is not straight-forward and
is not done in this routine.  Instead, power spectra from diffent intervals are
recorded in separate FITS extensions.  The user may also modify the
frequency resolution, determine the criteria for subtracting a
polynomial from the input light curve, and modify the upper and lower
period limits in which to compute the power spectrum.  The user may
also specify whether the window function is to be computed. 

.ih
PARAMETERS
.ls infile [file name]
The name of the input FITS file.  A file following the OGIP Timing
FITS File format is expected.  If no TIME column exists, the
routine constructs the times from the TIMEZERO and TIMEDEL
keywords.  
.le
.ls outfile [file name]
The name of the output FITS file.  Results from different time
intervals are placed in separate extensions.
.le
.ls times [string]
A list of paired start and stop time ranges for intervals to be 
analyzed.  A "-" will result in all the data being analyzed in a
single interval.  Omitting a start or stop time in the first or last
interval will default to the earliest or latest time in the file.  Up
to 15 time intervals may be specified.  
.le
.ls (inres = 1)  [integer]
The frequency resolution for the fourier transform.  Higher values of
inres proportionally decreases the size of the frequency steps,
resulting in an increase in the number of frequencies.  The number of
frequency steps is given by 
.nf
       inres * (max time - min time) * (mean freq. step)
.fi
where 
.nf
      (mean freq. step) = (1/(N-1)) [sum over i] 1 / T(i) - T(i-1))
.fi
.le
.ls rms [real*4]
The rms error to be achieved by subtracting a polynomial from the
light curve.  By specifiying a negative value, the highest degree of
polynomial to be tried is abs(rms).
.le
.ls (inminP = 0) [real*4]
The minimum period to be searched, in the same time unit as the time
series.  The INDEF value is 0.
.le
.ls (inmaxP = INDEF) [real*4]
The maximum period to be searched, in the same time unit as the time
series.  The INDEF value is determined by the sampling in the light curve.
.le 
.ls (window = no) [boolean]
Whether a window function is to be computed.  If so, it is added as a
column in the output extension.
.le
.ls (chatter = 9) [integer]
Amount of information to tell the user.
.le
.ls (timename = TIME) [string]
Name for the Time column in the input FITS file.  Note that the
input string is case sensitive.
.le 
.ls (ratename = RATE) [string]
Name for the Rate column in the input FITS file.  Note that the
input string is case sensitive.
.le 
.ls (errname = ERROR) [string]
Name for the Error column in the input FITS file.  Note that the
input string is case sensitive.
.le 
.ls (copyprime = yes) [boolean]
Whether to copy the primary header and array to  the  output. (Not
supported at this time.)
.le
.ls (copyall = no) [boolean]
If true, all other extensions in the input file will be copied to the
output (only in effect when 1 input file is specified).  However, this
has not yet been implemented for SCARGLE.
.le
.ih
EXAMPLES
.nf
1.  Analyze an input light curve, subtracting a
polynomial of order 5 or less.  Also compute the window function.

perdgrm sinetest2.lc sinetest2.ft - -5  window=yes
.fi
.nf

2.  Analyze the input light curve in 3 intervals, subtracting a
polynomial of order 2 or less in each interval.  The results are output to 3
separate extensions in the output file.

perdgrm sinetest.lc sinetest.ft 49000.001-49000.003,49000.003-49000.006,
49000.006- -2  
.fi
.ih    
NOTES:
The implementation of Scargle's algorithm embodied here is based on
routines developed by Koji Mukai and Alan Smale.

This routine can also be used with event lists, if the intensity at
each time stamp is given a value of 1. 
.ih
BUGS
.ls Version PERDGRM_V3.5.2.
.le
.ls Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
.endhelp
