HEADAS help file

NAME

cgbm_speclc - Extract spectra and lightcurves from an input FITS event file within a time interval associated to a burst detected by a specific CGBM detector.

USAGE

cgbm_speclc infile outroot gtifile timebin1 timebin2 pirangel pirangem pirangeh piranget ecol

DESCRIPTION

'cgbm_speclc' generates binned light curves and spectra for a input CALET CGBM detector event file and a GTI file, typically representing the burst time interval. The CGBM is constituted by three detectors HXM1, HXM2 and SGM each working in low and gain and the event file and GTI file are expected to be in FITS standad format. The task 'cgbm_bstgti' may be used to generate the time interval for the burst, the GTI file. The lightcurves may be generated setting up to four channel boundaries and two different time binning. The spectrum is extracted with the full range of channels but rebinned, using the task 'ftrbnpha', with a groupping to match the channels of the responses. There are two different pre-set grouppig file, one for low gain and one for the high gain, and they are located in the REFAREA defined at the HEAsoft installaton. The lightcurves and spectra are generated using the 'extractor' task.

The output of 'cgbm_speclc' is a single FITS lightcurve file, two FITS spectral files one with the original channels and one with the rebin channels. They are named outroot.lc, outroot.pi and outroot_rebin.pi respectively, where outroot is the value of the parameter 'outroot'. However during the process a number of intermediate files are generated that are removed if the paramater 'cleanup' is set to 'yes'.

The lightcurve format has three extensions with the following content:

There is one lightcurve extension for each of the requested time bin, for a maximun of two extenaion (only two differen time bin are allowed)
Each lightcurve extension contains a column TIME and up four sets of columns to store the rate error and fractional exposure for each of the channel boundaries. If all four channel boundaries are specified, the column names are RATE ERROR FRACEXP, RATE1 ERROR1 FRACEXP1, RATE2 ERROR2 FRACEXP2, RATE3 ERROR3 FRACEXP3 for total, low, medium and high channel range.
The third extension is input GTI appended to record the start and stop time used to filter the event file.

PARAMETERS

infile [filename]: Input event file. This is an event file from one of the CALET CGBM detector HXM1,or HXM2 or SGM.
outroot [string]: Root for the output files. The expected output file include : outroot.lc (lightcurve), outroot.pi (spectra), and outroot_rebin.pi (rebinned spectra).
gtifile [filename]: Input GTI file. The time interval within this file is used to extract the spectra and lightcurves. If the input GTI file contains more than one extension, the syntax 'filename+ext' allow to specify the extension. If the parameter is set tp "NONE", spectra and lightcurves are extracted using the GTI extension included with the event file
timebin1 [real]: Input Time bin (in second). This is first time bin used to construct the lightcurve. If timebin1 and timebin2 are empty the task does not generate the lightcurve.
timebin2 [real]: Input Time bin (in second). This is second time bin used to construct the lightcurve. If timebin1 and timebin2 are empty the task does not generate the lightcurve.
pirangel [string]: Minimum and maximun channel to generate the lower channel band 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.
pirangem [string]: Minimum and maximun channel to generate the medium channel band 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.
pirangeh [string]: Minimum and maximun channel to generate the high channel 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.
pirangt [string]: Minimum and maximun channel to generate the total 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.
(lcthresh = 0.99 [real]): 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.
(events = "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.
(binfile = "REFDATA") [string]: The name of file containing the channel groupping to rebin the spectra. If set to REFDATA, cgbm_speclc uses the standard groupping for the CGBM low and high gain located in the HEAsoft refarea. The REFDATA gropping files depend only on gain and not on istrument and they match the same channel of the responses. The code selects the appropriate file from REFDATA based on the ecol parameter.
(finchan [integer]: Number of final channels after rebbing the spectra. This parameter should not be change. If the parameter 'binfile' is specified, finchan is ignored. If 'binfile' is NONE and 'finchan' is set to 0, the spectrum is not rebinned.
(cleanup = yes) [boolean]: Cleanup all intermediate files is set to YES. The intermediate files are up-to-six different light curves generated by 'extractor' and all the STDOUT/STDERR logs generted by running the 'extractor' and 'ftrbnpha'. The up-to-six different light curves are combined into a single outputlightcurve.
(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.
(histary =yes [boolen]): If set to yes record the tasks parameters run in the header of the output file in the HISTORY keywords.
(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. Extract lightcurves and spectra using the high gain data (PI_HIGH) for the CGBM SGM instrument event file The lightcurves are generated in the channel bands 155-410, 411-2026 2027-4031 155-4031 using a binning of 1.0 s and 64 ms.

      cgbm_speclc infile="cgbm_20210104_sgm_112700.evt.gz" outfile="sgm12700" gtifile="bssgm12700.gti" 
                  timebin1="1" timebin2="0.064" pirangel="155:410" pirangem="411:2026" pirangeh="2027:4031" 
                  piranget="155:4031" ecol="PI_HIGH"

LAST MODIFIED