HEADAS help file for cgbm

NAME

cgbm_findrmf - Select RMFs from the CGBM CALDB for a given time, sky location, detector, and gain.

USAGE

cgbm_findrmf datetime ra dec attfile detector gain

DESCRIPTION

The CALET Gamma Ray Burst Monitor (CGBM) consists in three detectors SGM, HXM1 and HXM2 with a wide field of view of ~ 60 deg for the HXM and ~ 120 deg for the SGM. The HXM and SGM detectors have the difference of 10 degree in their boresight directions. The CGBM spectral responses have been generated for each the individual detector (SGM, HXM1 and HXM2), gain (LOW and HIGH), and direction expressed in term of the angles THETA and PHI relative to the instrument with a sampling of 5 deg. All responses are stored in in the calibration database (CALDB).

This task selects from CALDB the appropriate response and requires as input the following information: sky coordinates of the source, the ISS attitude, and the time of interest. The time is used to derive from the attitude the closest pointing quaternion that combined with the sky position determine the angles THETA and PHI of the incident direction. Using the THETA and PHI values together with the detector and gain, the task queries CALDB and the task works out the appropriate response within 5 degree of the incident direction. The HXM and SGM detectors have the difference of 10 degree in their boresight directions therefore the THETA and PHI for the SGM and HXM may be different. The task by default only retrieves the name of the closest responses from the incident angle (parameter closest set to 'yes') for all instruments and gains which names are written in the parameter file of the task. To download the responses to the local disk, the parameter download must be set to 'yes'. The task allows also to retrieve responses for single detector and/or gain using the parameters detector and gain respectively. The task requires to have the CALET CALDB set.

PARAMETERS

datetime [string]: The UTC input time of the event/observation in ISO format (YYYY-MM-DDTHH:mm:ss).
ra [real] (degrees; J2000): Right ascension of the source position.
dec [real] (degrees; J2000): Declination of the source position .
attfile [filename]: Name of input ISS attitude file (*.iat). This file is located in the CGBM archive in the directory auxil/ of the observation that include the source of interest.
detector=ALL [string]: Name of CGBM detector. Allowed values are SGM, HXM1, HXM2, or ALL. If set to ALL (default), the RMFs are found for all three detectors.
gain=ALL [string]: Gain value. Valid inputs are HIGH, LOW, or ALL. Default: ALL
(timetoler=15) [integer] (s): Specifies the time tolerance for matching the input datetime parameter with the time entries in the ISS attitude file. The default value is 15 seconds. If no time stamp in the attitude file falls within timetoler of the requested datetime, the orientation of the CALET instruments is considered undetermined.
(download=no) [boolean]: Download the RMFs from CALDB (yes/[no]).
(closest_only=yes) [boolean]: If download=yes, closest_only=yes (default) the task downloads only the best matching RMF. If closest_only=no, all RMFs found within a 5 degree area around the sky coordinates are downloaded. Ignored if download=no.
(chatter=1) [integer]: Control the screen output from the code. The default value of 1 provides moderate levels of output. Increasing the value increases the level of detail. Valid values run from 0 and 3.
(thetahxm) [real, output] (degrees, output): Populated with the calculated theta angle value for the co-aligned HXM1 and HXM2 detectors.
(phihxm) [real, output] (degrees, output): Populated with calculated phi angle value for the HXM1 and HXM2 detectors.
(thetasgm) [real, output] (degrees, output): Populated with the calculated theta angle value for the SGM detector.
(phisgm) [real, output] (degrees, output): Populated with the calculated phi angle value for the SGM detector.
(rmfhx1h) [filename, output]: Populated with the best matching HXM1 high gain RMF filename.
(rmfhx2h) [filename, output]: Populated with the best matching HXM2 high gain RMF filename.
(rmfhx1l) [filename, output]: Populated with the best matching HXM1 low gain RMF filename.
(rmfhx2l) [filename, output]: Populated with the best matching HXM2 low gain RMF filename.
(rmfsgmh) [filename, output]: Best matching SGM high gain RMF filename.
(rmfsgml) [filename, output]: Populated with the best matching SGM low gain RMF filename.
(clobber = no) [boolean]: Not implimented with this tool.
(history = no) [boolean]: Not implimented in this tool.
(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).(Optional)

EXAMPLE

Find the RMFs for all detectors and gains for the input time, ra, dec and attitude. Write results to terminal screen and also the logfile 'cgbm_findrmf.log'. The RMFs found are all around 5 deg within the incident direction, but are not downloaded. The default value for download is 'no', so it it is not necessary to specify download.
```
cgbm_findrmf datetime=2015-10-06T09:54:45 ra=147.4256 dec=70.5036 attfile=cgbm_20151006.iat.gz detector=ALL gain=ALL closest_only=no
```
Find the RMF for the low gain SGM detector and download the closest matching file found. Also record results to a logfile named 'cgbm_20160821_findrmf.log', overwritting any existing log file with the same name. The default value for closest_only is set to yes, so there is no need to specify this when invoking the command.
```
cgbm_findrmf datetime=2016-08-21T20:36:21.911 ra=171.248 dec=42.343 attfile=cgbm_20160821.iat.gz detector=SGM gain=LOW download=yes logfile="\!cgbm_20160821_findrmf.log"
  
```

LAST MODIFIED