.help lcmath Aug96 xanadu.xronos
.ih
NAME
lcmath - Subtracts or adds two binned lightcurves.
.ih
USAGE
lcmath infile bgfile outfile multi multb
.ih
DESCRIPTION
This program takes as input two binned lightcurves and calculates a result
lightcurve either subtracting (second from the first) or adding the two input
files. The two input files should cover the same time interval. In particular
the start time and the stop time of the first lightcurve should be included
within the start and stop time of the second lightcurve. Error are prompt if
the start and/or the stop are outside of the time interval of the second file.
The time resolution of the two files can be different, but the integration
time of the first input file should be always less than or equal to that in
the seconf input file. The task does not work for input files containing
"EVENT" table. Constant scaling and additive factors can be separately input
for both lightcurves. By default, the task will apply any vignetting (or 
collimator) and  deadtime correction information contained
in the input file (header keywords VIGNET and DEADC) to the result lightcurve.
The user may cancel this correction setting the parameter "docor".
The columns names recognized by the task are TIME, COUNT, RATE and 
ERROR. The units (TUNITn keyword) are expected to be 'count' for column name 
'COUNT' and 'count/s' for column name RATE. The input file structure is 
a FITS bintable with data stored in the column COUNT or RATE either as a single
element or a vector of element in each row. For the last case the task works 
correctly only if the column n contains a vector of counts in different 
channel (the value of the column keyword 1CTYPn should be 'CHANNEL').
The paramaters "emin" and "emax" are applicable in this case. The structure 
of the output file will have always data stored as a single element in 
each row.
.ih
ERRORS
If scaling and additive factors are input for both file1 and file2 
the derived counts are calculated as:
             count1=M1*x1 + C1      count2=M2*x2 + C2
where M1 and M2 are the input scaling values for the first and second 
lightcurve respectively; C1 and C2 are the additive input factors
in counts (rescaling for the fractional exposure) and 
x1 and x2 are the value always in counts read from the files 
(if the file contains rate x1 and x2 are the value after rescaling for the 
integration and exposure time).
The final results in the output file will be: 
             count3= count1 -/+ count2
divided for the integration time. 
The error for count3 is calculated as: 
             err3= sqrt( err1**2 + err2**2) 
where err3, err2, and err1 are the error values for the count3, count2 and
count1 respectively. 
To calculate the individual errors (i.e. err1 for the quantity count1 
and err2 for the quantity count2) the user can choose one of the 
6 different methods listed below. 

Method 1   
  err1=sqrt((sqrt(M1*sx1*sx1))**2 + C1) 

Method 2   
  err1=sqrt((M1*sx1)**2) 

Method 3   
  err1=sqrt( (sqrt(M1*sx1*sx1))**2) 

Method 4   
  err1=sqrt( (M1*sx1)**2 + C1) 

Method 5   
  err1=sqrt(count1) 

Method 6
  The error in the output file is set equal to the value
  of the error of first input file (i.e. err3=sx1)

If the file contains an error column, sx1 is the value in the file 
rescaled for the integration time and exposure, otherwise sx1 is set
as the sqrt(x1) or sqrt(x2). If x1 or x2 are 0 the error (sx1 or sx2)
is set to 1. If the scaling factor is 1 and the additive factor is 0, 
the methods 1,2,3,4 are equivalent.  

.ih
PARAMETERS
.ls infile [filename]
The name of the first input lightcurve. If the task is used in subtraction 
mode the file should contain source+background data.
.le
.ls bgfile [filename]
The name of the second input lightcurve. If the task is used in subtraction 
mode the file should contain background data.
.le
.ls outfile [filename]
The name of the output result lightcurve. If lcmath is used in the subtracting
mode the file contain source data only and the keyword BACKAPP is added
or updated.
.le
.ls multi = 1. [real]
Scaling factor for first input lightcurve.
.le
.ls multb = 1. [real]
Scaling factor for second input lightcurve (or background lightcurve).
.le
.ls (addsubr = no) [boolean]
Flag to Add input lightcurve instead of subtract. The default 
value is set to subtract (addsubr=no no add) the lightcurve.
.le
.ls (addi = 0.) [real]
Additive offset for first input lightcurve. This value should be 
given as counts (internally the value corrected for the bin fractional exposure).
.le
.ls (addb = 0.) [real]
Additive offset for second input lightcurve (or background lightcurve).
This value should be given as counts (internally the value 
is corrected for the bin fractional exposure).
.le
.ls (docor = yes) [boolean]
Whether to apply the corrections to the result lightcurve. If the input 
lightcurves have stored in the header the vignetting or collimator 
(VIGNET keyword) and the deadtime (keyword DEADC) correction, this 
is also apply by default to the output lightcurve.
.le
.ls (emin = 0) [integer]
Minimum energy channel to use.  Enter 0 for no lower bound.
.le
.ls (emax = 0) [integer]
Maximum energy channel to use.  Enter 0 for no upper bound.
.le
.ls (err_mode = 0) [integer]
Method to calculate the errors on the individual input lightcurve.
The value of the paramater ranges from 1 to 5 (see ERRORS section)
and is default to 1.
ERROR   
.le
.ls (tchat = 10) [integer]
Terminal chattiness level.
.le
.ls (lchat = 0) [integer]
Logfile chattiness level.
.ih
EXAMPLES
.fi
.ih
BUGS
Report problems to angelini@lheavx.gsfc.nasa.gov,
xanprob@athena.gsfc.nasa.gov.  Provide a detailed description of the
problem (possible a log file).
.ih
SEE ALSO
.endhelp
