Add hidden "use_irf_bkg" parameter to csphagen (#2659)

Jürgen Knödlseder
1 parent 2f7db38b
Showing 6 changed files with 64 additions and 24 deletions
ChangeLog
NEWS
cscripts/csphagen.par
cscripts/csphagen.py
doc/source/admin/release_history/1.6.rst
doc/source/users/reference_manual/csphagen.rst
-2018-08-01
+2018-08-03
         * Version 1.6.0 released
         ========================
+        Add hidden "use_irf_bkg" parameter to csphagen (#2659)
         Use full RMF true energy range for On/Off analysis in csspec (#2656)
         Defer import of ROOT module in csroot2caldb to run method (#2652)
         Transparently update parameter files (#2513)
 New Features and Important Changes in ctools 1.6.0
-1 August 2018
+3 August 2018
 Introduction
@@ -248,6 +248,17 @@ Use time reference of input observations if time selection is given in MET
 csphagen - Generate On/Off observations
 ---------------------------------------
+Add hidden "use_irf_bkg" parameter. By default the parameter is set to "yes",
+which means that the background acceptance provided in the IRF is used for
+the computation of the alpha parameter and the background rate, stored in the
+"BACKSCAL" column of the On spectrum and the "BACKRESP" column of the Off
+spectrum, respectively. If the parameter is set to "no" it is assumed that the
+background rate in the On and Off regions are the same, and the IRF background
+template is not used. In that case, the "BACKSCAL" column gives the ratio of
+the solid angles between On and Off regions, and the "BACKRESP" column is set
+to zero. The resulting data can only be fitted using the "wstat" statistic
+(#2659).
+
 Add hidden "nthreads" parameter and implement parallelisation of computations
 (#2421).
@@ -28,27 +28,28 @@ prefix,      s, h, onoff,,, &quot;Prefix for output files&quot;
 #
 # Script parameters
 #==================
-ebinalg,    s, a, LOG,FILE|LIN|LOG,, "Algorithm for defining energy bins"
-emin,       r, a, 0.1,,, "Start value for first energy bin in TeV"
-emax,       r, a, 100.0,,, "Stop value for last energy bin in TeV"
-enumbins,   i, a, 120,,, "Number of energy bins"
-ebinfile,   f, a, NONE,,, "Name of the file containing the energy bin definition"
-srcshape,   s, h, CIRCLE,CIRCLE,, "Shape of the source region"
-coordsys,   s, a, CEL,CEL|GAL,, "Coordinate system (CEL - celestial, GAL - galactic)"
-ra,         r, a, 83.63,0,360, "Right Ascension of source region centre (deg)"
-dec,        r, a, 22.01,-90,90, "Declination of source region centre (deg)"
-glon,       r, a, 184.56,0,360, "Galactic longitude of source region centre (deg)"
-glat,       r, a, -5.79,-90,90, "Galactic latitude of source region centre (deg)"
-rad,        r, a, 0.2,0,180, "Radius of source region circle (deg)"
-srcregfile, f, a, on.reg,,, "Source region file (ds9 or FITS WCS)"
-bkgmethod,  s, a, REFLECTED,REFLECTED|CUSTOM,, "Method for background estimation"
-bkgregfile, f, a, bkg.reg,,, "Background regions file (ds9 or FITS WCS)"
-bkgregmin,  i, h, 2,1,1000, "Minimum number of background regions"
-maxoffset,  r, h, 4.0,,, "Maximum offset of source from camera center to accept observation"
-stack,      b, a, no,,, "Stack multiple observations into single PHA, ARF and RMF files?"
-etruemin,   r, h, 0.01,,, "Minimum true energy (TeV)"
-etruemax,   r, h, 300.0,,, "Maximum true energy (TeV)"
-etruebins,  i, h, 30,,, "Number of bins per decade for true energy bins"
+ebinalg,     s, a, LOG,FILE|LIN|LOG,, "Algorithm for defining energy bins"
+emin,        r, a, 0.1,,, "Start value for first energy bin in TeV"
+emax,        r, a, 100.0,,, "Stop value for last energy bin in TeV"
+enumbins,    i, a, 120,,, "Number of energy bins"
+ebinfile,    f, a, NONE,,, "Name of the file containing the energy bin definition"
+srcshape,    s, h, CIRCLE,CIRCLE,, "Shape of the source region"
+coordsys,    s, a, CEL,CEL|GAL,, "Coordinate system (CEL - celestial, GAL - galactic)"
+ra,          r, a, 83.63,0,360, "Right Ascension of source region centre (deg)"
+dec,         r, a, 22.01,-90,90, "Declination of source region centre (deg)"
+glon,        r, a, 184.56,0,360, "Galactic longitude of source region centre (deg)"
+glat,        r, a, -5.79,-90,90, "Galactic latitude of source region centre (deg)"
+rad,         r, a, 0.2,0,180, "Radius of source region circle (deg)"
+srcregfile,  f, a, on.reg,,, "Source region file (ds9 or FITS WCS)"
+bkgmethod,   s, a, REFLECTED,REFLECTED|CUSTOM,, "Method for background estimation"
+bkgregfile,  f, a, bkg.reg,,, "Background regions file (ds9 or FITS WCS)"
+bkgregmin,   i, h, 2,1,1000, "Minimum number of background regions"
+use_irf_bkg, b, h, yes,,, "Use IRF background template?"
+maxoffset,   r, h, 4.0,,, "Maximum offset of source from camera center to accept observation"
+stack,       b, a, no,,, "Stack multiple observations into single PHA, ARF and RMF files?"
+etruemin,    r, h, 0.01,,, "Minimum true energy (TeV)"
+etruemax,    r, h, 300.0,,, "Maximum true energy (TeV)"
+etruebins,   i, h, 30,,, "Number of bins per decade for true energy bins"
 #
 # Standard parameters
@@ -157,6 +157,9 @@ class csphagen(ctools.csobservation):
             self._rad = self['rad'].real()
             self._src_reg.append(gammalib.GSkyRegionCircle(self._src_dir, self._rad))
+        # Query usage of IRF background template
+        self['use_irf_bkg'].boolean()
+
         # Return
         return
@@ -478,6 +481,12 @@ class csphagen(ctools.csobservation):
             # Set background regions for this observation
             bkg_reg = self._set_background_regions(obs)
+            # Get IRF background template usage flag
+            use_irf_bkg = self['use_irf_bkg'].boolean()
+            if not use_irf_bkg:
+                self._log_string(gammalib.NORMAL, 'IRF background template '
+                                 'not used, assume constant backround rate.')
+
             # If there are background regions then create On/Off observation
             # and append it to the output container
             if bkg_reg.size() >= self['bkgregmin'].integer():
@@ -486,7 +495,8 @@ class csphagen(ctools.csobservation):
                                                       self._etruebounds,
                                                       self._ebounds,
                                                       self._src_reg,
-                                                      bkg_reg)
+                                                      bkg_reg,
+                                                      use_irf_bkg)
                 onoff.id(obs.id())
             else:
@@ -519,6 +529,7 @@ class csphagen(ctools.csobservation):
         """
         # If the results contain an On/Off observation
         if result['onoff'].classname() == 'GCTAOnOffObservation':
+
             # Append observation to observation container
             outobs.append(result['onoff'])
@@ -32,6 +32,8 @@ Bug fixes
 Improvements
 ------------
+* [`2659 <https://cta-redmine.irap.omp.eu/issues/2659>`_] -
+  Add hidden ``use_irf_bkg`` parameter to :ref:`csphagen`
 * [`2656 <https://cta-redmine.irap.omp.eu/issues/2656>`_] -
   Use full ``RMF`` true energy range for On/Off analysis in :ref:`csspec`
 * [`2513 <https://cta-redmine.irap.omp.eu/issues/2513>`_] -
@@ -167,6 +167,20 @@ General parameters
     If this number of background regions is not available the observation is
     skipped.
+``(use_irf_bkg = yes) [boolean]``
+    Specifies whether the IRF background template should be used for the
+    computation of the ``alpha`` parameter and the predicted background rate in
+    the Off region that is stored in the ``BACKRESP`` column of the Off spectrum.
+
+    If the parameter is set to ``no`` the IRF background template is not used and
+    the background rate is assumed identical within the On and Off regions. This
+    is the classical IACT analysis method that is used when using reflected Off
+    regions. In that case the ``alpha`` parameter becomes independent of energy
+    and only reflects the ratio between the solid angles of the On and Off
+    regions. The ``BACKRESP`` column in the Off spectrum will be filled with zeros.
+    The data need to be fitted with the ``wstat`` statistic, fitting with ``cstat``
+    will not work.
+
 ``(maxoffset = 4.0) [real]``
     Maximum offset in degrees of source from camera center to accept the
     observation.