.help addsine Jan95 ftools.xte
.ih
NAME
addsine -- adds a sine curve (or a user-defined periodic function) 
to an existing timing FITS file.  
.ih
USAGE
addsine infile outfile intervals period perunit amplitude zerophase
noise 
.ih
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.
.ih
PARAMETERS
.ls 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.
.le
.ls 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.
.le
.ls 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. 
.le
.ls period [double precision real]
The period of the sine curve, in units given by the perunit parameter
.le
.ls perunit [string]
The units for the period, either in seconds (S) or days (D)
.le
.ls amplitude  [real*4]
The amplitude of the sine curve, using the same units as the input file.
.le
.ls zerophase  [double precision real]
The time of zero phase for the sinusoid, in MJD
.le 
.ls 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.  
.le
.ls (sigma) [real*4] 
The sigma to be used for Gaussian noise. 
.le
.ls (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.
.le
.ls (seed = -4597) [integer]
The initial seed for the random number generator.  Not that this must
be a negative number.
.le
.ls (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.
.le 
.ls (ratename = RATE) [string]
Name of the intensity column to be added to.  If ratename not found in
the input file, execution ceases.
.le
.ls (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. 
.le
.ls (copyprime = yes) [boolean]
Whether to copy the primary header and array to  the  output. (The
"no" option is 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 ADDSINE.
.le
.ih
EXAMPLES
.nf
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 
.fi
.nf

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.
.fi
.ih    
NOTES:
.ih
BUGS
.ls  ADDSINE_V3.3
.le
.ls Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
fakelc  addshots
.endhelp






