Rename "outcube" parameter to "outobs"

Jürgen Knödlseder
1 parent f25aeb73
Showing 7 changed files with 59 additions and 34 deletions
doc/source/admin/release_history/1.6.rst
doc/source/users/reference_manual/ctbin.rst
doc/source/users/reference_manual/ctselect.rst
src/ctbin/ctbin.cpp
src/ctbin/ctbin.hpp
src/ctbin/ctbin.par
test/test_ctbin.py
@@ -42,7 +42,8 @@ Improvements
 ------------
  
 * [`2714 <https://cta-redmine.irap.omp.eu/issues/2714>`_] -
-  Enable :ref:`ctbin` to produce counts cubes for a joint binned analysis
+  Enable :ref:`ctbin` to produce counts cubes for a joint binned analysis.
+  Rename ``outcube`` to ``outobs`` parameter.
 * [`2685 <https://cta-redmine.irap.omp.eu/issues/2685>`_] -
   Add ``ctbkgcube::cntcube()`` method
   Account for varying energy thresholds in :ref:`ctbin` weight computation
@@ -14,17 +14,27 @@ 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.
+specified in an observation definition file.
  
-:ref:`ctbin` generates a counts cube FITS file comprising three extensions. The
+In case that multiple event lists are given in an observation definition file
+there are two options. By default, the tool will loop over all event lists and
+fill all events into a single counts cube. If ``stack=no`` is specified, the
+tool will bin each event list into a separate counts cube.
+
+:ref:`ctbin` generates counts cube FITS file(s) 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.
  
+By default, the tool will write out a single, stacked, counts cube. If ``stack=no``
+is specified, the tool will write all counts cubes into a separate FITS file,
+prefixing the input event list file name with the string that is specified by
+the hidden ``prefix`` parameter. In addition, the tool will create an observation
+definition XML file that lists all produced counts cubes, and that can be used
+as input for any further analysis step.
+
  
 General parameters
 ------------------
@@ -32,8 +42,18 @@ General parameters
 ``inobs [file]``
     Input event list or observation definition XML file.
  
-``outcube [file]``
-    Output counts cube file.
+``outobs [file]``
+    Output counts cube file or observation definition XML file.
+
+``(stack = yes) [boolean]``
+    Specify whether stacking of the events in a single counts cube is requested.
+    By default this hidden parameter is set to yes, and the tool produces a
+    single counts cube FITS file on output. If ``no`` is specified, the tool
+    will produce a counts cube for each event list that is found in the input
+    observation, and will also write an observation definition XML file.
+
+``(prefix = "binned_") [string]``
+    Prefix for output counts cube in observation definition XML file.
  
 ``ebinalg <FILE|LIN|LOG> [string]``
     Algorithm for defining energy bins. For ``FILE``, the energy bins are defined
@@ -52,7 +52,7 @@ General parameters
     Output event list or observation definition XML file.
  
 ``(prefix = "selected_") [string]``
-    Prefix for output event lists in observation definition file.
+    Prefix for output event lists in observation definition XML file.
  
 ``(usepnt = yes) [boolean]``
     Use pointing instead of RA/DEC parameters?
@@ -462,10 +462,10 @@ void ctbin::save(void)
  
         // Save only if filename is valid and if there is at least one
         // observation
-        if ((*this)["outcube"].is_valid() && m_obs.size() > 0) {
+        if ((*this)["outobs"].is_valid() && m_obs.size() > 0) {
  
             // Get counts cube filename
-            m_outcube = (*this)["outcube"].filename();
+            GFilename outobs = (*this)["outobs"].filename();
  
             // Get CTA observation from observation container
             GCTAObservation* obs = dynamic_cast<GCTAObservation*>(m_obs[0]);
@@ -474,14 +474,14 @@ void ctbin::save(void)
             if (obs != NULL) {
  
                 // Log counts cube file name
-                log_value(NORMAL, "Counts cube file", m_outcube.url());
+                log_value(NORMAL, "Counts cube file", outobs.url());
  
                 // Save cube
-                obs->save(m_outcube, clobber());
+                obs->save(outobs, clobber());
  
             } // endif: observation was valid
  
-        } // endif: outcube file was valid
+        } // endif: outobs file was valid
  
     } // endif: counts cube was stacked
  
@@ -495,7 +495,7 @@ void ctbin::save(void)
             // Loop over all ids of observations that were binned
             for (int j = 0; j < m_ids.size(); ++j) {
  
-                // Skip if ID differes
+                // Skip if ID differs
                 if (m_ids[j] != m_obs[i]->id()) {
                     continue;
                 }
@@ -517,9 +517,16 @@ void ctbin::save(void)
         } // endfor: looped over all observations
  
         // Write XML file
-        if ((*this)["outcube"].is_valid()) {
-            m_outcube = (*this)["outcube"].filename();
-            m_obs.save(m_outcube);
+        if ((*this)["outobs"].is_valid()) {
+
+            // Get observation definition XML filename
+            std::string outobs = (*this)["outobs"].filename();
+
+            // Issue warning if output filename has no .xml suffix
+            log_string(TERSE, warn_xml_suffix(outobs));
+
+            // Save XML file
+            m_obs.save(outobs);
         }
  
     } // endelse: counts cube were not stacked
@@ -570,7 +577,6 @@ void ctbin::publish(const std::string&amp; name)
 void ctbin::init_members(void)
 {
     // Initialise members
-    m_outcube.clear();
     m_usepnt  = false;
     m_stack   = true;
     m_publish = false;
@@ -602,7 +608,6 @@ void ctbin::init_members(void)
 void ctbin::copy_members(const ctbin& app)
 {
     // Copy attributes
-    m_outcube = app.m_outcube;
     m_usepnt  = app.m_usepnt;
     m_stack   = app.m_stack;
     m_publish = app.m_publish;
@@ -669,7 +674,7 @@ void ctbin::get_parameters(void)
  
     // If needed later, query output filename now
     if (read_ahead()) {
-        (*this)["outcube"].query();
+        (*this)["outobs"].query();
     }
  
     // Set number of OpenMP threads
@@ -99,7 +99,6 @@ protected:
     void    obs_cube_stacked(void);
  
     // User parameters
-    GFilename   m_outcube;  //!< Output counts map file name
     bool        m_usepnt;   //!< Use pointing instead of xref/yref parameters
     bool        m_stack;    //!< Output one stacked cube or multiple cubes
     std::string m_prefix;   //!< Prefix for output path of multiple cubes
@@ -16,10 +16,10 @@
 #
 # General parameters
 #===================
-inobs,   f, a, events.fits,,, "Input event list or observation definition XML file"
-outcube, f, a, cntcube.fits,,, "Output counts cube file"
-stack,   b, h, yes,,, "Stack events into one cube?"
-prefix,  s, h, binned_,,, "Prefix for counts cubes in observation definition XML file"
+inobs,  f, a, events.fits,,, "Input event list or observation definition XML file"
+outobs, f, a, cntcube.fits,,, "Output counts cube file or observation definition XML file"
+stack,  b, h, yes,,, "Stack events into one cube?"
+prefix, s, h, binned_,,, "Prefix for counts cubes in observation definition XML file"
  
 #
 # Energy binning parameters
@@ -71,7 +71,7 @@ class Test(test):
  
         # Setup ctbin command
         cmd = ctbin+' inobs="'+self._events+'"'+ \
-                    ' outcube="cntmap_cmd1.fits"'+\
+                    ' outobs="cntmap_cmd1.fits"'+\
                     ' emin=1.0 emax=100.0 enumbins=10 ebinalg="LOG"'+ \
                     ' nxpix=40 nypix=40 binsz=0.1 coordsys="CEL"'+ \
                     ' xref=83.63 yref=22.01 proj="CAR"'+ \
@@ -87,7 +87,7 @@ class Test(test):
  
         # Setup ctbin command
         cmd = ctbin+' inobs="events_that_do_not_exist.fits"'+ \
-                    ' outcube="cntmap_cmd2.fits"'+\
+                    ' outobs="cntmap_cmd2.fits"'+\
                     ' emin=1.0 emax=100.0 enumbins=10 ebinalg="LOG"'+ \
                     ' nxpix=40 nypix=40 binsz=0.1 coordsys="CEL"'+ \
                     ' xref=83.63 yref=22.01 proj="CAR"'+ \
@@ -99,7 +99,7 @@ class Test(test):
  
         # Setup ctbin command with different ebounds than input
         cmd = ctbin+' inobs="'+self._events+'"'+ \
-                    ' outcube="cntmap_cmd3.fits"'+\
+                    ' outobs="cntmap_cmd3.fits"'+\
                     ' emin=2.0 emax=20.0 enumbins=10 ebinalg="LOG"'+ \
                     ' nxpix=40 nypix=40 binsz=0.1 coordsys="CEL"'+ \
                     ' xref=83.63 yref=22.01 proj="CAR"'+ \
@@ -117,7 +117,7 @@ class Test(test):
  
         # Setup ctbin command
         cmd = ctbin+' inobs="'+self._datadir+'/obs_unbinned_two.xml"'+ \
-                    ' outcube="obs_unbinned_two_binned.xml"'+\
+                    ' outobs="obs_unbinned_two_binned.xml"'+\
                     ' emin=1.0 emax=100.0 enumbins=10 ebinalg="LOG"'+ \
                     ' nxpix=40 nypix=40 binsz=0.1 coordsys="CEL"'+ \
                     ' xref=83.63 yref=22.01 proj="CAR"'+ \
@@ -170,7 +170,7 @@ class Test(test):
  
         # Check that saving does not nothing
         binning['logfile'] = 'ctbin_py0.log'
-        binning['outcube'] = 'ctbin_py0.fits'
+        binning['outobs']  = 'ctbin_py0.fits'
         binning.logFileOpen()
         binning.save()
         self.test_assert(not os.path.isfile('ctbin_py0.fits'),
@@ -184,7 +184,7 @@ class Test(test):
  
         # Now set ctbin parameters
         binning['inobs']    = self._events
-        binning['outcube']  = 'ctbin_py1.fits'
+        binning['outobs']   = 'ctbin_py1.fits'
         binning['ebinalg']  = 'LOG'
         binning['emin']     = 1.0
         binning['emax']     = 100.0
@@ -251,7 +251,7 @@ class Test(test):
  
         # Set-up ctbin using an observation container
         binning = ctools.ctbin(obs)
-        binning['outcube']  = 'ctbin_py3.fits'
+        binning['outobs']   = 'ctbin_py3.fits'
         binning['ebinalg']  = 'LOG'
         binning['emin']     = 1.0
         binning['emax']     = 100.0
@@ -285,7 +285,7 @@ class Test(test):
         pars = {'inobs': self._events, 'ebinalg': 'LIN', 'emin': 1.0,
                 'emax': 100.0, 'enumbins': 10, 'nxpix': 40, 'nypix': 40,
                 'binsz': 0.1, 'coordsys': 'CEL', 'proj': 'CAR',
-                'xref': 83.63, 'yref': 22.01, 'outcube': 'ctbin_py4.fits',
+                'xref': 83.63, 'yref': 22.01, 'outobs': 'ctbin_py4.fits',
                 'logfile': 'ctbin_py4.log', 'chatter': 2}
         binning = ctools.ctbin()
         binning.pardict(pars)
@@ -300,7 +300,7 @@ class Test(test):
         pars = {'inobs': self._datadir+'/obs_unbinned_two.xml', 'ebinalg': 'LIN', 'emin': 1.0,
                 'emax': 100.0, 'enumbins': 10, 'nxpix': 40, 'nypix': 40,
                 'binsz': 0.1, 'coordsys': 'CEL', 'proj': 'CAR',
-                'xref': 83.63, 'yref': 22.01, 'outcube': 'ctbin_py5.xml',
+                'xref': 83.63, 'yref': 22.01, 'outobs': 'ctbin_py5.xml',
                 'logfile': 'ctbin_py5.log', 'chatter': 2,
                 'prefix': 'cntcube_py5_', 'stack' : False}
         binning = ctools.ctbin()