perdgrm HEADAS help file

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.

USAGE

        perdgrm infile outfile times rms

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.

PARAMETERS

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.

outfile [file name]

The name of the output FITS file. Results from different time intervals are placed in separate extensions.

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.

(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

                    inres * (max time - min time) * (mean freq. step)

where

                   (mean freq. step) = (1/(N-1)) [sum over i] 1 / T(i) - T(i-1))

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).

(inminP = 0) [real*4]

The minimum period to be searched, in the same time unit as the time series. The INDEF value is 0.

(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.

(window = no) [boolean]

Whether a window function is to be computed. If so, it is added as a column in the output extension.

(chatter = 9) [integer]

Amount of information to tell the user.

(timename = TIME) [string]

Name for the Time column in the input FITS file. Note that the input string is case sensitive.

(ratename = RATE) [string]

Name for the Rate column in the input FITS file. Note that the input string is case sensitive.

(errname = ERROR) [string]

Name for the Error column in the input FITS file. Note that the input string is case sensitive.

(copyprime = yes) [boolean]

Whether to copy the primary header and array to the output. (Not supported at this time.)

(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.

EXAMPLES

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

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

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.

BUGS

Version PERDGRM_V3.5.2.
Please report problems to xtehelp@athena.gsfc.nasa.gov.