Add "statistic" parameter to ctbutterfly, cterror, cttsmap, and ctulimit (#2237)

Jürgen Knödlseder
1 parent 2767f430
Showing 18 changed files with 290 additions and 103 deletions
NEWS
configure.ac
cscripts/csiactobs.py
cscripts/csobs2caldb.py
cscripts/cstsmapsplit.par
doc/source/users/reference_manual/cstsmapsplit.rst
doc/source/users/reference_manual/ctbutterfly.rst
doc/source/users/reference_manual/cterror.rst
doc/source/users/reference_manual/cttsmap.rst
doc/source/users/reference_manual/ctulimit.rst
src/ctbutterfly/ctbutterfly.cpp
src/ctbutterfly/ctbutterfly.par
src/cterror/cterror.cpp
src/cterror/cterror.par
src/cttsmap/cttsmap.cpp
src/cttsmap/cttsmap.par
src/ctulimit/ctulimit.cpp
src/ctulimit/ctulimit.par
@@ -24,41 +24,49 @@ Support model
 None
-ctobssim - CTA observation simulation
--------------------------------------
-Use t-type parameters for "tmin" and "tmax" to all specifying times in various
-formats (#1864).
+ctbin - CTA event binning
+-------------------------
+None
-ctselect - CTA event selection
-------------------------------
-Use t-type parameters for "tmin" and "tmax" to all specifying times in various
-formats (#1864).
+ctbkgcube - CTA background cube generation
+------------------------------------------
+None
-ctbin - CTA event binning
--------------------------
+ctbutterfly - Generate butterfly diagrams
+-----------------------------------------
+Add "statistic" parameter to allow setting of optimizer statistic (#2237).
+
+
+ctcubemask - CTA cube filtering
+-------------------------------
 None
-ctlike - Maximum likelihood fitting
------------------------------------
-Rename "stats" parameter to "statistic" (#2238).
+ctedispcube - CTA energy dispersion cube generation
+---------------------------------------------------
+None
-cttsmap - Generation of Test Statistic map
-------------------------------------------
+cterror - Likelihood profile error computation
+----------------------------------------------
+Add "statistic" parameter to allow setting of optimizer statistic (#2237).
+
+
+ctexpcube - CTA exposure cube generation
+----------------------------------------
 None
-ctskymap - CTA sky mapping
---------------------------
-Header keywords informing about the dates and times covered by the observations
-used to generate the skymap, as well as the event energy range, are now appended
-as header keywords to the FITS file (#2194).
+ctlike - Maximum likelihood fitting
+-----------------------------------
+Rename "stats" parameter to "statistic" (#2237).
-Add the RING background method, which is a classical analysis methods for IACT
-data analysis, for background subtraction (#2207).
+
+ctmapcube - CTA map cube generation
+-----------------------------------
+None
 ctmodel - CTA counts cube modelling
@@ -72,8 +80,19 @@ parallelization of the tool has also been optimised so that diffuse models are
 not loaded over and over again (#2189).
-ctexpcube - CTA exposure cube generation
-----------------------------------------
+ctobssim - CTA observation simulation
+-------------------------------------
+Use t-type parameters for "tmin" and "tmax" to all specifying times in various
+formats (#1864).
+
+
+ctphase - Event phase computation
+---------------------------------
+None
+
+
+ctprob - Event probability computation
+--------------------------------------
 None
@@ -82,62 +101,143 @@ ctpsfcube - CTA point spread function cube generation
 None
-ctedispcube - CTA energy dispersion cube generation
----------------------------------------------------
-None
+ctselect - CTA event selection
+------------------------------
+Use t-type parameters for "tmin" and "tmax" to all specifying times in various
+formats (#1864).
-ctbkgcube - CTA background cube generation
+ctskymap - CTA sky mapping
+--------------------------
+Header keywords informing about the dates and times covered by the observations
+used to generate the skymap, as well as the event energy range, are now appended
+as header keywords to the FITS file (#2194).
+
+Add the RING background method, which is a classical analysis methods for IACT
+data analysis, for background subtraction (#2207).
+
+
+cttsmap - Generation of Test Statistic map
 ------------------------------------------
+Add "statistic" parameter to allow setting of optimizer statistic (#2237).
+
+
+ctulimit - Compute upper limit
+------------------------------
+Add "statistic" parameter to allow setting of optimizer statistic (#2237).
+
+
+cscaldb - Inspect calibration database
+--------------------------------------
 None
-ctmapcube - CTA map cube generation
------------------------------------
+csebins - Generate energy boundaries
+------------------------------------
 None
-ctcubemask - CTA cube filtering
--------------------------------
+csfindobs - Find IACT observations
+----------------------------------
 None
-ctbutterfly - Generate butterfly diagrams
------------------------------------------
+csiactcopy - Copy IACT observations
+-----------------------------------
 None
-ctulimit - Compute upper limit
-------------------------------
+csiactdata - Inspect IACT data store
+------------------------------------
 None
-cterror - Likelihood profile error computation
-----------------------------------------------
+csiactobs - Inspect IACT observation definition XML file
+--------------------------------------------------------
 None
-ctprob - Event probability computation
+cslightcrv - Generate light curve
+---------------------------------
+Use t-type parameters for "tmin" and "tmax" to all specifying times in various
+formats (#1864).
+
+
+csmodelinfo - Return model information
 --------------------------------------
 None
-ctphase - Event phase computation
----------------------------------
+csmodelmerge - Merge models
+---------------------------
 None
-cscripts
---------
+csmodelselect - Select models
+-----------------------------
+None
+
+
+csmodelsois - Puts selected sources in diffuse model cube
+---------------------------------------------------------
 Add csmodelsois script that replaces selected models in a model container by
 a diffuse map cube (#2180).
-Use t-type parameters for "tmin" and "tmax" to all specifying times in various
-formats (#1864).
+csobs2caldb - Generate calibration database entry for an IACT observation
+-------------------------------------------------------------------------
+None
+
+
+csobsdef - Generate observation definition XML file
+---------------------------------------------------
+None
+
+
+csobsinfo - Return observation definition information
+-----------------------------------------------------
+None
+
+
+csobsselect - Select observations
+---------------------------------
+None
+
+
+csphagen - Generate On/Off observations
+---------------------------------------
 The script csphagen was added to allow the generation of PHA, ARF and RMF datasets
 for classical On/Off IACT analysis (#2208).
+
+csphasecrv - Generate phase curve
+---------------------------------
+None
+
+
+cspull - Generate pull distributions
+------------------------------------
+Use t-type parameters for "tmin" and "tmax" to all specifying times in various
+formats (#1864).
+
+
+csresmap - Generate residual map
+--------------------------------
+None
+
+
+csroot2caldb - Generates calibration database from ROOT file
+------------------------------------------------------------
+None
+
+
+cssens - Computes sensitivity curve
+-----------------------------------
+None
+
+
+csspec - Generates Spectral Energy Distribution
+-----------------------------------------------
 The csspec script now can also handle On/Off spectra for SED generation (#2231).
 The csspec script now can also handle non-CTA data. For that purpose a "method"
@@ -148,6 +248,58 @@ will use &quot;SLICE&quot; for observations containing only CTA data and &quot;NODES&quot; for obser
 containing other data (#1927).
+cssrcdetect - Detects sources in sky map
+----------------------------------------
+None
+
+
+cstsdist - Computes Test Statistic distribution
+-----------------------------------------------
+Use t-type parameters for "tmin" and "tmax" to all specifying times in various
+formats (#1864).
+
+
+cstsmapmerge - Merge Test Statistic maps
+----------------------------------------
+None
+
+
+cstsmapsplit - Prepare split Test Statistic computation
+-------------------------------------------------------
+None
+
+
+csviscube - Generate visibility cube
+------------------------------------
+Use t-type parameters for "tmin" and "tmax" to all specifying times in various
+formats (#1864).
+
+
+csworkflow - Execute workflow
+-----------------------------
+None
+
+
+calutils - Calibration utilities
+--------------------------------
+None
+
+
+ioutils - Input/Output utilities
+--------------------------------
+None
+
+
+modutils - Model utilities
+--------------------------
+None
+
+
+obsutils - Observation utilities
+--------------------------------
+None
+
+
 Examples
 --------
 None
@@ -32,8 +32,8 @@ AC_INIT([ctools], [1.5.0.dev1], [jurgen.knodlseder@irap.omp.eu], [ctools])
 AC_CONFIG_SRCDIR([src/ctselect/ctselect.cpp])
 AC_CONFIG_MACRO_DIR([m4])
 #AM_INIT_AUTOMAKE([gnu no-dependencies foreign])
-AM_INIT_AUTOMAKE([gnu -Wno-portability foreign])
-#AM_INIT_AUTOMAKE([gnu -Wno-portability foreign serial-tests])
+#AM_INIT_AUTOMAKE([gnu -Wno-portability foreign])
+AM_INIT_AUTOMAKE([gnu -Wno-portability foreign serial-tests])
 AC_CONFIG_HEADER([config.h])
 #!/usr/bin/env python
 # ==========================================================================
-# Generates an IACT observation definition XML file.
+# Generates an IACT observation definition XML file
 #
 # Copyright (C) 2015-2017 Michael Mayer
 #
 #!/usr/bin/env python
 # ==========================================================================
-# Creates a calibration database entry for an IACT observation.
+# Creates a calibration database entry for an IACT observation
 #
 # Copyright (C) 2015-2017 Michael Mayer
 #
@@ -27,6 +27,7 @@ caldb,         s, a, prod2,,, &quot;Calibration database&quot;
 irf,           s, a, South_0.5h,,, "Instrument response function"
 edisp,         b, h, no,,, "Apply energy dispersion?"
 errors,        b, h, no,,, "Compute/store parameter errors?"
+statistic,     s, h, CSTAT,CSTAT|WSTAT|CHI2,, "Optimization statistic"
 outmap,        f, a, tsmap.fits,,, "Output Test Statistic map file"
 bins_per_job,  i, a, 5,,, "Number of TS map bins per task"
 compute_null,  b, a, yes,,,"Compute null hypothesis first?"
@@ -50,6 +50,14 @@ General parameters
 ``(edisp = no) [boolean]``
     Applies energy dispersion to response computation.
+``(errors = no) [boolean]``
+    Compute and store parameter errors?
+
+``(statistic = CSTAT) <CSTAT|WSTAT|CHI2> [string]``
+    Optimization statistic. ``CSTAT`` applies to all types of observations,
+    ``WSTAT``applies only to On/Off observations, and ``CHI2`` applies only
+    to binned or stacked observations.
+
 ``outmap [file]``
     Output Test Statistic map file.
@@ -86,6 +86,11 @@ General parameters
 ``(confidence = 0.68) [real]``
     Confidence level for error computation.
+``(statistic = CSTAT) <CSTAT|WSTAT|CHI2> [string]``
+    Optimization statistic. ``CSTAT`` applies to all types of observations,
+    ``WSTAT``applies only to On/Off observations, and ``CHI2`` applies only
+    to binned or stacked observations.
+
 ``(matrix = "NONE") [file]``
     Input covariance matrix file (not used)
@@ -30,13 +30,13 @@ General parameters
 ``inobs [file]``
     Input event list, counts cube or observation definition XML file.
- 	 	 
+
 ``inmodel [file]``
     Input model XML file.
- 	 	 
+
 ``srcname [string]``
     Name of source model for which the parameter errors should be computed.
- 	 	 
+
 ``expcube [file]``
     Input exposure cube file.
@@ -51,22 +51,27 @@ General parameters
 ``caldb [string]``
     Calibration database.
- 	 	 
+
 ``irf [string]``
     Instrumental response function.
- 	 	 
+
 ``(edisp = no) [boolean]``
     Applies energy dispersion to response computation.
- 	 	 
+
 ``outmodel [file]``
     Output model XML file with updated error information.
- 	 	 
+
 ``(confidence = 0.68) [real]``
     Confidence level for error computation.
-    
+
 ``(tol = 1e-3) [real]``
     Computation tolerance.
-   
+
+``(statistic = CSTAT) <CSTAT|WSTAT|CHI2> [string]``
+    Optimization statistic. ``CSTAT`` applies to all types of observations,
+    ``WSTAT``applies only to On/Off observations, and ``CHI2`` applies only
+    to binned or stacked observations.
+
 ``(max_iter = 50) [integer]``
     Maximum number of iterations before stopping the likelihood
     profil computations.
@@ -62,34 +62,39 @@ General parameters
 ``outmap [file]``
     Output Test Statistic map file.
-    
+
 ``(errors = no) [boolean]``
     Compute and store parameter errors?
- 	 	 
+
+``(statistic = CSTAT) <CSTAT|WSTAT|CHI2> [string]``
+    Optimization statistic. ``CSTAT`` applies to all types of observations,
+    ``WSTAT``applies only to On/Off observations, and ``CHI2`` applies only
+    to binned or stacked observations.
+
 ``(usepnt = no) [boolean]``
     Use CTA pointing direction for map centre instead of xref/yref parameters?
- 	 	 
+
 ``nxpix [integer]``
     Number of map pixels in Right Ascension or Galactic longitude.
- 	 	 
+
 ``nypix [integer]``
     Number of map pixels in Declination or Galactic latitude.
- 	 	 
+
 ``binsz [real]``
     Map pixel size (in degrees/pixel).
- 	 	 
+
 ``coordsys <CEL|GAL> [string]``
     Coordinate system (CEL - celestial, GAL - galactic).
- 	 	 
+
 ``proj <AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN> [string]``
     Projection method.
 ``xref [real]``
     Right Ascension / Galactic longitude of map centre (J2000, in degrees).
- 	 	 
+
 ``yref [real]``
     Declination / Galactic latitude of map centre (J2000, in degrees).
- 	 	 
+
 ``(binmin = -1) [integer]``
     First bin to compute.
@@ -98,7 +103,7 @@ General parameters
 ``(logLO = -1) [real]``
     LogLikelihood value of null hypothesis.
- 	 	 
+
 Standard parameters
 -------------------
@@ -22,19 +22,18 @@ upper flux limit (specified by the hidden parameters ``emin`` and ``emax``)
 into the log file.
-
 General parameters
 ------------------
 ``inobs [file]``
     Input event list, counts cube or observation definition XML file.
- 	 	 
+
 ``inmodel [file]``
     Input model XML file.
- 	 	 
+
 ``srcname [string]``
     Name of source model for which the upper flux limit should be computed.
- 	 	 
+
 ``expcube [file]``
     Input exposure cube file.
@@ -49,36 +48,41 @@ General parameters
 ``caldb [string]``
     Calibration database.
- 	 	 
+
 ``irf [string]``
     Instrumental response function.
- 	 	 
+
 ``(edisp = no) [boolean]``
     Applies energy dispersion to response computation.
- 	 	 
+
 ``(confidence = 0.95) [real]``
     Confidence level of upper limit.
-    
+
 ``(sigma_min = 0.0) [real]``
     Minimum boundary to start searching for upper limit value.
     Number of standard deviations above best fit value
-    
+
 ``(sigma_max = 10.0) [real]``
     Maximum boundary to start searching for upper limit value.
     Number of standard deviations above best fit value  
- 	 	 
+
 ``(eref = 1.0) [real])``
     Reference energy for differential limit (in TeV).
- 	 	 
+
 ``(emin = 1.0) [real])``
     Minimum energy for integral flux limit (in TeV).
- 	 	 
+
 ``(emax = 100) [real]``
     Maximum energy for integral flux limit (in TeV).
- 	 	 
+
 ``(tol = 1e-5) [real]``
     Computation tolerance.
-   
+
+``(statistic = CSTAT) <CSTAT|WSTAT|CHI2> [string]``
+    Optimization statistic. ``CSTAT`` applies to all types of observations,
+    ``WSTAT``applies only to On/Off observations, and ``CHI2`` applies only
+    to binned or stacked observations.
+
 ``(max_iter = 50) [integer]``
     Maximum number of iterations before stopping the upper
     limit computations.
@@ -103,7 +107,8 @@ Standard parameters
     Specifies whether an existing output file should be overwritten.
 ``(debug = no) [boolean]``
-    Enables debug mode. In debug mode the executable will dump any log file output to the console.
+    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").
@@ -451,17 +451,16 @@ void ctbutterfly::free_members(void)
  * @exception GException::feature_not_implemented
  *            Loading of covariance matrix is not yet implemented.
  *
- * Get all task parameters from parameter file or (if required) by querying
- * the user. Most parameters are only required if no observation exists so
- * far in the observation container. In this case, a single CTA observation
- * will be added to the container, using the definition provided in the
- * parameter file.
+ * Get all task parameters from parameter file.
  ***************************************************************************/
 void ctbutterfly::get_parameters(void)
 {
     // Setup observations from "inobs" parameter
     setup_observations(m_obs);
+    // Set observation statistic
+    set_obs_statistic(gammalib::toupper((*this)["statistic"].string()));
+
     // Setup models from "inmodel" parameter
     setup_models(m_obs, (*this)["srcname"].string());
@@ -475,8 +474,8 @@ void ctbutterfly::get_parameters(void)
     std::string matrixfilename = (*this)["matrix"].filename();
     if (matrixfilename != "NONE") {
         std::string msg = "Loading of matrix from file not implemented yet. "
-                "Use filename = \"NONE\" to induce a recomputation of "
-                "the matrix internally.";
+                          "Use filename = \"NONE\" to induce a recomputation "
+                          "of the matrix internally.";
         throw GException::feature_not_implemented(G_GET_PARAMETERS, msg);
         // m_covariance.load(matrixfilename);
     }
@@ -34,6 +34,7 @@ method,     s, h, GAUSSIAN, GAUSSIAN|ENVELOPE,,&quot;Butterfly computation method&quot;
 #=====================
 fit,        b, h, no,,, "Perform maximum likelihood fitting?"
 confidence, r, h, 0.68,0.0,1.0, "Confidence level"
+statistic,  s, h, CSTAT,CSTAT|WSTAT|CHI2,, "Optimization statistic"
 matrix,     f, h, "NONE",,, "Input covariance Matrix FITS file"
 #
 /***************************************************************************
  *                 cterror - Parameter error calculation tool              *
  * ----------------------------------------------------------------------- *
- *  copyright (C) 2015-2016 by Florent Forest                              *
+ *  copyright (C) 2015-2017 by Florent Forest                              *
  * ----------------------------------------------------------------------- *
  *                                                                         *
  *  This program is free software: you can redistribute it and/or modify   *
@@ -443,14 +443,16 @@ void cterror::free_members(void)
 /***********************************************************************//**
  * @brief Get application parameters
  *
- * Get all task parameters from parameter file or (if required) by querying
- * the user.
+ * Get all task parameters from parameter file.
  ***************************************************************************/
 void cterror::get_parameters(void)
 {
     // Setup observations from "inobs" parameter
     setup_observations(m_obs);
-    
+
+    // Set observation statistic
+    set_obs_statistic(gammalib::toupper((*this)["statistic"].string()));
+
     // Setup models from "inmodel" parameter
     setup_models(m_obs, (*this)["srcname"].string());
@@ -34,6 +34,7 @@ outmodel, f, a, &quot;results.xml&quot;,,, &quot;Output model definiton XML file&quot;
 #=============================
 confidence, r, h, 0.68,0.0,1.0, "Confidence level"
 tol,        r, h, 1e-3,,, "Computation tolerance"
+statistic,  s, h, CSTAT,CSTAT|WSTAT|CHI2,, "Optimization statistic"
 max_iter,   i, h, 50,1,1000, "Maximum number of iterations"
 #
 /***************************************************************************
  *                    cttsmap - TS map calculation tool                    *
  * ----------------------------------------------------------------------- *
- *  copyright (C) 2014-2016 by Michael Mayer                               *
+ *  copyright (C) 2014-2017 by Michael Mayer                               *
  * ----------------------------------------------------------------------- *
  *                                                                         *
  *  This program is free software: you can redistribute it and/or modify   *
@@ -525,17 +525,16 @@ void cttsmap::free_members(void)
  * @exception GException::invalid_value
  *            Test source has no RA/DEC parameters.
  *
- * Get all task parameters from parameter file or (if required) by querying
- * the user. Most parameters are only required if no observation exists so
- * far in the observation container. In this case, a single CTA observation
- * will be added to the container, using the definition provided in the
- * parameter file.
+ * Get all task parameters from parameter file.
  ***************************************************************************/
 void cttsmap::get_parameters(void)
 {
     // Setup observations from "inobs" parameter
     setup_observations(m_obs);
+    // Set observation statistic
+    set_obs_statistic(gammalib::toupper((*this)["statistic"].string()));
+
     // Setup models from "inmodel" parameter
     setup_models(m_obs, (*this)["srcname"].string());
@@ -32,6 +32,7 @@ outmap,    f, a, &quot;tsmap.fits&quot;,,, &quot;Output Test Statistic map file&quot;
 # TS map computation parameters
 #==============================
 errors,    b, h, no,,, "Compute and store parameter errors?"
+statistic, s, h, CSTAT,CSTAT|WSTAT|CHI2,, "Optimization statistic"
 #
 # Spatial binning parameters
@@ -449,14 +449,16 @@ void ctulimit::free_members(void)
 /***********************************************************************//**
  * @brief Get application parameters
  *
- * Get all task parameters from parameter file or (if required) by querying
- * the user.
+ * Get all task parameters from parameter file.
  ***************************************************************************/
 void ctulimit::get_parameters(void)
 {
     // Setup observations from "inobs" parameter
     setup_observations(m_obs);
-    
+
+    // Set observation statistic
+    set_obs_statistic(gammalib::toupper((*this)["statistic"].string()));
+
     // Setup models from "inmodel" parameter
     setup_models(m_obs, (*this)["srcname"].string());
@@ -37,6 +37,7 @@ eref,       r, h, 1.0,,, &quot;Reference energy for differential limit (TeV)&quot;
 emin,       r, h, 1.0,,, "Minimum energy for integral flux limit (TeV)"
 emax,       r, h, 100.0,,, "Maximum energy for integral flux limit (TeV)"
 tol,        r, h, 1e-5,,, "Computation tolerance"
+statistic,  s, h, CSTAT,CSTAT|WSTAT|CHI2,, "Optimization statistic"
 max_iter,   i, h, 50,1,1000, "Maximum number of iterations"
 #