NAME

burstfinder - Search for burst(s) and calculate the time intervals using as input a binned lightcurve.

USAGE

burstfinder infile outroot timewin numsdv fraction polyorder numsdv2 timewin2 mufactor

DESCRIPTION

burstfinder searches in a equally binned lightcurve in FITS format for bursts and outputs files with the burst time interval as well as other diagnostic files. By default the task expects an input lightcurve with columns named TIME and RATE, containing the time in second and rate as count/s, otherwise the parameters tcol and rcol maybe used to specify the names of the columns.
The task searches for the burst in the lightcurve with four steps.
In the first step the lightcurves is scanned with a sliding window technique to detect major deviation from an average. The average of the RATE values within a time window (parameter timewin) is calculated by sliding the window by one point. If the difference of the previous average with current RATE value is greater than a threshold (parameter numsdv), the rate of the current point is substituted with the average multiple by factor (see parameter fraction) and the following average uses the latter value if the parameter fill is set to yes else it is ignored.
The second step uses the rates calculated from the first step and fits a polinomial which order is defined by parameter polyorder. By default, the polynomial fitting also uses the errors on the rates (parameter use_covar set to yes).
At the third step, the original rate in the lightcurve is compared to the polynomial. The lightcurve is first smoothed (see parameter timewin2) and each bin is compared with the polynomial searching for deviations larger than a threshold (see parameter numsdv2 . If the deviation larger than the threshold, it assumes that there is a burst and starts a fine search for the start and stop of the burst by looking backward and forward for points that are below a threshold defined by the parameter mufactor. If there are multiple bursts detected and their time intervals are significatly close to each other (see parameter min_int) they are combined into a single interval.
The fouth step is executed if the parameter refit is set to yes where the rates of the original lightcurve are clipped for the time interval associated to the burst found in step three and a new polynomial fit is executed and step three is repeated with the new fit only if there is a signative difference in the sigma of the two fits (see parameter pdiff).

The task outputs a Good Time Interval file, a lightcurve file, and a summary file. The GTI file (suffix 'dur' in filename) contains up to 6 extensions that are : first and second extensions are reserved for the time intervals corresponding to the 90% and 50% of the burst respectively but are not populated (see task burstt90t50); the third extension is populated with the time interval for the peak of the burst; the fourth extension is populated with the time interval for the total burst; the fifth and sixth extension is populated with the pre and/or post background interval if both intevals exist else only with the one that exists. Each extension has a header keyword GTITYPE with value of GTI_90, GTI_50, GTI_PEAK, GTI_TOT, GTI_BKG1, GTI_BKG2) to identify the extension it contains. The lightcurve (suffix 'user' in filename) contains the original total non-background subtracted rate taken from the input lightcurve (TOTRATE and TOTRATE_ERROR), the background rates (BKGRATE and BKGRATE_ERROR) and the background subtracted rates (RATE and ERROR). The summary file (suffix 'summary' in filename) contains for each burst one line with summary information and is provided as FITS file and ASCII file If no bursts are found, the GTI and summary files are not output, but lightcurve file is always output .

PARAMETERS

infile [filename]
Input lightcurve. The lightcurve is expected to be equally binned containing the columns RATE and TIME.

outroot [filename]
Root name for the output files. The filenames for the lightcurve, gti and summary are made by adding to the root "user.lc", "dur.gti" "summary.fits" or "summary.txt respectivaly

(leapfile = "REFDATA") [string]
Name of the leap second file. If set to REFDATA (default), the leap second file in FTOOLS reference data directory is used.

timewin [real] (seconds)
Time window (in seconds) to calculate the average in the first step. The value should be larger of the original binning.

(gap_interval=100.0) [real] (seconds)
If the lightcurve has large gap, this parameter allows to restart the sliding window average from the first valid point after the gap. The default is 100 s.

numsdv [real]
Number of standard deviations used in the first step to calculate the threshold between the current value and moving average.

(fill=yes) [boolean]
If set to "no", exclude values that are above the standard deviation defined by numsdv in the average caculation. If set to "yes" (default), the points above the standard deviation are replaced by the average*(1-frac), where the avergae is the value of the rate average calculated for the timewin interval including the preceeding point and frac is defined by the parameter fraction

(fraction=0.01) [real]
Fraction used to calculate the rate to be replaced in the original lightcurve if fill=yes. Value range between 0 and 1, default is 0.01.

(polyorder=3) [integer]
The order of the polynomial used to fit data to model background. Default is 3 (i.e. cubic fit).

(use_covar=yes) [boolean]
If set to "yes" (default), the polynomial fit model takes error in rate into account when fitting. If set to "no", error on rate are not used

timewin2 [real]
Time window (in seconds) to calculate the average in the third step. The value should be larger of the original binning.

numsdv2 [real]
Number of standard deviations used in the third step to calculate the threshold between the polynomial fit and the smooth rates. Above numsdv2 is considr a burst.

mufactor [real]
Multiplicative factor to the standard deviation obtained from the polynomial fit and the smooth rate. This factor is used in the fine search of the start and stop of a burst.

(min_int = 30.0) [real] (seconds)
The minimum time between adjacent bursts. If two bursts are detected within min_int seconds of each other, they are merged and consider a single burst. Default is 30.0 seconds

(refit=yes) [boolean]
Execute the fourth step if set to "yes" (default), where burst intervals found in the third step are excluded from the lightcurve and the data are refit. If set to "no", the fourth step is not executed no refitting.

(maxiter=10) [integer]
If set (default is 10), the maximum number of times to iterate to potentially improve the polynomial fit solution. Ignored if refit is set to no.

(pdiff=0.1) [real]
Define the minimum difference in sigma between two subsequeent polynomial fits and is valid only if the parameter refit is set to yes. If the fit has improved sigma by more than pdiff times sigma, the new polynomial fit has improved and step two and three are remade.

(time_min = "NONE") [string]
The earliest time in the lightcurve to consider when searching for bursts. The time values may be provided as : If set to NONE (or blank: default), the input lightcurve search starts with the first data point.

(time_max = "NONE") [string]
The latest time in the lightcurve to consider when searching for bursts. The time values may be provided as : If set to NONE (or blank: default), the input lightcurve search ends at the last data point.

(trigtime = "NONE") [string]
Trigger time. The value is informative only and written in the output files, but not used in computations. The default setting is NONE (i.e. do not set TRIGTIME).

(tcol = TIME) [string]
Column name in the input lightcurve containing the time information. Default is TIME.

(rcol = RATE) [string])
Column name in the input lightcurve containing the count or rate information. Default is RATE.

(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 (default), 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. Also, a diagnostic FITS file with polynomial fitting is written out. (yes/[no]).

(logfile = NONE) [string]
Log filename. If set to DEFAULT, use the name of this task (i.e. burstfinder.log). If preceded by "!" overwrite the file if it exists. If set to NONE (default), no log file is created.

(history = no) [boolean]
If set to yes, add HISTORY keywords to the output files that record the parameters used to create them. Default is NO.

(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 lightcurve testfile.lc for bursts using for the first step timewin = 10 s, with replace points (fill=yes) that have a standard deviation > 3 (numsdv=3) with an average decrease by 0,01 (fraction=0.01). Fit the lightcurve from the first step with a cubic polynomial model (polyorder=3) using the error on rate (use_covar=yes). For the third step use a timewin2=1 s and a theshold of 2 (numsdv=2) when comparing the lightcurve with the polynomial fit and a value of mufactor=0.2 when fine searching the start and stop of the burst. The output files have root names starting with "burst_test". Do not attempt to refit after making an initial estimate of the burst interval (refit=no)). 

    burstfinder infile=testfile.lc outroot=burst_test timewin=10.0 numsdv=3 fraction=0.01 polyorder=3  numsdv2=3.0 
            timewin2=1.0 mufactor=0.2 fill=yes refit=no use_covar=yes
  2. Same as the example 1) but the lighcurve is only searched in the time interval defined by time_min and time_max provided in MET and record terminal output to a logfile "burst_test2.log". 

    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 fill=yes
refit=no use_covar=yes
  3. Same as the example 1) but after step 3 refit (refit=yes) the polynomial on the lightcurve clipped by the burst intervals and iterate up to 10 times (maxiter=10) to find the best solution. Exit if the fit improves by less than 10% between iterations (pdiff=0.1). Write to a log file "burst_test3.log" and clobber any previous logfile of the same name. 

    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 fill=no refit=yes maxiter=10 pdiff=0.1 logfile="\!burst_test3.log"

    SEE ALSO

    batblocks, cgbm_bstgti

    LAST MODIFIED

    February 2025 (burstfinder 1.951b)