CGBM_BSTGTI help file

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

LAST MODIFIED