Merge branch '1646-write-iact-docs' into integration

# Conflicts: # ChangeLog

Merge branch '1646-write-iact-docs' into integration
# Conflicts: # ChangeLog
Jürgen Knödlseder
2 parents 05b33a6b ac1a6460
Showing 14 changed files with 1699 additions and 60 deletions
ChangeLog
cscripts/csiactdata.py
cscripts/csiactobs.py
cscripts/csobsinfo.py
doc/source/reference_manual/csiactobs.rst
doc/source/reference_manual/csmodelmerge.rst
doc/source/reference_manual/cstsmapmerge.rst
doc/source/user_manual/iact_analysis/analysis.rst
doc/source/user_manual/iact_analysis/copy.rst
doc/source/user_manual/iact_analysis/high_level.rst
doc/source/user_manual/iact_analysis/index.rst
doc/source/user_manual/iact_analysis/simulation.rst
doc/source/user_manual/iact_analysis/tips.rst
doc/source/user_manual/index.rst
@@ -4,6 +4,7 @@
         ========================
         Test and import IACT scripts only for Python 2.6+ (#1715)
+        Add documentation for IACT analysis (#1646)
         Adapt to revise GTime operators (#1714)
         Add publish() methods to tools producing images (#1710)
         Read ahead output filename in cterror (#1700)
@@ -40,9 +40,10 @@ class csiactdata(ctools.cscript):
         Constructor.
         """
         # Set name
-        self.name     = "csiactdata"
-        self.version  = "1.0.0"
-        self.datapath = os.getenv("VHEFITS","")
+        self.name      = "csiactdata"
+        self.version   = "1.0.0"
+        self.datapath  = os.getenv("VHEFITS","")
+        self.prodnames = []
         # Make sure that parfile exists
         file = self.parfile()
@@ -156,6 +157,9 @@ class csiactdata(ctools.cscript):
         data      = json.loads(json_data)    
         configs   = data["datasets"]
+        # Initialise array for available names
+        self.prodnames = []
+        
         # Loop over configs and display unavailable storage first        
         for config in configs:
@@ -163,8 +167,11 @@ class csiactdata(ctools.cscript):
             hdu = os.path.join(self.datapath, config["hduindx"])
             obs = os.path.join(self.datapath, config["obsindx"])
+            filename_hdu = gammalib.GFilename(str(hdu)+"[HDU_INDEX]")
+            filename_obs = gammalib.GFilename(str(obs)+"[OBS_INDEX]")
+            
             # Check if index files are available
-            if not (gammalib.is_fits(str(hdu)) and gammalib.is_fits(str(obs))):
+            if not (filename_hdu.is_fits() and filename_obs.is_fits()):
                 self.log.parformat(str(config["name"]))
                 self.log("Not available")
                 self.log("\n")
@@ -180,13 +187,34 @@ class csiactdata(ctools.cscript):
             hdu = os.path.join(self.datapath, config["hduindx"])
             obs = os.path.join(self.datapath, config["obsindx"])
+            filename_hdu = gammalib.GFilename(str(hdu)+"[HDU_INDEX]")
+            filename_obs = gammalib.GFilename(str(obs)+"[OBS_INDEX]")
+            
             # Check if index files are available
-            if gammalib.is_fits(str(hdu)) and gammalib.is_fits(str(obs)):   
+            if (filename_hdu.is_fits() and filename_obs.is_fits()):
                 # Log data information  
                 self.log("\n")
                 self.log.header3(str(config["name"]))
+                
+                # Print important informations first
+                self.log.parformat("Name")
+                self.log(str(config["name"]))
+                self.log("\n")  
+                self.log.parformat("Observation index")
+                self.log(str(config["obsindx"]))
+                self.log("\n") 
+                self.log.parformat("HDU index")
+                self.log(str(config["hduindx"]))
+                self.log("\n") 
+                
+                # Append to available names
+                self.prodnames.append(str(config["name"]))
+                
+                # Print additional information
                 for key in config:
+                    if key in ["name","hduindx","obsindx"]:
+                        continue
                     self.log.parformat(str(key))
                     self.log(str(config[key]))
                     self.log("\n")  
@@ -194,6 +222,14 @@ class csiactdata(ctools.cscript):
         # Return
         return       
+    def names(self):
+        """ 
+        Return available FITS production names
+        """
+        
+        # Return 
+        return self.prodnames
+
 # ======================== #
 # Main routine entry point #
 # ======================== #
@@ -51,6 +51,7 @@ class csiactobs(ctools.cscript):
         self.inmodels  = None
         self.xml       = gammalib.GXml()
         self.models    = gammalib.GModels()
+        self.m_runlist = []
         # Make sure that parfile exists
         file = self.parfile()
@@ -136,9 +137,27 @@ class csiactobs(ctools.cscript):
         # Expand environment
         self.datapath = gammalib.expand_env(self.datapath)
-        # Read user parameters  
+        # Read FITS production
         self.m_prodname    = self["prodname"].string()
-        self.m_runlistfile = self["infile"].filename()
+        
+        # Read runlist file if list not already filled
+        if len(self.m_runlist) == 0:
+            
+            # Get file name
+            self.m_runlistfile = self["infile"].filename()
+            
+            # Read runlist from file
+            runfile = open(self.m_runlistfile.url())
+            for line in runfile.readlines():
+                if len(line) == 0:
+                    continue
+                if line[0] == '#':
+                    continue
+                if len(line.split()) > 0:
+                    self.m_runlist.append(line.split()[0])
+            runfile.close()
+        
+        # Read number of background parameters
         self.m_bkgpars     = self["bkgpars"].integer()
         # Output model file
@@ -220,6 +239,25 @@ class csiactobs(ctools.cscript):
         # Return
         return
+    def runlist(self, runlist):
+        """
+        Set observation list
+        """
+        
+        # Check if convertable to a python list
+        try:
+            
+            # Store a copy of input argument
+            self.m_runlist = list(runlist)
+            
+        except:
+            
+            # raise error if wrong type detected
+            raise RuntimeError("Argument of csiactobs.runlist() must be of type 'list'")
+        
+        # Return
+        return
+    
     def background_spectrum(self, run, prefactor, index, emin = 0.01, emax = 100.0):
         # Handle constant spectral model 
@@ -390,30 +428,16 @@ class csiactobs(ctools.cscript):
         self.xml.append(gammalib.GXmlElement("observation_list title=\"observation list\""))
         lib = self.xml.element("observation_list", 0)
-        # Read runlist from file
-        runlist = []
-        runfile = open(self.m_runlistfile.url())
-        for line in runfile.readlines():
-            if len(line) == 0:
-                continue
-            if line[0] == '#':
-                continue
-            if len(line.split()) > 0:
-                runlist.append(line.split()[0])
-            else:
-                runlist.append('')
-        runfile.close()
-
         # Log output
         if self.logTerse():
             self.log("\n")
-            self.log.header1("Looping over "+str(len(runlist))+" runs")
+            self.log.header1("Looping over "+str(len(self.m_runlist))+" runs")
         # Initialise energy range values for logging
         self.m_ebounds.clear()
         # Loop over runs
-        for obs_id in runlist:
+        for obs_id in self.m_runlist:
             # Create selection string
             obs_selection = "[OBS_ID=="+str(obs_id)+"]"
@@ -40,6 +40,14 @@ class csobsinfo(ctools.cscript):
         self.name    = "csobsinfo"
         self.version = "1.1.0"
+        # Initialise some members
+        if len(argv) > 0 and isinstance(argv[0],gammalib.GObservations):
+            self.obs = argv[0]
+            argv     = argv[1:]
+        else:      
+            self.obs = gammalib.GObservations()
+            self.obs.clear()   
+
         # Make sure that parfile exists
         file = self.parfile()
@@ -99,9 +107,10 @@ class csobsinfo(ctools.cscript):
         """
         Get parameters from parfile and setup the observation.
         """
-        # Get parameters     
-        self.require_inobs("csobsinfo::get_parameters")
-        self.obs = self.get_observations(False)
+        # Get parameters   
+        if self.obs.size() == 0:  
+            self.require_inobs("csobsinfo::get_parameters")
+            self.obs = self.get_observations(False)
         # Initialise object position
         self.obj_dir = gammalib.GSkyDir()
@@ -137,16 +146,16 @@ class csobsinfo(ctools.cscript):
         # Initialise arrays to store certain values for reuse
         # Todo, think about using a python dictionary
-        self.offsets  = []
-        self.zeniths  = []
-        self.azimuths = []
+        self.m_offsets  = []
+        self.m_zeniths  = []
+        self.m_azimuths = []
         self.pnt_ra   = []
         self.pnt_dec  = []
         obs_names     = []
         # Initialise output to be filled
-        self.ebounds   = gammalib.GEbounds()
-        self.gti       = gammalib.GGti()
+        self.m_ebounds   = gammalib.GEbounds()
+        self.m_gti       = gammalib.GGti()
         ontime         = 0.0
         livetime       = 0.0
         n_events       = 0
@@ -195,10 +204,10 @@ class csobsinfo(ctools.cscript):
             # If avaliable append energy boundaries
             if obs_bounds.size() > 0 : 
-                self.ebounds.merge(obs_bounds.emin(),obs_bounds.emax())
+                self.m_ebounds.append(obs_bounds.emin(),obs_bounds.emax())
             # Append time interval
-            self.gti.merge(obs_gti.tstart(), obs_gti.tstop())
+            self.m_gti.append(obs_gti.tstart(), obs_gti.tstop())
             # Increment global livetime and ontime
             ontime   += obs.ontime()
@@ -269,18 +278,18 @@ class csobsinfo(ctools.cscript):
                 # Log offset if possible
                 if self.m_offset:
                     offset = pnt_dir.dist_deg(self.obj_dir)
-                    self.offsets.append(offset)
+                    self.m_offsets.append(offset)
                     self.log.parformat("Offset")
                     self.log("%.2f" % (offset))
                     self.log("\n")
                 else:
-                    self.offsets.append(-1.0)
+                    self.m_offsets.append(-1.0)
                 # Retrieve zenith and azimuth and store for later use
                 zenith = obs.pointing().zenith()
                 azimuth = obs.pointing().azimuth()
-                self.zeniths.append(zenith)
-                self.azimuths.append(azimuth)
+                self.m_zeniths.append(zenith)
+                self.m_azimuths.append(azimuth)
                 # Log Zenith and Azimuth if required
                 if self.logExplicit():
@@ -315,15 +324,15 @@ class csobsinfo(ctools.cscript):
         # Log mean offset if possible
         if self.m_offset:
             self.log.parformat("Mean offset angle")
-            self.log("%.2f" % (sum(self.offsets)/len(self.offsets)))
+            self.log("%.2f" % (sum(self.m_offsets)/len(self.m_offsets)))
             self.log("\n")
         # Log mean azimuth and zenith angle
         self.log.parformat("Mean zenith angle")
-        self.log("%.2f" % (sum(self.zeniths)/len(self.zeniths)))
+        self.log("%.2f" % (sum(self.m_zeniths)/len(self.m_zeniths)))
         self.log("\n")
         self.log.parformat("Mean azimuth angle")
-        self.log("%.2f" % (sum(self.azimuths)/len(self.azimuths)))
+        self.log("%.2f" % (sum(self.m_azimuths)/len(self.m_azimuths)))
         self.log("\n")
         # Log name of observations if requested
@@ -338,25 +347,25 @@ class csobsinfo(ctools.cscript):
         # Log energy range
         self.log.header3("Energy range")
         self.log.parformat("Emin")
-        if self.ebounds.size() == 0:
+        if self.m_ebounds.size() == 0:
             self.log("undefined")
         else:
-            self.log(str(self.ebounds.emin()))
+            self.log(str(self.m_ebounds.emin()))
         self.log("\n")
         self.log.parformat("Emax")
-        if self.ebounds.size() == 0:
+        if self.m_ebounds.size() == 0:
             self.log("undefined")
         else:
-            self.log(str(self.ebounds.emax()))
+            self.log(str(self.m_ebounds.emax()))
         self.log("\n\n")
         # Log time range
         self.log.header3("Time range")
         self.log.parformat("Start [MJD]")
-        self.log(str(self.gti.tstart().mjd()))
+        self.log(str(self.m_gti.tstart().mjd()))
         self.log("\n")
         self.log.parformat("Stop [MJD]")
-        self.log(str(self.gti.tstop().mjd()))
+        self.log(str(self.m_gti.tstop().mjd()))
         self.log("\n")  
         # Log ontime and livetime in different units      
@@ -406,31 +415,31 @@ class csobsinfo(ctools.cscript):
         """
         Return zenith angles
         """
-        return self.zeniths
+        return self.m_zeniths
     def azimuths(self):
         """
         Return azimuth angles
         """
-        return self.azimuths
+        return self.m_azimuths
     def offsets(self):
         """
         Return offset angles
         """
-        return self.offsets
+        return self.m_offsets
     def ebounds(self):
         """
         Return energy boundaries
         """
-        return self.ebounds
+        return self.m_ebounds
     def gti(self):
         """
         Return good time intervals
         """
-        return self.gti
+        return self.m_gti
     def execute(self):
         """
@@ -67,7 +67,7 @@ General parameters
 ``(master_indx = master.json) [file]``
     Name of master index file.
-``(bkg_scale = yes) [boolean]
+``(bkg_scale = yes) [boolean]``
     Specifies whether the background scaling factor from the observation index
     file should be applied if available. 
@@ -12,10 +12,11 @@ Synopsis
 This script merges several model XML file into a single model XML file. The
 files are passed via the ``inmodels`` parameter. There are 4 options to specify
 a list of files that should be merged:
-- a space-separated list of file names (e.g. model1.xml model2.xml)
-- a comma-separated list of file names (e.g. model1.xml,model2.xml)
-- a wildcard string (e.g. mymodel*.xml)
-- an ASCII file containing the file names, one file per line (e.g. @mymodels.txt)
+
+* a space-separated list of file names (e.g. model1.xml model2.xml)
+* a comma-separated list of file names (e.g. model1.xml,model2.xml)
+* a wildcard string (e.g. mymodel*.xml)
+* an ASCII file containing the file names, one file per line (e.g. @mymodels.txt)
 Note that the "@" needs to be specified in case of an ASCII file name. It is
 also important to note that models with the same name cannot be appended. The
@@ -15,10 +15,11 @@ map again. Running :doc:`cttsmap` with the hidden parameters ``binmin`` and
 ``binmax`` specified will result in several sliced TS maps. This script merges
 them into one FITS file. The input slices can be passed via the ``inmaps``
 parameter. There are 4 options to specify a list of files that should be merged:
-- a space-separated list of file names (e.g. tsmap1.fits tsmap2.fits)
-- a comma-separated list of file names (e.g. tsmap1.fits,tsmap2.fits)
-- a wildcard string (e.g. tsmap*.xml)
-- an ASCII file containing the file names, one file per line (e.g. @mymaps.txt)
+
+* a space-separated list of file names (e.g. tsmap1.fits tsmap2.fits)
+* a comma-separated list of file names (e.g. tsmap1.fits,tsmap2.fits)
+* a wildcard string (e.g. tsmap*.xml)
+* an ASCII file containing the file names, one file per line (e.g. @mymaps.txt)
 Note that the "@" needs to be specified in case of an ASCII file name. 
+.. _sec_analysis:
+
+Analysing IACT data
+===================
+
+In order to analyse data from current IACTs, the data have to be retrieved. Information how
+to copy IACT data to a local machine can be found here: :ref:`sec_copy`
+
+Check available FITS production
+-------------------------------
+Before starting an analysis, it is important to know what kind of data need to be analysed.
+In the current scheme of `storing IACT data <http://gamma-astro-data-formats.readthedocs.org/en/latest/data_storage/index.html>`_,
+every FITS data set is represented with a unique name, e.g. ``"hess-fits-pa-release-1.0-Prod26-MppStd"``. This string
+has to be passed to some set of ctools to find and use the data for analysis.
+
+To check the available names of FITS data sets, it is recommended to run :ref:`csiactdata`.
+
+.. code-block:: bash
+
+  $ csiactdata
+  Path were data is located [] /path/to/fits/data/
+  
+This will list names of available FITS data sets on the screen. In the 
+following it is assumed the user has selected a data set called ``fits-data-name``.
+The query for the path where the data is located can be
+omitted by setting the environment variable ``VHEFITS`` to this locations. This might be convenient
+since some other tools also query for the same parameter and can use ``VHEFITS`` instead.
+
+Find observations
+-----------------
+To start an analysis, it is required to assemble a list of observations that should be used. For this purpose,
+:ref:`csfindobs` searches for observations according to user criteria.
+
+Search for sky pointings
+^^^^^^^^^^^^^^^^^^^^^^^^
+The most common search for observations is by pointing position in the sky.
+
+.. code-block:: bash
+
+  $ csfindobs
+  Name of FITS production (Run csiactdata to view your options) [fits-data-name] 
+  Right ascension [83.6331]
+  Declination [22.01] 
+  Search radius [2.5]
+  Runlist outfile [runlist.lis]
+  
+  
+Specifying additional search criteria
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The search for observations can be further constrained arbitrarily. For this purpose,
+:ref:`csfindobs` contains a hidden parameter ``expression``. It is possible to use any
+FITS selection expression that is `supported by cfitsio <http://www.isdc.unige.ch/integral/download/osa/doc/10.1/osa_um_intro/node38.html>`_.
+Available properties (i.e. column names) for selection, can be found 
+`here <http://gamma-astro-data-formats.readthedocs.org/en/latest/data_storage/obs_index/index.html>`_
+or by simply browsing the observation index file with a FITS viewer.
+
+Example:
+
+.. code-block:: bash
+
+  $ csfindobs expression="ZEN_PNT<30&&LIVETIME>1800"
+  ...
+  
+This command selects all observations that have a zenith angle less than 
+30 degrees and a livetime larger than 1800 seconds (i.e. 30 minutes).
+
+
+Omitting the pointing selection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can also omit the pointing selection, for example in case where you 
+don't know the sky coordinates of your object of interest. In that case, you 
+may directly use the object name in the expression and pass ``NONE`` as
+coordinate to :ref:`csfindobs`:
+
+.. code-block:: bash
+
+  $ csfindobs expression="OBJECT=='Crab Nebula'"
+  Name of FITS production (Run csiactdata to view your options) [fits-data-name] 
+  Right ascension [NONE]
+  Runlist outfile [runlist.lis]
+
+This will omit the selection of pointing positions.
+
+.. note::
+
+   By default, :ref:`csfindobs` only selects data of highest quality (i.e. QUALITY=0).
+   You may overwrite this default by specifying the hidden parameter 
+   ``min_qual``. For example, ``min_qual=1`` selects all data with a 
+   looser quality criteria.
+
+Create an observation list
+--------------------------
+The runlist ASCII file containing a list of selected observation IDs must now be converted to an
+observation definition XML file. This file contains information about the location of the files that are required
+for the analysis. The purpose of the tool :ref:`csiactobs` is to do this conversion.
+
+.. code-block:: bash
+
+  $ csiactobs
+  Data storage name (Run csiactdata to view your options) [] fits-data-name
+  Runlist file [runlist.lis]
+  Number of free parameters per background model [1] 
+  Output model XML file [bgmodels.xml] 
+  Observation XML outfile [obs.xml]
+
+This tools has now performed various tasks:
+
+* Use the IACT data storage to convert the observation list ``runlist.lis`` into an observation definition XML file ``obs.xml``.
+* Create a model XML file that contains the background models. In ctools, each observation has its own independent background model. The number of free parameters per model was set to 1, i.e. the normalisation of the background is left free for each observation. The models were saved in ``bgmodels.xml``.
+* The tool uses an internal hierarchy for assigning the background models. The hidden parameter ``bkg_mod_hiera`` (default=irf|aeff|gauss) steers the order how background models should be created. In case the IRF background model is not available, the script automatically falls back to the background model from effective area (GCTAModelAeffBackground). 
+* There are some further hidden parameters to steer the start parameters for the Aeff and Gaussian background model. Have a look at :ref:`csiactobs` to view a full list of parameters.
+* In ``csiactobs.log`` (or on screen if ``debug=yes``), the script logs the complete energy range of the observation container. These values might be important for later usage (e.g. in binned analysis).
+
+In case a sky model is already prepared, it is possible to also provide the hidden parameter ``inmodel``. The output
+model XML file will then contain both, the background model and the input sky model:
+
+.. code-block:: bash
+
+  $ csiactobs inmodel="mymodel.xml"
+  
+Alternatively, models can be merged at any times using the simple tool :ref:`csmodelmerge`:
+
+.. code-block:: bash
+
+  $ csmodelmerge
+  Input model XML files [bgmodels.xml crab.xml]
+  Output model file [crab_models.xml]
+  
+Note that the number of files to merge is not limited to two. Detailled options how the input model XML file can
+be passed is given on the reference page of :ref:`csmodelmerge`. It is also important to know that each model in the container
+must have a unique name. This implies, for instance, merging the same XML model twice will result in an exception.
+
+A list of available sky models can be found `here <http://gammalib.sourceforge.net/user_manual/modules/model.html>`_.
+Of particular help to create sky models for your dataset is the section about :ref:`modelling CTA data <models>`.
+
+
+Example XML files
+-----------------
+To get familiar with the XML syntax and format, example files for an observation container and a model container
+are shown in the following.
+
+Observation XML file
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: xml
+
+	<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+	<observation_list title="observation list">
+	  <observation name="Crab Nebula" id="11111" instrument="HESS">
+	    <parameter name="EventList" file="/path/to/fits/file/events_11111.fits.gz" />
+	    <parameter name="EffectiveArea" file="/path/to/fits/file/aeff_11111.fits.gz" />
+	    <parameter name="PointSpreadFunction" file="/path/to/fits/file/psf_11111.fits.gz" />
+	    <parameter name="EnergyDispersion" file="/path/to/fits/file/edisp_11111.fits.gz" />
+	    <parameter name="Background" file="/path/to/fits/file/bgmodel_11111.fits.gz" />
+	  </observation>
+	  <observation name="Crab Nebula" id="11112" instrument="HESS">
+	    <parameter name="EventList" file="/path/to/fits/file/events_11112.fits.gz" />
+	    <parameter name="EffectiveArea" file="/path/to/fits/file/aeff_11112.fits.gz" />
+	    <parameter name="PointSpreadFunction" file="/path/to/fits/file/psf_11112.fits.gz" />
+	    <parameter name="EnergyDispersion" file="/path/to/fits/file/edisp_11112.fits.gz" />
+	    <parameter name="Background" file="/path/to/fits/file/bgmodel_11112.fits.gz" />
+	  </observation>
+	  <observation name="Crab Nebula" id="11113" instrument="HESS">
+	    <parameter name="EventList" file="/path/to/fits/file/events_11113.fits.gz" />
+	    <parameter name="EffectiveArea" file="/path/to/fits/file/aeff_11113.fits.gz" />
+	    <parameter name="PointSpreadFunction" file="/path/to/fits/file/psf_11113.fits.gz" />
+	    <parameter name="EnergyDispersion" file="/path/to/fits/file/edisp_11113.fits.gz" />
+	    <parameter name="Background" file="/path/to/fits/file/bgmodel_11113.fits.gz" />
+	  </observation>
+	  <observation name="Crab Nebula" id="11114" instrument="HESS">
+	    <parameter name="EventList" file="/path/to/fits/file/events_11114.fits.gz" />
+	    <parameter name="EffectiveArea" file="/path/to/fits/file/aeff_11114.fits.gz" />
+	    <parameter name="PointSpreadFunction" file="/path/to/fits/file/psf_11114.fits.gz" />
+	    <parameter name="EnergyDispersion" file="/path/to/fits/file/edisp_11114.fits.gz" />
+	    <parameter name="Background" file="/path/to/fits/file/bgmodel_11114.fits.gz" />
+	  </observation>
+	</observation_list>
+
+Model XML file
+^^^^^^^^^^^^^^
+
+.. code-block:: xml
+
+	<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+	<source_library title="source library">
+	  <source name="bkg_11111" type="CTAIrfBackground" instrument="HESS" id="11111">
+	    <spectrum type="ConstantValue">
+	      <parameter name="Value" value="1" error="0" scale="1" min="0.01" max="100" free="1" />
+	    </spectrum>
+	  </source>
+	  <source name="bkg_11112" type="CTAIrfBackground" instrument="HESS" id="11112">
+	    <spectrum type="ConstantValue">
+	      <parameter name="Value" value="1" error="0" scale="1" min="0.01" max="100" free="1" />
+	    </spectrum>
+	  </source>
+	  <source name="bkg_11113" type="CTAIrfBackground" instrument="HESS" id="11113">
+	    <spectrum type="ConstantValue">
+	      <parameter name="Value" value="1" error="0" scale="1" min="0.01" max="100" free="1" />
+	    </spectrum>
+	  </source>
+	  <source name="bkg_11114" type="CTAIrfBackground" instrument="HESS" id="11114">
+	    <spectrum type="ConstantValue">
+	      <parameter name="Value" value="1" error="0" scale="1" min="0.01" max="100" free="1" />
+	    </spectrum>
+	  </source>
+	    <source name="Crab" type="PointSource">
+	    <spectrum type="PowerLaw">
+	       <parameter name="Prefactor" scale="1e-17" value="3.0"  min="1e-07" max="1000.0" free="1"/>
+	       <parameter name="Index"     scale="-1"    value="2.5" min="0.0"   max="+5.0"   free="1"/>
+	       <parameter name="Scale"     scale="1e6"   value="1.0"  min="0.01"  max="1000.0" free="0"/>
+	    </spectrum>
+	    <spatialModel type="SkyDirFunction">
+	      <parameter name="RA"  scale="1.0" value="83.6331" min="-360" max="360" free="1"/>
+	      <parameter name="DEC" scale="1.0" value="22.0145" min="-90"  max="90"  free="1"/>
+	    </spatialModel>
+	  </source>
+	</source_library>
+
+.. note::
+
+   It is important to ensure background models are properly linked to their respective observation.
+   Therefore it is required to keep the attributes ``instrument`` and ``id`` the same for the observation
+   and the corresponding background model. The tool :ref:`csiactobs` assures this automatically.
+
+Run ctselect
+------------
+To prepare the data for analysis, cuts have to be applied to the event data. The selection is performed by :ref:`ctselect`.
+This tool writes out selected event lists into the local directory. If the observation XML file contains several runs, it is recommended
+to first create a separate folder and specify this folder in the hidden ``prefix`` argument.
+
+.. code-block:: bash
+
+  $ mkdir selected
+  
+.. code-block:: bash
+
+  $ ctselect usethres=DEFAULT usepnt=yes prefix=selected/selected_
+  Input event list or observation definition file [events.fits] obs.xml
+  Lower energy limit (TeV) [0.1]
+  Upper energy limit (TeV) [100.0]
+  Radius of ROI (degrees) (0-180) [3.0] 2.5
+  Start time (CTA MET in seconds) [0.0]
+  End time (CTA MET in seconds) [0.0]
+  Output event list or observation definition file [selected_events.fits] selected_obs.xml 
+  
+For IACT analysis, it is recommended to use the hidden parameter ``usethres="DEFAULT"``. This instructs :ref:`ctselect`
+to extract the safe energy range from the instrument response functions and apply them to the data. This safe energy range
+is thus superior to the energy limit passed via the user parameters. In addition, to analyse the complete field of view,
+the parameter ``usepnt=yes`` uses, for each observation, the pointing position as centre for the selection radius.
+The radius parameter is dependent on the intrument, for an instrument with a 5 degree field of view, a radius of 2.5 degrees
+seems reasonable. The time selection is not applied in the above example; 
+specifying 0 as start and end time skips the time selection.
+For time-resolved analysis, it is important to know the MET time that is required to extract.
+The result of the selection step is written into the observation XML file ``selected_obs.xml``, which now contains references
+to the new selected event FITS files.
+
+Unbinned analysis
+-----------------
+Once the data is selected, the easiest way to analyse is an unbinned analysis. Note that the input model XML
+file must now contain the background models and source components to describe the field of view.
+
+.. code-block:: bash
+
+  $ ctlike
+  Event list, counts cube or observation definition file [events.fits] selected_obs.xml
+  Source model [$CTOOLS/share/models/crab.xml] crab_models.xml
+  Source model output file [crab_results.xml]
+  
+The result of the fit was stored in ``crab_results.xml``. Note that fitted parameters, ``Prefactors`` in particular,
+typically use MeV as energy unit. To monitor the progress of the fit on the screen, one can simply run with the option ``debug=yes``.
+Alternatively, the logfile ``ctlike.log`` can be inspected after the fit. 
+
+On default, energy dispersion is not considered in the fit. To switch on the usage of the energy migration matrix,
+the hidden parameter ``edisp=yes`` can be provided. Note that this will cause a significant reduction of the computing
+speed.
+
+Stacked (binned) analysis
+-------------------------
+The stacked analysis mode is using a binned analysis where all observations are included and stacked into one event cube.
+This analysis mode is much faster than unbinned analysis when having a large dataset (e.g. > 100 hours).
+For this type of binned analysis, some intermediate data products have to be produced. The products are a binned data cube,
+an exposure cube, a PSF cube, and a background cube. 
+
+Bin events
+^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ ctbin
+  Event list or observation definition file [events.fits] selected_obs.xml
+  First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
+  Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
+  Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
+  Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL]
+  Image scale (in degrees/pixel) [0.02]
+  Size of the X axis in pixels [200] 
+  Size of the Y axis in pixels [200]
+  Algorithm for defining energy bins (FILE|LIN|LOG) [LOG]
+  Start value for first energy bin in TeV [0.1] 0.5
+  Stop value for last energy bin in TeV [100.0] 50
+  Number of energy bins [20]
+  Output counts cube [cntcube.fits]
+
+Note that bins only get filled if the bin of the cube is fully contained in the energy range and RoI of a considered observation.
+It is therefore useful to provide the energy range given by :ref:`csiactobs` above. This ensures a maximum agreement between
+observations and binning and reduces the loss of data.
+
+Create exposure cube
+^^^^^^^^^^^^^^^^^^^^
+After binning the events into a three-dimensional cube, an exposure cube has to be computed.
+The exposure is defined as the effective area times the dead-time corrected observation time.
+Each observation from the input container gets stacked in the resulting cube. The exposure is stored
+in units of :math:`cm^2 s`. The exposure cube does not have to contain the same binning as the event cube
+but for simplicity, the event cube can be passed to adopt the binning parameters. Note, however, that the
+exposure cube is defined in true sky coordinates and energy while the counts cube is defined in reconstructed
+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 accommodate for spill over of events due to the point spread function
+and energy dispersion. By computing the exposure cube 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. In the example below, however, no source at the edge of the
+field of view is present. Therefore, for simplicity, the count cube is used as input cube to extract the binning.
+
+This task of computing the exposure cube is is performed by :ref:`ctexpcube`. 
+
+.. code-block:: bash
+
+  $ ctexpcube
+  Event list or observation definition file [NONE] selected_obs.xml
+  Input counts cube file to extract exposure cube definition [NONE] cntcube.fits
+  Output exposure cube file [expcube.fits]
+  
+Alternatively, the exposure cube can be created with different binning than the event cube:
+
+.. code-block:: bash
+
+  $ ctexpcube
+  Input event list or observation definition XML file [NONE] selected_obs.xml 
+  Input counts cube file to extract exposure cube definition [NONE] 
+  First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 
+  Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 
+  Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] 
+  Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] 
+  Image scale (in degrees/pixel) [0.02] 0.04
+  Size of the X axis in pixels [200] 100
+  Size of the Y axis in pixels [200] 100
+  Lower energy limit (TeV) [0.5] 
+  Upper energy limit (TeV) [50.0] 
+  Number of energy bins [20] 30
+  Output exposure cube file [expcube.fits] 
+
+Create PSF cube
+^^^^^^^^^^^^^^^
+As a next step for the binned analysis, a cube containing the point spread function (PSF) must be computed.
+Since the PSF cannot be stored by one single parameter, the PSF cube computed by :ref:`ctpsfcube` has a fourth dimension.
+In each bin of the cube, the PSF is stored as a function of offset from source. The granularity of the
+PSF histogram is determined by the hidden parameter ``anumbins`` (default: 200). Therefore, when passing
+the event cube to adopt the sky binning for the PSF cube, the resulting FITS file can become quite large due to
+the fourth dimension. Usually in IACT analysis, the PSF doesn't change too dramatically across the field of view.
+Therefore the user can think about reducing the spatial binning of the PSF cube:
+
+.. code-block:: bash
+
+  $ ctpsfcube
+  Input event list or observation definition XML file [NONE] selected_obs.xml 
+  Input counts cube file to extract PSF cube definition [NONE] 
+  First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 
+  Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 
+  Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] 
+  Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] 
+  Image scale (in degrees/pixel) [1.0] 0.2
+  Size of the X axis in pixels [10] 20
+  Size of the Y axis in pixels [10] 20
+  Lower energy limit (TeV) [0.1] 0.5
+  Upper energy limit (TeV) [100.0] 50
+  Number of energy bins [20] 
+  Output PSF cube file [psfcube.fits]
+  
+Depending on the required PSF precision, one could reduce the number of offset bins via the hidden parameter
+``anumbins``:
+
+.. code-block:: bash
+
+  $ ctpsfcube anumbins=100
+
+Create background cube
+^^^^^^^^^^^^^^^^^^^^^^
+Last but not least, for a binned IACT analysis a cube containing the background rate in sky coordinates and
+reconstructed energy has to be computed. This task is performed by :ref:`ctbkgcube`. The binning here can also differ
+from the event cube. For simplicity, however, the example below uses the event cube to adopt the binning.
+
+.. code-block:: bash
+
+  $ ctbkgcube debug=yes
+  Input event list or observation definition XML file [NONE] selected_obs.xml 
+  Input counts cube file to extract background cube definition [NONE] cntcube.fits 
+  Input model XML file [NONE] crab_models.xml 
+  Output background cube file [bkgcube.fits] 
+  Output model XML file [NONE] binned_models.xml
+
+Note that this tool also requires the parameters of an input and output model. In the model XML file that came out of
+:ref:`csiactobs`, one background model per observation is included. This models get merged and averaged in the background
+sky cube. In the output model the background models per obseervation will be removed. Instead, a global background model
+for the newly created background cube is included. Sky models present in the input model XML file will also be included in the 
+new XML file, which subsequently can be used for binned :ref:`ctlike`.
+
+Example for stacked model XML file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The output model of :ref:`ctbkgcube` looks the following:
+
+.. code-block:: xml
+
+	<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+	<source_library title="source library">
+	  <source name="BackgroundModel" type="CTACubeBackground" instrument="CTA,HESS,MAGIC,VERITAS">
+	    <spectrum type="PowerLaw">
+	      <parameter name="Prefactor" value="1" error="0" scale="1" min="0.01" max="100" free="1" />
+	      <parameter name="Index" value="0" error="0" scale="1" min="-5" max="5" free="1" />
+	      <parameter name="Scale" value="1" scale="1e+06" free="0" />
+	    </spectrum>
+	  </source>
+	  <source name="Crab" type="PointSource">
+	    <spectrum type="PowerLaw">
+	       <parameter name="Prefactor" scale="1e-17" value="3.0"  min="1e-07" max="1000.0" free="1"/>
+	       <parameter name="Index"     scale="-1"    value="2.48" min="0.0"   max="+5.0"   free="1"/>
+	       <parameter name="Scale"     scale="1e6"   value="1."  min="0.01"  max="1000.0" free="0"/>
+	    </spectrum>
+	    <spatialModel type="SkyDirFunction">
+	      <parameter name="RA"  scale="1.0" value="83.6331" min="-360" max="360" free="0"/>
+	      <parameter name="DEC" scale="1.0" value="22.0145" min="-90"  max="90"  free="0"/>
+	    </spatialModel>
+	  </source>
+	</source_library>
+	
+The background model with ``type=CTACubeBackground`` is used to scale the background cube stored in the FITS file
+created by :ref:`ctbkgcube`.
+
+Run ctlike
+^^^^^^^^^^
+Having all the intermediate data products ready, a binned analysis can be conducted using :ref:`ctlike`.
+
+.. code-block:: bash
+
+  $ ctlike
+  Input event list, counts cube or observation definition XML file [events.fits] cntcube.fits 
+  Input exposure cube file (only needed for stacked analysis) [NONE] expcube.fits 
+  Input PSF cube file (only needed for stacked analysis) [NONE] psfcube.fits 
+  Input background cube file (only needed for stacked analysis) [NONE] bkgcube.fits 
+  Input model XML file [binned_models.xml]
+  Output model XML file [binned_results.xml]
+	
+Note that when passing an event cube to :ref:`ctlike`, the tool behaves differently than in unbinned mode.
+It queries directly for the additional ingredients for the binned analysis. It is important to pass the background model
+generated by :ref:`ctbkgcube` here to ensure the proper modelling of the background in the fit.
+The usage of energy dispersion cannot be included in binned analyses yet. Therefore, the hidden parameter ``edisp=yes``
+has no effect in this case.
+
+
+
+
+.. _sec_copy:
+
+Copying IACT data
+==================
+
+Before you start
+----------------
+Currently the way how IACT data is stored is quite prototypical. The ctools can work
+with IACT data that is stored following the `specifications here <http://gamma-astro-data-formats.readthedocs.org/en/latest/data_storage/index.html>`_.
+The script :ref:`csiactcopy` can be used to transfer these data from one system to another.
+IACT data is the property of collaborations (such as HESS, MAGIC or VERITAS) and not publicly available. If you are member of one of these
+collaborations, you should have access to a central place where the FITS data is stored and maintained.
+
+Mount remote file system
+------------------------
+Note that :ref:`csiactcopy` does not include functionality to establish a conection to a remote file system.
+For the moment, it is capable of copying data from one location to another. Therefore it is necessary to
+mount the remote file system where the data is located on the local machine. This can be achieved using e.g.
+`sshfs <https://github.com/libfuse/sshfs>`_:
+
+.. code-block:: bash
+
+  $ sshfs user@remote.server.com:/path/to/remote/fits/data/ /path/to/mountpoint/
+
+The success of this operation can be verified by checking if there is a file called ``master.json``
+in the mounted directory.
+
+Copy data 
+---------
+After mounting the file system to a folder of your choice (``/path/to/mountpoint/`` in this case), the copying of the data can be initiated.
+To monitor the progress on the screen, the hidden parameter ``debug=yes`` can be used. To increase the chattiness of the output,
+the hidden parameter ``chatter`` can e.g. be set to 3.
+
+.. code-block:: bash
+  
+  $ csiactcopy debug=yes chatter=3
+  Location of remote master file [/path/to/mountpoint/master.json] 
+  Name of FITS production to download [iact-fits]
+  Destination path of FITS data [/path/to/local/fits/data/] 
+  
+The name of the FITS production must be available in the remote 
+``master.json`` file. In case the names of the available productions are unkown
+there are two options to determine an appropriate name:
+
+*  Run :ref:`csiactdata` and set as ``datapath`` the mountpoint
+*  Try any name, :ref:`csiactcopy` will throw a ``RuntimeError`` with the available production names if the input name is not found
+
+Copy only a subset of the data
+------------------------------
+If the user is interested only in a small subset of the remote FITS production,
+it is also possible to download only parts of the data. The user simply has to provide an
+ASCII file containing a list of observation IDs to be downloaded (one ID per line). The hidden
+parameter ``runlist`` then needs to be specified.
+
+.. code-block:: bash
+  
+  $ csiactcopy runlist=myrunlist.txt debug=yes
+  
+Troubleshooting
+---------------
+In case a download was interupted (e.g. the remote file system was disconnected), the script can simply be rerun.
+The index files which list the files available on the system are refreshed after the copying process.
+The hidden boolean parameter ``clobber`` (default=yes) specifies if the user wishes that local content should be overwritten with
+remote content. In turn, specifying ``clobber=no`` can speed up the process since remote content does not need to be copied
+if it is already available on the user machine.
+
+To verify the copying process was successful, it is recommended to run :ref:`csiactdata` after the process in order to list available productions
+on the local machine. The output should now include the copied FITS production name.
+.. _sec_high_level:
+
+High level analysis tools for IACT data
+=======================================
+
+This section describes and explains how to create high level output. The following tools are explained:
+
+* :ref:`csobsinfo` (inspect and observation XML files)
+* :ref:`csmodelinfo` (inspect model XML files)
+* :ref:`ctulimit` (compute upper limits)
+* :ref:`cterror` (compute asymmetric errors)
+* :ref:`csspec` (compute spectral points)
+* :ref:`cslightcrv` (compute a light curve)
+* :ref:`csresmap` (compute a residual map)
+* :ref:`cttsmap` (compute a test statistics map)
+
+Inspecting observation definition files
+---------------------------------------
+After having created an observation definition file, the user might want to know a summary of its content.
+Important quantities usually are the number of observations, the total livetime, or the mean zenith angle.
+For this purpose, :ref:`csobsinfo` inspects an observation XML container for its content.
+
+.. code-block:: bash
+
+  $ csobsinfo
+  Event list, counts cube, or observation definition file [obs.xml] selected_obs.xml 
+  
+This dumps general information of the observation container in a logfile ``csobsinfo.log``.
+For a direct output on the screen, pass the hidden parameter ``debug=yes`` on the command line:
+
+.. code-block:: bash
+
+  $ csobsinfo debug=yes
+  Event list, counts cube, or observation definition file [obs.xml] selected_obs.xml 
+  ...
+  2016-02-19T15:43:08: +=========+
+  2016-02-19T15:43:08: | Summary |
+  2016-02-19T15:43:08: +=========+
+  2016-02-19T15:43:08:  Unbinned observations .....: 4
+  2016-02-19T15:43:08:  Number of events ..........: 6085
+  2016-02-19T15:43:08:  Binned observations .......: 0
+  2016-02-19T15:43:08:  Number of bins ............: 0
+  2016-02-19T15:43:08: 
+  2016-02-19T15:43:08: === Pointings ===
+  2016-02-19T15:43:08:  Mean zenith angle .........: 46.89
+  2016-02-19T15:43:08:  Mean azimuth angle ........: 13.63
+  2016-02-19T15:43:08: 
+  2016-02-19T15:43:08: === Energy range ===
+  2016-02-19T15:43:08:  Emin ......................: 461.48 GeV
+  2016-02-19T15:43:08:  Emax ......................: 37.8832 TeV
+  2016-02-19T15:43:08: 
+  2016-02-19T15:43:08: === Time range ===
+  2016-02-19T15:43:08:  Start [MJD] ...............: 53343.9212153
+  2016-02-19T15:43:08:  Stop [MJD] ................: 53347.9321065
+  2016-02-19T15:43:08:  Total ontime ..............: 6877.00 s = 114.62 min = 1.91 h
+  2016-02-19T15:43:08:  Total livetime ............: 6427.52 s = 107.13 min = 1.79 h
+  ... 
+
+Further options are described on the reference page :ref:`csobsinfo`. 
+
+Inspecting model XML files
+--------------------------
+Similar to the observation containers, model XML file can be inspected, too.
+The tool :ref:`csmodelinfo` gives a summary of the model container. In particular,
+the number of free parameters, number of sky and background models and also number of
+parameters that are at their limits might be of interest.
+
+.. code-block:: bash
+
+  $ csmodelinfo debug=yes
+  Input model XML file [$CTOOLS/share/models/crab.xml] 
+  2016-02-19T15:50:40: +=========+
+  2016-02-19T15:50:40: | Summary |
+  2016-02-19T15:50:40: +=========+
+  2016-02-19T15:50:40: === Instrument specific models ===
+  2016-02-19T15:50:40:  All .......................: 1
+  2016-02-19T15:50:40:  CTA .......................: 1
+  2016-02-19T15:50:40: === Model types ===
+  2016-02-19T15:50:40:  PointSource ...............: 1
+  2016-02-19T15:50:40:  CTAIrfBackground ..........: 1
+  2016-02-19T15:50:40: 
+  2016-02-19T15:50:40: +=======================+
+  2016-02-19T15:50:40: | Parameter information |
+  2016-02-19T15:50:40: +=======================+
+  2016-02-19T15:50:40:  All parameters ............: 10
+  2016-02-19T15:50:40:  Fixed parameters ..........: 6
+  2016-02-19T15:50:40:  Free parameters (total) ...: 4
+  2016-02-19T15:50:40:  Free background parameters : 2
+  2016-02-19T15:50:40:  Free source parameters ....: 2
+  2016-02-19T15:50:40:  Free spectral parameters ..: 2
+  2016-02-19T15:50:40:  Parameters at limit .......: 0
+
+
+Compute upper limit
+-------------------
+Very often in gamma-ray astronomy sources are at the verge of detection or even not detectable.
+In such cases, it is useful to derive an upper limit using :ref:`ctulimit`.
+
+.. code-block:: bash
+
+	$ ctulimit
+	Input event list, counts cube or observation definition XML file [selected_obs.xml]
+	Input model XML file [crab_models.xml]  
+	Source of interest [Crab] 
+	
+The upper limit will be stored in the log file. To get the limit printed on screen, use the hidden parameter
+``debug=yes``.
+
+Compute asymmetric errors
+-------------------------
+When an analysis approaches its final state, it makes sense to have asymmetric errors on the parameters of the
+source of interest. For this purpose, the tool :ref:`cterror` can be used:
+
+.. code-block:: bash
+
+	$ cterror debug=yes
+	Input event list, counts cube or observation definition XML file [selected_obs.xml] 
+	Input model XML file [crab_models.xml] 
+	Source of interest [Crab] 
+	Output model XML file [cterror_results.xml] 
+
+The output model does not contain asymmetric errors yet. The positive and negative uncertainties can be read from the
+logfile (or from screen) if ``debug=yes`` was specified.
+
+Compute spectral points
+-----------------------
+A very common task in astronomy is to compute spectral data points. To determine a spectral data point, a small energy
+range is considered and the model prefactor and its uncertainty is evaluated. The tool :ref:`csspec` works on both, binned
+and unbinned data. 
+
+Unbinned
+^^^^^^^^
+
+.. code-block:: bash
+
+	$ csspec debug=yes
+	Input event list, counts cube, or observation definition XML file [events.fits] selected_obs.xml 
+	Input model XML file [$CTOOLS/share/models/crab.xml] crab_models.xml 
+	Source name [Crab] 
+	Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] 
+	Lower energy limit for spectral points (TeV) [0.1] 0.5
+	Upper energy limit for spectral points (TeV) [100.0] 50.0
+	Number of spectral points (1-10000) [20] 10
+	Output spectrum file [spectrum.fits] 
+	
+Binned
+^^^^^^
+
+.. code-block:: bash
+
+	$ csspec debug=yes
+	Input event list, counts cube, or observation definition XML file [cntcube.fits] 
+	Input exposure cube file (only needed for stacked analysis) [expcube.fits] 
+	Input PSF cube file (only needed for stacked analysis) [psfcube.fits] 
+	Input background cube file (only needed for stacked analysis) [bkgcube.fits] 
+	Input model XML file [binned_models.xml] 
+	Source name [Crab] 
+	Number of spectral points (1-10000) [10] 
+	Lower energy limit for spectral points (TeV) [0.5] 
+	Upper energy limit for spectral points (TeV) [50.0] 
+	Output spectrum file [spectrum.fits] 
+
+
+Plot spectral points
+^^^^^^^^^^^^^^^^^^^^
+Instead of supporting a plotting library, simple example scripts are available to visualise data products.
+Have a look at ``$CTOOLS/examples/show_spectrum.py`` how a spectrum can be plotted using ``matplotlib``.
+To have first glance at the above computed spectrum one can use this script in the following way:
+
+.. code-block:: bash
+  
+  $ python $CTOOLS/examples/show_spectrum.py spectrum.fits
+
+
+Compute light curves
+--------------------
+Euqally common in astronomy are light curves from a time-series analysis. The tool :ref:`cslightcrv` takes as input only
+an unbinned observation container (or a single event list). Counts cube are not possible as inout since the time informstion
+is lost during the binning procedure. Nevertheless, in case of large time bins, it is possible to require a binned analysis
+in each time bin. The tool will accordingly slice the event list and create the data products for the stacked analysis in each
+time span.
+
+.. code-block:: bash
+
+	$ cslightcrv
+	Input event list, counts cube, or observation definition XML file [selected_obs.xml]
+	Input model XML file [crab_models.xml]  
+	Source name [Crab] 
+	Algorithm for defining time bins (FILE|LIN|GTI) [GTI] 
+	Number of energy bins per light curve bin (0=unbinned) [0] 
+	Lower energy limit of events (TeV) [0.1] 0.5
+	Upper energy limit of events (TeV) [100.0] 50
+	Output light curve file [lightcurve.fits]  
+
+Compute a residual map
+----------------------
+A frequent means to visually inspect the fitted model with respect to the input data is to create residual maps.
+Using :ref:`csresmap` such a map can easily be computed. The tool internally bins the data according to user parameters.
+(if data is not already provided in a binned state). Taking into account the corresponding IRFs,
+:reF:`csresmap` computes a model map (running :ref:`ctmodel`). Subsequently, there are several choices how data
+and model should be compared. There are three options:
+
+* ``SUB``: the subtraction of the model from the counts. The resulting map will display differences in absolute counts.
+* ``SUBDIV``: the subtraction and division by the model. The resulting map will display relative differences of the data with respect to the model.
+* ``SUBDIVSQRT``: the subtraction and division by the square root of the model. The resulting map will display an approximation of a residual significance map. In case of sufficient count statistic per bin, the bin value represents the significance. 
+
+Example unbinned observation container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+	$ csresmap
+	Input event list, counts cube, or observation definition XML file [selected_obs.xml]
+	Input model XML file [crab_results.xml]
+	First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 
+	Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 
+	Coordinate System (CEL|GAL) [CEL] 
+	Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] 
+	Size of the X axis in pixels [100]
+	Size of the Y axis in pixels [100]
+	Pixel size (deg/pixel) [0.02]
+	Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUBDIV]
+	Output residual map file [resmap.fits] 
+
+Example binned/stacked observation container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The tool behaves differently if the input observation parameter is a count cube. It will query for the additional binned reponse components.
+
+.. code-block:: bash
+
+	$ csresmap 
+	Input event list, counts cube, or observation definition XML file [cntcube.fits]
+	Input model cube file (generated with ctmodel) [NONE] 
+	Input exposure cube file (only needed for stacked analysis) [expcube.fits]
+	Input PSF cube file (only needed for stacked analysis) [psfcube.fits]  
+	Input background cube file (only needed for stacked analysis) [bkgcube.fits] 
+	Input model XML file [binned_results.xml] 
+	Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUBDIV] 
+	Output residual map file [resmap.fits] 
+	
+Note that the tool also queries for an input model cube file (which we set to ``NONE`` here). This is very convenient in case the model cube has already been precomputed
+using :ref:`ctmodel`.
+
+Example with input model cube
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In case a model cube can be provided, :ref:`csresmap` simply collapses both cube into one skymap and applies the specified algorithm.
+
+.. code-block:: bash
+
+	$ csresmap
+	Input event list, counts cube, or observation definition XML file [cntcube.fits]
+	Input model cube file (generated with ctmodel) [modcube.fits] 
+	Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUB] 
+	Output residual map file [resmap.fits] 
+
+
+Compute a test statistics (TS) map
+----------------------------------
+The test statistics quantity is a more precise measurement of statistic than the ``SUBDIVSQRT`` option in :ref:`csresmap`. 
+To get familiar with the concept of this procedure, :ref:`read more about TS maps <sec_tsmap>`.
+
+.. code-block:: bash
+
+	$ cttsmap
+	Input event list, counts cube or observation definition XML file [selected_obs.xml]  
+	Input model XML file [crab_results.xml] 
+	Test source name [Crab] 
+	First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 
+	Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 
+	Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] 
+	Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] 
+	Image scale (in degrees/pixel) [0.05]
+	Size of the X axis in pixels [20]
+	Size of the Y axis in pixels [20]
+	Output Test Statistic map file [tsmap.fits] 
+
+The output file will contain a sky map holding the TS map. In complementary extensions, for each free parameter of the source model, a map displaying the parameter
+value is added to the output file. For instance a map of the prefactor can be visualised with `DS9 <http://ds9.si.edu/>`_ as follows:
+
+.. code-block:: bash
+  
+  $ ds9 tsmap.fits[Prefactor] 
+
+Since :ref:`cttsmap` has to run a parameter optimisation in each skymap bin, it is very time comsuming to
+compute a fine-granulated TS sky map. Read here how to split up the :ref:`computation into several jobs <sec_tips>`. 
+Similar as many other tools :ref:`cttsmap` can also work on binned observation input:
+
+.. code-block:: bash
+  
+	$ cttsmap debug=yes
+	Input event list, counts cube or observation definition XML file [cntcube.fits]
+	Input exposure cube file (only needed for stacked analysis) [expcube.fits] 
+	Input PSF cube file (only needed for stacked analysis) [psfcube.fits] 
+	Input background cube file (only needed for stacked analysis) [bkgcube.fits] 
+	Input model XML file [binned_results.xml] 
+	Test source name [Crab] 
+	First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 
+	Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 
+	Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] 
+	Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] 
+	Image scale (in degrees/pixel) [0.05] 
+	Size of the X axis in pixels [20] 
+	Size of the Y axis in pixels [20] 
+	Output Test Statistic map file [tsmap.fits] 
+
+	
 \ No newline at end of file
+Analysing current IACT data
+===========================
+
+.. toctree::
+   :maxdepth: 2
+
+   copy
+   analysis
+   high_level
+   simulation
+   tips
+
+.. _sec_simulation:
+
+Simulating IACT data
+====================
+This section describes how to run simulations with current IACT data. In particular, a guide how to simulate data for a given set of IRFs, or a given set of
+observations is provided. In addition, tools to compute sensitivity curves or pull distributions are presented.
+All tools are based on the event list simulator :ref:`ctobssim`.
+
+Simulations for a specific observation container 
+------------------------------------------------
+On default, :ref:`ctobssim` builds a new observation container by querying relevant user parameters. In case
+an observation XML container is already in place, the hidden parameter ``inobs`` can be specified (:ref:`see here how to create an
+observation container <sec_analysis>`). It might be useful to run :ref:`ctselect` beforehand to ensure that the simulation knows about
+energy thresholds, field of view, etc. If an unselected observation container is used, the simulation tool will query for global energy
+boundaries and a global RoI radius. The following example illustrates the usage of an already selected observation container.
+
+.. code-block:: bash
+ 
+	$ ctobssim inobs=selected_obs.xml
+	Input model XML file [crab_models.xml] 
+	Output event data file or observation definition XML file [sim_obs.xml] 
+	
+Note that :ref:`ctobssim` writes a new event list file per observation into the current directory. If the observation container
+is large, it might be convenient to create a new folder and specify the ``prefix`` keyword (similar to :ref:`ctselect`):
+
+.. code-block:: bash
+  
+  $ mkdir simulated
+  $ ctobssim inobs=selected_obs.xml prefix=simulated/sim_events_
+  ...
+  
+The newly created observation container can be used in the same way as a normal observation container, i.e. it can be analysed with
+:ref:`ctlike` etc. 
+
+.. note::
+
+	On default, :ref:`ctobssim` uses the same seed in every execution, i.e. the tool will always return the same simulated event list, regardless
+	when, where and how it was executed. To steer this the user can provide the hidden integer parameter ``seed``:
+	
+	.. code-block:: bash
+	
+		$ ctobssim inobs=selected_obs.xml seed=2
+  
+  This might be important if simulations are run in parallel.
+
+Simulating observation time for a given set of IRFs
+---------------------------------------------------
+There are other use cases to run simulations, for instance when there is no observation container available yet. This might be the case e.g
+for an observation proposal: one would want to use a certain set of IRFs to simulate e.g. 50 hours of data to check whether a source
+of interest can be detected. For this purpose it is necessary to first find a set of suitable IRFs to be used for
+simulations. This can be easily done using :ref:`csfindobs` and using the ``expression`` parameter. The following example extracts
+observations with at a certain zenith angle range (20-25 degrees) and azimuth angle range (90-100 degrees):
+
+.. code-block:: bash
+	
+	$ csfindobs expression="AZ_PNT>90.0&&AZ_PNT<100.0&&ZEN_PNT>20.0&&ZEN_PNT<25.0"
+	Name of FITS production (Run csiactdata to view your options) [fits-prod-name]
+	Right ascension [83.6331] NONE
+	Runlist outfile [zen20_az90.lis]
+	
+Of course, further details could be specified, e.g. one might want to check for a certain range of muon efficieny, or any other parameter which impacts IRFs.
+The output runlist subsequently has to be converted to an observation XML file using :ref:`csiactobs` (:ref:`see here how to execute this tool <sec_analysis>`).
+In the following it is assumed that the observation XML file of the selected representative observations is produced and called ``myobs.xml``.
+
+Create caldb entry
+^^^^^^^^^^^^^^^^^^
+Now, one of the observations in this container have to be added to the local calibration database. This database is used
+by ctools to extract IRFs for simulations.
+
+.. code-block:: bash
+
+	$ csobs2caldb
+	Input observation definition file [myobs.xml] 
+	Response output name (e.g. Zenith50) [zen20_az90] 
+	
+Note that the response name has been specified to "zen20_az90". Any name can be chosen which represents the observation which was inserted into the database.
+On default, :ref:`csobs2caldb` uses the first observation in the provided XML file. This can be modifyied by specifying the hidden integer parameter index, e.g.:
+
+.. code-block:: bash
+
+  $ csobs2caldb index=1
+  
+This would use the second entry instead of the first from the observation container to extract the IRFs.
+
+.. note::
+
+  The ``index`` parameter starts counting from zero.  
+
+Check caldb entries
+^^^^^^^^^^^^^^^^^^^
+In order to check if the calibration database has successfully been added, the tool :ref:`cscaldb` can be used to inspect the calibration database:
+
+.. code-block:: bash
+
+	$ cscaldb debug=yes
+	...
+	2016-02-25T15:57:11: +==============+
+	2016-02-25T15:57:11: | Mission: cta |
+	2016-02-25T15:57:11: +==============+
+	2016-02-25T15:57:11: === Response functions in database "hess" ===
+	2016-02-25T15:57:11: zen20_az90
+	2016-02-25T15:57:11: 
+	2016-02-25T15:57:11: === Response functions in database "prod2" ===
+	2016-02-25T15:57:11: North_0.5h
+	2016-02-25T15:57:11: North_50h
+	2016-02-25T15:57:11: North_5h
+	2016-02-25T15:57:11: South_0.5h
+	2016-02-25T15:57:11: South_50h
+	2016-02-25T15:57:11: South_5h
+	...
+
+Note that the observation of the actual instrument ("hess" in this example) was added to the CTA mission. This is mainly for structural and simplicity reasons
+and might be improved eventually. Nevertheless, this caldb entry can now be used to simulate any observation duration.
+
+Simulate
+^^^^^^^^
+
+.. code-block:: bash
+  
+	$ ctobssim
+	RA of pointing (degrees) (0-360) [83.63] 
+	Dec of pointing (degrees) (-90-90) [22.01] 
+	Radius of FOV (degrees) (0-180) [2.5] 
+	Start time (MET in s) [0.0] 
+	End time (MET in s) [18000.0] 
+	Lower energy limit (TeV) [0.5] 
+	Upper energy limit (TeV) [50] 
+	Calibration database [hess] 
+	Instrument response function [zen20_az90] 
+	Input model XML file [input_model.xml] 
+	Output event data file or observation definition XML file [simulated_events.fits]
+	
+Here, a total duration of 5 hours at the crab position was simulated using the newly created caldb entry. Note that the choice of the energy range is up to the user.
+One should bear in mind that simulations only make sense in energy ranges where the IRFs are well-defined. The simulation
+assumes one observation of defined duration here. Accordingly, only one FITS event list is written as output. The input XML model
+must now contain only one background model and (of course) all sky models that are needed. Here is an example of an input model
+e.g. for the Crab Nebula:
+
+.. code-block:: xml
+
+	<?xml version="1.0" standalone="no"?>
+	<source_library title="source library">
+	  <source name="Crab" type="PointSource">
+	    <spectrum type="PowerLaw">
+	       <parameter name="Prefactor" scale="1e-17" value="3.5"  min="1e-07" max="1000.0" free="1"/>
+	       <parameter name="Index"     scale="-1"    value="2.5"  min="0.0"   max="+5.0"   free="1"/>
+	       <parameter name="Scale"     scale="1e6"   value="1.0"  min="0.01"  max="1000.0" free="0"/>
+	    </spectrum>
+	    <spatialModel type="SkyDirFunction">
+	      <parameter name="RA"  scale="1.0" value="83.6331" min="-360" max="360" free="0"/>
+	      <parameter name="DEC" scale="1.0" value="22.0145" min="-90"  max="90"  free="0"/>
+	    </spatialModel>
+	  </source>
+	  <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
+	    <spectrum type="PowerLaw">	
+	      <parameter name="Prefactor" scale="1.0"  value="1.0"  min="1e-3" max="1e+3"   free="1"/>	
+	      <parameter name="Index"     scale="1.0"  value="0.0"  min="-5.0" max="+5.0"   free="1"/>	
+	      <parameter name="Scale"     scale="1e6"  value="1.0"  min="0.01" max="1000.0" free="0"/>	
+	    </spectrum>
+	  </source>	
+	</source_library>
+
+Note that since the caldb entry (:ref:`csobs2caldb`) has been produced under the mission "CTA", the event list is now considered a CTA observation (regardless of the input instrument).
+Therefore, it is important to have "CTA" specified in the instrument attribute of the background model XML component. Of course the addition of any sky model can be
+done without a problem.
+
+The output of this kind of simulation is a single FITS event list file that can be used for further analysis.
+For instance one could run :ref:`ctlike` in the following way:
+
+.. code-block:: bash
+
+	$ ctlike
+	Input event list, counts cube or observation definition XML file [simulated_events.fits] 
+	Calibration database [hess] 
+	Instrument response function [zen20_az90] 
+	Input model XML file [input_model.xml] 
+	Output model XML file [simulated_fit_results.xml] 
+	
+Note that :ref:`ctlike` automatically queries for the IRF database in case no full observation container is provided. Any other tool taking
+unbinned observations as input will behave the same way. Now all means to run simulations with current IACTs are at hand.
+The following sections will describe tools for running higher level simulation analysis.
+
+Create pull distributions
+-------------------------
+Pull distributions inspect the capability of the science tools to find source parameters in the data that were injected into the simulations.
+The tool :ref:`cspull` will run several times the sequence of simulating and fitting the data. After each sequence, the pull value of the
+fitted parameters is written into an ASCII file. The pull value ``p`` of parameter ``X`` is defined as follows:
+
+.. math::
+  p = \frac{X_{\rm fitted} - X_{\rm true}}{\Delta X_{\rm fitted}}
+  
+Where :math:`\Delta X_{\rm fitted}` is the derived error of the fitted parameter :math:`X_{\rm fitted}`. After several trials, the pull value should follow
+a normal distribution. Knowing this, the tool may help to distinguish if a source is detectable and can be normally reconstructed.
+The tool can either work on an input observation container or on the caldb entry that was created above. The number of trials is queried by the tool, too.
+
+Example: observation container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+	$ cspull inobs=selected_obs.xml 
+	Number of energy bins (0=unbinned) [0] 
+	Input model XML file [crab_results.xml] 
+	Output pull distribution file [pull.dat] 
+	Number of trials [100] 
+
+Note that the tool asks for the energy binning. It will use an unbinned analysis if zero bins are provided. Otherwise
+it will query for binning parameters and will convert the simulated observations into a binned/stacked observation by running
+:ref:`ctbin`, :ref:`ctexpcube`, :ref:`ctpsfcube` and :ref:`ctbkgcube` in order before fitting the simulated data with :ref:`ctlike`.
+
+Example: caldb entry
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+	$ cspull
+	RA of pointing (deg) (0-360) [83.6331] 
+	Dec of pointing (deg) (-90-90) [22.0145] 
+	Duration (in s) [18000.0] 
+	Lower energy limit (TeV) [0.5]
+	Upper energy limit (TeV) [50]
+	Calibration database [hess] 
+	Instrument response function [zen20_az90] 
+	Number of energy bins (0=unbinned) [0]
+	Input model XML file [input_models.xml] 
+	Output pull distribution file [pull.dat] 
+	Number of trials [100] 
+
+Again, the caldb entry ``zen20_az90`` which was created above is used to simulate 5 hours of data. The data is simulated and analysed 100
+times in a row and the output is written into the file ``pull.dat``.
+
+Visualise pull distributions
+----------------------------
+The output ASCII file of :ref:`cspull` can be inspected by the user using own scripts. As a starting point, the ``example`` folder
+contains a script that can be used to visualise the pull distribution histogram:
+
+.. code-block:: bash
+
+	$ python $CTOOLS/examples/show_pull_histogram.py pull.dat Pull_Crab_Prefactor 50
+
+Run the script without arguments to see the usage. In case a wrong parameter name was provided, the tool will print available parameters on the screen.
+The last integer parameter defines the binning of the histogram. In addition, the tool shows the standard normal distribution which should
+match the pull distribution for a high number of trials if everything went well.
+
+Create sensitivity curve
+------------------------
+A very important means to illustrate if a source can be detected with a certain significance is a sensitivity curve.
+The tool :ref:`cssens` can be used to compute either an integral, or a differential sensitivity curve for a given observation container.
+Analogous to :ref:`cspull`, the tool works either on an unbinned observation container or using a caldb entry. 
+The script :ref:`cssens` computes the differential or integrated CTA sensitivity using maximum likelihood fitting of a test source.
+The differential sensitivity is determined for a number of energy bins, the integral sensitivity is determined for a number
+of energy thresholds. The test source is fitted to simulated data using ctlike to determine it’s detection significance as a
+function of source flux. The source flux is then varied until the source significance achieves a given level, specified by the 
+(hidden) significance parameter ``sigma``. To damp variations between individual Monte Carlo simulations, a sliding average is
+applied in the significance computation (controlled by hidden ``num_avg parameter``). Note that this procedure might take a while to compute.
+To switch from diffferential to integral sensitivity, the hidden parameter ``type="Integral"`` has to be specified. It should be noted that
+the results are written to a file ``sensitivity.dat``. To change the output file name, the hidden parameter ``outfile=mysensitivity.dat``
+can be provided.
+
+
+Example: observation container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+	$ cssens inobs=selected_obs.xml
+	Input model XML file [crab_results.xml] 
+	Source name [Crab] 
+	Lower energy limit (TeV) [0.5] 
+	Upper energy limit (TeV) [50] 
+	Number of energy bins for differential sensitivity computation [21] 
+
+Example: caldb entry
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+	$ cssens 
+	Calibration database [hess] 
+	Instrument response function [zen20_az90] 
+	Effective exposure time (s) [18000.0] 
+	Radius of ROI (deg) [2.5] 
+	Input model XML file [input_models.xml] 
+	Source name [Crab] 
+	Lower energy limit (TeV) [0.5] 
+	Upper energy limit (TeV) [50] 
+	Number of energy bins for differential sensitivity computation [21]
+	
+Note that the input model in the latter case only requires to contain one background model (see section above). Using this setup,
+the user can specify the observation time for the sensitivity curve. In this example, again, 5 hours are used.
+
+Visualise sensitivity curves
+----------------------------
+In order to show a sensitivity curve, there is also a script in the example folder:
+
+.. code-block:: bash
+
+	$ python $CTOOLS/examples/show_sensitivity.py sensitivity.dat
+	
+This will display a sensitivity curve for the applied settings.
+.. _sec_tips:
+
+Tips, Tricks and FAQs
+=====================
+This section shows some of the wrinkles that could fascilitate the users' life when running IACT analyses.
+
+Visualise observations
+----------------------
+A very common task is to inspect the observation container and visualise several quantities.
+
+Create a skymap of counts
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The tool :ref:`ctskymap` allows to create a single map of counts contained inside an observation container.
+In contrast to :ref:`ctbin`, ctskymap takes into account all events that fall into the skymap energy range and spatial range.
+Since :ref:`ctbin` is intended for binned/stacked analysis, it respects energy thresholds, RoI selections etc.
+Accordingly, :ref:`ctskymap` should be used for a simple visualisation of the counts.
+
+
+.. code-block:: bash
+
+	$ ctskymap debug=yes
+	Input event list or observation definition XML file [events.fits] obs.xml 
+	Lower energy limit (TeV) [0.1] 
+	Upper energy limit (TeV) [100.0] 
+	First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 
+	Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 
+	Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] 
+	Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] 
+	Image scale (in degrees/pixel) [0.02] 
+	Size of the X axis in pixels [200] 
+	Size of the Y axis in pixels [200] 
+	Output skymap file [skymap.fits] 
+	
+Create region file of pointings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In particular, one might want to know how the pointings of the observation container distribute across the sky.
+For this purpose, :ref:`csobsinfo` provides the hidden parameter ``ds9file`` which signals to produce a region file that
+contains these information:
+
+.. code-block:: bash
+
+	$ csobsinfo ds9file=pointings.reg debug=yes
+	Event list, counts cube, or observation definition file [obs.xml] 
+	
+Together with the previously produced skymap, one can plot the pointings using e.g. ds9:
+
+.. code-block:: bash
+  
+  $ ds9 skymap.fits -regions pointings.reg
+
+Plot zenith angle distribution of observations
+----------------------------------------------
+The tool :ref:`csobsinfo` dumps more information into the log file. Some of them might be of interest to catch in a script.
+Therefore, one could simply use this tool via python and plot some distributions:
+
+.. code-block:: python
+
+  # Run script
+  import cscripts
+  info = cscripts.csobsinfo()
+  info["inobs"] = "selected_obs.xml"
+  info.run()
+  
+  # Plot data
+  import matplotlib.pyplot as plt
+  plt.hist(info.zeniths(), bins=10, range=[0,90])
+  plt.show()
+  
+This will plot a histogram showing the zenith angle distribution of the observation container. In addition there are more methods
+to access information in python:
+
+.. code-block:: python
+
+  # csobsinfo can also return:
+  info.azimuths() # list of azimuth values
+  info.offsets()  # list of offset values (only computed if hidden parameter offset=yes was specified)
+  info.ebounds()  # gammalib.GEbounds object of energy ranges
+  info.gti()      # gammalib.GGti object containing good time intervals 
+  
+
+Visualise models
+----------------
+Similar to :ref:`csobsinfo`, there is :ref:`csmodelinfo` to find out more about the content of a model XML file. In order to show the
+position and sizes of the model on top of a skymap, this tool has the hidden parameter ``ds9file``, too.
+
+.. code-block:: bash
+
+	csmodelinfo ds9file=models.reg debug=yes
+	Input model XML file [$CTOOLS/share/models/crab.xml]
+
+There are several options regarding the color, text and other attributes of the region file. To see a full list, 
+:ref:`visit the reference page <csmodelinfo>`.
+Analogous to the pointings of the observation container, the models can be visualised using e.g. ds9:
+
+.. code-block:: bash
+  
+  $ ds9 skymap.fits -regions models.reg
+
+Manipulating models in python
+-----------------------------
+This step will give some guidance how to work with model XML files in python and how to manipulate their content
+
+.. code-block:: python
+
+	import gammalib
+	
+	# Open model file
+	models = gammalib.GModels("$CTOOLS/share/models/crab.xml")
+	
+	# Access a model component
+	src = models["Crab"]
+	print(src)
+	
+	# Retrieve the spectral or spatial component
+	print(src.spectral())
+	print(src.spatial())
+	
+	# Print the spectral parameter "Prefactor"
+	prefactor = src.spectral()["Prefactor"]
+	print("Prefactor: "+str(prefactor.value())+" +- "+str(prefactor.error()))
+	
+	# Set the prefactor value
+	prefactor.value(3.5e-17)
+	
+	# Loop over models and fix all parameters
+	for model in models:
+		
+		# Loop over model parameters
+		for par in model:
+			
+			# Fix parameter
+			par.fix()
+	
+	# Release one specific parameter
+	models["Crab"]["Prefactor"].free()
+	
+	# Set the parameter range
+	models["Crab"]["Prefactor"].min(1e-18)
+	models["Crab"]["Prefactor"].max(1e-16)
+	
+	# ... or in one step:
+	models["Crab"]["Prefactor"].range(1e-18, 1e-16)
+	
+	# Remove model from container
+	models.remove("Crab")
+	
+	# Save model to another XML file
+	models.save("mymodels.xml")
+  
+
+Retrieve likelihood values from :ref:`ctlike`
+---------------------------------------------
+For some purposes, it might be useful to retrieve the fitted likelihood value and other results of the fit with :ref:`ctlike`.
+
+.. code-block:: python
+
+	import gammalib
+	import ctools
+	
+	# Create ctlike
+	like = ctools.ctlike()
+	like["inobs"]   = "selected_obs.xml"
+	like["inmodel"] = "mymodels.xml"
+	like.run()
+	
+	# Get optimizer from ctlike
+	opt = like.opt()
+	print(opt)
+	
+	# Get likelihood value from optimizer
+	print(opt.value())
+	
+	# Get fit status:
+	print(opt.status())
+	# 0: converged
+	# 1: stalled
+	# 2: singular curvature matrix encountered
+	# 3: curvature matrix not positive definite
+	# 4: errors are inaccurate
+
+Speed up analysis
+-----------------
+In some cases it may occur that the analysis takes very long. There are several reasons that can slow down the analysis quite severly.
+Not all issues can be tackled. Nevertheless, here is a list of actions that have proven to speed up the fit.
+
+* Consider switching to binned analysis if the observation time exceeds 50-100 hours.
+* Diffuse and extended sources in the RoI are computational expensive. However, in unbinned analysis they impact the speed much more.
+* Usage of energy dispersion in unbinned analysis could also cause a long fit. Try switching it off if speed is important.
+* Switch to a machine that supports OpenMP. This allows to parallelise the fit onto several cores.
+
+Compute excess maps
+-------------------
+A very important means to visualise images of sources are excess maps. The tool :ref:`csresmap` can also be used to create such a map.
+The user, however, has to manually remove the source(s) of interest from the input model XML file.
+
+.. code-block:: python
+
+  import gammalib
+  models = gammalib.GModels("crab_models.xml")
+  models.remove("Crab")
+  models.save("models_without_crab.xml")
+  
+Of course, this can also be done by editing the XML file with an editor.
+
+Subsequently, :ref:`csresmap` can be executed using the ``algorithm=SUB`` parameter:
+
+.. code-block:: bash
+
+	$ csresmap
+	Input event list, counts cube, or observation definition XML file [selected_obs.xml]
+	Input model XML file [models_without_crab.xml]
+	First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 
+	Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 
+	Coordinate System (CEL|GAL) [CEL] 
+	Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] 
+	Size of the X axis in pixels [100]
+	Size of the Y axis in pixels [100]
+	Pixel size (deg/pixel) [0.02]
+	Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUB]
+	Output residual map file [excessmap.fits] 
+
+
+Compute flux maps
+-----------------
+The creation of a flux map is much more expensive in terms of computing than an excess map. In the section about
+:ref:`high level analysis tools <sec_high_level>`, the usage of :ref:`cttsmap` was demonstrated. This tool can also
+be used to generate flux maps. For this, the user has to incoorporate a test source in the XML model file. This source
+should consist of a spectral component using a PowerLaw2 model:
+
+.. code-block:: xml
+
+	<source name="TestSource" type="PointSource">
+	 <spectrum type="PowerLaw2">
+	  <parameter scale="1e-07" name="Integral"   min="1e-07" max="1000.0"    value="1.0" free="1"/>
+	  <parameter scale="1.0"   name="Index"      min="-5.0"  max="+5.0"      value="-2.0" free="1"/>
+	  <parameter scale="1.0"   name="LowerLimit" min="10.0"  max="1000000.0" value="100.0" free="0"/>
+	  <parameter scale="1.0"   name="UpperLimit" min="10.0"  max="1000000.0" value="500000.0" free="0"/>
+	 </spectrum>
+	 <spatialModel type="SkyDirFunction">
+	  <parameter free="0" max="360" min="-360" name="RA" scale="1" value="83.6331" />
+	  <parameter free="0" max="90" min="-90" name="DEC" scale="1" value="22.0145" />
+	 </spatialModel>
+	</source>
+
+The further content of the rest of the XML model file depends on the user requirements:
+
+* For an absolute flux map, all other sky models should be removed
+* For a residual flux map, all other sky models should be kept
+
+The tool :ref:`cttsmap` will create one skymap per free spectral parameter in the model. In the result FITS file,
+there will be an extension called "Integral" that contains the flux map. For the above XML example, the source name
+"TestSource" should be specified to :ref:`cttsmap`.
+
+Speed up TS map computation
+---------------------------
+Since the computation of a TS map can be extremely time consuming, the option of splitting the computation into several jobs
+is supported. This might be of particular interest if the user has access to a batch farm.
+
+Split TS map computation
+^^^^^^^^^^^^^^^^^^^^^^^^
+For the purpose of job splitting, the hidden parameter ``binmin`` and ``binmax`` were included in the tool. These are integer parameter
+that specify which bins should be computed. For instance, if the map should consist of 30x30(=900) pixels, the user could e.g. execute
+
+.. code-block:: bash
+
+	$ cttsmap binmin=0 binmax=299 outmap=tsmap_0_299.fits
+	...
+	$ cttsmap binmin=300 binmax=599 outmap=tsmap_300_599.fits
+	...
+	$ cttsmap binmin=600 binmax=899 outmap=tsmap_600_899.fits
+	...
+	
+Each command could run on a different machine.
+
+.. note::
+
+  The output file name of individual jobs should be different. Otherwise files could overwrite each other. The naming of the individual slices
+  is up to the user.
+  
+Merge sliced TS maps
+^^^^^^^^^^^^^^^^^^^^
+The tool :ref:`cstsmapmerge` is intended to take care of merging the files that were produced while splitting the TS map computation.
+There are several options to pass the files to be merged as arguments:
+
+* a space-separated list of file names (e.g. tsmap1.fits tsmap2.fits)
+* a comma-separated list of file names (e.g. tsmap1.fits,tsmap2.fits)
+* a wildcard string (e.g. tsmap*.xml)
+* an ASCII file containing the file names, one file per line (e.g. @mymaps.txt)
+
+In this example the ASCII file method is presented:
+
+.. code-block:: bash 
+
+	# Put slice files into an ascii file
+	$ ls tsmap_*.fits > tsmapfiles.txt
+	
+	# Run cstsmapmerge
+	$ cstsmapmerge
+	Input TS map FITS files [@tsmapfiles.txt]
+	Output TS map FITS file [mytsmap.fits]
+
+
+Creating a python analysis pipeline
+-----------------------------------
+It is easily possible to build an own analysis workflow with a simple python script. The following source code example shows a python script
+running from gathering observations until fitting spectral points without storing intermediate data products on disk. It assumes that the
+environment variable ``$VHEFITS`` is set to the path where IACT FITS data is located.
+
+.. code-block:: python
+  
+	import gammalib
+	import ctools
+	import cscripts
+	
+	# Set debug flag
+	debug = True
+	
+	# Set flag to use energy dispersion
+	edisp = False
+	
+	# Set inmodel file name
+	inmodel = "$GAMMALIB/test/data/model_point_plaw.xml"
+	
+	# Expand environment variable
+	inmodel = gammalib.expand_env(inmodel)
+	
+	# Extract coordinates and model properties
+	models  = gammalib.GModels(inmodel)
+	srcname = models[0].name()
+	ra      = models[0]["RA"].value()
+	dec     = models[0]["DEC"].value()
+	
+	# Find FITS production name
+	iactdata          = cscripts.csiactdata()
+	iactdata["debug"] = debug
+	iactdata.run()
+	
+	# Use first available production
+	prodname = iactdata.names()[0]
+	
+	# Run csfindobs
+	findobs             = cscripts.csfindobs()
+	findobs["ra"]       = ra
+	findobs["dec"]      = dec
+	findobs["rad"]      = 2.5
+	findobs["prodname"] = prodname
+	findobs["debug"]    = debug
+	findobs["outfile"]  = "NONE"
+	findobs.run()
+	
+	# Retrieve obervation IDs (runlist)
+	obs_ids = findobs.obs_ids()
+	
+	# Build observation container
+	iactobs             = cscripts.csiactobs()
+	iactobs["prodname"] = prodname
+	iactobs["inmodel"]  = inmodel
+	iactobs["bkgpars"]  = 1
+	iactobs["outobs"]   = "NONE"
+	iactobs["outmodel"] = "NONE"	
+	iactobs["debug"]    = debug
+	iactobs.runlist(obs_ids)
+	iactobs.run()
+	
+	# Retrieve observation container and energy boundaries
+	obs     = iactobs.obs()
+	ebounds = iactobs.ebounds()
+	
+	# Run ctselect
+	select             = ctools.ctselect(obs)
+	select["usepnt"]   = True
+	select["rad"]      = 2.5
+	select["usethres"] = "DEFAULT"
+	select["tmin"]     = 0.0
+	select["tmax"]     = 0.0
+	select["emin"]     = 0.1
+	select["emax"]     = 100.0
+	select["debug"]    = debug
+	select.run()
+	
+	# Pass selected observations to ctlike
+	like          = ctools.ctlike(select.obs())
+	like["debug"] = debug
+	like["edisp"] = edisp
+	like.run()
+	
+	# Compute a spectrum and save
+	spec             = cscripts.csspec(like.obs())
+	spec["srcname"]  = srcname
+	spec["emin"]     = ebounds.emin().TeV()
+	spec["emax"]     = ebounds.emax().TeV()
+	spec["enumbins"] = 10
+	spec["edisp"]    = edisp
+	spec["ebinalg"]  = "LOG"
+	spec["debug"]    = debug
+	spec["outfile"]  = "spectrum.fits"
+	spec.execute()
+	
+	# Remove model for excess map computation
+	like.obs().models().remove(srcname)
+	
+	# Compute an excess map
+	resmap             = cscripts.csresmap(like.obs())
+	resmap["xref"]     = ra
+	resmap["yref"]     = dec
+	resmap["proj"]     = "CAR"
+	resmap["coordsys"] = "CEL"
+	resmap["emin"]     = ebounds.emin().TeV()
+	resmap["emax"]     = ebounds.emax().TeV()
+	resmap["nxpix"]    = 100
+	resmap["nypix"]    = 100
+	resmap["binsz"]    = 0.02
+	resmap["outmap"]   = "excessmap.fits"
+	resmap.execute()
+
+The results of this analysis workflow can be inspected using an example python script and e.g. ds9:
+
+.. code-block:: bash
+  
+  $ python $CTOOLS/examples/show_spectrum.py spectrum.fits
+  $ ds9 excessmap.fits
+  
 \ No newline at end of file
@@ -8,6 +8,7 @@ User Manual
    introduction
    getting
    getting_started/index
+   iact_analysis/index
    plotting
    glossary