From 527a4d1fadb89dd71d13b5671313994305b06e4f Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Sun, 6 Dec 2015 01:24:16 +0100 Subject: [PATCH] Update reference manual documentation. --- doc/source/reference_manual/cscaldb.rst | 2 +- doc/source/reference_manual/csobsdef.rst | 4 ++-- doc/source/reference_manual/ctbin.rst | 23 ++++++++++++++++------- doc/source/reference_manual/ctbkgcube.rst | 48 +++++++++++++++++++++++++++++++++++++++++------- doc/source/reference_manual/ctexpcube.rst | 37 +++++++++++++++++++++++++++++++------ doc/source/reference_manual/ctpsfcube.rst | 40 ++++++++++++++++++++++++++++++++-------- 6 files changed, 123 insertions(+), 31 deletions(-) diff --git a/doc/source/reference_manual/cscaldb.rst b/doc/source/reference_manual/cscaldb.rst index 536d98c..bfbe18e 100644 --- a/doc/source/reference_manual/cscaldb.rst +++ b/doc/source/reference_manual/cscaldb.rst @@ -1 +1 @@ -.. _cscaldb: cscaldb ======= Dumps all available instrument response functions into log fil. Synopsis -------- This scripts dumps all instrument response functions that are available in the calibration database into the log file. If you want the information on the screen, add the ``debug=yes`` parameter. General parameters ------------------ None Standard parameters ------------------- ``(chatter = 2) [integer]`` Verbosity of the executable: chatter = 0: no information will be logged chatter = 1: only errors will be logged chatter = 2: errors and actions will be logged chatter = 3: report about the task execution chatter = 4: detailed report about the task execution ``(clobber = yes) [boolean]`` Specifies whether an existing output counts cube should be overwritten. ``(debug = no) [boolean]`` Enables debug mode. In debug mode the executable will dump any log file output to the console. ``(mode = ql) [string]`` Mode of automatic parameters (default is "ql", i.e. "query and learn"). Related tools ------------- None \ No newline at end of file +.. _cscaldb: cscaldb ======= Dumps all available instrument response functions into log file. Synopsis -------- This scripts dumps all instrument response functions that are available in the calibration database into the log file. If you want the information on the screen, add the ``debug=yes`` parameter. General parameters ------------------ None Standard parameters ------------------- ``(chatter = 2) [integer]`` Verbosity of the executable: chatter = 0: no information will be logged chatter = 1: only errors will be logged chatter = 2: errors and actions will be logged chatter = 3: report about the task execution chatter = 4: detailed report about the task execution ``(clobber = yes) [boolean]`` Specifies whether an existing output counts cube should be overwritten. ``(debug = no) [boolean]`` Enables debug mode. In debug mode the executable will dump any log file output to the console. ``(mode = ql) [string]`` Mode of automatic parameters (default is "ql", i.e. "query and learn"). Related tools ------------- None \ No newline at end of file diff --git a/doc/source/reference_manual/csobsdef.rst b/doc/source/reference_manual/csobsdef.rst index b9f4bf9..e2da151 100644 --- a/doc/source/reference_manual/csobsdef.rst +++ b/doc/source/reference_manual/csobsdef.rst @@ -46,8 +46,8 @@ Here some usage examples: Creates observation definition file with a ROI radius of 5 deg. ``csobsdef caldb=prod2 irf=South_50h`` - Creates observation definition file using the "South_50h" IRF in the - "prod2" calibration database. + Creates observation definition file using the ``South_50h`` IRF in the + ``prod2`` calibration database. General parameters diff --git a/doc/source/reference_manual/ctbin.rst b/doc/source/reference_manual/ctbin.rst index 45ed5b5..3831fd1 100644 --- a/doc/source/reference_manual/ctbin.rst +++ b/doc/source/reference_manual/ctbin.rst @@ -3,18 +3,27 @@ ctbin ===== -Generate a counts cube for binned maximum likelihood analysis. +Generate counts cube from event list(s). Synopsis -------- -This tool computes the counts cube for use in a binned maximum likelihood -analysis. The counts cubes are 3-dimensional data cubes spanned by Right -Ascension or Galactic longitude, Declination or Galactic latitude, and energy. -The energy binning may be either linear, logarithmic, or custom defined. -If an observation definition XML file containing several observations is -provided on input, the tool will stack all data into a single counts cube. +This tool creates a counts cube and fills it with events. A counts cube is +a 3-dimensional data cube spanned by Right Ascension or Galactic longitude, +Declination or Galactic latitude, and energy. The energy binning may be either +linear, logarithmic, or custom defined using an input file. The events are +either taken from a single event list file or from the event lists that are +specified in an observation definition file. In case that multiple event +lists are given in an observation definition file, the tool will loop over +all event lists and fill all events into a single counts cube. + +ctbin generates a counts cube FITS file comprising three extensions. The +primary extension contains a 3-dimensional image that contains the counts +cube values. The next extension named ``EBOUNDS`` contains a binary table +that defines the energy boundaries of the counts cube. The last extension +named ``GTI`` contains a binary table that defines the Good Time Intervals +of all event lists that have been filled into the counts cube. General parameters diff --git a/doc/source/reference_manual/ctbkgcube.rst b/doc/source/reference_manual/ctbkgcube.rst index 9809f52..c4b4188 100644 --- a/doc/source/reference_manual/ctbkgcube.rst +++ b/doc/source/reference_manual/ctbkgcube.rst @@ -3,24 +3,55 @@ ctbkgcube ========= -Generate a background cube for binned maximum likelihood analysis. +Generate background cube for a counts cube. Synopsis -------- -This tool generates a background cube for use in a binned maximum -likelihood analysis. +This tool generates a background cube for a counts cube based on an input +model. A background cube is a 3-dimensional cube spanned by Right Ascension +or Galactic longitude, Declination or Galactic latitude, and energy. The +energy binning may be either linear, logarithmic, or custom defined using an +input file. The input model is used to predict the expected number of +background counts in each background cube bin. + +ctbkgcube requires on input the event list or observation definition file +that has been used in the generation of the counts cube using :doc:`ctbin`. + +To assure consistency between an existing counts cube and the +corresponding background cube, it is recommended to specify the counts +cube as ``incube`` parameter. This will instruct ctbkgcube to extract the +background cube definition (such as sky coordinates and projection, number +of pixels, pixel scale, energy binning) from the counts cube. + +ctbkgcube generates a background cube FITS file comprising two extensions. +The primary extension contains a 3-dimensional image that contains the +background cube values. The next extension named ``EBOUNDS`` contains a +binary table that defines the energy boundaries of the background cube. + +ctbkgcube generates also an output model XML file that can serve as input +for a maximum likelihood analysis. The output model XML file is a copy of +the input model XML file where the input background model has been replaced +by a background model of type ``CTACubeBackground``. The ``CTACubeBackground`` +background model instructs any tool analysing binned data to extract +background information from a background cube. The ``CTACubeBackground`` +model has a spectral component that can be adjusted in a maximum +likelihood fit to accomodate for uncertainties in the prediction of the +energy dependence of the background rate. ctbkgcube will use a power law +as spectral component, but you can replace this by any component of your +choice. + General parameters ------------------ ``inobs [file]`` - Input event list, cube or observation definition XML file. + Input event list or observation definition XML file. ``inmodel [file]`` - Input (background) model XML file. + Input model XML file. ``incube [file]`` Counts cube for background cube definition. @@ -28,11 +59,14 @@ General parameters ``outcube [file]`` Output background cube file. +``outmodel [file]`` + Output model XML file. + ``caldb [string]`` Calibration database. ``irf [string]`` - Response function. + Instrument response function. ``ebinalg [string]`` Algorithm for defining energy bins. @@ -105,4 +139,4 @@ Standard parameters Related tools ------------- -None +:doc:`ctbin` diff --git a/doc/source/reference_manual/ctexpcube.rst b/doc/source/reference_manual/ctexpcube.rst index 26fdc51..b66e56c 100644 --- a/doc/source/reference_manual/ctexpcube.rst +++ b/doc/source/reference_manual/ctexpcube.rst @@ -3,14 +3,39 @@ ctexpcube ========= -Generate an exposure cube for binned maximum likelihood analysis. +Generate exposure cube for a counts cube. Synopsis -------- -This tool generates an exposure cube for use in a binned maximum likelihood -analysis. +This tool generates an exposure cube for a counts cube. An exposure cube is +a 3-dimensional cube spanned by Right Ascension or Galactic longitude, +Declination or Galactic latitude, and energy, that gives the exposure +as function of true sky direction and energy. The energy binning of the cube +may be either linear, logarithmic, or custom defined using an input file. + +ctexpcube requires on input the event list or observation definition file +that has been used in the generation of the counts cube using :doc:`ctbin`. + +For the user's convenience, the counts cube can be specified as ``incube`` +parameter which will instruct ctexpcube to extract the exposure cube +definition (such as sky coordinates and projection, number of pixels, pixel +scale, energy binning) from the counts cube. Note, however, that the exposure +cube is defined in true sky coordinates and energy while the counts cube is +defined in measured sky coordinates and energy. Consequently, the sky area +and energy range covered by the exposure cube should be slightly larger than +that of the counts cube to accomodate for spill over of events due to the +point spread function and energy dispersion. By computing the exposure map +on the same grid as the counts cube, the spill over of events from sources at +the edge of cube will not be handled correctly. + +ctexpcube generates an exposure cube FITS file comprising three extensions. +The primary extension contains a 3-dimensional image that contains the +exposure values. The next extension named ``EBOUNDS`` contains a binary table +that defines the energy boundaries of the exposure cube. The last extension +named ``GTI`` contains a binary table that defines the Good Time Intervals +of the exposure cube. General parameters @@ -20,7 +45,7 @@ General parameters Input event list or observation definition XML file. ``incube [file]`` - Counts cube for PSF cube definition. + Counts cube for exposure cube definition. ``outcube [file]`` Output exposure cube file. @@ -29,7 +54,7 @@ General parameters Calibration database. ``irf [string]`` - Response function. + Instrument response function. ``(edisp = no) [boolean]`` Apply energy dispersion for response computation? @@ -105,4 +130,4 @@ Standard parameters Related tools ------------- -None +:doc:`ctbin` diff --git a/doc/source/reference_manual/ctpsfcube.rst b/doc/source/reference_manual/ctpsfcube.rst index 5f0d716..80ac18f 100644 --- a/doc/source/reference_manual/ctpsfcube.rst +++ b/doc/source/reference_manual/ctpsfcube.rst @@ -3,15 +3,39 @@ ctpsfcube ========= -Generate a point spread function cube for binned maximum likelihood -analysis. +Generate point spread function cube for a counts cube. Synopsis -------- -This tool generates a point spread function cube for use in a binned -maximum likelihood analysis. +This tool generates a point spread function cube for a counts cube. A point +spread function cube is a 4-dimensional cube spanned by Right Ascension or +Galactic longitude, Declination or Galactic latitude, energy, and offset +angle between true and measured arrival direction of a photon. The energy +binning of the cube may be either linear, logarithmic, or custom defined +using an input file. + +ctpsfcube requires on input the event list or observation definition file +that has been used in the generation of the counts cube using :doc:`ctbin`. + +It is not recommended to use the counts cube for the point spread function +cube definition, although this is formally possibly by specifying the counts +cube as ``incube`` parameter. This leads however to a large FITS file on +output since the number of bins in the counts cube will be multiplied by +the number of offset angle bins (typically 200). Since the point spread +function varies only little over the field of fiew of the camera it is +recommended to use a rather coarse spatial binning to keep the file size +manageable (with a typical value of ``binsz=1.0``). + +ctpsfcube generates a point spread function cube FITS file comprising three +extensions. The primary extension contains a 3-dimensional image that contains +the point spread function values. The energy and offset angle dimensions +of the point spread function cube are folded into the 3rd dimension of the +FITS image. The next extension named ``EBOUNDS`` contains a binary table +that defines the energy boundaries of the exposure cube. The last extension +named ``DELTAS`` contains a binary table that defines the offset angles +between true and measured arrival direction of the photon. General parameters @@ -21,16 +45,16 @@ General parameters Input event list or observation definition XML file. ``incube [file]`` - Counts cube for PSF cube definition. + Counts cube for point spread function cube definition. ``outcube [file]`` - Output PSF cube file. + Output point spread function cube file. ``caldb [string]`` Calibration database. ``irf [string]`` - Response function. + Instrument response function. ``(edisp = no) [boolean]`` Apply energy dispersion for response computation. @@ -113,4 +137,4 @@ Standard parameters Related tools ------------- -None +:doc:`ctbin` -- libgit2 0.21.4