NAME
burstfinder - Find time intervals in an input FITS binned lihtcurve that characterize start and stop of a burst.
USAGE
burstfinder infile outroot timewin numsdv fraction polyorder numsdv2 timewin2 mufactor
DESCRIPTION
'burstfinder' searches the lightcurve for time intervals associated to a burst
and writes out files containing these time intervals. The input file is a FITS lightcurve
from which the task read the TIME and RATE (or COUNT) columns and the header keyword TIMEDEL.
The search for the time intervals is accomplished by a two steps approch :
- The first step uses a sliding-window technique to remove extreme outliers in the
lighcurve. Internally read the RATE column from the input lightcurve and make a copy NEW_RATE.
For each point calculates an average value based a time window (parameter "timewin') of previous
data points. If the difference between the current RATE value and the previous average value is
greater than a threshold (parameter 'numsdv'), the value of NEW_RATE is calculated as
((1-fraction) * average(i-1)) + fraction * RATE(i) where fraction is an input parameter.
At the end of the sliding-window process, the NEW_RATE should be devoid of any major peaks
and this array is fitted with a polynomial (see parameter 'polyorder').
- The second step compares the RATE values with the polynomial fit.
The RATE values are first smoothed by finding the average value at each data point
using the +/- values in a time window (see parameter 'timewin2').
The calculated average is compared with the polynomial fit. If the difference
between the average value and the polynomial fit is greater than a threshould, defined
as sigma*numsdv2 where sigma is calculated from the polynomial fit and
'numsdv2' is a parameter, the algorithm searches backward. The backward search stops
when the difference between the average value and the polynomial fit is near or below
sigma*mufactor where 'mufactor' is a multiplicative input parameter.
This is set as the start of the burst. To find the end of the burst, the algorithm keeps track of
the average value moving forward until it is near or below the polynomial fit, set as end of the burst.
The algorithm returns all time intervals where a possible burst is detected and if two time intervals
are significantly close to each other (see parameter "min_int'), they are combined into a single
time interval.The start and stop time found for each burst is considered the total time interval
of the burst.
For each burst total time interval , 'burstfinder' calculates start and stop time corresponding to
the 90% , 50% and peak flux of the burst as well as the pre-burst and post burst backgroud.
The information is written out in three different output files :
- A FITS file (_dur.gti) containing separate GTI extensions for time intervals (start and stop)
corresponding to the total, peak, T90 and T50 of the burst as well GTI extensions for the
pre- and post-burst backgrounds. The
- A FITS file (_summary.fits) containing one extension where each row reports start stop
for the total, peak, T90, T50 for a burst together with the start and stop for the pre and post burst
backgroud and the rate for the total burst interval.
- An ASCII file containing the same information in the _summary.fits.
PARAMETERS
- infile [filename]
- Input lightcurve. The input file is a binned FITS format lightcurve which contains the burst.
The lightcurves should contain the column TIME and either RATE or COUNTS.
- outroot [filename]
- Root for the output files. 'burstfinder' creates three outfiles :
1) outroot_dur.gti containing several GTI extension each for a specific time interval
(T90, T50, total, and peak burst intervals, plus time intervals for pre- and post-burst
backgrounds ), 2) outroot_summary.fits containing a single extension with the
same start and stop time intervals as in the GTI extension as well total rate and background rates,
3) outroot_summary.txt ASCII format of the summary file with the same information of the fits
file equivalent.
- (leapfile = "REFDATA" [string])
- Name of the input leap second file. If set to REFDATA (default)
uses the leapsecond file in REFDATA area. The REFDATA area is an enviroment
variable set with the FTOOLs
- timewin [real]
- Time window (in seconds) to calculate the average in the first step. Default 10s
- numsdv [integer]
- Number of standard deviations used in the first step to calculate the threshould
used to evaluate the difference between the current RATE value and the previous average value.
Deafult is set to 3.
- fraction [real]
- Fraction used in the calculation of the threshould together with the parameter
numsdv in the first step. Value range between 0 and 1, default set to 0.01.
- polyorder [integer]
- The order of the polynomial used in the fit. Default is set to 3.
- numsdv2 [integer]
- The number of standard deviations used in the second step to calculate the threshould
used to evaluate the difference between the calculated average and the polynomial fit.
Deafault is set to 3.
- timewin2 [real]
- Time window (in seconds) to calculate the moving average in the second step.
Default set to 1.
- mufactor [real]
- Multiplicative factor to the sigma used in the second step to calculate the
threshould used to evaluate the difference between the calculated average and the
polynomial fit to determine the start of the burst. Default set to 0.1.
- (time_min = "NONE" [string])
- The earliest time in the lightcurve to consider when searching for bursts.
The time values may be provided as :
- Mission Elapsed Time (MET), real number, corresponding to the number of seconds from the
start of the mission time.
- ISO style date in UTC of the form "YYYY-MM-DDThh:mm:ss.ff"
If set to NONE,the default, the entire input lightcurve is considered to search for the bursts.
- (time_max = "NONE" [string])
- The latest time in the lightcurve file to consider when searching for
bursts. The time values may be provided as :
- Mission Elapsed Time (MET), real number, corresponding to the number of seconds from the
start of the mission time.
- ISO style date in UTC of the form "YYYY-MM-DDThh:mm:ss.ff"
If set to NONE,the default, the entire input lightcurve is considered to search for the bursts.
- (trigtime = "NONE" [string])
- Trigger time. The value is only used for information and written in the
output files. The trigger time may be provided as :
- Mission Elapsed Time (MET), real number, corresponding to the number of seconds from the
start of the mission time.
- ISO style date in UTC of the form "YYYY-MM-DDThh:mm:ss.ff"
By default is set to NONE.
- (tcol = TIME [string])
- Column name in the FITS lightcurve containing the time information.
- (rcol = RATE [string])
- Column name in the FITS lightcurve containing the count or rate information.
Default is set to RATE.
- (min_int = 30. [real])
- The minimum time (in seconds) to seperate bursts. If
two bursts are detected less than min_int seconds of each other, these
are considered a single burst.
- (clobber = no [boolean])
- Overwrites the existing output file if set to yes (yes/[no]).
- (chatter = 1 [integer, 0 - 3])
- Chatter level for output. Set to 0 to suppress output, or to 1,
2, or 3 for increasing the chatter of the output.
- (debug = no [boolean])
- Diagnostic output is printed out on the screen if set to yes
(yes/[no]).
- (logfile = !DEFAULT [string])
-
Log filename. If set to DEFAULT uses the name of the task and, if preceded by
“!” overwrite the file if it exists. If set to
NONE no log file is created.
- (mode = ql) [string ql|hl|q]
- Mode to query the parameter file. Acceptable values include: "ql (query and learn/remember),
"hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).
EXAMPLES
1. Search the testfile.lc lightcurve for burst using for the first step search a sliding window of 10s, a standard
deviation of 3, a fraction of 0.01 , a polynomial order of 3, and for the second step a time window for the
average of 1s a standard deviation of 3 and a multiplicative factor of 0.2.
The output are written in files with root name staring with "burst_test'.
burstfinder infile=testfile.lc outroot=burst_test timewin=10.0 numsdv=3 fraction=0.01 polyorder=3 numsdvs=3.0
timewin2=1.0 mufactor=0.2
2. Same as the exmaple 1) but the lighcurve is only serach in the time interval defined by time_min and time_max provided in MET
and a log is set to record the run.
burstfinder infile='testfile.lc' outroot='burst_test' timewin=10.0 numsdv=3.0 fraction=0.01 polyorder=3 numsdv2=3.0
timewin2=1.0 mufactor=0.2 time_min=6.80012E+08 time_max=6.80018E+08 logfile=burst_test2.log
SEE ALSO
LAST MODIFIED
February 2024