HEADAS help file for cgbm

NAME

cgbm_speclc - Extract spectra and/or lightcurves from a CGBM event file within a time interval.

USAGE

cgbm_speclc infile outroot gtifile timebin1 timebin2 pirangel pirangem pirangeh ecol

DESCRIPTION

cgbm_speclc extracts binned lightcurves and/or spectra from a CALET CGBM detector (HXM1, HXM2, or SGM) event file and a GTI file. 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 allows to specify with PI colums to use. The task uses the extractor to generate the following files:

Up to two lightcurves containing up to fours energy bands with two different time binning. Up to three channels boundaries may be specified by the parameters pirangel, pirangem, and pirangeh and the task calculates a total rates. The output file has up to three extensions one for each time binning and a GTI extention. Each of the extensions contains a TIME column, RATE and ERROR for the total rate and up to 3 columns named RATE1, RATE2, RATE3 with the rate for any energy bands specified, and up to three columns for their errors (columns ERROR1, ERROR2 and ERROR3). For the CGBM here are the standard three channel ranges for each of the detectors and gain: * High-gain ** PI | HXM (keV) | SGM (keV) | 155- 410 | 4-10 | 40-100 | 411-2026 | 10-50 | 100-450 | 2027-4031 | 50-100 | 450-1000 | * Low-gain PI | HXM (keV) | SGM (keV) | 80- 119 | 60-100 | 550-830 | 120- 383 | 100-300 | 830-2600 | 384-4079 | 300-3000 | 2600-28000|
Up to two spectra: one in the original channel and one rebinned spectrum with channels matching the response. The original spectra has the full range of channels. The rebin spectrum is calculated with ftrbnpha and uses a CGBM-specific predefined rebinning (see parameter binfile set to REFDATA). The channels in the rebin spectrum matches the channel over which the responses in CALDB are calculated.

If the parameter lc_only is set to "yes", spectral products are not generated. If timebin1 is set to NONE (or left blank), the lightcurve is not generated.

PARAMETERS

infile [filename]: The input event file for the CGM SGD or HXM1 ofr HXM2 .
outroot [string]: Rootname for the output files.
gtifile [filename]: The input GTI file. If the parameter is set to NONE or blank, spectra and lightcurves are extracted using the GTI in the input event file.
timebin1 [real] (seconds): The first of up to two time bins used to construct the lightcurve. If timebin1 is set to NONE or blank, the task will not generate the lightcurve.
timebin2 [real] (seconds): The second time bin for the lightcurve. If timebin2 is set to NONE or blank, the lightcurve is generated only if the timebin1 is set. This parameter is ignored if timebin1 is NONE or blank.
pirangel [integer:integer] (chan): Minimum and maximum channels to include in the low band lightcurve. The range is a string in the format "min:max", where both min and max are integers. For example, pirange="80:119" selects channels 80 through 119.
pirangem [integer:integer] (chan): Minimum and maximum channels to include in the medium band lightcurve. The range is a string in the format "min:max", where both min and max are integers. For example, pirange="120:383" selects channels 120 through 383.
pirangeh [integer:integer] (chan): Minimum and maximum channels to include in the high band lightcurve. The range is a string in the format "min:max", where both min and max are integers. For example, pirange="384:4079" selects channels 384 through 4079.
(lcthresh = 0.99) [real]: Minimum fractional exposure in the lightcurve. Allowed values ranges from 0 (keep all time bins) to 1 (keep only fully exposed bins). Default is 0.99.
(events = "EVENTS") [string]: Name of the extension containing events in the input file. Default is EVENTS.
ecol [string]: Column name in the input file containing the channel information. For CGBM, this should be one of PHA_HIGH, PHA_LOW, PH_HIGH, or PI_LOW.
(tcol = "TIME") [string]: Column name in the input file containing the time information. Default is TIME.
(binfile = "REFDATA") [string]: The name of file containing the channel grouping to rebin the spectra. If set to REFDATA, use the standard grouping provided with HEASoft. If set to NONE, no rebinning is performed. Ignored if lconly is set to yes.
(lconly = no) [boolean]: If set to yes, no spectra are made. Default is no.
(cleanup = yes) [boolean]: Remove all temporary files on completion if set to yes (default).
(clobber = no) [boolean]: Overwrites pre-existing output files if set to yes. Default is 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]).
(logfile = !DEFAULT) [string]: Log filename. If set to DEFAULT, uses the name of the task (i.e. cgbm_speclc.log) and, if preceded by “!” clobber any pre-existing log file. If set to NONE, no log file is created. Default is %ldquo;!DEFAULT”
(history = yes) [boolean]: If set to yes, record the task 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

Extract lightcurves and spectra using the high gain data (PI_HIGH) from a CGBM SGM event file. Generate lightcurves for bands 155-410, 411-2026, 2027-4031, and a TOTAL channel band 155-4031 using each of 1.0 s and 64 ms time bins. Limit the events used to make products to those contained within GTIs defined by the file bssgm12700.gti. Use the HEASoft reference data to define the CGBM rebin grouping when making rebinned spectra. Create a log file of this named cgbm_speclc.log, overwritting any previous log file with that name.
```
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" 
            ecol="PI_HIGH" binfile=REFDATA lconly=no
```
Extract a lightcurve from a CGBM SGM instrument event file, but no spectra. The lightcurve contains three channel ranges: 155-410, 411-2026, and a TOTAL channel band 155-2026 using a 0.5 s binning. Use only events within the GTI specified by bssgm12700.gti.
```
cgbm_speclc infile="cgbm_20210104_sgm_112700.evt.gz" outfile="sgm12700" gtifile="bssgm12700.gti" 
            timebin1=0.5 timebin2=NONE pirangel="155:410" pirangem="411:2026" 
            ecol="PI_HIGH" lconly=yes
```

Extract a spectra, but no lightcurve, from the CGBM SGM instrument using the low gain data in the event file. Do not create a rebinned spectra.

cgbm_speclc infile="cgbm_20210104_sgm_112700.evt.gz" outfile="sgm12700" gtifile="bssgm12700.gti" 
            timebin1=NONE ecol="PI_LOW" binfile=NONE

LAST MODIFIED