NAME

USAGE

DESCRIPTION

cgbm_bstgti identifies time intervals associated with bursts detected by a CALET CGBM detector (HXM1, HXM2, or SGM) for a specific gain. The task uses a single input event file either for the SGM or HXM1 or HXM2 and uses the columns TIME, PI_LOW or PI_HIGH which reports the time, the low gain energy channel and the high gain energy channel. The ecol parameter specifies which gain column to use. The task first generates a binned lightcurve from the input event file using the extractor task and then uses burstfinder to search the lightcurve for bursts and calculates the time intervals in four steps (see help of burstfinder). The task outputs a Good Time Interval file, two lightcurves curve and a summary file. The GTI file (suffix 'dur' in filename) contains up to 6 extensions that are : first and second extensions are reserved to the time intervals corresponding to the 90% and 50% of the burst respectivaly 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 an header keyword GTITYPE with value of GTI_90, GTI_50, GTI_PEAK, GTI_TOT, GTI_BKG1, GTI_BKG2) to identify the extension content. The lightcurves are : one the output of the extractor where the rate corresponds to the total rate non-background subtracted and the second (suffix 'user' in filename) contains the original total rate non-background subtracted taken from the extractor lightcurve (see columns 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 light curve file is always output .

Many of the input parameters are either for extractor or for burstfinder that are general tasks. The recommended default bin time is either 1 sec or .25 sec (paramter timebin) and channel range (parameter pirange ) for the CGBM for each of the detetors and gain are : SGM high gain energy 40- 1000 keV pirange=173:4095 SGM low gain energy 550-28000 keV pirange=78:3999 HXM1/HXM2 high gain energy 4- 100 keV pirange=166:4095 HXM1/HXM2 low gain energy 60- 3000 keV pirange=80:4000

PARAMETERS

infile [filename]

Input event file./dd>

outroot [filename]

Root name for the output files.

(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.

timebin [real] (seconds)

The time bin (in seconds) used to generate the binned lightcurve from infile.

(lcthresh = 0.99) [real]

Minimum fractional exposure to retain bins in the lightcurve. Allowed values ranges from 0 (keep all bins) to 1 (keep the bin only if fully exposed). The default is 0.99.

pirange [integer:integer] (chan)

Specifies the minimum and maximum channels to include in the lightcurve. Provide the range as a string in the format "min:max", where both min and max are integers. For example, pirange="80:140" selects channels 80 through 140.

(extension = "EVENTS") [string]

Extension name to find events in the input FITS event file. Default is EVENTS.

ecol [string]

Column name in the FITS event file containing the channel information. For CGBM, these would be "PI_LOW" for low gain, or "PI_HIGH" for high gain data.

timewin [real] (seconds)

Time window (in seconds) to calculate the average in the first step. The value should be larger of the ori\ ginal 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 rem\ ade.

(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), the number of seconds from the start of the mission time, defined by keywords MJDREF (or MJDREFI and MJDREF) in the input lightcurve; or
• ISO style UTC date in the form "YYYY-MM-DDThh:mm:ss.ff"

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 file to consider when searching for bursts. The time values may be provided as :

• MET or
• ISO style UTC date

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 file containing the time information. Default is TIME.

(clobber = no) [boolean]

Overwrites the existing output files 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 (yes/[no]). Also creates a diagnostic outroot_fit.lc file.

(logfile = !DEFAULT) [string]

Log filename. If set to DEFAULT uses the name of the task (i.e. cgbm_bstgti.log) and, if preceded by "!" overwrite the file if it exists. If set to NONE (or blank), no log file is created.

(history = no [boolean])

If set to yes, add HISTORY keywords to the output files record parameter settings. Default is NO.

(mode = ql) [string ql|hl|q]

Mode to query the parameter file. Acceptable values include: "ql" (query and learn/remember; DEFAULT), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

1. Run cgbm_bstgti on a CGBM SGM event file using the low gain channels in the range 384-4079, a lightcurve time binning of 64 ms and search for the burst using a sliding window width of 10 s in the initial first pass, flagging any interval more than 3 standard deviations from this average as an outlier. Use the fill model to estimate background for any outlier using 0.99 times the sliding average plus 0.01 times the data value. Fit this background model with a cubic polynomial using the default covariance fitting algorithm. In the second pass, use an averaging time window of 1 s, setting the burst detection threshold for rates higher than 3 standard deviations above the background model, and set begin and end time bins for burst(s) when the rate first falls below 0.2 standard deviations. The output files have root names starting with "sgm112700". Do not attempt to iterate or refit after making an initial estimate of the burst interval(s).

     cgbm_bstgti infile=cgbm_20210104_sgm_112700.evt.gz outroot=sgm112700 timebin=0.064
       pirange="384:4079" ecol=PI_LOW numsdv=3.0 fraction=0.01 timewin=10  polyorder=3
       numsdv2=3.0 timewin2=1.0  mufactor=0.2 fill=yes refit=no
   

SEE ALSO

extractor - generate a binned lightcurve from an event file
burstfinder - find in a lightcurve time intervals that characterize the burst
batblocks - tool to find bursts in Swift BAT data

LAST MODIFIED