diff --git a/doc/source/fhelp/ctbutterfly.html b/doc/source/fhelp/ctbutterfly.html new file mode 100644 index 0000000..f170cd6 --- /dev/null +++ b/doc/source/fhelp/ctbutterfly.html @@ -0,0 +1,300 @@ + + +ctbutterfly + + + + + + +

ctbutterfly

+

Butterfly calculation tool.

+
+

Synopsis

+

Calculates +the confidence band of a spectral model, taking into account the +covariance matrix of a likelihood fit. +

+
+

Links

+ +

+
+

General parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 infile +[file]
  XML or fits file that defines the observation
   
 srcmdl +[file]
  Model XML file containing the source and background definitions
   
 srcname + [file]
  Name of model for which butterfly should be computed
   
 caldb + [string]
  Calibration database repository.
   
 irf + [string]
  Instrumental response function that + should be used for event generation.
   
 outfile + [file]
  Output butterfly file name
   
 (matrix = "NONE") + [file]
  Input covariance matrix file (not used)
   
 emin + [double]
  Minimum energy of butterfly (in + TeV).
   
 emax + [double]
  Maximum energy of butterfly (in + TeV).
   
 (ebinalg + = "LOG") <FILE|LIN|LOG> + [string]
  Butterfly binning algorithm
   
 (enumbins + = 100) + [string]
  Number of energy bins of butterfly
   
 (ebinfile + = "NONE") + [string]
  File for energy binning algorithm
   
+

Standard parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 (chatter += 2) [integer]
  Verbosity of the executable:
+chatter = 0: no information will be +logged
+chatter = 1: only errors will be logged
+chatter = 2: errors and actions will be +logged
+chatter = 3: report about the task +execution
+chatter = 4: detailed report about the +task execution
   
 (clobber += yes) [boolean]
  Specifies whether an existing output +event list should be overwritten.
   
 (debug += no) [boolean]
  Enables debug mode. In debug mode +the executable will dump any log file output in the console.
   
 (mode += ql) [string]
  Mode of automatic parameters.
   
+
+

Related FTOOLS

+
+
+

Last updated by: Michael +Mayer 30 October +2014 +

+
+ \ No newline at end of file diff --git a/doc/source/tools_reference.rst b/doc/source/tools_reference.rst index 6a9903b..082a6e8 100644 --- a/doc/source/tools_reference.rst +++ b/doc/source/tools_reference.rst @@ -14,6 +14,7 @@ ctools * `ctobssim `__ --- Observation simulator. * `ctselect `__ --- Performs sub-selections of event data which are needed for unbinned maximum likelihood analysis. * `ctskymap `__ --- Computes sky map from CTA data. +* `ctbutterfly `__ --- Computes a butterfly from a spectral model. cscripts -------- diff --git a/doc/source/user_manual/getting_started/butterfly.jpg b/doc/source/user_manual/getting_started/butterfly.jpg new file mode 100644 index 0000000..814edc1 --- /dev/null +++ b/doc/source/user_manual/getting_started/butterfly.jpg diff --git a/doc/source/user_manual/getting_started/quickstart.rst b/doc/source/user_manual/getting_started/quickstart.rst index edc0d2e..fcc93fd 100644 --- a/doc/source/user_manual/getting_started/quickstart.rst +++ b/doc/source/user_manual/getting_started/quickstart.rst @@ -19,6 +19,8 @@ The example consists of the following analysis steps: - :ref:`sec_unbinned_cta` +- :ref:`sec_butterfly_cta` + .. _sec_simulating_cta: @@ -638,3 +640,64 @@ the same events for both analyses. 2014-01-09T21:47:54: +==============+ 2014-01-09T21:47:54: 2014-01-09T21:47:54: Application "ctlike" terminated after 6 wall clock seconds, consuming 0.163384 seconds of CPU time. + + + .. _sec_butterfly_cta: + +Calculate and visualise butterfly +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To visualise the analysis results retrieved above, one can calculate the +confidence band of the spectral fit. The tool ctbutterfly takes the optimised +source model as input. It takes the covariance matrix from the fit to conduct a +Gaussian error propagation for each energy value. It will write the +butterfly information into an ASCII file. +The following example shows how to compute such a butterfly from the command +line. + +.. code-block:: bash + + $ ctbutterfly + Input event list, cube or observation definition file [$CTOOLS/test/data/crab_events.fits.gz] + Calibration database [share/caldb/data/cta/dummy//cta_dummy_irf] share/caldb/data/cta/dummy/bcf/ + Instrument response function [cta_dummy_irf] + Source model [$CTOOLS/test/data/crab.xml] + Source of interest [CrabNebula] Crab + Start value for first energy bin in TeV [0.1] + Stop value for last energy bin in TeV [100.] + Output ascii file [butterfly.txt] + +Below some lines of the ``ctbutterfly.log``: + +.. code-block:: xml + + 2014-10-30T17:51:39: +===========================+ + 2014-10-30T17:51:39: | Compute covariance matrix | + 2014-10-30T17:51:39: +===========================+ + 2014-10-30T17:51:39: + 2014-10-30T17:51:39: +====================+ + 2014-10-30T17:51:39: | Generate butterfly | + 2014-10-30T17:51:39: +====================+ + 2014-10-30T17:51:39: + 2014-10-30T17:51:39: +========================+ + 2014-10-30T17:51:39: | Save Butterfly to file | + 2014-10-30T17:51:39: +========================+ + 2014-10-30T17:51:39: + 2014-10-30T17:51:39: Application "ctbutterfly" terminated after 15 wall clock seconds, consuming 0.051253 seconds of CPU time. + +Now that you have computed the confidence band of the spectral fit and +that you will have an ASCII file named ``butterfly.txt'' on disk you can +visualise the butterfly using the script ``show_butterfly.py'' that is +in the ctools ``example'' folder. You will need matplotlib on your system +to make this work. To launch the script, type: + +.. code-block:: bash + python $CTOOLS/examples/python/show_butterfly.py butterfly.txt + +This will result in a canvas which should look like the following: + +.. figure:: butterfly.jpg + :width: 60% + + *Confidence band of the fit* + \ No newline at end of file diff --git a/examples/Makefile.am b/examples/Makefile.am index 0a76710..819671c 100644 --- a/examples/Makefile.am +++ b/examples/Makefile.am @@ -7,7 +7,8 @@ scripts = README \ make_ts_distributions.py \ make_unbinned_analysis.py \ show_pull_histogram.py \ - show_ts_distribution.py + show_ts_distribution.py \ + show_butterfly # Set directories scriptsdir = $(datadir)/examples/python diff --git a/examples/show_butterfly.py b/examples/show_butterfly.py new file mode 100644 index 0000000..1f522a7 --- /dev/null +++ b/examples/show_butterfly.py @@ -0,0 +1,76 @@ +#! /usr/bin/env python +# ========================================================================== +# This script shows how to plot a butterfly created with ctbutterfly +# +# Copyright (C) 2014 Michael Mayer +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +# +# ========================================================================== + +import gammalib +import sys +try: + import matplotlib.pyplot as plt +except: + sys.exit("This script needs matplotlib") + +# =============== # +# Script entry # +# =============== # +if __name__ == "__main__": + + # check for given butterfly file + if not len(sys.argv) == 2: + sys.exit("Usage: show_butterfly.py butterfly.txt") + + # Read given butterfly file + filename = sys.argv[1] + csv = gammalib.GCsv(filename) + + # initialise arrays to be filled + butterfly_x = [] + butterfly_y = [] + + line_x = [] + line_y = [] + + # loop over rows of the file + nrows = csv.nrows() + for row in range(nrows): + # Compute upper edge of confidence band + butterfly_x.append(csv.real(row,0)) + butterfly_y.append(csv.real(row,1)+csv.real(row,2)) + + # Set line values + line_x.append(csv.real(row,0)) + line_y.append(csv.real(row,1)) + + # Loop over the rows backwards to compute the lower edge + # of the confidence band + for row in range(nrows): + index = nrows - 1 - row + + butterfly_x.append(csv.real(index,0)) + butterfly_y.append(csv.real(index,1)-csv.real(index,2)) + + # plot the butterfly and spectral line + plt.figure() + plt.loglog() + plt.grid() + plt.plot(line_x,line_y,color='black',ls='-') + plt.fill(butterfly_x,butterfly_y,color='green',alpha=0.5) + plt.xlabel("Energy [MeV]") + plt.ylabel(r"dN/dE [MeV$^{-1}$ s$^{-1}$ cm$^{-2}$]") + plt.show() \ No newline at end of file