.help fakelc Jan95 ftools.xte
.ih
NAME
fakelc -- creates a fake light curve given a mean count rate.  The
output may be either an event list or a binned light curve.
.ih
USAGE
fakelc outfile type binsize binunit span spanunit cts ctsunit noise
.ih
DESCRIPTION
This task creates a single light curve with a given mean count rate.
The output light curve may take the form of either an event list or a
binned time series.  The ouput may be either an uninterrupted light
curve, or one containing data gaps.  The length of the continuous
segments is random, given the average duration of the data gaps.
Continuous segments and data gaps resulting from data sampling
typcially obtained from satellites in low
earth orbit may also be chosen. 
The user may
also specify sampling appropriate for the sampling from one HEXTE
cluster on XTE.  The output
FITS file conforms to the OGIP standards for a timing file.  No energy
information is included in the output.

The mean intensity may be specified in either counts or counts/s.
Noise may be added in the form of Poisson statistics or Gaussian
statistics.  If the latter, a sigma for the distribution is input.
.ih
PARAMETERS
.ls outfile [file name]
The name of the output FITS file.  This file complies with the OGIP
Timing FITS File Format. 
.le
.ls type = E or B [string]
The type of light curve to be produced:  E for an event list; B for a
binned light curve.  
.le
.ls binsize  [double precision real]
The sampling to be used for the fake light curve, in units of binunit.  
If a binned light curve, then this is the bin size.  For an event
list, it is the accuracy of the time stamp.  For an event list, multiple
events occuring within the time stamp accuracy are retained.  Hence,
there may be multiple time stamps in the event list.
.le
.ls binunit = s or d [string]
Time unit to be used in the light curve - seconds (s) or days (d).  Note that
for an event list, TUNIT also determines the time unit in the count
rate: count/s or count/d.
.le
.ls span  [double precision real]
The total live time for the fake observation.
.le
.ls spanunit = s or d [string]
Time unit to be used for the total live time of the fake observation,
in seconds (s) or days (d).  This time unit is also used for gaplength.
.le
.ls cts  [real*4]
The mean intensity for the light curve, in units determined by the
ctsunit parameter.  
.le
.ls ctsunit = count or count/s [string]
The units on the input intensity.  For an event list, if count is
used, a rate is computed using the BINSIZE.  Also, for an event list 
the time unit for a rate is determined by BINUNIT, so that the rate may
be either count/s or count/d.
.le
.ls noise  [integer]
The noise option to be used in producing a binned light curve.  The
integer values take on 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 CTSUNIT = 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.
  For event lists, this parameter is ignored.
.le
.ls (sigma) [real*4] 
The sigma to be used for Gaussian noise. 
.le
.ls (tstart)  [double precision real]
The absolute start time of the fake observation, nominally in MJD, but
may be input as zero.  The default value is MJD 49352.000696574074
(Jan 1, 1994, 0 hr, 1 m, 0.184 s), the reference time for the XTE mission.
.le
.ls (hexte = no) [logical]
A switch to utilize the XTE HEXTE standard modulation of 32-s on
source and 32-s off source for a single cluster.
.le
.ls (nsegs = 1)  [integer]
The number of data segments in the light curve.  Each data segment is
a continuous time series.  If nsegs > 1, then gaps will be generated
in the time axis.  The output FITS file has at least a TIME and RATE
column (and an ERROR column if noise > 0).  
.le
.ls (gaplength)  [double precision real]
The average length of each data gap for nsegs > 1.  The units are
those given by the SPANUNIT parameter.  This average
length is used to generate segments of random duration and gaps of
random size.  For nsegs = 1, this parameter has no effect.
.le
.ls (orbit = no) [boolean] 
An option to assign times according to the sampling for a typical XTE
orbit.  
.le
.ls (seed = -3267) [integer]
The initial seed for the random number generator.  Note that this must
be a negative integer.
.le
.ih
EXAMPLES
.nf
1.  Create a binned fake light curve using a constant value intensity
of 50 count/s.  The bin size is set to 0.25 s, and the total
time span is 864 s in one segment of data.  No noise is added, and
output is directed to test.lc

fakelc outfile=test.lc type=B binsize=0.25 binunit=s cts=50
ctsunit=count/s noise=0 span=864 spanunit=s 
.fi
.nf

2.  Create a binned fake light curve with a bin size of 86.4 s.  The
total live time is 1 day, but the data is broken up into 10 segments having an
average data gap of 0.05 d.  The mean intensity is 50, with units in
counts.  Poisson noise is added.  Output is directed to the file test2.lc.

fakelc outfile=test2.lc type=B binsize=86.4 binunit=s cts=50
ctsunit=count noise=1 span=1 spanunit=d  nsegs=10 gaplength=0.05
.fi
.nf

3.  Create an event list in which the average
count rate is 0.5 count/s, and the timing accuracy is 1 s.  A total
time span of 1 day is divided into 5 intervals with an average data
gap length of 0.1 days.  Output is directed to test3.lc

fakelc outfile=test3.evt type=E binsize= 1.0 binunit=s cts=0.5
ctsunit=count/s noise=0 span=0.5 spanunit=d nsegs=5 gaplength=0.1
.fi
.ih    
NOTES:
.ih
BUGS
.ls Version FAKELC_V3.3
.le
.ls Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
addsine  addshots
.endhelp
