NAME
cgbm_bstgti - Find time intervals in an input FITS event file that characterize start and stop of a burst detected by a specific CGBM detector
USAGE
cgbm_bstgti infile outroot timebin pirange timewin numsdv fraction polyorder numsdv2
timewin2 mufactor min_int
DESCRIPTION
'cgbm_bstgti' searches for time intervals associated to a burst detected
with one of CALET CGBM detectors (HXM1, HXM2, or SGM). The input file
is a CALET CGBM detector FITS event file which include two different columns
to derive spectra based on the gain. The low gain is named PI_LOW and the high
gain is named PI_HIGH.
'cgbm_bstgti' first create a binned lightcurve for a given channel range using the
'extractor' task, and after searches the lightcurve for time intervals that
characterize the burst using the 'burstfinder' task.
The search of the lightcurve is accomplished
with a two steps approch : 1) a sliding-window algorithm to smooth out the curve
and fit with a polynomial, 2) Compare the lightcurve with the polynomial fit data
to search for the burst times that satisfy a threshold.
For each burst, 'burstfinder' calculates start and stop time corresponding to
the total, 90% , 50% and peak flux of the burst as well as the pre-burst and
post burst backgroud. The GTIs are written out in three different output files :
More information is available in the help of 'burstfinder'.
PARAMETERS
- infile [filename]
- Input event file. This is an event file from one of the CALET CGBM detector HXM1,or HXM2 or SGM.
- 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
- timebin [real]
- The time bin (in seconds) used to generate the binned lightcurve rom the input event file.
- (lcthresh = 0.99 [real number])
- Minimum fractional exposure to retain bins in the lightcurve. Allowed values ranges from 0 (keep
the bin even with 0 exposure) to 1 (keep the bin only if fully exposed). Default is set to 0.99.
- pirange [string]
- Minimum and maximun channel to generate the lightcurve. The mix/max
channels are provided as a string with syntax "min:max" where the min and max are integer values.
Example: pirange="80:140" uses all events in the channel range from 80 through 140 when generating the
lightcurve.
- (extension = "EVENTS" [string])
- Extension name to read the event in the input FITS event file. Default is set to EVENTS.
- ecol [string]
- Column name in the FITS event file containing the channel information. The CGBM detectors
have to channel columns "PI_LOW" for the instrument low gain data and "PI_HIGH" for the instrument
high gain data.
- (tcol = "TIME" [string])
- Column name in the FITS event file containing the time information.
- (rcol = "RATE" [string])
- Column name in the FITS lightcurve containing the count or rate information.
Default is set to RATE.
- 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. Run 'cgbm_bstgti' on CALET CGBM SGM event data using the low gain channels in the range 384-4079 using a binning
for the lightcurve of 64ms and search for the burst using for the first step 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 "sgm112700'.
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. mufactor=0.2
SEE ALSO
extractor _ generate a binned lightcurve from an event file
burstfinder - find in a lightcurve time intervals that characterize the burst
LAST MODIFIED
June 2023