.help addshots Jan95 ftools.xte
.ih
NAME
addshots -- add shot noise to an input light curve
.ih
USAGE
addshots infile outfile intervals rate amplitude duration shape noise
.ih
DESCRIPTION
This task adds a shot noise light curve to an input binned light curve.  
The user specifies the shot shape, amplitude, duration, and rate.  The 
user also specifies a noise option.  The currently supported shot
shapes are square, exponential decay, and exponential decay with a
sinusoidal modulation.  The user may also specify a
distribution of shot durations to give a f^delta power law in the
power density spectrum.
.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 in the input 
file, the routine constructs the times from the TIMEZERI, TIMEZERF and 
TIMEDEL keywords.  If the TIME column is present, then a shot light curve 
will be added to every time bin falling within the specified time intervals.
.le
.ls outfile [file name]
The name of the output FITS format.  The format of this file follows the 
OGIP Timing FITS File Format.  Keywords from the input file are copied to 
the output file.
.le
.ls intervals [string]
The time interval(s) within which to add a shot light curve.  The time unit 
is the same as that of the input light curve.  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 start or stop time e.g., -35622.0, or 45329.0- .
Up to 15 time intervals may be specified.  Results from different
intervals are output to different extensions.
.le
.ls rate [double precision real]
The shot rate, in number / s.
.le
.ls shape = SQUARE, EXPON or EXPSIN [string]
The shot shape.  Currently the following profiles are provided:
flat-top (SQUARE), exponentially decaying (EXPON), or exponential decay 
with a sinusoidal modulation (EXPSIN).
.le
.ls amplitude [real]
The shot amplitude, in counts/s.
.le
.ls duration [double precision real]
The shot duration, in seconds.  For EXPON and EXPSIN shots, this is the
exponential decay constant; for 
SQUARE shots, it is the total duration.
.le
.ls noise [integer]
The noise option to be used in producing the shot light curve.  The integer 
values have the following meanings:  0 = no noise; 1 = Poisson noise; 2 = 
Gaussian noise.  The Poisson statistics are governed by the intensity as 
expressed in counts.  (If the input intensity is in COUNT/S, the conversion 
to COUNTS is done internally using the bin 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, ADDSHOTS 
assumes the input data is noise-less.  Adding a noise shot light curve to a 
noise-less input will result in the creation of an ERROR column in the 
output FITS file.  If Poisson nose is specified, the ERROR is computed 
using Poisson statistics on the total counts (input + shots).  If Gaussian 
noise is specified, the sigma inputted is applied only to the shot light 
curve.
.le
.ls (sigma) [real]
The sigma to be used for the Gaussian noise.
.le
.ls (epsilon = 0) [real]
For a distribution of shot durations, the minimum duration.
.le
.ls (zeta = 0) [real]
For a distribution of shot durations, the maximum duration.
.le
.ls (delta = 0) [real]
For a distribution of shot durations, the desired power law for the
resulting power density spectrum.  Note that -2 .le. delta .le. 0.
.le
.ls (alpha = 0) [real]
The exponent for a power law dependence of the amplitude on the
duration.  Note that alpha must be negative, and the dependence takes
the form of 
  amp = amp * (duration/bin)^(alpha/2)
.le 
.ls (amod = 0) [real]
The amplitude for the sinusoidal modulation in the EXPSIN profile.
Note that shots having only positive intensity result when amod < amp.
When amod > amp, the shot profile itself may contain negative intensity 
values.
.le
.ls (period = 0) [double precision]
The period for the sinusoidal modulation in the EXPSIN profile.
.le
.ls (psig = 0) [double precision]
The sigma for the deviation in the period of the sinusoidal modulation
in the EXPSIN profile.  Specific periods are generated from a gaussian
distribution based on period and psig.
.le
.ls (seed = -3971) [integer]
Initial seed for the random number generator.  Note that this must be
a negative integer.
.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.)
.le
.ls (copyall = no) [boolean]
Whether to copy all other extension in the input file to the output file.  
(The "yes" option is not supported.)
.le
.ih
EXAMPLES
.nf
1.  Add shot noise comprised of exponentially decaying shots to an
input light curve.  The shots have an amplitude of 10 count/s, a
decay time of 2.5 seconds, and have no noise added.
The shot rate is 5 shots per second

addshots infile=test.lc outfile=shottest.lc intervals=- rate=5.
amplitude= 10. duration=2.5 shape=EXPON noise=0 
.fi
.nf

2.  Add shot noise to the first part of the input light curve.  Use
square shots, with an amplitude of 0.1 count/s, a duration of 235
seconds, a shot rate of 0.05 shots/s, and poisson noise added with 
the shot light curve.

addshots infile=test2.lc outfile=shottest2.lc intervals=-49000.45
rate=0.05 amplitude= 0.1 duration=235. shape=SQUARE noise=1 
.fi
.ih
NOTES:
.ih
BUGS
.ls Version ADDSHOTS_V3.3
.le
.ls  Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
fakelc addsine
.endhelp 
