NAME

addsine -- adds a sine curve (or a user-defined periodic function) to an existing timing FITS file.

USAGE

        addsine infile outfile intervals period perunit amplitude zerophase noise 

DESCRIPTION

This task adds a sine curve to an existing light curve. The user specifies the period, amplitude, and time of zero phase of the sinusoid. The user may also choose whether noise is put on the sine curve. The user may specify a user-defined pulse shape to add instead of a sinusoidal variation.

PARAMETERS

infile [file name]

The name of the input FITS file. A file conforming to the OGIP Timing FITS File format is expected. If no time column exists, the routine constructs the times from the TIMEZERO and TIMEDEL keywords. If a time column is present, then the sine curve will be added to every time bin falling within the desired time intervals.

outfile [file name]

The name of the output FITS file. The format of this file follows the OGIP Timing FITS File Format. The header keywords from the input file are copied to the output file.

intervals [string]

The time interval(s) within which to add the sine curve, expressed in MJD. These intervals are listed as pairs of start and stop times. To default to all the data in the file, use -. To default an interval to the beginning or end of the data, omit the interval's start or stop time, e.g. -35632.0 or 32752.0- . Up to 15 time intervals may be specified. Results from different intervals are output to different extensions.

period [double precision real]

The period of the sine curve, in units given by the perunit parameter

perunit [string]

The units for the period, either in seconds (S) or days (D)

amplitude [real*4]

The amplitude of the sine curve, using the same units as the input file.

zerophase [double precision real]

The time of zero phase for the sinusoid, in MJD

noise [integer]

The noise option to be used in producing the sinusoid. The integer values have the following meanings: 0 = no noise; 1 = Poisson noise; 2 = Gaussian noise.

The Poisson statistics are governed by the mean intensity as expressed in counts. (If the units on the intensity column is COUNT/S, the conversion to COUNTS is done internally using the sample size.) If Gaussian noise is specified, the sigma for the Gaussian distribution is specified using the sigma parameter. If the input file does not have an error column, ADDSINE currently assumes the input data is noiseless. Adding a noisy sine curve to a noise-less input will result in the creation of an ERROR column in the ouput FITS file. If Poisson noise is specified, the error is computed using Poisson statistics on the total counts (input + sine). If Gaussian noise is specified, the sigma inputted here is applied only to the sine curve.

(sigma) [real*4]

The sigma to be used for Gaussian noise.

(profile) [string]

Name of an optional file which contains a user-defined pulse shape. The file is a two column ascii file in which the first column is the phase and the second column is the corresponding normalized intensity. Up to 50 phase bins may be specified. A linear interpolation is used to derive intensity values for phases not explicitly given.

(seed = -4597) [integer]

The initial seed for the random number generator. Not that this must be a negative number.

(timename = TIME) [string]

Name of the time column to be used. If no time column exists, then times will be constructed based on the time bin size given in the header.

(ratename = RATE) [string]

Name of the intensity column to be added to. If ratename not found in the input file, execution ceases.

(errname = ERROR) [string]

Name of the column containing the uncertainty values for the intensity column. If errname not found, the input data is assumed to be noiseless.

(copyprime = yes) [boolean]

Whether to copy the primary header and array to the output. (The "no" option is 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 ADDSINE.

EXAMPLES

1. Add a sine curve to all data in an input file. The sine curve has a period of 2.53 s, an amplitude of 10 (in the units of the input file), and a time of zero phase of 49000. Poisson noise is added to the sine curve. addsine infile=test.lc outfile=sinetest.lc intervals=- period=2.53 perunit=s amplitude=10 zerophase=49000. noise=1

2. Add a sine curve to the latter part of a data file. The sine curve has a period of 0.367 d, an amplitude of 10 (in units of the input file), and a time of zero phase of 49000. Gaussian noise is added, with a sigma of 3. addsine infile=test2.lc outfile=sinetest2.lc intervals=49000.4- period=0.367 perunit=d amplitude=10 zerophase=49000. noise=2 sigma=3.

NOTES:

BUGS

ADDSINE_V3.3

Please report problems to xtehelp@athena.gsfc.nasa.gov.

SEE ALSO

fakelc addshots

CATEGORY