NAME
bctimebst -- Calculate a lightcurve and determine a burst time range based upon Bayesian block analysis.
USAGE
bctimebst infile outprefix timecol cntscol (emin) (emax)
DESCRIPTION
This tasks calcultes the time interval of the burst and additional intervals to characterize the burst as well as
the background interval. The input data are the files output from 'bcrebevt' and works for single detector
or multiple detectors where each detector is in a separate input file. It is required for the input files to have
the same time and channel binning, e.g. the TIMEDEL and TFORMS2 keywords values must be the same in all input files.
The task first calculates total lightcurve using the counts over the energy range specified by the paramater 'emin' and 'emax'.
If data are from multiple detector (one detector per input file) the tasks combines data from all detectors over the
energy range with the time binning value found in the TIMEDEL keyword of the input files.
The total combined lightcurve is than rebinned using the Bayesian block algorithm
(see Scargle et al., 2013, ApJ 764 167) and it is the baseline for the burst time interval calculation.
The time interval is found with a three steps iterative process using the Bayesian block "lightcurves" :
a) First : Find the peak of the lightcurve and an estimate of the start and stop of the burst.
b) Second: Fit the background using a polynomian fit in the lightcurve regions outside the estimated start and
stop interval of the burst.
c) Third : Subtract the fitted background from the lightcurve and using the latter lightcurve and restart
for a) recalculating the peak and the burst interval.
The iterative process stops when two consegutive iterations provide the same time interval for the burst.
At the first iteraction the all lightcurve is used for b); for subsequent iteration the background regions
are those outside of the first Bayesian block above background and the last Bayesian block above background.
The time interval found within this process is the total time on burst to include the start and the stop of the burst.
The task also provides the T90 and T50 which are respectivaly the interval containing the 90% and 50% of the burst flux
and the peak interval.
A cumulative counts curve is derived from the total combined lightcurve from the total time interval on burst and
the T90 is defined to include the 5% to 95% interval while the T50 includes the 25% to 75% interval.
The peak interval is defined as the time interval with the highest number of counts in the combined lightcurve within
the total time interval.
'bctimebst' outputs the times as good time intervals in a FITS file containing 5 extensions:
1- total time interval of the burst where the start and stop are defined as the 1st Bayesian block
and last Bayesian block above background respectively
2- T90 defined as the 90% of the flux with the total time interval
3- T50 defined as the 50% of teh flux with the total time interval
4- Peak defined as the time interval with the highest number of counts in the combined
lightcurve within the total time interval
5- Background time interval determined within this task
The task also outputs : a) plot file of the combined lightcurve (sum of all detectors) with
the Bayesian block, the start and stop of the total burst, and the background level overplotted;
b) Lightcurve of the combined data as FITS file and ASCII file; c) Bayesian block as FITS files.
PARAMETERS
infile [file name]
Name of FITS files or @filename containing list of files (one per line). The inputs approprite for this task
are the ouputs of the 'bcrebevt'.
outprefix [string]
Prefix to be used by all output files by this task.
timecol=TIME [string]
Name of the column containing the time information. By default is set to TIME.
cntscol=COUNT [string]
Name of the column containing the information the information of the counts. By default is set to COUNT.
emin=45.3 [float]
Minimum energy in keV to consider.
emax=316. [float]
Maximum energy in keV to consider.
(fprob=0.05) [float]
This is the false allarm probability used in Bayesian block analysis for the the background fitting.
The value ranges between 0 and 1. By default is set to 0.05 and not recommended to change.
(poly=3) [int]
The order of the polynimial used to fit the background. The default is set to 3, a compromise
to not overfitting the data and avoid edge effects. Not recommended to change.
(niter=100) [int]
This parameter sets the maximun number of iteration for the backgroud fitting. The value is set
to a large number while testing shows that will converge quickly if the backgroud is well modeled
by the polinomyal
(bnum=5) [int]
This value is a multiplicative number applied to the blocks before and after the burst
to exclude leading and trailing edge intervals of burst. This paramater allows to
estimate the background far away from the start and stop of the burst interval.
(refdata=REFDATA) [string]
Directory name where the FITS template for the output are located. By default this is set to enviroment variable
REFDATA.
(chatter=1) [int]
Level of chatter/verbosity of the task. Allow value are between 0-5 default is 1.
(log=no) [bool]
Flag to allow the log file creation. By default the log file is not created (log=no), if the parameter log is
set to 'yes' a log is created with a filename set to taskname_DDMMYYYY_HHMMSS.log.
(clobber=no) [bool]
Flag to overwrite existing output files. By default teh file output are not overwrite (clobber=no)
EXAMPLES
- bctimebst infile=@data.lis outprefix=test timecol=TIME cntscol=COUNT emin=10 emax=100
BUGS
SEE ALSO
LAST MODIFIED
Nov 2023