reference manual and tests for ctedispcube, minor changes in source code (#1724)

Maria Haupt
1 parent 464e5f56
Showing 7 changed files with 315 additions and 13 deletions
doc/source/reference_manual/ctedispcube.rst
doc/source/reference_manual/ctpsfcube.rst
doc/source/reference_manual/index.rst
src/ctedispcube/ctedispcube.cpp
src/ctedispcube/ctedispcube.par
test/test_ctedispcube.py
test/test_ctools.sh
+.. _ctedispcube:
+
+ctedispcube
+=========
+
+Generate energy dispersion cube for a counts cube.
+
+
+Synopsis
+--------
+
+This tool generates an energy dispersion cube for a counts cube. An energy 
+dispersion cube is a 4-dimensional cube spanned by Right Ascension or
+Galactic longitude, Declination or Galactic latitude, energy, and fraction 
+between recontructed and true photon energy. The energy binning of the cube 
+may be either linear, logarithmic, or custom defined using an input file.
+
+ctedispcube 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 energy dispersion 
+cube definition, although this is formally possible 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 energy dispersion 
+varies only little over the field of view 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``).
+
+ctedispcube generates an energy dispersion cube FITS file comprising three
+extensions. The primary extension contains a 3-dimensional image that contains
+the energy disperison values. The energy and fraction dimensions of the enrgy 
+dispersion 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 fraction between recontructed and true photon 
+energy.
+
+
+General parameters
+------------------
+
+``inobs [file]``
+    Input event list or observation definition XML file.
+
+``incube [file]``
+    Input counts cube file to extract energy dispersion cube definition.
+
+``caldb [string]``
+    Calibration database.
+
+``irf [string]``
+    Instrument response function.
+
+``(edisp = no) [boolean]``
+    Apply energy dispersion for response computation.
+
+``outcube [file]``
+    Output energy dispersion cube file.
+
+``ebinalg <FILE|LIN|LOG> [string]``
+    Algorithm for defining energy bins.
+ 	 	 
+``emin [real]``
+    Lower energy value for first energy bin (in TeV).
+ 	 	 
+``emax [real]``
+    Upper energy value for last energy bin (in TeV).
+ 	 	 
+``enumbins [integer]``
+    Number of energy bins.
+ 	 	 
+``ebinfile [file]``
+    Name of the file containing the energy bin definition.
+ 	 	 
+``(usepnt = no) [boolean]``
+    Use CTA pointing direction for cube centre instead of xref/yref parameters?
+ 	 	 
+``nxpix [integer]``
+    Number of cube bins in Right Ascension or Galactic longitude.
+ 	 	 
+``nypix [integer]``
+    Number of cube bins in Declination or Galactic latitude.
+ 	 	 
+``binsz [real]``
+    Cube bin size (in degrees/pixel).
+ 	 	 
+``coordsys <CEL|GAL> [string]``
+    Coordinate system (CEL - celestial, GAL - galactic).
+ 	 	 
+``xref [real]``
+    Right Ascension / Galactic longitude of cube centre (J2000, in degrees).
+ 	 	 
+``yref [real]``
+    Declination / Galactic latitude of cube centre (J2000, in degrees).
+ 	 	 
+``proj <AIT|AZP|CAR|MER|MOL|STG|TAN> [string]``
+    Projection method.
+
+``(mmax = 10.0) [real]``
+    Upper bound of fraction between recontructed and true photon energy.
+
+``(migrabins = 200) [integer]``
+    Number of migration bins.
+ 	 	 
+
+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 energy dispersion cube file 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").
+
+``(logfile = ctedispcube.log) [string]``
+    Name of log file.
+
+
+Related tools or scripts
+------------------------
+
+:doc:`ctbin`
@@ -20,7 +20,7 @@ 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 definition, although this is formally possible 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 
@@ -19,6 +19,7 @@ ctools
    ctbkgcube --- Generates background cube <ctbkgcube>
    ctbutterfly --- Compute butterfly <ctbutterfly>
    ctcubemask --- Filter counts cube <ctcubemask>
+   ctedispcube --- Generates energy dispersion cube <ctedispcube>
    ctexpcube --- Generates exposure cube <ctexpcube>
    ctlike --- Performs maximum likelihood fitting <ctlike>
    ctmodel --- Computes model counts cube <ctmodel>
@@ -376,8 +376,8 @@ void ctedispcube::get_parameters(void)
     std::string incube = (*this)["incube"].filename();
  
     // Get additional binning parameters
-    double amax     = (*this)["amax"].real();
-    int    anumbins = (*this)["anumbins"].integer();
+    double mmax     = (*this)["mmax"].real();
+    int    migrabins = (*this)["migrabins"].integer();
  
     // Check for filename validity
     if ((incube == "NONE") || (gammalib::strip_whitespace(incube) == "")) {
@@ -386,7 +386,7 @@ void ctedispcube::get_parameters(void)
         GCTAEventCube cube = create_cube(m_obs);
  
         // Define edisp cube
-        m_edispcube = GCTACubeEdisp(cube, amax, anumbins);
+        m_edispcube = GCTACubeEdisp(cube, mmax, migrabins);
  
     }
  
@@ -397,7 +397,7 @@ void ctedispcube::get_parameters(void)
         GCTAEventCube cube(incube);
  
         // Define edisp cube
-        m_edispcube = GCTACubeEdisp(cube, amax, anumbins);
+        m_edispcube = GCTACubeEdisp(cube, mmax, migrabins);
  
     } // endelse: cube loaded from file
  
@@ -4,14 +4,14 @@
 #                                                                           #
 # ------------------------------------------------------------------------- #
 #                                                                           #
-#  File:      ctpsfcube.par                                                 #
-#  Version:   1.0.0                                                         #
+#  File:      ctedispcube.par                                               #
+#  Version:   1.1.0                                                         #
 #                                                                           #
-#  Author:    Chia-Chun Lu                                                  #
-#             c.lu@mpi-hd.mpg.de                                            #
-#             MPIK                                                          #
+#  Author:    Maria Haupt                                                   #
+#             maria.haupt@desy.de                                           #
+#             DESY                                                          #
 #                                                                           #
-#  Purpose:   Parameter file for the ctpsfcube application                  #
+#  Purpose:   Parameter file for the ctedispcube application                #
 #                                                                           #
 #############################################################################
 #
@@ -48,8 +48,8 @@ proj,     s, a, &quot;CAR&quot;, AIT|AZP|CAR|MER|MOL|STG|TAN,, &quot;Projection method&quot;
 #
 # Angular separation binning parameters
 #======================================
-amax,     r, h, 0.3,,, "Upper bound of angular separation between true and measued photon direction (degrees)"
-anumbins, i, h, 200,,, "Number of angular separation bins"
+mmax,     r, h, 10.0,,, "Upper bound of fraction between recontructed and true photon energy"
+migrabins, i, h, 100,,, "Number of migration bins"
  
 #
 # Standard parameters
+#! /usr/bin/env python
+# ==========================================================================
+# This scripts performs unit tests for the ctedispcube tool.
+#
+# Copyright (C) 2014-2016 Juergen Knoedlseder
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+# ==========================================================================
+import gammalib
+import ctools
+
+
+# ============================= #
+# Test class for ctedispcube tool #
+# ============================= #
+class Test(gammalib.GPythonTestSuite):
+    """
+    Test class for ctedispcube tool.
+    """
+    # Constructor
+    def __init__(self):
+        """
+        Constructor.
+        """
+        # Call base class constructor
+        gammalib.GPythonTestSuite.__init__(self)
+
+        # Set members
+        self.events_name = "data/crab_events.fits"
+        self.caldb       = "irf"
+        self.irf         = "cta_dummy_irf"
+
+        # Return
+        return
+
+    # Set test functions
+    def set(self):
+        """
+        Set all test functions.
+        """
+        # Set test name
+        self.name("ctedispcube")
+
+        # Append tests
+        self.append(self.test_functional, "Test ctedispcube functionality")
+
+        # Return
+        return
+
+    # Test ctedispcube functionnality
+    def test_functional(self):
+        """
+        Test ctedispcube functionnality.
+        """
+        # Set-up ctedispcube
+        edispcube = ctools.ctedispcube()
+        edispcube["inobs"]    = self.events_name
+        edispcube["incube"]   = "NONE"
+        edispcube["outcube"]  = "edispcube.fits"
+        edispcube["caldb"]    = self.caldb
+        edispcube["irf"]      = self.irf
+        edispcube["ebinalg"]  = "LOG"
+        edispcube["emin"]     = 0.1
+        edispcube["emax"]     = 100
+        edispcube["enumbins"] = 20
+        edispcube["nxpix"]    = 10
+        edispcube["nypix"]    = 10
+        edispcube["binsz"]    = 0.4
+        edispcube["coordsys"] = "CEL"
+        edispcube["proj"]     = "CAR"
+        edispcube["xref"]     = 83.63
+        edispcube["yref"]     = 22.01
+        edispcube["mmax"]     = 0.3
+        edispcube["migrabins"] = 10
+
+        # Run tool
+        self.test_try("Run ctedispcube")
+        try:
+            edispcube.run()
+            self.test_try_success()
+        #except Exception as e:
+        #    msg = "Exception occured in ctedispcube: %s." % (e,)
+        except:
+            msg = "Exception occured in ctedispcube."
+            self.test_try_failure(msg)
+
+        # Save EDISP cube
+        self.test_try("Save EDISP cube")
+        try:
+            edispcube.save()
+            self.test_try_success()
+        #except Exception as e:
+        #    msg = "Exception occured in saving EDISP cube: %s." % (e,)
+        except:
+            msg = "Exception occured in saving EDISP cubes."
+            self.test_try_failure(msg)
+
+        # Return
+        return
@@ -43,6 +43,7 @@ ctselect=../src/ctselect/ctselect
 ctskymap=../src/ctskymap/ctskymap
 ctexpcube=../src/ctexpcube/ctexpcube
 ctpsfcube=../src/ctpsfcube/ctpsfcube
+ctedispcube=../src/ctedispcube/ctedispcube
 ctbkgcube=../src/ctbkgcube/ctbkgcube
 ctcubemask=../src/ctcubemask/ctcubemask
 ctbutterfly=../src/ctbutterfly/ctbutterfly
@@ -272,6 +273,57 @@ $ECHO &quot; ok&quot;
  
  
 #
+# Test ctedispcube
+# ==============
+$ECHO -n "Test ctedispcube: "
+#
+# Run 1
+$ctedispcube inobs="data/crab_events.fits" \
+             incube="NONE" \
+             outcube="edispcube1.fits" \
+             caldb="irf" \
+             irf="cta_dummy_irf" \
+             emin=0.1 \
+             emax=100.0 \
+             enumbins=20 \
+             nxpix=10 \
+             nypix=10 \
+             binsz=0.4 \
+             coordsys="CEL" \
+             xref=83.63 \
+             yref=22.01 \
+             proj="CAR" \
+             mmax=10.0 \
+             migrabins=100
+$ECHO -n "."
+if [ -s "edispcube1.fits" ]
+then
+$ECHO -n "."
+else
+$ECHO " edispcube1.fits file is not found"
+exit 1
+fi
+#
+# Run 2
+$ctedispcube inobs="events.fits" \
+             incube="cntmap2.fits" \
+             outcube="edispcube2.fits" \
+             caldb="irf" \
+             irf="cta_dummy_irf" \
+             mmax=10.0 \
+             migrabins=5
+$ECHO -n "."
+if [ -s "edispcube2.fits" ]
+then
+$ECHO -n "."
+else
+$ECHO " edispcube2.fits file is not found"
+exit 1
+fi
+$ECHO " ok"
+
+
+#
 # Test ctbkgcube
 # ==============
 $ECHO -n "Test ctbkgcube: "