NAME

addshots -- add shot noise to an input light curve

USAGE

        addshots infile outfile intervals rate amplitude duration shape noise

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.

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

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.

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.

rate [double precision real]

The shot rate, in number / s.

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

amplitude [real]

The shot amplitude, in counts/s.

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.

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.

(sigma) [real]

The sigma to be used for the Gaussian noise.

(epsilon = 0) [real]

For a distribution of shot durations, the minimum duration.

(zeta = 0) [real]

For a distribution of shot durations, the maximum duration.

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

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

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

(period = 0) [double precision]

The period for the sinusoidal modulation in the EXPSIN profile.

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

(seed = -3971) [integer]

Initial seed for the random number generator. Note that this must be a negative integer.

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

(copyall = no) [boolean]

Whether to copy all other extension in the input file to the output file. (The "yes" option is not supported.)

EXAMPLES

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 

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 

NOTES:

BUGS

Version ADDSHOTS_V3.3

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

SEE ALSO

fakelc addsine

CATEGORY