Fermi Gamma-ray Space Telescope

Documentation for the GBM Response Generator

SA_GBM_RSP_Gen.pl:

A routine that processes Fermi Gamma-ray Burst Monitor (GBM) science data and creates level 1 ICD-compliant FITS Detector Response Function files (GS-104 from GLAST-GS-ICD-0006). Written, Aug. 13, 2008, by RDP @ UAH.

(To install, please see the Installation Instructions.)

NOTE: GRB trigger data from GBM already have a standard set of response functions delivered to the data archive, so there is generally no need to redo them.

The GBM response file generator has two modes of operation:
1) Production of response files for a triggered event from GBM, and
2) production of response files for an arbitrary source location at an arbitrary time.

The first step in either case is to download GBM files from the FSSC data archive. Trigger data is available from the GBM Trigger Catalog, regardless of the source classification:
http://heasarc.gsfc.nasa.gov/W3Browse/fermi/fermigtrig.html

However, gamma-ray burst data are more easily found by using the Burst Catalog:
http://heasarc.gsfc.nasa.gov/W3Browse/fermi/fermigbrst.html

which can be searched for individual bursts using several different criteria, such as the official burst name, GBM burst number, or time of the burst.

The daily GBM data can be found here:
http://heasarc.gsfc.nasa.gov/W3Browse/fermi/fermigdays.html

Once your data have been dowloaded, you must expand the archive file in the usual manner and cd to the directory containing the data files. Usually, this may be found inside the directory structure created when the archive has been expanded, as in the following example:
trigger/2017/bn170116238/current

Mode 1) assumes that the working directory contains GBM trigger data files, and must include the trigdat file and CSPEC (or CTIME) data files for the GBM detectors of interest (this could be all of them). In addition, a tcat file may be present. The spacecraft position and attitude history is found in the trigdat file; the source location and trigger type are found in the trigdat file, but are superseded by the values found in the tcat file. The PHA counts data energy boundaries are found in the respective data files: 128 channels in CSPEC and 8 channels in CTIME. To create the standard response files for the trigger time, simply execute the perl script with the -Ccspec option from the command line (assumes that the CSPEC data files are in the current working directory, '.'):

> SA_GBM_RSP_Gen.pl -Ccspec .

The many options described below can override the default behavior. Only the -C option is required; supply one of -Ccspec or -Cctime, as appropriate. The -R and -D options are used to input a specific source location in degrees RA and Dec, overriding the position found in either the trigdat or tcat files. Multiple matrices that account for spacecraft slew during a long transient can be generated by passing both a start and end time, either in Fermi mission elapsed time (via -S and -E) or as times relative to the trigger time (-P and -Q). For both of these options, a single FITS RSP type 2 file is generated for each detector. NOTE: in case the Fermi spacecraft was performing a pointed observation during the requested time interval, only a single response matrix will be generated for each detector, with an '.rsp' extension, instead of '.rsp2', to indicate that there is only a single matrix in the file. To select only CSPEC (128 energy channels) or CTIME (8 energy channels) type response files, use the -C option. A restricted set of detectors can be selected by passing -d options, one for each desired detector; this option takes values from 0 to 13, where 12 and 13 select BGO detectors 0 and 1, respectively. Place any options, separated by spaces, before the working directory path:

> SA_GBM_RSP_Gen.pl -R83.633 -D22.045 -Cctime -d13 -P-50. -Q200. -OTRANSNT .

Mode 2) requires a GBM position history file as well as daily CSPEC and/or CTIME files that cover the time of interest. To run the software in this mode, options for the start time (-S in Fermi mission elapsed time in seconds) and the source location (-R and -D, as RA and Dec in degrees) must be supplied at the minimum (along with the required -C). For multiple response matrices that account for spacecraft slewing over the observing time interval, an ending time (-E) should be provided. The note concerning Fermi pointed observation time intervals, described above, applies here as well.

TUTORIAL:

Trigger Mode 1

NOTE: GRB trigger data from GBM already have a standard set of response functions delivered to the data archive, so there is generally no need to redo them.

For the trigger data mode (1), you will obtain the data at the Fermi Science Support Center data access page (https://fermi.gsfc.nasa.gov/ssc/data/access/) from either the 'GBM Trigger Catalog' table (all triggers) or the 'GBM Burst Catalog' table (all GRBs). You are interested in the spectrum of the second pulse (at ~125 s) of GRB160804775, so select the burst catalog. Continue to the Browse page for this Table. To obtain the data, type 'GRB160804775' in the 'name' field, go to the bottom of the page and select the 'Start Search' button. Select the single row of the catalog that the query returns. You want the entire set of data products, so select the 'Retrieve' button. After a small wait, the link to a ~130 MB tar file appears; select this link to download the file.

If you are concerned about space, the minimum set of files required for response file generation is '*tcat*;*trigdat*;*cspec*' for the Browse query page 'File name filter' box.

Move the downloaded file to a directory of your choice, cd there and extract the data as usual ('tar -xvf w3browse-*.tar'). Next, drill down the directory tree to find the files: triggers->2016->bn160804775->current.

You notice that there is a set of single-matrix response files (*.rsp), but they wil not cover the emission at 125 s. You have a choice to create multiple-matrix files (*.rsp2) that cover all the burst, or single-matrix files for the second outburst. We cover starting and ending times selection in the following tutorial, so choose the single-matrix path. All the response matrices in the current directory have version number 1 (*.v01.rsp), so you will have to choose another version number (the response generation software will fail on attempts to overwrite existing files. With this in mind, the command to run is:
SA_GBM_RSP_gen.pl -Ccspec -Q125. -V2 .

Trigger Mode 2

For the second mode, creating response matrices for non-triggered times, you need to know the date and time for when the source is active, as well as which detectors were viewing it. V404 Cyg had an occultation rise on 15/06/26 at 53475.07 seconds into the day. A flare occurred 53934.5 seconds into the day or 459 seconds after the rise and continued to flare for about 3350 seconds where the source is again occulted.

Go to the Fermi Science Support Center Data Access page and select the data set under 'GBM Daily Data'. Continue to the Browse page for this Table. Put the date (20150626) into the 'day_id' field and select the 'Start Search' button. One row should be retrieved from the search, so select it.

Next, since we only want to retrieve the poshist and cspec data files, type '*poshist*;*cspec*' into the "File name filter" box. You can now click the 'Retrive' button, which brings up a page containing a link to the data files, in a tar file. Download the file by clicking on the link.

In this example, the file size was 85 MB, so make sure that there is enough space in the download drive for it. You should now extract the data files in a directory of your choice, using your favorite extraction method ('tar -xvf w3browse-*.tar' if nothing comes to mind). Drill down the directory tree to find the files: daily->2015->06->26->current and cd there.

Now, you need to determine the Fermi Mission Elapsed Time (MET) of your observation. One way (not necessarily the best!) would be to examine a CSPEC file FITS primary header with FV, and find the value for TSTART (= 456969596.828596). Comparing with DATE-OBS = 2015-06-25T23:59:56, it is clear that the MET at the start of the day should be TSTART + 3.1 s = 456969600. This represents 5289 days since January 1, 2001, the MET reference date. To this, add the start time of the flare (start option -S457023534) and the duration to get the bracketing times for when the flare was visible (end option -E457026884).

Visual inspection of the cspec datafiles (with rmfit) indicates that the brightest detectors were NaI #4, 6 and 8. The source location for V404 Cyg ia RA = 306.0 and Dec = 33.9, in degrees. So, the proper command line to create a file for each detector that contain separate response matrices for every 3 degrees of spacecraft slew covering these times would be:
SA_GBM_RSP_GEN.pl -Ccspec d4 -d6 -d8 -R306.0 -D33.9 -A3 -S457023534 -E457026884 -OV404Cyg .

EXAMPLES:

  1. Primary mode is autonomous, gathering the requisite parameters for DRM production from the files that are present in the current working directory, which can be passed as the single formal parameter. Note: the path argument must be supplied *after* all command line options.

  2. USAGE: SA_GBM_RSP_Gen.pl -Ccspec (or -Cctime) /path/to/working/directory
    A single -C option is required; note this means that generation of both CTIME and CSPEC response files requires two separate runs of the code.
    OUTPUTS: 1 Level 1 FITS .rsp file, for each ctime/cspec file present.

  3. Output files are date-stamped according to the trigger ID that is found in each trigger data packet or by the time submitted in the -S command-line option.

  4. SA_GBM_RSP_Gen.pl -Ccspec -S241112294.624758 /path/to/working/directory (or)
    SA_GBM_RSP_Gen.pl -Ccspec -S241112294.624758 -E241112335.585184 /path/to/working/directory

    The response matrix can be made in one of two output types: single or multiple.
    The single matrix is the OGIP standard RSP for the time given on the command line
    (also: single RSP matrices can get the trigger time from a trigdat file).

    Multiple matrices are in a new format, RSP type II (RSPII), where several matrices for a given observation share the same file, indexed by EXTVER and ordered by time. The time sequence of matrices can trace out the changing orientation of the source with respect o the observatory, while it is in a slew. The cadence of new matrices is determined by a fixed angle of slew, defaulting to a new matrix being produced for every 2 degrees on the sky, which can be overridden by the -A command-line argument (in degrees):

    SA_GBM_RSP_Gen.pl -Ccspec -S241112294.624758 -E241112335.585184 -A3 /path/to/working/directory

  5. SA_GBM_RSP_Gen.pl -Ccspec -R75.278 -D45.2762 /path/to/working/directory

    For non-burst observations, the source position Right Ascension and Declination can be specified by two command-line parameters (in degrees). Typical operations allow the source position to be automatically read from a tcat file (GS-105).

  6. SA_GBM_RSP_Gen.pl -Ccspec -d0 -d1 ... /path/to/working/directory Individual detectors to process can be input from the command line, and will override the default selection of detectors, which is taken to be those ctime or cspec files in the current working directory. This allows processing to be restricted to the burst triggered detectors or to only those detectors viewing a given source, even though all detector's files are in the directory.

  7. SA_GBM_RSP_Gen.pl -Ccspec -N /path/to/working/directory

    The -N parameter will force the code into single-matrix mode. Other parameters can override this, especially the -S and -E pair.

  8. SA_GBM_RSP_Gen.pl -Ccspec -OGRB /path/to/working/directory

    The -Oclass option indicates the source object class; the class is 'GRB' in the example above. This parameter is optional, since the program can find the class from a TCAT file. Indicates which of the standard source object classes to use for the CLASS keyword in the primary FITS header of the output response file(s):
    our @classes = ('ERROR','UNRELOC','LOCLPAR','BELOWHZ','GRB','SGR','TRANSNT','DISTPAR', 'SFL','CYGX1','SGR1806','GROJ422'); Use this parameter when it is desirable to override the value in the TCAT file, or when there is no TCAT/TRGIDAT file to read it from. Since the argument is a string, this could pretty much be any possible value; however, a string consisting of no more than 8 uppercase characters is preferred. The generic 'TRANSNT' is the default, if there is no supplied TCAT file.

  9. SA_GBM_RSP_Gen.pl -Cctime /path/to/working/directory -or-
    SA_GBM_RSP_Gen.pl -Ccspec /path/to/working/directory

    Indicates which of the two data types from which to draw the energy thresholds to be used in the construction of the responses. The photon (input) edges are standardized within the DRM code, but the output edges correspond to the current gain and needs to be provided anew each time. Notice that this is not an optional parameter. If *both* sets of files are in the working directory, use the -C option to tell the program which set of responses to create.

  10. SA_GBM_RSP_Gen.pl -Ccspec -P-20.0 -Q40.0 /path/to/working/directory

    Determines offset(s) in seconds relative to the trigger time to determine the quaternion to be used for the spacecraft attitude calculation. -Q is useful alone in conjunction with single-matrix mode (-N), since the default is to use the quaternion right at the trigger time. In conjunction with -P, in multiple-matrix mode (no -N), DRMs are calculated from T+(-P value) to T+(-Q value), so using the example above, the time span would be -20 to +40 seconds.

  11. SA_GBM_RSP_Gen.pl -Ccspec -V1 /path/to/working/directory

    The output file version number can be set with the -V command-line parameter. No checking is made to see whether this is really the next number in the sequence, nor even if it is a number!