Added simulation part of the documentation

Michael Mayer
1 parent cd6bebbf
Showing 4 changed files with 557 additions and 22 deletions
doc/source/user_manual/iact_analysis/analysis.rst
doc/source/user_manual/iact_analysis/high_level.rst
doc/source/user_manual/iact_analysis/simulation.rst
doc/source/user_manual/iact_analysis/tips.rst
@@ -74,10 +74,10 @@ For this purpose one can simply pass an invalid coordinate to :ref:`csfindobs`.
 The selection by region will simply be omitted.
-Note
-^^^^
-On default, :ref:`csfindobs` only select data of highest quality (i.e. QUALITY=0). Specifying the hidden parameter e.g. ``min_qual=1``
-allows to select all data with looser quality criteria.
+.. note::
+
+	On default, :ref:`csfindobs` only select data of highest quality (i.e. QUALITY=0). Specifying the hidden parameter e.g. ``min_qual=1``
+	allows to select all data with looser quality criteria.
 Create an observation list
 --------------------------
@@ -219,7 +219,7 @@ Example unbinned observation container
 	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]
+	Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUBDIV]
 	Output residual map file [resmap.fits] 
 Example binned/stacked observation container
@@ -235,7 +235,7 @@ The tool behaves differently if the input observation parameter is a count cube.
 	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) [SUB] 
+	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
@@ -2,29 +2,299 @@
 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
-Create sensitiviy curve
------------------------
+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
-----------------------------
 \ No newline at end of file
+----------------------------
+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.
@@ -2,39 +2,304 @@
 Tips, Tricks and FAQs
 =====================
+This section shows some of the wrinkles that could fascilitate the users' life when running 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 indended 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
+	Parfile "csobsinfo.par" not found. Create default parfile.
+	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 that 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
+	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:",prefactor.value(),"+-",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.
-Create count map with one energy bin
-------------------------------------
+* 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 map
-------------------
+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] 
-Split TS map computation
-------------------------
 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>
-Accessing fit parameters in python
-----------------------------------
+The further content of the rest of the XML model file depends on the user requirements:
-Accessing upper limits in python
---------------------------------
+* For an absolute flux map, all other sky models should be removed
+* For a residual flux map, all other sky models should be kept
-Manipulate models in python
+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 =90 pixels, the use could e.g. execute
+
+.. code-block:: bash
+
+	$ cttsmap binmin=0 binmax=299
+	...
+	$ cttsmap binmin=300 binmax=599
+	...
+	$ cttsmap binmin=600 binmax=899
+	...
+	
+on different machines.
+
+.. note::
+
+  The output file name of individual jobs can be the same. If the parameters are specified, the output file name will be appended by the suffix
+  "_<binmin>_<binmax>" to distinguish between the sliced TS maps.
+  
+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
 -----------------------------------
 \ No newline at end of file