NAME
    gtrspgen - Creates a "Detector Response Matrix" (DRM or RSP) FITS
    file from the multi-dimensional response functions.

USAGE

    gtrspen respalg specfile scfile outfile irfs time thetacut
    dcostheta ebinalg emin emax enumbins denergy ebinfile

DESCRIPTION

        The gtrspgen tool produces a Response Matrix (RSP) file
        required to analyze a binned spectrum in an HEASARC standard
        (i.e. XSPEC compatible) format.  The response matrix is
        computed from the detailed response functions provided by the
        LAT instrument team. The elements of the matrix are directly
        related to the probability of an incident photon with a true
        energy of E being detected by the LAT with an apparent energy
        E'.  The source position, the observation time, and energy
        grid are extracted from a type-I PHA (spectrum) file, while
        the pointing/livetime history file provides the instrument
        orientation during the observation. The tool has two main
        options called "GRB" and "PS". The "GRB" option is for short
        observations during which the instrument's pointing does not
        change significantly. This is relevant for most gamma-ray
        burst observations. The "PS" option is for an observation
        relevant to a point source over more than a fraction of an
        orbit, requiring that the instrument response be averaged over
        the different source directions in instrument coordinates.
        This tool needs as input two files: A pointing history or
        "spacecraft" file covering the time of the observation, which
        can be obtained from the Fermi Science Support Center (FSSC)
        web site, and a PHA file, which can be created using the gtbin
        tool (see the gtbin help). For the LAT data have to
        be binned into energy channels using the gtbin tool. But the
        first step in the analysis is to select all the counts from a
        region of 10 to 15 degrees around the burst position from the
        time range that includes the burst. These counts can be
        selected using the gtselect tool.  For further information on
        how to perform a Binned GRB Spectral analysis using the LAT
        data it is highly recommended to read the Cicerone Manual:
http://fermi.gsfc.nasa.gov/ssc/data/analysis/documentation/Cicerone/Cicerone_GRBs/GRB_binned_analysis.html
        and/or the analysis thread:
http://fermi.gsfc.nasa.gov/ssc/data/analysis/scitools/


PARAMETERS

General Parameters

respalg [string: GRB|PS]
      The type of response computation to perform, either GRB or PS.
      If set to GRB, the response will be computed for a single
      specific time supplied by the user. If set to PS, a response
      from a longer observation will be computed. The default value
      is GRB.

specfile [file]
      Name of input spectrum file, in PHA format. 
                 
scfile [file]
     Spacecraft data file.

outfile [file]
     Name of output response file, in the HEASARC "RSP" format.          

irfs [string]
     The instrument response function that will be used.

(sctable = SC_DATA) [string]
     Table containing spacecraft data.
                 
(resptpl = DEFAULT) [file]
     The full path to the template used to create the output file. This
     should not normally be changed. If DEFAULT is given, the rspgen
     application will use the standard template for LAT RSP files. This is
     a hidden parameter. The default value is "DEFAULT".

GRB Response Parameters

time = 0 [double]
     The time of the burst in Mission Elapsed Time (MET) seconds. 

Point Source Response Parameters

thetacut = 60  [double]
     The maximum angle cutoff for the differential exposure computation in
     degrees. 
                 
dcostheta = 0.05 [double]
     The bin size to be used for the spacecraft pointing history
     (cos(theta)).

Energy Binning Parameters

ebinalg = LOG [string: FILE|LIN|LOG]
      Indicates how the output energy bins will be specified. Legal values are
      FILE (bins will be read from a bin definition file), LIN (linearly
      uniform bins), and LOG (logarithmically uniform bins). This is only
      used if energy binning is required by the output type selected by the
      algorithm parameter. The default value is LOG.
                 
(efield= ENERGY) [string]
      This is the name of the field containing the energy values for energy
      binning. This is a hidden parameter. The default value is consistent
      with the event LAT data file format.
                 
emin = 30 [double]
      The lowest energy of the first interval for linearly or
      logarithmically uniform bins in MeV. Only used if ebinalg is LIN or
      LOG. The default value is 30 MeV.
                 
emax = 200000[double]
      The highest energy of the last interval for linearly or
      logarithmically uniform bins in MeV. Only used if ebinalg is LIN or
      LOG. The default value is 200000 MeV.
                 
enumbins = 100 [integer]
      The number of bins for logarithmically uniform bins. Only used if
      ebinalg is LOG. The default value is 100.
                 
denergy = 50 [double]
      The width of linearly uniform bins in MeV. Only used if ebinalg is
      LIN. The default value is 50.
                 
ebinfile = NONE [file]
      The name of the energy bin definition file. Only used if ebinalg is
      FILE. The default value is "NONE".


Other hidden parameters:

(chatter)  
      This parameter fixes the output verbosity: no screen output
      (0), nominal screen output (2), maximum verbosity (4). The
      default value is 2.

(clobber = yes)
      If true, an existing file of the same name will be overwritten. 
       This is a hidden parameter. The default value is: "yes".

(debug = no)   
      Activate debugging mode. The default value is "no". When debug
      is "no", all exceptions that are not caught and handled by
      individual tool-specific code are caught by a top-level
      exception handler that displays information about the exception
      and then exits. When debug is "yes", such exceptions are not
      caught by the top level code. Instead the tool produces a
      segmentation violation, which is more useful for
      debugging. When debugging mode is enabled, the tool produces
      more verbose output describing any errors or exceptions that
      are encountered.

(gui = no) 
     Graphical user Interface (GUI) mode activated if "yes" is
     specified. The default value is "no".

(mode = ql)
     Mode of automatic parameters. The default value is "ql". 

        
EXAMPLES

     The way that the parameters are passed follows the FTOOLs model: They
     could be passed by answering prompts, as a list in a command line,
     or by editing the parameter file.
 
     To be prompted for gtrspgen simply type in the command line: 

>gtrspgen

     This will prompt for parameter values. Beware that not all parameters
     are prompted: some of the parameter are "hidden".  If you want to
     change one of the "hidden" parameter you may specify its value in the
     command line. For example if you do want to open the GUI option type
     in the command line:

>gtrspgen gphinumbins=4
 

     An example of how to run the gtrspgen tool is given below:

> gtrspgen
This is gtrspgen version ScienceTools-v9r33p0-fssc-20140317
Response calculation method (GRB|PS) [GRB] 
Spectrum file name[] GRB.pha
Spacecraft data file name[] spacecraft_data_file.fits
Output file name[] GRB.rsp
Time of GRB (s)[0.] 252374400
Response function to use [CALDB] CALDB
Algorithm for defining true energy bins (FILE|LIN|LOG) [LOG] 
Start value for first energy bin in MeV[30.] 
Stop value for last energy bin in MeV[200000.] 
Number of logarithmically uniform energy bins[100] 


    In this case the GRB option was chosen. The spectrum file was
    generated previously with gtbin with the name: GRB.pha.

    The same task can also be run in the command line in this way:

>gtrspgen respalg=GRB specfile=GRB.pha scfile=spacecraft_data_file.fits
 outfile=GRB.rsp time=252374400 irfs=CALDB ebinalg=LOG emin=30
 emax=200000 enumbins=100



KNOWN BUGS


SEE ALSO

    * gtbin 

    * gtselect

    * The Cicerone Manual:
    http://fermi.gsfc.nasa.gov/ssc/data/analysis/documentation/Cicerone/Cicerone_GRBs/GRB_binned_analysis.html


