Simon Bonnefoy / ctools

Commit a4a41902c10b0f650226daf461c773b8c3096e7e

Authored by Jürgen Knödlseder
2 parents 4065b3d9 b1ae56cb

Merge branch 'release' into devel 

# Conflicts:
#	ChangeLog
#	NEWS
#	doc/source/reference_manual/cscaldb.rst
Inline Side-by-side
Showing 80 changed files with 2155 additions and 1636 deletions
ChangeLog
  View file @a4a4190
... ... @@ -7,11 +7,12 @@
7 7 Add csobs2caldb script (#1579)
8 8  
9 9  
10   -2015-11-19 Juergen Knoedlseder <jurgen.knodlseder@irap.omp.eu>
  10 +2015-12-07 Juergen Knoedlseder <jurgen.knodlseder@irap.omp.eu>
11 11  
12 12 * Version 1.0.0 released
13 13 ========================
14 14  
  15 + Update end-user documentation
15 16 Implement handling of stacked data in csspec (#1566)
16 17 Resolve Python test problem on El Capitan (#1563)
17 18  
... ...
... ... @@ -2,7 +2,7 @@ New Features and Important Changes in ctools 1.1.0
2 2  
3 3 Author(s) : Juergen Knoedlseder
4 4  
5   -24 November 2015
  5 +7 December 2015
6 6  
7 7  
8 8 1. Introduction
... ...
cscripts/cslightcrv.py
  View file @a4a4190
... ... @@ -98,15 +98,15 @@ class cslightcrv(ctools.cscript):
98 98  
99 99 # Create default parfile
100 100 pars = gammalib.GApplicationPars()
101   - pars.append(gammalib.GApplicationPar("inobs","f","a","events.fits","","","Event list, counts cube, or observation definition file"))
102   - pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Source model"))
  101 + pars.append(gammalib.GApplicationPar("inobs","f","a","events.fits","","","Input event list, counts cube, or observation definition XML file"))
  102 + pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Input model XML file"))
103 103 pars.append(gammalib.GApplicationPar("srcname","s","a","Crab","","","Source name"))
104   - pars.append(gammalib.GApplicationPar("outfile","f","a","lightcurve.fits","","","Output file name"))
105   - pars.append(gammalib.GApplicationPar("expcube","f","a","NONE","","","Exposure cube file (only needed for stacked analysis)"))
106   - pars.append(gammalib.GApplicationPar("psfcube","f","a","NONE","","","PSF cube file (only needed for stacked analysis)"))
107   - pars.append(gammalib.GApplicationPar("bkgcube","s","a","NONE","","","Background cube file (only needed for stacked analysis)"))
  104 + pars.append(gammalib.GApplicationPar("expcube","f","a","NONE","","","Input exposure cube file (only needed for stacked analysis)"))
  105 + pars.append(gammalib.GApplicationPar("psfcube","f","a","NONE","","","Input PSF cube file (only needed for stacked analysis)"))
  106 + pars.append(gammalib.GApplicationPar("bkgcube","s","a","NONE","","","Input background cube file (only needed for stacked analysis)"))
108 107 pars.append(gammalib.GApplicationPar("caldb","s","a","prod2","","","Calibration database"))
109   - pars.append(gammalib.GApplicationPar("irf","s","a","South_50h","","","Instrument response function"))
  108 + pars.append(gammalib.GApplicationPar("irf","s","a","South_0.5h","","","Instrument response function"))
  109 + pars.append(gammalib.GApplicationPar("outfile","f","a","lightcurve.fits","","","Output light curve file"))
110 110 pars.append(gammalib.GApplicationPar("tbinalg","s","a","GTI","FILE|LIN|GTI","", "Algorithm for defining time bins"))
111 111 pars.append(gammalib.GApplicationPar("tmin","r","a","51544.5","","days","Lightcurve start time [MJD]"))
112 112 pars.append(gammalib.GApplicationPar("tmax","r","a","51544.6","","days","Lightcurve stop time [MJD]"))
... ...
cscripts/csobsdef.py
  View file @a4a4190
... ... @@ -128,8 +128,8 @@ class csobsdef(ctools.cscript):
128 128  
129 129 # Create default parfile
130 130 pars = gammalib.GApplicationPars()
131   - pars.append(gammalib.GApplicationPar("inpnt","f","a","NONE","","","Pointing definition file"))
132   - pars.append(gammalib.GApplicationPar("outobs","f","a","obs.xml","","","Output observation definition file"))
  131 + pars.append(gammalib.GApplicationPar("inpnt","f","a","NONE","","","Input pointing definition file"))
  132 + pars.append(gammalib.GApplicationPar("outobs","f","a","obs.xml","","","Output observation definition XML file"))
133 133 pars.append(gammalib.GApplicationPar("duration","r","a","1800.0","","","Pointing duration (seconds)"))
134 134 pars.append(gammalib.GApplicationPar("caldb","s","h","","","","Calibration database"))
135 135 pars.append(gammalib.GApplicationPar("irf","s","h","","","","Instrument response function"))
... ...
cscripts/cspull.py
  View file @a4a4190
... ... @@ -101,13 +101,13 @@ class cspull(ctools.cscript):
101 101  
102 102 # Create default parfile
103 103 pars = gammalib.GApplicationPars()
104   - pars.append(gammalib.GApplicationPar("inobs","f","h","NONE","","","Event list, counts cube, or observation definition file"))
105   - pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Source model"))
106   - pars.append(gammalib.GApplicationPar("outfile","f","a","pull.dat","","","Output file name"))
  104 + pars.append(gammalib.GApplicationPar("inobs","f","h","NONE","","","Input event list, counts cube, or observation definition XML file"))
  105 + pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Input model XML file"))
107 106 pars.append(gammalib.GApplicationPar("caldb","s","a","prod2","","","Calibration database"))
108   - pars.append(gammalib.GApplicationPar("irf","s","a","South_50h","","","Instrument response function"))
109   - pars.append(gammalib.GApplicationPar("deadc","r","h","0.95","0","1","Deadtime correction factor"))
  107 + pars.append(gammalib.GApplicationPar("irf","s","a","South_0.5h","","","Instrument response function"))
110 108 pars.append(gammalib.GApplicationPar("edisp","b","h","no","","","Apply energy dispersion?"))
  109 + pars.append(gammalib.GApplicationPar("deadc","r","h","0.95","0","1","Deadtime correction factor"))
  110 + pars.append(gammalib.GApplicationPar("outfile","f","a","pull.dat","","","Output pull distribution file"))
111 111 pars.append(gammalib.GApplicationPar("profile","b","h","no","","","Use likelihood profile method for errors?"))
112 112 pars.append(gammalib.GApplicationPar("ntrials","i","a","10","","","Number of trials"))
113 113 pars.append(gammalib.GApplicationPar("ra","r","a","83.6331","0","360","RA of pointing (deg)"))
... ...
cscripts/csresmap.py
  View file @a4a4190
... ... @@ -103,16 +103,16 @@ class csresmap(ctools.cscript):
103 103  
104 104 # Create default parfile
105 105 pars = gammalib.GApplicationPars()
106   - pars.append(gammalib.GApplicationPar("inobs","f","a","events.fits","","","Event list, counts cube, or observation definition file"))
107   - pars.append(gammalib.GApplicationPar("modcube","f","a","NONE","","","Model cube file (generated with ctmodel)"))
108   - pars.append(gammalib.GApplicationPar("expcube","f","a","NONE","","","Exposure cube file (only needed for stacked analysis)"))
109   - pars.append(gammalib.GApplicationPar("psfcube","f","a","NONE","","","PSF cube file (only needed for stacked analysis)"))
110   - pars.append(gammalib.GApplicationPar("bkgcube","f","a","NONE","","","Background cube file (only needed for stacked analysis)"))
111   - pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Source model"))
112   - pars.append(gammalib.GApplicationPar("outmap","f","a","resmap.fits","","","Output residual map"))
113   - pars.append(gammalib.GApplicationPar("edisp","b","h","no","","","Apply energy dispersion?"))
  106 + pars.append(gammalib.GApplicationPar("inobs","f","a","events.fits","","","Input event list, counts cube, or observation definition XML file"))
  107 + pars.append(gammalib.GApplicationPar("modcube","f","a","NONE","","","Input model cube file (generated with ctmodel)"))
  108 + pars.append(gammalib.GApplicationPar("expcube","f","a","NONE","","","Input exposure cube file (only needed for stacked analysis)"))
  109 + pars.append(gammalib.GApplicationPar("psfcube","f","a","NONE","","","Input PSF cube file (only needed for stacked analysis)"))
  110 + pars.append(gammalib.GApplicationPar("bkgcube","f","a","NONE","","","Input background cube file (only needed for stacked analysis)"))
  111 + pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Input model XML file"))
114 112 pars.append(gammalib.GApplicationPar("caldb","s","a","prod2","","","Calibration database"))
115   - pars.append(gammalib.GApplicationPar("irf","s","a","South_50h","","","Instrument response function"))
  113 + pars.append(gammalib.GApplicationPar("irf","s","a","South_0.5h","","","Instrument response function"))
  114 + pars.append(gammalib.GApplicationPar("edisp","b","h","no","","","Apply energy dispersion?"))
  115 + pars.append(gammalib.GApplicationPar("outmap","f","a","resmap.fits","","","Output residual map file"))
116 116 pars.append(gammalib.GApplicationPar("ebinalg","s","h","LOG","LIN|LOG|FILE","","Binning algorithm"))
117 117 pars.append(gammalib.GApplicationPar("emin","r","h","0.1","","","Lower energy limit (TeV)"))
118 118 pars.append(gammalib.GApplicationPar("emax","r","h","100.0","","","Upper energy limit (TeV)"))
... ...
cscripts/cssens.py
  View file @a4a4190
... ... @@ -97,14 +97,14 @@ class cssens(ctools.cscript):
97 97  
98 98 # Create default parfile
99 99 pars = gammalib.GApplicationPars()
100   - pars.append(gammalib.GApplicationPar("inobs","f","h","NONE","","","Event list, counts cube, or observation definition file"))
101   - pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Source model"))
  100 + pars.append(gammalib.GApplicationPar("inobs","f","h","NONE","","","Input event list, counts cube, or observation definition XML file"))
  101 + pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Input model XML file"))
102 102 pars.append(gammalib.GApplicationPar("srcname","s","a","Crab","","","Source name"))
103   - pars.append(gammalib.GApplicationPar("offset","r","h","0.0","","","Source offset angle (deg)"))
104 103 pars.append(gammalib.GApplicationPar("caldb","s","a","prod2","","","Calibration database"))
105   - pars.append(gammalib.GApplicationPar("irf","s","a","South_50h","","","Instrument response function"))
  104 + pars.append(gammalib.GApplicationPar("irf","s","a","South_0.5h","","","Instrument response function"))
106 105 pars.append(gammalib.GApplicationPar("deadc","r","h","0.95","0","1","Deadtime correction factor"))
107   - pars.append(gammalib.GApplicationPar("outfile","f","h","sensitivity.dat","","","Output file name"))
  106 + pars.append(gammalib.GApplicationPar("outfile","f","h","sensitivity.dat","","","Output sensitivity ASCII file"))
  107 + pars.append(gammalib.GApplicationPar("offset","r","h","0.0","","","Source offset angle (deg)"))
108 108 pars.append(gammalib.GApplicationPar("duration","r","a","180000.0","","","Effective exposure time (s)"))
109 109 pars.append(gammalib.GApplicationPar("rad","r","a","5.0","","","Radius of ROI (deg)"))
110 110 pars.append(gammalib.GApplicationPar("edisp","b","h","no","","","Apply energy dispersion?"))
... ...
cscripts/csspec.py
  View file @a4a4190
... ... @@ -100,16 +100,16 @@ class csspec(ctools.cscript):
100 100  
101 101 # Create default parfile
102 102 pars = gammalib.GApplicationPars()
103   - pars.append(gammalib.GApplicationPar("inobs","f","a","events.fits","","","Event list, counts cube, or observation definition file"))
104   - pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Source model"))
  103 + pars.append(gammalib.GApplicationPar("inobs","f","a","events.fits","","","Input event list, counts cube, or observation definition XML file"))
  104 + pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Input model XML file"))
105 105 pars.append(gammalib.GApplicationPar("srcname","s","a","Crab","","","Source name"))
106   - pars.append(gammalib.GApplicationPar("outfile","f","a","spectrum.fits","","","Output file name"))
107   - pars.append(gammalib.GApplicationPar("expcube","f","a","NONE","","","Exposure cube file (only needed for stacked analysis)"))
108   - pars.append(gammalib.GApplicationPar("psfcube","f","a","NONE","","","PSF cube file (only needed for stacked analysis)"))
109   - pars.append(gammalib.GApplicationPar("bkgcube","f","a","NONE","","","Background cube file (only needed for stacked analysis)"))
  106 + pars.append(gammalib.GApplicationPar("expcube","f","a","NONE","","","Input exposure cube file (only needed for stacked analysis)"))
  107 + pars.append(gammalib.GApplicationPar("psfcube","f","a","NONE","","","Input PSF cube file (only needed for stacked analysis)"))
  108 + pars.append(gammalib.GApplicationPar("bkgcube","f","a","NONE","","","Input background cube file (only needed for stacked analysis)"))
110 109 pars.append(gammalib.GApplicationPar("caldb","s","a","prod2","","","Calibration database"))
111   - pars.append(gammalib.GApplicationPar("irf","s","a","South_50h","","","Instrument response function"))
  110 + pars.append(gammalib.GApplicationPar("irf","s","a","South_0.5h","","","Instrument response function"))
112 111 pars.append(gammalib.GApplicationPar("edisp","b","h","no","","","Apply energy dispersion?"))
  112 + pars.append(gammalib.GApplicationPar("outfile","f","a","spectrum.fits","","","Output spectrum file"))
113 113 pars.append(gammalib.GApplicationPar("emin","r","a","0.1","","","Lower energy limit for spectral points (TeV)"))
114 114 pars.append(gammalib.GApplicationPar("emax","r","a","100.0","","","Upper energy limit for spectral points (TeV)"))
115 115 pars.append(gammalib.GApplicationPar("enumbins","i","a","20","1","10000","Number of spectral points"))
... ...
cscripts/cstsdist.py
  View file @a4a4190
... ... @@ -94,17 +94,17 @@ class cstsdist(ctools.cscript):
94 94  
95 95 # Create default parfile
96 96 pars = gammalib.GApplicationPars()
97   - pars.append(gammalib.GApplicationPar("inobs","f","h","NONE","","","Event list, counts cube, or observation definition file"))
98   - pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Source model"))
  97 + pars.append(gammalib.GApplicationPar("inobs","f","h","NONE","","","Input event list, counts cube, or observation definition XML file"))
  98 + pars.append(gammalib.GApplicationPar("inmodel","f","a","$CTOOLS/share/models/crab.xml","","","Input model XML file"))
99 99 pars.append(gammalib.GApplicationPar("srcname","s","a","Crab","","","Source name"))
100   - pars.append(gammalib.GApplicationPar("outfile","f","a","ts.dat","","","Output file name"))
101   - pars.append(gammalib.GApplicationPar("expcube","s","a","NONE","","","Exposure cube file (only needed for stacked analysis)"))
102   - pars.append(gammalib.GApplicationPar("psfcube","s","a","NONE","","","PSF cube file (only needed for stacked analysis)"))
103   - pars.append(gammalib.GApplicationPar("bkgcube","s","a","NONE","","","Background cube file (only needed for stacked analysis)"))
  100 + pars.append(gammalib.GApplicationPar("expcube","s","a","NONE","","","Input exposure cube file (only needed for stacked analysis)"))
  101 + pars.append(gammalib.GApplicationPar("psfcube","s","a","NONE","","","Input PSF cube file (only needed for stacked analysis)"))
  102 + pars.append(gammalib.GApplicationPar("bkgcube","s","a","NONE","","","Input background cube file (only needed for stacked analysis)"))
104 103 pars.append(gammalib.GApplicationPar("caldb","s","a","prod2","","","Calibration database"))
105   - pars.append(gammalib.GApplicationPar("irf","s","a","South_50h","","","Instrument response function"))
  104 + pars.append(gammalib.GApplicationPar("irf","s","a","South_0.5h","","","Instrument response function"))
106 105 pars.append(gammalib.GApplicationPar("deadc","r","h","0.95","","","Deadtime correction factor"))
107 106 pars.append(gammalib.GApplicationPar("edisp","b","h","no","","","Apply energy dispersion?"))
  107 + pars.append(gammalib.GApplicationPar("outfile","f","a","ts.dat","","","Output Test Statistics distribution file"))
108 108 pars.append(gammalib.GApplicationPar("ntrials","i","a","10","","","Number of trials"))
109 109 pars.append(gammalib.GApplicationPar("ra","r","a","83.63","0","360","RA of pointing (deg)"))
110 110 pars.append(gammalib.GApplicationPar("dec","r","a","22.01","-90","90","Dec of pointing (deg)"))
... ...
doc/source/develop.rst
  View file @a4a4190
... ... @@ -8,12 +8,12 @@ to the development.
8 8 Contributions can come in any areas: writing C++ code, contributing Python
9 9 scripts, writing documentation, testing code, etc.
10 10  
11   -The ctools development is managed by a development platform that is
12   -accessible at `<https://cta-redmine.irap.omp.eu/projects/ctools/>`_.
  11 +The ctools software development is managed by a
  12 +`Redmine <https://cta-redmine.irap.omp.eu/projects/ctools/>`_ platform.
13 13 Please check out the
14 14 `Wiki <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Contributing_to_ctools>`_
15   -on that platform that contains information on how to contribute to the
16   -ctools development.
  15 +on that platform to learn how you can contribute to the ctools software
  16 +development.
17 17  
18 18 You may also want to get in the ctools information flow by subscribing to
19 19 the ctools@irap.omp.eu mailing list.
... ... @@ -24,5 +24,5 @@ to allow newcomers to get familiar with the code base and the coding
24 24 practices.
25 25 You are highly invited to join one of the next coding sprints.
26 26  
27   -You can also follow `@gammalib <https://twitter.com/gammalib>`_ on
28   -twitter to get informed about new release of GammaLib and ctools.
29 27 \ No newline at end of file
  28 +You can also follow `@ctools_software <https://twitter.com/ctools_software>`_ on
  29 +twitter to get informed about new ctools releases.
30 30 \ No newline at end of file
... ...
doc/source/download.rst
  View file @a4a4190
... ... @@ -13,7 +13,7 @@ bugs.
13 13 Releases
14 14 --------
15 15  
16   -The latest ctools release is ``ctools-0.10.0`` (1 November 2015).
  16 +The latest ctools release is ``ctools-1.0.0`` (6 December 2015).
17 17  
18 18 Below a table of ctools releases. Please note that at this stage of the
19 19 project there is a strict link between the ctools and gammalib versions.
... ... @@ -28,6 +28,9 @@ gammalib.
28 28 * - `ctools <http://cta.irap.omp.eu/ctools/releases/ctools/ChangeLog>`_
29 29 - `gammalib <http://cta.irap.omp.eu/ctools/releases/gammalib/ChangeLog>`_
30 30 - Mac OS X package
  31 + * - `1.0.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.0.0.tar.gz>`_
  32 + - `1.0.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.0.0.tar.gz>`_
  33 + - `ctools-1.0.0-macosx10.3.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.0.0-macosx10.3.dmg>`_
31 34 * - `0.10.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0.tar.gz>`_
32 35 - `0.11.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz>`_
33 36 - `ctools-0.10.0-macosx10.3.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0-macosx10.3.dmg>`_
... ...
doc/source/help.rst
  View file @a4a4190
... ... @@ -3,8 +3,44 @@
3 3 Getting Help
4 4 ============
5 5  
6   -Any questions, bug reports, or suggested enhancements related to
7   -ctools should be submitted via the
8   -`issue tracker <https://cta-redmine.irap.omp.eu/projects/ctools/issues/new>`_
9   -or the
10   -`mailing list <mailto:ctools@irap.omp.eu>`_.
11 6 \ No newline at end of file
  7 +If you need help you should first check the
  8 +:ref:`Frequently Asked Questions <faq>` and the list of
  9 +:ref:`Known Issues <issues>`.
  10 +In case that you do not find an answer to your question you may post your
  11 +question on the ctools@irap.omp.eu mailing list.
  12 +To subscribe to this list you simply need to send an e-mail to
  13 +ctools-subscribe@irap.omp.eu (content is irrelevant).
  14 +
  15 +You can also use the `Redmine <https://cta-redmine.irap.omp.eu/projects/ctools>`_
  16 +system that we use for the ctools software development management to ask for
  17 +support, report a bug, or request a new feature. To use the system you
  18 +will first need to
  19 +`register <https://cta-redmine.irap.omp.eu/account/register>`_.
  20 +
  21 +Once registered, you can sign-in and ask for support by creating a
  22 +`support issue <https://cta-redmine.irap.omp.eu/projects/ctools/issues/new>`_.
  23 +Specify ``Support`` as Tracker, choose a short and meaningful subject,
  24 +and add an exhaustive description of your request.
  25 +
  26 +If you find a bug you should first check the
  27 +`list of bugs <https://cta-redmine.irap.omp.eu/projects/ctools/issues?utf8=?&set_filter=1&f%5B%5D=status_id&op%5Bstatus_id%5D=*&f%5B%5D=tracker_id&op%5Btracker_id%5D=%3D&v%5Btracker_id%5D%5B%5D=1&f%5B%5D=&c%5B%5D=tracker&c%5B%5D=status&c%5B%5D=priority&c%5B%5D=subject&c%5B%5D=assigned_to&c%5B%5D=updated_on&c%5B%5D=fixed_version&c%5B%5D=done_ratio&group_by=>`_
  28 +to see whether your bug is already known. If the bug is known, you may edit
  29 +the issue and add some information (e.g. a log file, screen shot, etc.).
  30 +If the bug is not yet known, please create a
  31 +`bug issue <https://cta-redmine.irap.omp.eu/projects/ctools/issues/new>`_.
  32 +Specify ``Bug`` as Tracker, provide a short and meaningful subject, and add
  33 +an exhaustive description of the bug. Include the ctools software version,
  34 +your operating system, and the conditions under which the bug occurred. Ideally
  35 +you should provide all files and the command sequence (or a script) that
  36 +will allow us to reproduce the bug.
  37 +
  38 +If you would like to suggest some enhancements to ctools you should create
  39 +a
  40 +`feature issue <https://cta-redmine.irap.omp.eu/projects/ctools/issues/new>`_.
  41 +Specify ``Feature`` as Tracker, choose a short and meaningful subject,
  42 +and add an exhaustive description of your feature request.
  43 +Also explain the motivation for your request and provide some hint on how
  44 +urgently you need the new feature.
  45 +
  46 +You may click on ``Watch`` in the top-right corner of the issue page to make sure
  47 +that you will receive an e-mail notification when the issue is updated.
12 48 \ No newline at end of file
... ...
doc/source/reference_manual/cscaldb.rst
  View file @a4a4190
1   -.. _cscaldb: cscaldb ======= Dumps all available instrument response functions into log file. Synopsis -------- This scripts dumps all instrument response functions that are available in the calibration database into the log file. If you want the information on the screen, add the ``debug=yes`` parameter. General parameters ------------------ None 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 counts cube should be overwritten. ``(debug = no) [boolean]`` Enables debug mode. In debug mode the executable will dump any log file output to the console. ``(mode = ql) [string]`` Mode of automatic parameters (default is "ql", i.e. "query and learn"). Related tools ------------- None
2 1 \ No newline at end of file
  2 +.. _cscaldb:
  3 +
  4 +cscaldb
  5 +=======
  6 +
  7 +Dumps all available instrument response functions into log file.
  8 +
  9 +
  10 +Synopsis
  11 +--------
  12 +
  13 +This scripts dumps all instrument response functions that are available
  14 +in the calibration database into the log file. If you want the information
  15 +on the screen, add the ``debug=yes`` parameter.
  16 +
  17 +
  18 +General parameters
  19 +------------------
  20 +
  21 +None
  22 +
  23 +
  24 +Standard parameters
  25 +-------------------
  26 +
  27 +``(chatter = 2) [integer]``
  28 + Verbosity of the executable:
  29 + chatter = 0: no information will be logged
  30 +
  31 + chatter = 1: only errors will be logged
  32 +
  33 + chatter = 2: errors and actions will be logged
  34 +
  35 + chatter = 3: report about the task execution
  36 +
  37 + chatter = 4: detailed report about the task execution
  38 +
  39 +``(clobber = yes) [boolean]``
  40 + Specifies whether an existing output counts cube should be overwritten.
  41 +
  42 +``(debug = no) [boolean]``
  43 + Enables debug mode. In debug mode the executable will dump any log file output to the console.
  44 +
  45 +``(mode = ql) [string]``
  46 + Mode of automatic parameters (default is "ql", i.e. "query and learn").
  47 +
  48 +
  49 +Related tools of scripts
  50 +------------------------
  51 +
  52 +None
... ...
doc/source/reference_manual/csobsdef.rst
  View file @a4a4190
... ... @@ -46,8 +46,8 @@ Here some usage examples:
46 46 Creates observation definition file with a ROI radius of 5 deg.
47 47  
48 48 ``csobsdef caldb=prod2 irf=South_50h``
49   - Creates observation definition file using the "South_50h" IRF in the
50   - "prod2" calibration database.
  49 + Creates observation definition file using the ``South_50h`` IRF in the
  50 + ``prod2`` calibration database.
51 51  
52 52  
53 53 General parameters
... ...
doc/source/reference_manual/ctbin.rst
  View file @a4a4190
... ... @@ -3,18 +3,27 @@
3 3 ctbin
4 4 =====
5 5  
6   -Generate a counts cube for binned maximum likelihood analysis.
  6 +Generate counts cube from event list(s).
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool computes the counts cube for use in a binned maximum likelihood
13   -analysis. The counts cubes are 3-dimensional data cubes spanned by Right
14   -Ascension or Galactic longitude, Declination or Galactic latitude, and energy.
15   -The energy binning may be either linear, logarithmic, or custom defined.
16   -If an observation definition XML file containing several observations is
17   -provided on input, the tool will stack all data into a single counts cube.
  12 +This tool creates a counts cube and fills it with events. A counts cube is
  13 +a 3-dimensional data cube spanned by Right Ascension or Galactic longitude,
  14 +Declination or Galactic latitude, and energy. The energy binning may be either
  15 +linear, logarithmic, or custom defined using an input file. The events are
  16 +either taken from a single event list file or from the event lists that are
  17 +specified in an observation definition file. In case that multiple event
  18 +lists are given in an observation definition file, the tool will loop over
  19 +all event lists and fill all events into a single counts cube.
  20 +
  21 +ctbin generates a counts cube FITS file comprising three extensions. The
  22 +primary extension contains a 3-dimensional image that contains the counts
  23 +cube values. The next extension named ``EBOUNDS`` contains a binary table
  24 +that defines the energy boundaries of the counts cube. The last extension
  25 +named ``GTI`` contains a binary table that defines the Good Time Intervals
  26 +of all event lists that have been filled into the counts cube.
18 27  
19 28  
20 29 General parameters
... ... @@ -94,7 +103,9 @@ Standard parameters
94 103 Name of log file.
95 104  
96 105  
97   -Related tools
98   --------------
  106 +Related tools or scripts
  107 +------------------------
99 108  
100   -None
  109 +:doc:`ctexpcube`
  110 +:doc:`ctpsfcube`
  111 +:doc:`ctbkgcube`
... ...
doc/source/reference_manual/ctbkgcube.rst
  View file @a4a4190
... ... @@ -3,36 +3,70 @@
3 3 ctbkgcube
4 4 =========
5 5  
6   -Generate a background cube for binned maximum likelihood analysis.
  6 +Generate background cube for a counts cube.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool generates a background cube for use in a binned maximum
13   -likelihood analysis.
  12 +This tool generates a background cube for a counts cube based on an input
  13 +model. A background cube is a 3-dimensional cube spanned by Right Ascension
  14 +or Galactic longitude, Declination or Galactic latitude, and energy. The
  15 +energy binning may be either linear, logarithmic, or custom defined using an
  16 +input file. The input model is used to predict the expected number of
  17 +background counts in each background cube bin.
  18 +
  19 +ctbkgcube requires on input the event list or observation definition file
  20 +that has been used in the generation of the counts cube using :doc:`ctbin`.
  21 +
  22 +To assure consistency between an existing counts cube and the
  23 +corresponding background cube, it is recommended to specify the counts
  24 +cube as ``incube`` parameter. This will instruct ctbkgcube to extract the
  25 +background cube definition (such as sky coordinates and projection, number
  26 +of pixels, pixel scale, energy binning) from the counts cube.
  27 +
  28 +ctbkgcube generates a background cube FITS file comprising two extensions.
  29 +The primary extension contains a 3-dimensional image that contains the
  30 +background cube values. The next extension named ``EBOUNDS`` contains a
  31 +binary table that defines the energy boundaries of the background cube.
  32 +
  33 +ctbkgcube generates also an output model XML file that can serve as input
  34 +for a maximum likelihood analysis. The output model XML file is a copy of
  35 +the input model XML file where the input background model has been replaced
  36 +by a background model of type ``CTACubeBackground``. The ``CTACubeBackground``
  37 +background model instructs any tool analysing binned data to extract
  38 +background information from a background cube. The ``CTACubeBackground``
  39 +model has a spectral component that can be adjusted in a maximum
  40 +likelihood fit to accomodate for uncertainties in the prediction of the
  41 +energy dependence of the background rate. ctbkgcube will use a power law
  42 +as spectral component, but you can replace this by any component of your
  43 +choice.
  44 +
14 45  
15 46  
16 47 General parameters
17 48 ------------------
18 49  
19 50 ``inobs [file]``
20   - Input event list, cube or observation definition XML file.
  51 + Input event list or observation definition XML file.
21 52  
22 53 ``inmodel [file]``
23   - Input (background) model XML file.
  54 + Input model XML file.
24 55  
25 56 ``incube [file]``
26   - Counts cube for background cube definition.
27   -
28   -``outcube [file]``
29   - Output background cube file.
  57 + Input counts cube file to extract background cube definition.
30 58  
31 59 ``caldb [string]``
32 60 Calibration database.
33 61  
34 62 ``irf [string]``
35   - Response function.
  63 + Instrument response function.
  64 +
  65 +``outcube [file]``
  66 + Output background cube file.
  67 +
  68 +``outmodel [file]``
  69 + Output model XML file.
36 70  
37 71 ``ebinalg <FILE|LIN|LOG> [string]``
38 72 Algorithm for defining energy bins.
... ... @@ -102,7 +136,7 @@ Standard parameters
102 136 Name of log file.
103 137  
104 138  
105   -Related tools
106   --------------
  139 +Related tools or scripts
  140 +------------------------
107 141  
108   -None
  142 +:doc:`ctbin`
... ...
doc/source/reference_manual/ctbutterfly.rst
  View file @a4a4190
... ... @@ -9,16 +9,31 @@ Computes butterfly diagram for a power law model.
9 9 Synopsis
10 10 --------
11 11  
12   -Calculates the confidence band of a power law model, taking into account the
13   -covariance matrix resulting from a maximum likelihood fit. The tool derives
14   -the envelope of all power law models whose prefactor and spectral index fall
15   -within the error ellipse that is associated with the covariance of the
16   -parameters. It outputs an ASCII file in column separated value (CSV) format
17   -containing the results. Each row in the result file corresponds to an energy.
18   -The columns give the energy in MeV, the fitted intensity in ph/cm2/s/MeV,
19   -and the minimum and maximum intensity that envelope the power law model
20   -with a given confidence (by default a confidence level of 68% is used, but
21   -the level can be adjusted using the ``confidence`` parameter).
  12 +This tool calculates a butterfly diagram for a specific source with power law
  13 +spectral model. The butterfly diagram is the envelope of all power law models
  14 +that are within a given confidence limit compatible with the data. By default
  15 +a confidence level of 68% is used, but the level can be adjusted using the
  16 +hidden ``confidence`` parameter. ctbutterfly computes this envelope by
  17 +evaluating for each energy the minimum and maximum intensity of all power law
  18 +models that fall within the error ellipse of the prefactor and index parameters.
  19 +The error ellipse is derived from the covariance matrix of a maximum likelihood
  20 +fit.
  21 +
  22 +ctbutterfly assumes that the input model (parameter ``inmodel``) has been
  23 +adjusted using :doc:`ctlike` to the data, but if this is not the case you
  24 +can request a maximum likelihood fit by setting the hidden parameter ``fit=yes``.
  25 +
  26 +ctbutterfly writes the butterfly diagram into an ASCII file with 4 columns
  27 +separated by a whitespace. Each row in the result file corresponds to a specific
  28 +energy. The meaning of the columns are:
  29 +
  30 +* Energy in MeV
  31 +* Fitted intensity for that energy in ph/cm2/s/MeV
  32 +* Minimum intensity for that energy in ph/cm2/s/MeV
  33 +* Maximum intensity for that energy in ph/cm2/s/MeV
  34 +
  35 +The butterfly diagram can be displayed using the ``show_butterfly.py`` script
  36 +in the example folder.
22 37  
23 38  
24 39 General parameters
... ... @@ -28,19 +43,19 @@ General parameters
28 43 Input event list, counts cube or observation definition XML file.
29 44  
30 45 ``inmodel [file]``
31   - Model XML file containing the source and background definitions.
  46 + Input model XML file.
32 47  
33 48 ``srcname [string]``
34   - Name of model component for which butterfly should be computed.
  49 + Name of source model for which the butterfly diagram should be computed.
35 50  
36 51 ``expcube [file]``
37   - Exposure cube file (only needed for stacked analysis).
  52 + Input exposure cube file (only needed for stacked analysis).
38 53  
39 54 ``psfcube [file]``
40   - PSF cube file (only needed for stacked analysis).
  55 + Input PSF cube file (only needed for stacked analysis).
41 56  
42 57 ``bkgcube [file]``
43   - Background cube file (only needed for stacked analysis).
  58 + Input background cube file (only needed for stacked analysis).
44 59  
45 60 ``caldb [string]``
46 61 Calibration database.
... ... @@ -54,8 +69,9 @@ General parameters
54 69 ``outfile [file]``
55 70 Output butterfly ASCII file name.
56 71  
57   -``(refit = no) [boolean]``
58   - Performs refitting of solution ignoring any provided covariance matrix.
  72 +``(fit = no) [boolean]``
  73 + Performs maximum likelihood fitting of input model ignoring any provided
  74 + covariance matrix.
59 75  
60 76 ``(confidence = 0.68) [real]``
61 77 Confidence level for error computation.
... ... @@ -107,8 +123,9 @@ Standard parameters
107 123 Name of log file.
108 124  
109 125  
110   -Related tools
111   --------------
  126 +Related tools or scripts
  127 +------------------------
112 128  
  129 +:doc:`ctlike`
113 130 :ref:`ctulimit`
114 131 :ref:`cterror`
... ...
doc/source/reference_manual/ctcubemask.rst
  View file @a4a4190
... ... @@ -3,14 +3,32 @@
3 3 ctcubemask
4 4 ==========
5 5  
6   -Filter a counts cube.
  6 +Mask out bins of a counts cube.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12 12 This tool masks out specific regions from a counts cube by setting the
13   -corresponding pixels to negative values.
  13 +corresponding bin values to -1. Bins with negative values will be ignored
  14 +in a maximum likelihood analysis. A mask is applied spatially and spectrally.
  15 +
  16 +ctcubemask applies a spatial mask that is comprised of a circular selection
  17 +region and a list of circular exclusion regions. The circular selection region
  18 +is specified by the sky direction of the centre and the radius of the circle.
  19 +The circular exclusion regions are specified by an ASCII file in ds9 format.
  20 +The ASCII file contains one row per exclusion region, given in the format
  21 +
  22 +``circle(83.63, 21.5, 0.4)``
  23 +
  24 +where ``83.63`` and ``21.5`` are the Right Ascension and Declination of
  25 +the centre and ``0.4`` is the radius (in degrees) of the exclusion circle.
  26 +
  27 +ctcubemask also selects only counts cube energy layers that are fully comprised
  28 +in the energy interval specified by the ``emin`` and ``emax`` parameters.
  29 +
  30 +ctcubemask generates a counts cube FITS file that is a copy of the input
  31 +counts cube and for which all masked bins have been set to -1.
14 32  
15 33  
16 34 General parameters
... ... @@ -19,9 +37,6 @@ General parameters
19 37 ``inobs [file]``
20 38 Input counts cube or observation definition XML file.
21 39  
22   -``regfile [file]``
23   - Exclusion region file in ds9 format.
24   -
25 40 ``outcube [file]``
26 41 Output counts cube or observation definition XML file.
27 42  
... ... @@ -41,6 +56,9 @@ General parameters
41 56 ``rad [real]``
42 57 Radius of circular selection region (in degrees).
43 58  
  59 +``regfile [file]``
  60 + Input exclusion region file in ds9 format.
  61 +
44 62 ``emin [real]``
45 63 Lower energy limit (in TeV).
46 64  
... ... @@ -72,11 +90,11 @@ Standard parameters
72 90 ``(mode = ql) [string]``
73 91 Mode of automatic parameters (default is "ql", i.e. "query and learn").
74 92  
75   -``(logfile = ctexpcube.log) [string]``
  93 +``(logfile = ctcubemask.log) [string]``
76 94 Name of log file.
77 95  
78 96  
79   -Related tools
80   --------------
  97 +Related tools or scripts
  98 +------------------------
81 99  
82   -None
  100 +:doc:`ctbin`
... ...
doc/source/reference_manual/cterror.rst
  View file @a4a4190
... ... @@ -3,15 +3,26 @@
3 3 cterror
4 4 =======
5 5  
6   -Computes parameter errors for a specific sky model component using
7   -a likelihood profile method.
  6 +Computes parameter errors for a source model from the likelihood profiles.
8 7  
9 8  
10 9 Synopsis
11 10 --------
12 11  
13   -This tool computes the parameter errors for a specific sky model using
14   -a likelihood profile method.
  12 +This tool computes the parameter errors for a specific source model using
  13 +the likelihood profiles. Starting from the maximum likelihood model parameters,
  14 +the tool finds the minimum and maximum model parameters that lead to a decrease
  15 +of the likelihood that corresponds to a given confidence level. By default a
  16 +confidence level of 68% is used, but this level can be adjusted using the hidden
  17 +``confidence`` parameter.
  18 +
  19 +cterror generates an output model XML file that contains the values of the
  20 +best fitting model parameters. For all free parameters, an ``error`` attribute
  21 +is added that provides the statistical uncertainty in the parameter estimate
  22 +as obtained from the likelihood profile. While cterror computes asymmetrical
  23 +errors, which are written into the log file, the XML file will contain the
  24 +mean error that is obtained by computing the mean of the negative and the
  25 +positive parameter errors.
15 26  
16 27  
17 28 General parameters
... ... @@ -21,22 +32,19 @@ General parameters
21 32 Input event list, counts cube or observation definition XML file.
22 33  
23 34 ``inmodel [file]``
24   - Model XML file containing the source and background definitions.
25   -
26   -``outmodel [file]``
27   - Model XML file with updated error information.
  35 + Input model XML file.
28 36  
29 37 ``srcname [string]``
30   - Name of model component for which upper limit should be computed.
  38 + Name of source model for which the parameter errors should be computed.
31 39  
32 40 ``expcube [file]``
33   - Exposure cube file (only needed for stacked analysis).
  41 + Input exposure cube file (only needed for stacked analysis).
34 42  
35 43 ``psfcube [file]``
36   - PSF cube file (only needed for stacked analysis).
  44 + Input PSF cube file (only needed for stacked analysis).
37 45  
38 46 ``bkgcube [file]``
39   - Background cube file (only needed for stacked analysis).
  47 + Input background cube file (only needed for stacked analysis).
40 48  
41 49 ``caldb [string]``
42 50 Calibration database.
... ... @@ -47,6 +55,9 @@ General parameters
47 55 ``(edisp = no) [boolean]``
48 56 Applies energy dispersion to response computation.
49 57  
  58 +``outmodel [file]``
  59 + Output model XML file with updated error information.
  60 +
50 61 ``(confidence = 0.68) [real]``
51 62 Confidence level for error computation.
52 63  
... ... @@ -86,8 +97,9 @@ Standard parameters
86 97 Name of log file.
87 98  
88 99  
89   -Related tools
90   --------------
  100 +Related tools or scripts
  101 +------------------------
91 102  
  103 +:ref:`ctlike`
92 104 :ref:`ctulimit`
93 105 :ref:`ctbutterfly`
... ...
doc/source/reference_manual/ctexpcube.rst
  View file @a4a4190
... ... @@ -3,14 +3,39 @@
3 3 ctexpcube
4 4 =========
5 5  
6   -Generate an exposure cube for binned maximum likelihood analysis.
  6 +Generate exposure cube for a counts cube.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool generates an exposure cube for use in a binned maximum likelihood
13   -analysis.
  12 +This tool generates an exposure cube for a counts cube. An exposure cube is
  13 +a 3-dimensional cube spanned by Right Ascension or Galactic longitude,
  14 +Declination or Galactic latitude, and energy, that gives the exposure
  15 +as function of true sky direction and energy. The energy binning of the cube
  16 +may be either linear, logarithmic, or custom defined using an input file.
  17 +
  18 +ctexpcube requires on input the event list or observation definition file
  19 +that has been used in the generation of the counts cube using :doc:`ctbin`.
  20 +
  21 +For the user's convenience, the counts cube can be specified as ``incube``
  22 +parameter which will instruct ctexpcube to extract the exposure cube
  23 +definition (such as sky coordinates and projection, number of pixels, pixel
  24 +scale, energy binning) from the counts cube. Note, however, that the exposure
  25 +cube is defined in true sky coordinates and energy while the counts cube is
  26 +defined in measured sky coordinates and energy. Consequently, the sky area
  27 +and energy range covered by the exposure cube should be slightly larger than
  28 +that of the counts cube to accomodate for spill over of events due to the
  29 +point spread function and energy dispersion. By computing the exposure map
  30 +on the same grid as the counts cube, the spill over of events from sources at
  31 +the edge of cube will not be handled correctly.
  32 +
  33 +ctexpcube generates an exposure cube FITS file comprising three extensions.
  34 +The primary extension contains a 3-dimensional image that contains the
  35 +exposure values. The next extension named ``EBOUNDS`` contains a binary table
  36 +that defines the energy boundaries of the exposure cube. The last extension
  37 +named ``GTI`` contains a binary table that defines the Good Time Intervals
  38 +of the exposure cube.
14 39  
15 40  
16 41 General parameters
... ... @@ -20,20 +45,20 @@ General parameters
20 45 Input event list or observation definition XML file.
21 46  
22 47 ``incube [file]``
23   - Counts cube for PSF cube definition.
24   -
25   -``outcube [file]``
26   - Output exposure cube file.
  48 + Input counts cube file to extract exposure cube definition.
27 49  
28 50 ``caldb [string]``
29 51 Calibration database.
30 52  
31 53 ``irf [string]``
32   - Response function.
  54 + Instrument response function.
33 55  
34 56 ``(edisp = no) [boolean]``
35 57 Apply energy dispersion for response computation?
36 58  
  59 +``outcube [file]``
  60 + Output exposure cube file.
  61 +
37 62 ``ebinalg <FILE|LIN|LOG> [string]``
38 63 Algorithm for defining energy bins.
39 64  
... ... @@ -102,7 +127,7 @@ Standard parameters
102 127 Name of log file.
103 128  
104 129  
105   -Related tools
106   --------------
  130 +Related tools or scripts
  131 +------------------------
107 132  
108   -None
  133 +:doc:`ctbin`
... ...
doc/source/reference_manual/ctlike.rst
  View file @a4a4190
... ... @@ -3,26 +3,54 @@
3 3 ctlike
4 4 ======
5 5  
6   -Performs binned and unbinned maximum likelihood analysis of CTA data.
  6 +Perform maximum likelihood model fitting.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -Determines the flux, spectral index, position or extent of gamma-ray
13   -sources using maximum likelihood model fitting of CTA data. The analysis
14   -can be done in a binned or an unbinned formulation of the log-likelihood
15   -function. For binned analysis, a counts cube produced by :doc:`ctbin` is
16   -required. If several observations have been stacked into a single counts
17   -cube, an exposure cube, a PSF cube and a background cube have to be
18   -provided. For a single observation it is sufficient to specify the
19   -instrument response function. For unbinned analysis, an event list
20   -processed by :doc:`ctselect` is required. Based on files specified on
21   -input, ctlike automatically selects between binned or unbinned analysis.
22   -The tool can also be applied to lists of observations, specified in form
23   -of an observation definition file in XML format. Events of each observation
24   -are kept separate, and are associated to their appropriate instrument
25   -response function.
  12 +This tool performs a maximum likelihood fitting of a model to unbinned or
  13 +binned data. All model parameters marked with the attribute ``free="1"``
  14 +in the input model XML file will be adjusted to the value that maximises
  15 +the probability that the observed data have been drawn from the model.
  16 +The tool can mix the analysis of unbinned and binned data, and is also able
  17 +to perform a joint maximum likelihood analysis of data collected in
  18 +separate observations or with different instruments.
  19 +
  20 +ctlike will automatically switch between unbinned, binned and joint analysis
  21 +on basis of the file provided on input (parameter ``inobs``). Providing an
  22 +event list will lead to an unbinned analysis while providing a counts cube
  23 +will lead to a binned analysis. If several observations have been stacked
  24 +into a single counts cube, an exposure cube, a point spread function cube and
  25 +a background cube need also to be provided. ctlike will automatically prompt
  26 +for these parameters in case that a counts cube is given. Answering ``NONE``
  27 +will ignore the exposure cube, point spread function cube and background cube
  28 +and handle the data as a single observation using the specified instrument
  29 +response function (parameters ``caldb`` and ``irf``).
  30 +
  31 +Multiple observations, including data collected with different instruments,
  32 +can be handled by specifying an observation definition file on input. Each of
  33 +the observations will be kept separatly and associated with its appropriate
  34 +instrument response functions, as opposed to a stacked analysis where average
  35 +response functions, computed using :doc:`ctexpcube`, :doc:`ctpsfcube` and :doc:`ctbkgcube`,
  36 +are used. If an observation definition file is provided, ctlike will use the
  37 +joint likelihood of all the observations for parameter optimisation.
  38 +
  39 +By default, ctlike will use the Poisson statistics for likelihood computation,
  40 +but for binned analysis also Gaussian statistics can be specified (parameter
  41 +``stat``). Optionally, a refit can be done after an initial fit (parameter ``refit``),
  42 +but normally this is not needed. For all model components that have the
  43 +``tscalc="1"`` attribute set, ctlike will also compute the Test Statistics
  44 +value that is a measure of the source significance. Optionally, the spatial
  45 +model parameters can be kept fixed during that computation (parameter
  46 +``fix_spat_for_ts``).
  47 +
  48 +ctlike generates an output model XML file that contains the values of the
  49 +best fitting model parameters. For all free parameters, an ``error`` attribute
  50 +is added that provides the statistical uncertainty in the parameter estimate.
  51 +If computation of the Test Statistics has been requested for a model component,
  52 +a ``ts`` attribute providing the Test Statistics value is added. The output
  53 +model can be used as an input model for other ctools.
26 54  
27 55  
28 56 General parameters
... ... @@ -32,16 +60,16 @@ General parameters
32 60 Input event list, counts cube or observation definition XML file.
33 61  
34 62 ``inmodel [string]``
35   - Source model input XML file.
  63 + Input model XML file.
36 64  
37 65 ``expcube [file]``
38   - Exposure cube file (only needed for stacked analysis).
  66 + Input exposure cube file (only needed for stacked analysis).
39 67  
40 68 ``psfcube [file]``
41   - PSF cube file (only needed for stacked analysis).
  69 + Input PSF cube file (only needed for stacked analysis).
42 70  
43 71 ``bkgcube [file]``
44   - Background cube file (only needed for stacked analysis).
  72 + Input background cube file (only needed for stacked analysis).
45 73  
46 74 ``caldb [string]``
47 75 Calibration database.
... ... @@ -49,16 +77,16 @@ General parameters
49 77 ``irf [string]``
50 78 Instrument response function.
51 79  
  80 +``(edisp = no) [boolean]``
  81 + Applies energy dispersion to response computation.
  82 +
52 83 ``outmodel [string]``
53   - Source model result XML file with values and uncertainties updated by
  84 + Output model XML file with values and uncertainties updated by
54 85 the maximum likelihood fit.
55 86  
56 87 ``(stat = POISSON) [string]``
57 88 Fitting statistics (POISSON or GAUSSIAN; only affects binned analysis).
58 89  
59   -``(edisp = no) [boolean]``
60   - Applies energy dispersion to response computation.
61   -
62 90 ``(refit = no) [boolean]``
63 91 Perform refitting of solution after initial fit.
64 92  
... ... @@ -95,7 +123,7 @@ Standard parameters
95 123 Name of log file.
96 124  
97 125  
98   -Related tools
99   --------------
  126 +Related tools or scripts
  127 +------------------------
100 128  
101 129 None
... ...
doc/source/reference_manual/ctmodel.rst
  View file @a4a4190
... ... @@ -3,48 +3,67 @@
3 3 ctmodel
4 4 =======
5 5  
6   -Computes model counts cube.
  6 +Generate model cube.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool computes a model counts cube based on an XML model. The counts
13   -cube is a 3-dimensional data cube spanned by Right Ascension or Galactic
14   -longitude, Declination or Galactic latitude, and energy.
  12 +This tool generates a model cube based on an input model. A model cube is
  13 +a 3-dimensional cube providing the number of predicted counts for a model as
  14 +function of Right Ascension or Galactic longitude, Declination or Galactic
  15 +latitude, and energy. The energy binning may be either linear, logarithmic,
  16 +or custom defined using an input file.
  17 +
  18 +ctmodel requires on input either a counts cube, an event list or an observation
  19 +definition file.
  20 +
  21 +If a counts cube is provided, ctmodel will use the definition of this cube
  22 +(such as sky coordinates and projection, number of pixels, pixel scale,
  23 +energy binning) to compute a model cube. In case that the counts cube combines
  24 +multiple observations (i.e. for a so-called "stacked cube"), an exposure cube,
  25 +a point spread function cube and a background cube have to be provided
  26 +(otherwise you may just enter ``NONE`` when the names of these files are
  27 +queried).
  28 +
  29 +If an event list is provided, ctmodel will query for a counts cube to
  30 +extract the model cube definition (parameter ``incube``). If no counts cube
  31 +is provided (``incube=NONE``), ctmodel tools will query for cube definition
  32 +parameters.
  33 +
  34 +If an observation definition file is provided, ctmodel will query for a counts
  35 +cube to extract the model cube definition, unless the observation definition
  36 +file contains a single binned observation (in that case, the counts cube of
  37 +that observation will be used to extract the model cube definition).
  38 +
  39 +ctmodel generates a model cube FITS file comprising three extensions. The
  40 +primary extension contains a 3-dimensional image that contains the model
  41 +cube values. The next extension named ``EBOUNDS`` contains a binary table
  42 +that defines the energy boundaries of the background cube. The last extension
  43 +named ``GTI`` contains a binary table that defines the Good Time Intervals
  44 +that are covered by the model cube.
15 45  
16 46  
17 47 General parameters
18 48 ------------------
19 49  
20   -``incube [file]``
21   - Input counts cube. If a filename is given the counts cube will be
22   - used to define the dimensions of the model cube. The content of
23   - the counts cube is not relevant.
  50 +``inobs [file]``
  51 + Input event list, counts cube or observation definition XML file.
24 52  
25 53 ``inmodel [string]``
26   - Source model XML file.
27   -
28   -``outcube [file]``
29   - Output model counts cube.
30   -
31   -``(edisp = no) [boolean]``
32   - Apply energy dispersion to response computation.
  54 + Input model XML file.
33 55  
34   -``inobs [file]``
35   - Input event list, counts cube or observation definition XML file.
36   - This information is needed to determine the observation information
37   - (number of observations, duration, liftime, pointing, eventually
38   - observation specific instrument response functions, etc.).
  56 +``incube [file]``
  57 + Input counts cube file to extract model cube definition.
39 58  
40 59 ``expcube [file]``
41   - Exposure cube file (only needed for stacked analysis).
  60 + Input exposure cube file (only needed for stacked analysis).
42 61  
43 62 ``psfcube [file]``
44   - PSF cube file (only needed for stacked analysis).
  63 + Input PSF cube file (only needed for stacked analysis).
45 64  
46 65 ``bkgcube [file]``
47   - Background cube file (only needed for stacked analysis).
  66 + Input background cube file (only needed for stacked analysis).
48 67  
49 68 ``caldb [string]``
50 69 Calibration database.
... ... @@ -52,6 +71,12 @@ General parameters
52 71 ``irf [string]``
53 72 Instrument response function.
54 73  
  74 +``(edisp = no) [boolean]``
  75 + Apply energy dispersion to response computation.
  76 +
  77 +``outcube [file]``
  78 + Output model cube file.
  79 +
55 80 ``ra [real]``
56 81 Right Ascension of pointing (J2000, in degrees).
57 82  
... ... @@ -138,7 +163,10 @@ Standard parameters
138 163 Name of log file.
139 164  
140 165  
141   -Related tools
142   --------------
  166 +Related tools or scripts
  167 +------------------------
143 168  
144   -None
  169 +:doc:`ctbin`
  170 +:doc:`ctexpcube`
  171 +:doc:`ctpsfcube`
  172 +:doc:`ctbkgcube`
... ...
doc/source/reference_manual/ctobssim.rst
  View file @a4a4190
... ... @@ -3,14 +3,39 @@
3 3 ctobssim
4 4 ========
5 5  
6   -Simulates CTA events.
  6 +Simulate event list(s).
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -Generate photon events from astrophysical sources and background events
13   -from an instrumental background model.
  12 +This tool simulates event list(s) using the instrument characteristics
  13 +specified by the instrument response function(s) and an input model. The
  14 +simulation includes photon events from astrophysical sources and background
  15 +events from an instrumental background model.
  16 +
  17 +By default, ctobssim creates a single event list. ctobssim queries a pointing
  18 +direction, the radius of the simulation region, a time interval, an energy
  19 +interval, an instrumental response function, and an input model. ctobssim uses
  20 +a numerical random number generator for the simulations with a seed value
  21 +provided by the hidden ``seed`` parameter. Changing this parameter for
  22 +subsequent runs will lead to different event samples.
  23 +
  24 +ctobssim performs a safety check on the maximum photon rate for all model
  25 +components to avoid that the tool locks up and requests huge memory
  26 +ressources, which may happen if a mistake was made in setting up the input
  27 +model (for example if an error in the flux units is made). The maximum allowed
  28 +photon rate is controlled by the hidden ``maxrate`` parameter, which by default
  29 +is set to 1e6.
  30 +
  31 +ctobssim can also generate multiple event lists if an observation definition
  32 +file is specified on input using the hidden ``inobs`` parameter. In that
  33 +case, simulation information will be gathered from the file, and for each
  34 +observation an event list will be created.
  35 +
  36 +For each event file, the simulation parameters will be written as data
  37 +selection keywords to the FITS header. These keywords are mandatory for any
  38 +unbinned maximum likelihood analysis of the event data.
14 39  
15 40  
16 41 General parameters
... ... @@ -23,14 +48,7 @@ General parameters
23 48 simulation.
24 49  
25 50 ``inmodel [file]``
26   - XML file that describes the astrophysical sources and the instrumental
27   - background model.
28   -
29   -``outevents [file]``
30   - Output event list or observation definition XML file.
31   -
32   -``(prefix = sim_events_) [string]``
33   - Prefix for event list in observation definition XML file.
  51 + Input model XML file.
34 52  
35 53 ``caldb [string]``
36 54 Calibration database.
... ... @@ -38,6 +56,15 @@ General parameters
38 56 ``irf [string]``
39 57 Instrumental response function.
40 58  
  59 +``(edisp = no) [boolean]``
  60 + Apply energy dispersion?
  61 +
  62 +``outevents [file]``
  63 + Output event list or observation definition XML file.
  64 +
  65 +``(prefix = sim_events_) [string]``
  66 + Prefix for event list in observation definition XML file.
  67 +
41 68 ``(seed = 1) [integer]``
42 69 Integer seed value to be used for Monte Carlo simulations. Keep this
43 70 parameter at the same value for repeatable simulations, or increment
... ... @@ -65,9 +92,6 @@ General parameters
65 92 ``emax [real]``
66 93 Upper energy limit of simulated events (in TeV).
67 94  
68   -``(edisp = no) [boolean]``
69   - Apply energy dispersion?
70   -
71 95 ``(deadc = 0.95) [real]``
72 96 Average deadtime correction factor.
73 97  
... ... @@ -107,7 +131,7 @@ Standard parameters
107 131 Name of log file.
108 132  
109 133  
110   -Related tools
111   --------------
  134 +Related tools or scripts
  135 +------------------------
112 136  
113   -None
  137 +:doc:`csobsdef`
... ...
doc/source/reference_manual/ctpsfcube.rst
  View file @a4a4190
... ... @@ -3,15 +3,39 @@
3 3 ctpsfcube
4 4 =========
5 5  
6   -Generate a point spread function cube for binned maximum likelihood
7   -analysis.
  6 +Generate point spread function cube for a counts cube.
8 7  
9 8  
10 9 Synopsis
11 10 --------
12 11  
13   -This tool generates a point spread function cube for use in a binned
14   -maximum likelihood analysis.
  12 +This tool generates a point spread function cube for a counts cube. A point
  13 +spread function cube is a 4-dimensional cube spanned by Right Ascension or
  14 +Galactic longitude, Declination or Galactic latitude, energy, and offset
  15 +angle between true and measured arrival direction of a photon. The energy
  16 +binning of the cube may be either linear, logarithmic, or custom defined
  17 +using an input file.
  18 +
  19 +ctpsfcube requires on input the event list or observation definition file
  20 +that has been used in the generation of the counts cube using :doc:`ctbin`.
  21 +
  22 +It is not recommended to use the counts cube for the point spread function
  23 +cube definition, although this is formally possibly by specifying the counts
  24 +cube as ``incube`` parameter. This leads however to a large FITS file on
  25 +output since the number of bins in the counts cube will be multiplied by
  26 +the number of offset angle bins (typically 200). Since the point spread
  27 +function varies only little over the field of fiew of the camera it is
  28 +recommended to use a rather coarse spatial binning to keep the file size
  29 +manageable (with a typical value of ``binsz=1.0``).
  30 +
  31 +ctpsfcube generates a point spread function cube FITS file comprising three
  32 +extensions. The primary extension contains a 3-dimensional image that contains
  33 +the point spread function values. The energy and offset angle dimensions
  34 +of the point spread function cube are folded into the 3rd dimension of the
  35 +FITS image. The next extension named ``EBOUNDS`` contains a binary table
  36 +that defines the energy boundaries of the exposure cube. The last extension
  37 +named ``DELTAS`` contains a binary table that defines the offset angles
  38 +between true and measured arrival direction of the photon.
15 39  
16 40  
17 41 General parameters
... ... @@ -21,20 +45,20 @@ General parameters
21 45 Input event list or observation definition XML file.
22 46  
23 47 ``incube [file]``
24   - Counts cube for PSF cube definition.
25   -
26   -``outcube [file]``
27   - Output PSF cube file.
  48 + Input counts cube file to extract point spread function cube definition.
28 49  
29 50 ``caldb [string]``
30 51 Calibration database.
31 52  
32 53 ``irf [string]``
33   - Response function.
  54 + Instrument response function.
34 55  
35 56 ``(edisp = no) [boolean]``
36 57 Apply energy dispersion for response computation.
37 58  
  59 +``outcube [file]``
  60 + Output point spread function cube file.
  61 +
38 62 ``ebinalg <FILE|LIN|LOG> [string]``
39 63 Algorithm for defining energy bins.
40 64  
... ... @@ -110,7 +134,7 @@ Standard parameters
110 134 Name of log file.
111 135  
112 136  
113   -Related tools
114   --------------
  137 +Related tools or scripts
  138 +------------------------
115 139  
116   -None
  140 +:doc:`ctbin`
... ...
doc/source/reference_manual/ctselect.rst
  View file @a4a4190
... ... @@ -3,14 +3,36 @@
3 3 ctselect
4 4 ========
5 5  
6   -Performs sub-selections of event data.
  6 +Select events from event list(s).
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -Creates a new FITS file of selected events from an input event list based
13   -on spatial, temporal, and energy cuts.
  12 +This tool selects events from one or several event lists. Event selection
  13 +is based on a circular acceptance region, a time interval and an energy
  14 +interval. In addition, any expression following the cfitsio syntax can be
  15 +used for event selection.
  16 +
  17 +Optionally, ctselect may also apply energy thresholds. If ``usethres=DEFAULT``
  18 +is specified, ctselect will extract any save thresholds from the instrument
  19 +response functions, and if they exist, will apply them to the respective
  20 +event list. Alternatively, if ``usethres=USER`` is specified, ctselect will
  21 +extract any user thresholds from the observation definition file (attributes
  22 +``emin`` and ``emax``), and if either of the attributes exists, will apply
  23 +them to the respective event list.
  24 +
  25 +If an event list is provided on input, ctselect creates a new FITS file on
  26 +output that contains only the selected events. In case that an observation
  27 +definition file is specified on input, ctselect creates for each event file
  28 +referenced in the observation definition file a new FITS file with the value
  29 +of ``prefix`` prepended to the file name that contains only the selected
  30 +events. In addition, a new observation definition file will be written
  31 +that references the new FITS files.
  32 +
  33 +For each event file, the event selection parameters will be writted as data
  34 +selection keywords to the FITS header. These keywords are mandatory for any
  35 +unbinned maximum likelihood analysis of the event data.
14 36  
15 37  
16 38 General parameters
... ... @@ -98,7 +120,7 @@ Standard parameters
98 120 Name of log file.
99 121  
100 122  
101   -Related tools
102   --------------
  123 +Related tools or scripts
  124 +------------------------
103 125  
104 126 None
... ...
doc/source/reference_manual/ctskymap.rst
  View file @a4a4190
... ... @@ -3,13 +3,18 @@
3 3 ctskymap
4 4 ========
5 5  
6   -Computes sky map from CTA data.
  6 +Generate sky map from event list(s).
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool generates a sky map from CTA data.
  12 +This tool creates a sky map from either a single event list or event lists
  13 +provided in an observation definition file. The tool will loop over all event
  14 +lists that are provided and fill all events into a single sky map. Only events
  15 +within an energy interval spanned by ``emin`` and ``emax`` are considered.
  16 +
  17 +ctskymap generates a FITS file comprising a sky map as primary extension.
13 18  
14 19  
15 20 General parameters
... ... @@ -19,7 +24,7 @@ General parameters
19 24 Input event list or observation definition XML file.
20 25  
21 26 ``outmap [file]``
22   - Output sky map.
  27 + Output sky map file.
23 28  
24 29 ``emin [real]``
25 30 Minimum energy in map (in TeV).
... ... @@ -80,7 +85,7 @@ Standard parameters
80 85 Name of log file.
81 86  
82 87  
83   -Related tools
84   --------------
  88 +Related tools or scripts
  89 +------------------------
85 90  
86 91 None
... ...
doc/source/reference_manual/cttsmap.rst
  View file @a4a4190
... ... @@ -3,13 +3,25 @@
3 3 cttsmap
4 4 =======
5 5  
6   -Generate a Test Statistic map.
  6 +Generate a Test Statistic (TS) map.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool generates a Test Statistic map.
  12 +This tool generates a Test Statistic (TS) map for a specific source model.
  13 +cttsmap works for point, radial and elliptical source models. The tool
  14 +displaces the specified source on a grid of sky directions and computes for
  15 +each direction the TS value for the model. The TS value is defined as twice
  16 +the difference between the log-likelihood obtained for the full model
  17 +(including the specified source) and the log-likelihood obtained for a model
  18 +that excludes the specified source. The square-root of the TS values
  19 +corresponds roughly to the pre-trial detection signifiance of the source (in
  20 +Gaussian sigma).
  21 +
  22 +cttsmap generates a FITS file comprising a sky map of TS values followed by
  23 +one extension per free parameter that contains sky maps of the fitted
  24 +parameter values.
13 25  
14 26  
15 27 General parameters
... ... @@ -19,26 +31,25 @@ General parameters
19 31 Input event list, counts cube or observation definition XML file.
20 32  
21 33 ``inmodel [file]``
22   - Input source model XML file.
  34 + Input model XML file.
23 35  
24 36 ``srcname [string]``
25   - Name of the source in the source model XML file for which the Test
26   - Statistic map should be computed.
  37 + Name of source model for which the TS map should be computed.
27 38  
28 39 ``expcube [file]``
29   - Exposure cube file (only needed for stacked analysis).
  40 + Input exposure cube file (only needed for stacked analysis).
30 41  
31 42 ``psfcube [file]``
32   - PSF cube file (only needed for stacked analysis).
  43 + Input PSF cube file (only needed for stacked analysis).
33 44  
34 45 ``bkgcube [file]``
35   - Background cube file (only needed for stacked analysis).
  46 + Input background cube file (only needed for stacked analysis).
36 47  
37 48 ``caldb [string]``
38 49 Calibration database.
39 50  
40 51 ``irf [string]``
41   - Response function.
  52 + Instrumental response function.
42 53  
43 54 ``(edisp = no) [boolean]``
44 55 Applies energy dispersion to response computation.
... ...
doc/source/reference_manual/ctulimit.rst
  View file @a4a4190
1 1 .. _ctulimit:
2 2  
3 3 ctulimit
4   -===========
  4 +========
5 5  
6   -Computes upper limit for a specific sky model component.
  6 +Computes upper flux limit for a source model.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -Computes the upper limit flux of a given source.
  12 +This tools computes the upper flux limit for a specific source model. Except
  13 +of the node function, all spectral models are supported. Starting from the
  14 +maximum likelihood model parameters, the tool finds the model flux that leads
  15 +to a decrease of the likelihood that corresponds to a given confidence level.
  16 +By default a confidence level of 95% is used, but this level can be adjusted
  17 +using the hidden ``confidence`` parameter.
  18 +
  19 +ctulimit writes the differential upper flux limit at a given reference
  20 +energy (specified by the hidden parameter ``eref``) and the integrated
  21 +upper flux limit (specified by the hidden parameters ``emin`` and ``emax``)
  22 +into the log file.
  23 +
13 24  
14 25  
15 26 General parameters
... ... @@ -19,19 +30,19 @@ General parameters
19 30 Input event list, counts cube or observation definition XML file.
20 31  
21 32 ``inmodel [file]``
22   - Model XML file containing the source and background definitions.
  33 + Input model XML file.
23 34  
24 35 ``srcname [string]``
25   - Name of model component for which upper limit should be computed.
  36 + Name of source model for which the upper flux limit should be computed.
26 37  
27 38 ``expcube [file]``
28   - Exposure cube file (only needed for stacked analysis).
  39 + Input exposure cube file (only needed for stacked analysis).
29 40  
30 41 ``psfcube [file]``
31   - PSF cube file (only needed for stacked analysis).
  42 + Input PSF cube file (only needed for stacked analysis).
32 43  
33 44 ``bkgcube [file]``
34   - Background cube file (only needed for stacked analysis).
  45 + Input background cube file (only needed for stacked analysis).
35 46  
36 47 ``caldb [string]``
37 48 Calibration database.
... ... @@ -53,11 +64,14 @@ General parameters
53 64 Maximum boundary to start searching for upper limit value.
54 65 Number of standard deviations above best fit value
55 66  
  67 +``(eref = 1.0) [real])``
  68 + Reference energy for differential limit (in TeV).
  69 +
56 70 ``(emin = 1.0) [real])``
57   - Minimum energy of flux limits (in TeV).
  71 + Minimum energy for integral flux limit (in TeV).
58 72  
59 73 ``(emax = 100) [real]``
60   - Maximum energy of flux limits (in TeV).
  74 + Maximum energy for integral flux limit (in TeV).
61 75  
62 76 ``(tol = 1e-5) [real]``
63 77 Computation tolerance.
... ... @@ -98,4 +112,6 @@ Standard parameters
98 112 Related tools
99 113 -------------
100 114  
101   -:ref:`cterror`
102 115 \ No newline at end of file
  116 +:ref:`ctlike`
  117 +:ref:`cterror`
  118 +:ref:`ctbutterfly`
... ...
doc/source/user_manual/enhancing.rst deleted
View file @4065b3d
1   -Enhancing ctools
2   -================
3   -
4   -Most ctools users will run the existing ctools or cscripts,
5   -which cover the most common simulation and analysis needs.
6   -
7   -Advanced users and developers can write their own tools and scripts.
8   -The following C++ and Python examples can help get you started:
9   -
10   -* :doxy:`ctlike`
11   -* :doxy:`obsutils`
12   -* :doxy:`cstsdist`
13   -
14   -Building your own cscripts
15   ---------------------------
16   -
17   -To be written ...
18   -
19   -
20   -Building your own ctools
21   -------------------------
22   -
23   -To be written ...
doc/source/user_manual/expert.rst deleted
View file @4065b3d
1   -Behind the scenes
2   -=================
3   -
4   -CTA data structure
5   -------------------
6   -
7   -To be written ...
8   -
9   -
10   -Instrument response functions
11   ------------------------------
12   -
13   -To be written ...
14   -
15   -
16   -Maximum likelihood fitting
17   ---------------------------
18   -
19   -To be written ...
doc/source/user_manual/getting.rst
  View file @a4a4190
... ... @@ -29,15 +29,15 @@ No system administrator privileges are needed to install ctools.
29 29  
30 30 .. _sec_installing_gammalib:
31 31  
32   -Installing gammalib
  32 +Installing GammaLib
33 33 -------------------
34 34  
35   -ctools is built on top of gammalib, hence gammalib needs to be built,
  35 +ctools is built on top of GammaLib, hence GammaLib needs to be built,
36 36 installed and configured before ctools can be installed. In case that
37 37 ctools is already installed on your system you may skip reading this
38 38 section and continue with the :ref:`sec_building_ctools` section.
39 39  
40   -You will need the following to build the gammalib:
  40 +You will need the following to build the GammaLib:
41 41  
42 42 - About 200 MB of free disk space.
43 43  
... ... @@ -58,12 +58,12 @@ You will need the following to build the gammalib:
58 58 Furthermore it is recommended to have readline and ncurses installed
59 59 (including the developer packages).
60 60  
61   -After downloading the gammalib tarball (see :ref:`download`), save it
  61 +After downloading the GammaLib tarball (see :ref:`download`), save it
62 62 in an appropriate location (for example ``$HOME/builds``), and type
63 63  
64 64 .. code-block:: bash
65 65  
66   - $ tar xvfz gammalib-0.11.0.tar.gz
  66 + $ tar xvfz gammalib-1.0.0.tar.gz
67 67  
68 68 (the ``$`` symbol indicates the console prompt and is not part of the
69 69 command that you should type in).
... ... @@ -73,7 +73,7 @@ typing
73 73  
74 74 .. code-block:: bash
75 75  
76   - $ cd gammalib-0.11.0
  76 + $ cd gammalib-1.0.0
77 77 $ ./configure
78 78 $ make
79 79 $ make check
... ... @@ -82,6 +82,8 @@ typing
82 82 The last step may require system administator privileges. In this case,
83 83 use
84 84  
  85 +.. code-block:: bash
  86 +
85 87 $ sudo make install
86 88  
87 89 If you do not have system administrator privileges, change the install
... ... @@ -133,7 +135,7 @@ an appropriate location (for example ``$HOME/builds``), and type
133 135  
134 136 .. code-block:: bash
135 137  
136   - $ tar xvfz ctools-0.10.0.tar.gz
  138 + $ tar xvfz ctools-1.0.0.tar.gz
137 139  
138 140 (the ``$`` symbol indicates the console prompt and is not part of the
139 141 command that you should type in).
... ... @@ -142,7 +144,7 @@ Step in the directory and build the ctools by typing
142 144  
143 145 .. code-block:: bash
144 146  
145   - $ cd ctools-0.10.0
  147 + $ cd ctools-1.0.0
146 148 $ ./configure
147 149 $ make
148 150  
... ... @@ -181,7 +183,7 @@ following output at the end of the unit testing:
181 183 PASS: test_python.py
182 184 make[4]: Nothing to be done for `all'.
183 185 ============================================================================
184   - Testsuite summary for ctools 0.10.0
  186 + Testsuite summary for ctools 1.0.0
185 187 ============================================================================
186 188 # TOTAL: 3
187 189 # PASS: 3
... ... @@ -345,19 +347,8 @@ As a quick check that your setup is okay you can run ``csinfo check``:
345 347 ===> Your Gammalib / ctools setup is OK.
346 348  
347 349 If the setup is not okay, run the ``csinfo info`` command to print
348   -detailed information about your setup.
349   -There's also a ``csinfo list`` command to quickly list the available tools:
350   -
351   -.. code-block:: bash
352   -
353   - $ csinfo
354   -
355   - Print info about Gammalib and ctools to the console.
356   -
357   - Available commands:
358   - csinfo list List available ctools and cscripts
359   - csinfo check Check Gammalib / ctools setup
360   - csinfo info Print Gammalib / ctools setup info
  350 +detailed information about your setup. There's also a ``csinfo list``
  351 +command to quickly list the available tools.
361 352  
362 353  
363 354 .. _sec_known_problems:
... ...
doc/source/user_manual/getting_started/beyond.rst
  View file @a4a4190
... ... @@ -3,12 +3,12 @@
3 3 Beyond the first steps
4 4 ----------------------
5 5  
6   -Assuming that you have read the :ref:`quickstart <quickstart>` tutorial,
7   -here now some chapters to read if you intend to do more complex
8   -analyses.
9   -Once you have gone through these chapters you should have a pretty complete
  6 +Now that you are familiar with the ctools basics, here are some sections
  7 +to read if you intend to do more complex analyses.
  8 +Once you have gone through these sections you should have a pretty complete
10 9 picture about the capabilities of ctools.
11   -And you should be ready for doing your own cutting edge analyses.
  10 +And you should be ready for doing your own cutting edge CTA science data
  11 +analyses.
12 12  
13 13 .. toctree::
14 14 :maxdepth: 2
... ... @@ -19,11 +19,3 @@ And you should be ready for doing your own cutting edge analyses.
19 19 beyond_residual
20 20 beyond_irf
21 21 beyond_model
22   -
23   -
24   -
25   -
26   -
27   -
28   -
29   -
... ...
doc/source/user_manual/getting_started/beyond_combine.rst
  View file @a4a4190
... ... @@ -25,9 +25,9 @@ nebula, each offset by 0.5 deg from the nebula in opposite directions:
25 25 Lower energy limit (TeV) [0.1]
26 26 Upper energy limit (TeV) [100.0]
27 27 Calibration database [prod2]
28   - Instrument response function [South_50h]
29   - Model [$CTOOLS/share/models/crab.xml]
30   - Output event data file or observation definition file [events.fits] events1.fits
  28 + Instrument response function [South_0.5h]
  29 + Input model XML file [$CTOOLS/share/models/crab.xml]
  30 + Output event data file or observation definition XML file [events.fits] events1.fits
31 31  
32 32 .. code-block:: bash
33 33  
... ... @@ -40,16 +40,16 @@ nebula, each offset by 0.5 deg from the nebula in opposite directions:
40 40 Lower energy limit (TeV) [0.1]
41 41 Upper energy limit (TeV) [100.0]
42 42 Calibration database [prod2]
43   - Instrument response function [South_50h]
44   - Model [$CTOOLS/share/models/crab.xml]
45   - Output event data file or observation definition file [events1.fits] events2.fits
  43 + Instrument response function [South_0.5h]
  44 + Input model XML file [$CTOOLS/share/models/crab.xml]
  45 + Output event data file or observation definition XML file [events1.fits] events2.fits
46 46  
47 47 This will produce the two event files ``events1.fits`` and ``events2.fits``
48 48 on disk.
49 49  
50   -As next step we have to create an **observation definition XML file** that
  50 +As next step you have to create an **observation definition XML file** that
51 51 collects both observations in a list.
52   -Here is how such a file would look like:
  52 +Here is how that file looks like:
53 53  
54 54 .. code-block:: xml
55 55  
... ... @@ -86,116 +86,140 @@ ctools knows which instrument specific functions need to be called.**
86 86 Imaging Air Cherenkov Telescope in a joint analysis.
87 87 **Please recall that instrument strings are case sensitive.**
88 88  
89   -Now we are ready to do a joint maximum likelihood analysis using
90   -:ref:`ctlike`:
  89 +Now you are ready to do a joint maximum likelihood analysis using
  90 +:ref:`ctlike`. Type:
91 91  
92 92 .. code-block:: bash
93 93  
94   - $ ctlike
95   - Event list, counts cube or observation definition file [selected_events.fits] obs.xml
  94 + $ ctlike chatter=3
  95 + Input event list, counts cube or observation definition XML file [events.fits] obs.xml
96 96 Calibration database [prod2]
97   - Instrument response function [South_50h]
98   - Source model [$CTOOLS/share/models/crab.xml]
99   - Source model output file [crab_results.xml]
  97 + Instrument response function [South_0.5h]
  98 + Input model XML file [$CTOOLS/share/models/crab.xml]
  99 + Output model XML file [crab_results.xml]
100 100  
101   -Instead of providing an event list or a counts cube, we now provided the
  101 +Instead of providing an event list or a counts cube, you now provided the
102 102 filename of the observation definition XML file (here ``obs.xml``) as input
103   -parameter.
104   -:ref:`ctlike` recognises this format and automatically performs a
105   -joint analysis, as indicated in the log file:
  103 +parameter. :ref:`ctlike` recognises this format and automatically performs a
  104 +joint analysis. To see the result of this you needed to specify the
  105 +``chatter=3`` parameter so that the chattiness is increased in the log
  106 +file:
106 107  
107 108 .. code-block:: xml
108 109  
109   - 2015-05-22T20:17:07: +==============+
110   - 2015-05-22T20:17:07: | Observations |
111   - 2015-05-22T20:17:07: +==============+
112   - 2015-05-22T20:17:07: === GObservations ===
113   - 2015-05-22T20:17:07: Number of observations ....: 2
114   - 2015-05-22T20:17:07: Number of predicted events : 0
115   - 2015-05-22T20:17:07: === GCTAObservation ===
116   - 2015-05-22T20:17:07: Name ......................:
117   - 2015-05-22T20:17:07: Identifier ................: 00001
118   - 2015-05-22T20:17:07: Instrument ................: CTA
119   - 2015-05-22T20:17:07: Event file ................: events1.fits
120   - 2015-05-22T20:17:07: Event type ................: EventList
121   - 2015-05-22T20:17:07: Statistics ................: Poisson
122   - 2015-05-22T20:17:07: Ontime ....................: 1800 s
123   - 2015-05-22T20:17:07: Livetime ..................: 1710 s
124   - 2015-05-22T20:17:07: Deadtime correction .......: 0.95
125   - 2015-05-22T20:17:07: User energy range .........: undefined
126   - 2015-05-22T20:17:07: === GCTAPointing ===
127   - 2015-05-22T20:17:07: Pointing direction ........: (RA,Dec)=(83.63,21.51)
  110 + 2015-12-07T21:23:07: +==============+
  111 + 2015-12-07T21:23:07: | Observations |
  112 + 2015-12-07T21:23:07: +==============+
  113 + 2015-12-07T21:23:07: === GObservations ===
  114 + 2015-12-07T21:23:07: Number of observations ....: 2
  115 + 2015-12-07T21:23:07: Number of models ..........: 2
  116 + 2015-12-07T21:23:07: Number of predicted events : 0
  117 + 2015-12-07T21:23:07: === GCTAObservation ===
  118 + 2015-12-07T21:23:07: Name ......................: Crab
  119 + 2015-12-07T21:23:07: Identifier ................: 00001
  120 + 2015-12-07T21:23:07: Instrument ................: CTA
  121 + 2015-12-07T21:23:07: Event file ................: events1.fits
  122 + 2015-12-07T21:23:07: Event type ................: EventList
  123 + 2015-12-07T21:23:07: Statistics ................: Poisson
  124 + 2015-12-07T21:23:07: Ontime ....................: 1800 s
  125 + 2015-12-07T21:23:07: Livetime ..................: 1710 s
  126 + 2015-12-07T21:23:07: Deadtime correction .......: 0.95
  127 + 2015-12-07T21:23:07: User energy range .........: undefined
  128 + 2015-12-07T21:23:07: === GCTAPointing ===
  129 + 2015-12-07T21:23:07: Pointing direction ........: (RA,Dec)=(83.63,21.51)
  130 + 2015-12-07T21:23:07: === GCTAResponseIrf ===
  131 + 2015-12-07T21:23:07: Caldb mission .............: cta
  132 + 2015-12-07T21:23:07: Caldb instrument ..........: prod2
  133 + 2015-12-07T21:23:07: Response name .............: South_0.5h
  134 + 2015-12-07T21:23:07: Energy dispersion .........: Not used
  135 + 2015-12-07T21:23:07: Save energy range .........: undefined
  136 + 2015-12-07T21:23:07: === GCTAEventList ===
  137 + 2015-12-07T21:23:07: Number of events ..........: 22593
  138 + 2015-12-07T21:23:07: Time interval .............: 51544.5 - 51544.5 days
  139 + 2015-12-07T21:23:07: Energy interval ...........: 0.1 - 100 TeV
  140 + 2015-12-07T21:23:07: Region of interest ........: RA=83.63, DEC=21.51 [0,0] Radius=5 deg
  141 + 2015-12-07T21:23:07: === GCTAObservation ===
  142 + 2015-12-07T21:23:07: Name ......................: Crab
  143 + 2015-12-07T21:23:07: Identifier ................: 00002
  144 + 2015-12-07T21:23:07: Instrument ................: CTA
  145 + 2015-12-07T21:23:07: Event file ................: events2.fits
  146 + 2015-12-07T21:23:07: Event type ................: EventList
  147 + 2015-12-07T21:23:07: Statistics ................: Poisson
  148 + 2015-12-07T21:23:07: Ontime ....................: 1800 s
  149 + 2015-12-07T21:23:07: Livetime ..................: 1710 s
  150 + 2015-12-07T21:23:07: Deadtime correction .......: 0.95
  151 + 2015-12-07T21:23:07: User energy range .........: undefined
  152 + 2015-12-07T21:23:07: === GCTAPointing ===
  153 + 2015-12-07T21:23:07: Pointing direction ........: (RA,Dec)=(83.63,22.51)
  154 + 2015-12-07T21:23:07: === GCTAResponseIrf ===
  155 + 2015-12-07T21:23:07: Caldb mission .............: cta
  156 + 2015-12-07T21:23:07: Caldb instrument ..........: prod2
  157 + 2015-12-07T21:23:07: Response name .............: South_0.5h
  158 + 2015-12-07T21:23:07: Energy dispersion .........: Not used
  159 + 2015-12-07T21:23:07: Save energy range .........: undefined
  160 + 2015-12-07T21:23:07: === GCTAEventList ===
  161 + 2015-12-07T21:23:07: Number of events ..........: 22529
  162 + 2015-12-07T21:23:07: Time interval .............: 51544.5 - 51544.5 days
  163 + 2015-12-07T21:23:07: Energy interval ...........: 0.1 - 100 TeV
  164 + 2015-12-07T21:23:07: Region of interest ........: RA=83.63, DEC=22.51 [0,0] Radius=5 deg
128 165 ...
129   - 2015-05-22T20:17:07: === GCTAObservation ===
130   - 2015-05-22T20:17:07: Name ......................:
131   - 2015-05-22T20:17:07: Identifier ................: 00002
132   - 2015-05-22T20:17:07: Instrument ................: CTA
133   - 2015-05-22T20:17:07: Event file ................: events2.fits
134   - 2015-05-22T20:17:07: Event type ................: EventList
135   - 2015-05-22T20:17:07: Statistics ................: Poisson
136   - 2015-05-22T20:17:07: Ontime ....................: 1800 s
137   - 2015-05-22T20:17:07: Livetime ..................: 1710 s
138   - 2015-05-22T20:17:07: Deadtime correction .......: 0.95
139   - 2015-05-22T20:17:07: User energy range .........: undefined
140   - 2015-05-22T20:17:07: === GCTAPointing ===
141   - 2015-05-22T20:17:07: Pointing direction ........: (RA,Dec)=(83.63,22.51)
  166 + 2015-12-07T21:23:07: +=================================+
  167 + 2015-12-07T21:23:07: | Maximum likelihood optimisation |
  168 + 2015-12-07T21:23:07: +=================================+
  169 + 2015-12-07T21:23:07: >Iteration 0: -logL=304176.886, Lambda=1.0e-03
  170 + 2015-12-07T21:23:08: >Iteration 1: -logL=304161.799, Lambda=1.0e-03, delta=15.088, max(|grad|)=12.922804 [Index:3]
  171 + 2015-12-07T21:23:08: >Iteration 2: -logL=304161.783, Lambda=1.0e-04, delta=0.015, max(|grad|)=0.098155 [Index:3]
  172 + 2015-12-07T21:23:08: >Iteration 3: -logL=304161.783, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.000598 [Index:3]
142 173 ...
143   - 2015-05-22T20:17:07: +=================================+
144   - 2015-05-22T20:17:07: | Maximum likelihood optimisation |
145   - 2015-05-22T20:17:07: +=================================+
146   - 2015-05-22T20:17:07: >Iteration 0: -logL=201836.657, Lambda=1.0e-03
147   - 2015-05-22T20:17:07: >Iteration 1: -logL=201829.438, Lambda=1.0e-03, delta=7.220, max(|grad|)=22.756507 [Index:7]
148   - 2015-05-22T20:17:07: >Iteration 2: -logL=201829.432, Lambda=1.0e-04, delta=0.005, max(|grad|)=0.086395 [Index:3]
149   - 2015-05-22T20:17:07: >Iteration 3: -logL=201829.432, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.001287 [Index:3]
150   - 2015-05-22T20:17:07:
151   - 2015-05-22T20:17:07: +=========================================+
152   - 2015-05-22T20:17:07: | Maximum likelihood optimization results |
153   - 2015-05-22T20:17:07: +=========================================+
154   - 2015-05-22T20:17:07: === GOptimizerLM ===
155   - 2015-05-22T20:17:07: Optimized function value ..: 201829.432
156   - 2015-05-22T20:17:07: Absolute precision ........: 0.005
157   - 2015-05-22T20:17:07: Acceptable value decrease .: 2
158   - 2015-05-22T20:17:07: Optimization status .......: converged
159   - 2015-05-22T20:17:07: Number of parameters ......: 10
160   - 2015-05-22T20:17:07: Number of free parameters .: 4
161   - 2015-05-22T20:17:07: Number of iterations ......: 3
162   - 2015-05-22T20:17:07: Lambda ....................: 1e-06
163   - 2015-05-22T20:17:07: Maximum log likelihood ....: -201829.432
164   - 2015-05-22T20:17:07: Observed events (Nobs) ...: 31799.000
165   - 2015-05-22T20:17:07: Predicted events (Npred) ..: 31799.000 (Nobs - Npred = 2.67544e-06)
166   - 2015-05-22T20:17:07: === GModels ===
167   - 2015-05-22T20:17:07: Number of models ..........: 2
168   - 2015-05-22T20:17:07: Number of parameters ......: 10
169   - 2015-05-22T20:17:07: === GModelSky ===
170   - 2015-05-22T20:17:07: Name ......................: Crab
171   - 2015-05-22T20:17:07: Instruments ...............: all
172   - 2015-05-22T20:17:07: Instrument scale factors ..: unity
173   - 2015-05-22T20:17:07: Observation identifiers ...: all
174   - 2015-05-22T20:17:07: Model type ................: PointSource
175   - 2015-05-22T20:17:07: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
176   - 2015-05-22T20:17:07: Number of parameters ......: 6
177   - 2015-05-22T20:17:07: Number of spatial par's ...: 2
178   - 2015-05-22T20:17:07: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
179   - 2015-05-22T20:17:07: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
180   - 2015-05-22T20:17:07: Number of spectral par's ..: 3
181   - 2015-05-22T20:17:07: Prefactor ................: 5.8727e-16 +/- 8.04314e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
182   - 2015-05-22T20:17:07: Index ....................: -2.49825 +/- 0.0118418 [-0,-5] (free,scale=-1,gradient)
183   - 2015-05-22T20:17:07: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
184   - 2015-05-22T20:17:07: Number of temporal par's ..: 1
185   - 2015-05-22T20:17:07: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
186   - 2015-05-22T20:17:07: === GCTAModelIrfBackground ===
187   - 2015-05-22T20:17:07: Name ......................: CTABackgroundModel
188   - 2015-05-22T20:17:07: Instruments ...............: CTA
189   - 2015-05-22T20:17:07: Instrument scale factors ..: unity
190   - 2015-05-22T20:17:07: Observation identifiers ...: all
191   - 2015-05-22T20:17:07: Model type ................: "PowerLaw" * "Constant"
192   - 2015-05-22T20:17:07: Number of parameters ......: 4
193   - 2015-05-22T20:17:07: Number of spectral par's ..: 3
194   - 2015-05-22T20:17:07: Prefactor ................: 1.01608 +/- 0.0152751 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
195   - 2015-05-22T20:17:07: Index ....................: 0.0226023 +/- 0.0086794 [-5,5] (free,scale=1,gradient)
196   - 2015-05-22T20:17:07: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
197   - 2015-05-22T20:17:07: Number of temporal par's ..: 1
198   - 2015-05-22T20:17:07: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  174 +
  175 + 2015-12-07T21:23:08: +=========================================+
  176 + 2015-12-07T21:23:08: | Maximum likelihood optimisation results |
  177 + 2015-12-07T21:23:08: +=========================================+
  178 + 2015-12-07T21:23:08: === GOptimizerLM ===
  179 + 2015-12-07T21:23:08: Optimized function value ..: 304161.783
  180 + 2015-12-07T21:23:08: Absolute precision ........: 0.005
  181 + 2015-12-07T21:23:08: Acceptable value decrease .: 2
  182 + 2015-12-07T21:23:08: Optimization status .......: converged
  183 + 2015-12-07T21:23:08: Number of parameters ......: 10
  184 + 2015-12-07T21:23:08: Number of free parameters .: 4
  185 + 2015-12-07T21:23:08: Number of iterations ......: 3
  186 + 2015-12-07T21:23:08: Lambda ....................: 1e-06
  187 + 2015-12-07T21:23:08: Maximum log likelihood ....: -304161.783
  188 + 2015-12-07T21:23:08: Observed events (Nobs) ...: 45122.000
  189 + 2015-12-07T21:23:08: Predicted events (Npred) ..: 45122.000 (Nobs - Npred = 1.04131e-06)
  190 + 2015-12-07T21:23:08: === GModels ===
  191 + 2015-12-07T21:23:08: Number of models ..........: 2
  192 + 2015-12-07T21:23:08: Number of parameters ......: 10
  193 + 2015-12-07T21:23:08: === GModelSky ===
  194 + 2015-12-07T21:23:08: Name ......................: Crab
  195 + 2015-12-07T21:23:08: Instruments ...............: all
  196 + 2015-12-07T21:23:08: Instrument scale factors ..: unity
  197 + 2015-12-07T21:23:08: Observation identifiers ...: all
  198 + 2015-12-07T21:23:08: Model type ................: PointSource
  199 + 2015-12-07T21:23:08: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  200 + 2015-12-07T21:23:08: Number of parameters ......: 6
  201 + 2015-12-07T21:23:08: Number of spatial par's ...: 2
  202 + 2015-12-07T21:23:08: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  203 + 2015-12-07T21:23:08: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  204 + 2015-12-07T21:23:08: Number of spectral par's ..: 3
  205 + 2015-12-07T21:23:08: Prefactor ................: 5.78382e-16 +/- 7.27218e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  206 + 2015-12-07T21:23:08: Index ....................: -2.5314 +/- 0.0112546 [-0,-5] (free,scale=-1,gradient)
  207 + 2015-12-07T21:23:08: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  208 + 2015-12-07T21:23:08: Number of temporal par's ..: 1
  209 + 2015-12-07T21:23:08: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  210 + 2015-12-07T21:23:08: === GCTAModelIrfBackground ===
  211 + 2015-12-07T21:23:08: Name ......................: CTABackgroundModel
  212 + 2015-12-07T21:23:08: Instruments ...............: CTA
  213 + 2015-12-07T21:23:08: Instrument scale factors ..: unity
  214 + 2015-12-07T21:23:08: Observation identifiers ...: all
  215 + 2015-12-07T21:23:08: Model type ................: "PowerLaw" * "Constant"
  216 + 2015-12-07T21:23:08: Number of parameters ......: 4
  217 + 2015-12-07T21:23:08: Number of spectral par's ..: 3
  218 + 2015-12-07T21:23:08: Prefactor ................: 1.0008 +/- 0.00839192 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  219 + 2015-12-07T21:23:08: Index ....................: 0.0102998 +/- 0.0051965 [-5,5] (free,scale=1,gradient)
  220 + 2015-12-07T21:23:08: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  221 + 2015-12-07T21:23:08: Number of temporal par's ..: 1
  222 + 2015-12-07T21:23:08: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
199 223  
200 224 The log file indicates that the fit converged quickly, the spectral
201 225 parameters of the Crab nebula have now been constrained using the events
... ...
doc/source/user_manual/getting_started/beyond_irf.rst
  View file @a4a4190
... ... @@ -6,9 +6,9 @@ Connecting observations to dedicated instrument response functions
6 6 So far the same instrument response function has been used for all
7 7 observations in our analysis examples.
8 8 You may have recognised that we always specified the calibration database
9   -``prod2`` and the instrument response function ``South_50h`` that
  9 +``prod2`` and the instrument response function ``South_0.5h`` that
10 10 are shipped with ctools.
11   -When combining multiple observations in a joint analysis we may however
  11 +When combining multiple observations in a joint analysis you may however
12 12 need to specify dedicated instrument response functions for the
13 13 different observations.
14 14  
... ... @@ -26,40 +26,40 @@ the northern array and the other with the southern array:
26 26 Lower energy limit (TeV) [0.1]
27 27 Upper energy limit (TeV) [100.0]
28 28 Calibration database [prod2]
29   - Instrument response function [South_50h] North_50h
30   - Model [$CTOOLS/share/models/crab.xml]
31   - Output event data file or observation definition file [events.fits] events1.fits
  29 + Instrument response function [South_0.5h] North_0.5h
  30 + Input model XML file [$CTOOLS/share/models/crab.xml]
  31 + Output event data file or observation definition XML file [events.fits] north.fits
32 32  
33 33 .. code-block:: bash
34 34  
35 35 $ ctobssim
36 36 RA of pointing (degrees) (0-360) [83.63]
37   - Dec of pointing (degrees) (-90-90) [22.01] 22.51
  37 + Dec of pointing (degrees) (-90-90) [21.51] 22.51
38 38 Radius of FOV (degrees) (0-180) [5.0]
39 39 Start time (MET in s) [0.0]
40 40 End time (MET in s) [1800.0]
41 41 Lower energy limit (TeV) [0.1]
42 42 Upper energy limit (TeV) [100.0]
43 43 Calibration database [prod2]
44   - Instrument response function [North_50h] South_50h
45   - Model [$CTOOLS/share/models/crab.xml]
46   - Output event data file or observation definition file [events1.fits] events2.fits
  44 + Instrument response function [North_0.5h] South_0.5h
  45 + Input model XML file [$CTOOLS/share/models/crab.xml]
  46 + Output event data file or observation definition XML file [north.fits] south.fits
47 47  
48   -Now we combine the information about these two observations in an
  48 +You now need to combine the information about these two observations in an
49 49 observation definition XML file:
50 50  
51 51 .. code-block:: xml
52 52  
53   - <?xml version="1.0" standalone="no"?>
54   - <observation_list title="observation library">
55   - <observation name="Crab" id="00001" instrument="CTA">
56   - <parameter name="EventList" file="events1.fits"/>
57   - <parameter name="Calibration" database="prod2" response="North_50h"/>
58   - </observation>
59   - <observation name="Crab" id="00002" instrument="CTA">
60   - <parameter name="EventList" file="events2.fits"/>
61   - <parameter name="Calibration" database="prod2" response="South_50h"/>
62   - </observation>
  53 + <?xml version="1.0" standalone="no"?>
  54 + <observation_list title="observation library">
  55 + <observation name="Crab" id="00001" instrument="CTA">
  56 + <parameter name="EventList" file="north.fits"/>
  57 + <parameter name="Calibration" database="prod2" response="North_0.5h"/>
  58 + </observation>
  59 + <observation name="Crab" id="00002" instrument="CTA">
  60 + <parameter name="EventList" file="south.fits"/>
  61 + <parameter name="Calibration" database="prod2" response="South_0.5h"/>
  62 + </observation>
63 63 </observation_list>
64 64  
65 65 Each observation now has a ``Calibration`` parameter with the attributes
... ... @@ -97,126 +97,136 @@ Within this database there are six response functions:
97 97 ``North_0.5h``, ``North_5h``, ``North_50h``,
98 98 ``South_0.5h``, ``South_5h``, and ``South_50h``.
99 99  
100   -We now jointly fit both observations using :ref:`ctlike`:
  100 +You now jointly fit both observations using :ref:`ctlike`:
101 101  
102 102 .. code-block:: bash
103 103  
104   - $ ctlike
105   - Event list, counts cube or observation definition file [obs.xml] obs_irf.xml
106   - Source model [$CTOOLS/share/models/crab.xml]
107   - Source model output file [crab_results.xml]
  104 + $ ctlike chatter=3
  105 + Input event list, counts cube or observation definition XML file [events.fits] obs_irf.xml
  106 + Input model XML file [$CTOOLS/share/models/crab.xml]
  107 + Output model XML file [crab_results.xml]
108 108  
109 109 To see the usage of the individual response functions you may inspect the
110   -log file. You will notice that each observation now has a specific response
  110 +log file (you need to set ``chatter=3`` to see the details of the
  111 +observations in the log file).
  112 +You will notice that each observation now has a specific response
111 113 function and that the filename of the response information differs for
112 114 both observations.
113 115  
114 116 .. code-block:: xml
115 117  
116   - 2015-05-22T22:06:43: +==============+
117   - 2015-05-22T22:06:43: | Observations |
118   - 2015-05-22T22:06:43: +==============+
119   - 2015-05-22T22:06:43: === GObservations ===
120   - 2015-05-22T22:06:43: Number of observations ....: 2
121   - 2015-05-22T22:06:43: Number of predicted events : 0
122   - 2015-05-22T22:06:43: === GCTAObservation ===
123   - 2015-05-22T22:06:43: Name ......................:
124   - 2015-05-22T22:06:43: Identifier ................: 00001
125   - 2015-05-22T22:06:43: Instrument ................: CTA
126   - 2015-05-22T22:06:43: Event file ................: events1.fits
127   - 2015-05-22T22:06:43: Event type ................: EventList
128   - 2015-05-22T22:06:43: Statistics ................: Poisson
129   - 2015-05-22T22:06:43: Ontime ....................: 1800 s
130   - 2015-05-22T22:06:43: Livetime ..................: 1710 s
131   - 2015-05-22T22:06:43: Deadtime correction .......: 0.95
132   - 2015-05-22T22:06:43: User energy range .........: undefined
133   - 2015-05-22T22:06:43: === GCTAPointing ===
134   - 2015-05-22T22:06:43: Pointing direction ........: (RA,Dec)=(83.63,21.51)
135   - 2015-05-22T22:06:43: === GCTAResponseIrf ===
136   - 2015-05-22T22:06:43: Caldb mission .............: cta
137   - 2015-05-22T22:06:43: Caldb instrument ..........: prod2
138   - 2015-05-22T22:06:43: Response name .............: North_50h
139   - 2015-05-22T22:06:43: Energy dispersion .........: Not used
140   - 2015-05-22T22:06:43: Save energy range .........: undefined
  118 + 2015-12-07T22:22:18: +==============+
  119 + 2015-12-07T22:22:18: | Observations |
  120 + 2015-12-07T22:22:18: +==============+
  121 + 2015-12-07T22:22:18: === GObservations ===
  122 + 2015-12-07T22:22:18: Number of observations ....: 2
  123 + 2015-12-07T22:22:18: Number of models ..........: 2
  124 + 2015-12-07T22:22:18: Number of predicted events : 0
  125 + 2015-12-07T22:22:18: === GCTAObservation ===
  126 + 2015-12-07T22:22:18: Name ......................: Crab
  127 + 2015-12-07T22:22:18: Identifier ................: 00001
  128 + 2015-12-07T22:22:18: Instrument ................: CTA
  129 + 2015-12-07T22:22:18: Event file ................: north.fits
  130 + 2015-12-07T22:22:18: Event type ................: EventList
  131 + 2015-12-07T22:22:18: Statistics ................: Poisson
  132 + 2015-12-07T22:22:18: Ontime ....................: 1800 s
  133 + 2015-12-07T22:22:18: Livetime ..................: 1710 s
  134 + 2015-12-07T22:22:18: Deadtime correction .......: 0.95
  135 + 2015-12-07T22:22:18: User energy range .........: undefined
  136 + 2015-12-07T22:22:18: === GCTAPointing ===
  137 + 2015-12-07T22:22:18: Pointing direction ........: (RA,Dec)=(83.63,21.51)
  138 + 2015-12-07T22:22:18: === GCTAResponseIrf ===
  139 + 2015-12-07T22:22:18: Caldb mission .............: cta
  140 + 2015-12-07T22:22:18: Caldb instrument ..........: prod2
  141 + 2015-12-07T22:22:18: Response name .............: North_0.5h
  142 + 2015-12-07T22:22:18: Energy dispersion .........: Not used
  143 + 2015-12-07T22:22:18: Save energy range .........: undefined
  144 + 2015-12-07T22:22:18: === GCTAEventList ===
  145 + 2015-12-07T22:22:18: Number of events ..........: 8469
  146 + 2015-12-07T22:22:18: Time interval .............: 51544.5 - 51544.5 days
  147 + 2015-12-07T22:22:18: Energy interval ...........: 0.1 - 100 TeV
  148 + 2015-12-07T22:22:18: Region of interest ........: RA=83.63, DEC=21.51 [0,0] Radius=5 deg
  149 + 2015-12-07T22:22:18: === GCTAObservation ===
  150 + 2015-12-07T22:22:18: Name ......................: Crab
  151 + 2015-12-07T22:22:18: Identifier ................: 00002
  152 + 2015-12-07T22:22:18: Instrument ................: CTA
  153 + 2015-12-07T22:22:18: Event file ................: south.fits
  154 + 2015-12-07T22:22:18: Event type ................: EventList
  155 + 2015-12-07T22:22:18: Statistics ................: Poisson
  156 + 2015-12-07T22:22:18: Ontime ....................: 1800 s
  157 + 2015-12-07T22:22:18: Livetime ..................: 1710 s
  158 + 2015-12-07T22:22:18: Deadtime correction .......: 0.95
  159 + 2015-12-07T22:22:18: User energy range .........: undefined
  160 + 2015-12-07T22:22:18: === GCTAPointing ===
  161 + 2015-12-07T22:22:18: Pointing direction ........: (RA,Dec)=(83.63,22.51)
  162 + 2015-12-07T22:22:18: === GCTAResponseIrf ===
  163 + 2015-12-07T22:22:18: Caldb mission .............: cta
  164 + 2015-12-07T22:22:18: Caldb instrument ..........: prod2
  165 + 2015-12-07T22:22:18: Response name .............: South_0.5h
  166 + 2015-12-07T22:22:18: Energy dispersion .........: Not used
  167 + 2015-12-07T22:22:18: Save energy range .........: undefined
  168 + 2015-12-07T22:22:18: === GCTAEventList ===
  169 + 2015-12-07T22:22:18: Number of events ..........: 22529
  170 + 2015-12-07T22:22:18: Time interval .............: 51544.5 - 51544.5 days
  171 + 2015-12-07T22:22:18: Energy interval ...........: 0.1 - 100 TeV
  172 + 2015-12-07T22:22:18: Region of interest ........: RA=83.63, DEC=22.51 [0,0] Radius=5 deg
141 173 ...
142   - 2015-05-22T22:06:43: === GCTAObservation ===
143   - 2015-05-22T22:06:43: Name ......................:
144   - 2015-05-22T22:06:43: Identifier ................: 00002
145   - 2015-05-22T22:06:43: Instrument ................: CTA
146   - 2015-05-22T22:06:43: Event file ................: events2.fits
147   - 2015-05-22T22:06:43: Event type ................: EventList
148   - 2015-05-22T22:06:43: Statistics ................: Poisson
149   - 2015-05-22T22:06:43: Ontime ....................: 1800 s
150   - 2015-05-22T22:06:43: Livetime ..................: 1710 s
151   - 2015-05-22T22:06:43: Deadtime correction .......: 0.95
152   - 2015-05-22T22:06:43: User energy range .........: undefined
153   - 2015-05-22T22:06:43: === GCTAPointing ===
154   - 2015-05-22T22:06:43: Pointing direction ........: (RA,Dec)=(83.63,22.51)
155   - 2015-05-22T22:06:43: === GCTAResponseIrf ===
156   - 2015-05-22T22:06:43: Caldb mission .............: cta
157   - 2015-05-22T22:06:43: Caldb instrument ..........: prod2
158   - 2015-05-22T22:06:43: Response name .............: South_50h
159   - 2015-05-22T22:06:43: Energy dispersion .........: Not used
160   - 2015-05-22T22:06:43: Save energy range .........: undefined
  174 + 2015-12-07T22:22:18: +=================================+
  175 + 2015-12-07T22:22:18: | Maximum likelihood optimisation |
  176 + 2015-12-07T22:22:18: +=================================+
  177 + 2015-12-07T22:22:18: >Iteration 0: -logL=214691.468, Lambda=1.0e-03
  178 + 2015-12-07T22:22:18: >Iteration 1: -logL=214679.380, Lambda=1.0e-03, delta=12.088, max(|grad|)=9.713100 [Index:3]
  179 + 2015-12-07T22:22:18: >Iteration 2: -logL=214679.365, Lambda=1.0e-04, delta=0.015, max(|grad|)=0.092975 [Index:3]
  180 + 2015-12-07T22:22:18: >Iteration 3: -logL=214679.365, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.000749 [Index:3]
161 181 ...
162   - 2015-05-22T22:06:43: +=================================+
163   - 2015-05-22T22:06:43: | Maximum likelihood optimisation |
164   - 2015-05-22T22:06:43: +=================================+
165   - 2015-05-22T22:06:43: >Iteration 0: -logL=138039.472, Lambda=1.0e-03
166   - 2015-05-22T22:06:43: >Iteration 1: -logL=138035.501, Lambda=1.0e-03, delta=3.971, max(|grad|)=16.203761 [Index:7]
167   - 2015-05-22T22:06:43: >Iteration 2: -logL=138035.496, Lambda=1.0e-04, delta=0.005, max(|grad|)=-0.053284 [Index:7]
168   - 2015-05-22T22:06:43: >Iteration 3: -logL=138035.496, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.001386 [Index:7]
169   - 2015-05-22T22:06:44:
170   - 2015-05-22T22:06:44: +=========================================+
171   - 2015-05-22T22:06:44: | Maximum likelihood optimization results |
172   - 2015-05-22T22:06:44: +=========================================+
173   - 2015-05-22T22:06:44: === GOptimizerLM ===
174   - 2015-05-22T22:06:44: Optimized function value ..: 138035.496
175   - 2015-05-22T22:06:44: Absolute precision ........: 0.005
176   - 2015-05-22T22:06:44: Acceptable value decrease .: 2
177   - 2015-05-22T22:06:44: Optimization status .......: converged
178   - 2015-05-22T22:06:44: Number of parameters ......: 10
179   - 2015-05-22T22:06:44: Number of free parameters .: 4
180   - 2015-05-22T22:06:44: Number of iterations ......: 3
181   - 2015-05-22T22:06:44: Lambda ....................: 1e-06
182   - 2015-05-22T22:06:44: Maximum log likelihood ....: -138035.496
183   - 2015-05-22T22:06:44: Observed events (Nobs) ...: 20814.000
184   - 2015-05-22T22:06:44: Predicted events (Npred) ..: 20814.000 (Nobs - Npred = 2.67698e-06)
185   - 2015-05-22T22:06:44: === GModels ===
186   - 2015-05-22T22:06:44: Number of models ..........: 2
187   - 2015-05-22T22:06:44: Number of parameters ......: 10
188   - 2015-05-22T22:06:44: === GModelSky ===
189   - 2015-05-22T22:06:44: Name ......................: Crab
190   - 2015-05-22T22:06:44: Instruments ...............: all
191   - 2015-05-22T22:06:44: Instrument scale factors ..: unity
192   - 2015-05-22T22:06:44: Observation identifiers ...: all
193   - 2015-05-22T22:06:44: Model type ................: PointSource
194   - 2015-05-22T22:06:44: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
195   - 2015-05-22T22:06:44: Number of parameters ......: 6
196   - 2015-05-22T22:06:44: Number of spatial par's ...: 2
197   - 2015-05-22T22:06:44: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
198   - 2015-05-22T22:06:44: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
199   - 2015-05-22T22:06:44: Number of spectral par's ..: 3
200   - 2015-05-22T22:06:44: Prefactor ................: 5.9184e-16 +/- 9.68924e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
201   - 2015-05-22T22:06:44: Index ....................: -2.49569 +/- 0.0145376 [-0,-5] (free,scale=-1,gradient)
202   - 2015-05-22T22:06:44: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
203   - 2015-05-22T22:06:44: Number of temporal par's ..: 1
204   - 2015-05-22T22:06:44: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
205   - 2015-05-22T22:06:44: === GCTAModelIrfBackground ===
206   - 2015-05-22T22:06:44: Name ......................: CTABackgroundModel
207   - 2015-05-22T22:06:44: Instruments ...............: CTA
208   - 2015-05-22T22:06:44: Instrument scale factors ..: unity
209   - 2015-05-22T22:06:44: Observation identifiers ...: all
210   - 2015-05-22T22:06:44: Model type ................: "PowerLaw" * "Constant"
211   - 2015-05-22T22:06:44: Number of parameters ......: 4
212   - 2015-05-22T22:06:44: Number of spectral par's ..: 3
213   - 2015-05-22T22:06:44: Prefactor ................: 1.02524 +/- 0.0182054 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
214   - 2015-05-22T22:06:44: Index ....................: 0.0229728 +/- 0.0104713 [-5,5] (free,scale=1,gradient)
215   - 2015-05-22T22:06:44: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
216   - 2015-05-22T22:06:44: Number of temporal par's ..: 1
217   - 2015-05-22T22:06:44: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
218   -
219   -
  182 + 2015-12-07T22:22:18: +=========================================+
  183 + 2015-12-07T22:22:18: | Maximum likelihood optimisation results |
  184 + 2015-12-07T22:22:18: +=========================================+
  185 + 2015-12-07T22:22:18: === GOptimizerLM ===
  186 + 2015-12-07T22:22:18: Optimized function value ..: 214679.365
  187 + 2015-12-07T22:22:18: Absolute precision ........: 0.005
  188 + 2015-12-07T22:22:18: Acceptable value decrease .: 2
  189 + 2015-12-07T22:22:18: Optimization status .......: converged
  190 + 2015-12-07T22:22:18: Number of parameters ......: 10
  191 + 2015-12-07T22:22:18: Number of free parameters .: 4
  192 + 2015-12-07T22:22:18: Number of iterations ......: 3
  193 + 2015-12-07T22:22:18: Lambda ....................: 1e-06
  194 + 2015-12-07T22:22:18: Maximum log likelihood ....: -214679.365
  195 + 2015-12-07T22:22:18: Observed events (Nobs) ...: 30998.000
  196 + 2015-12-07T22:22:18: Predicted events (Npred) ..: 30998.000 (Nobs - Npred = 1.02755e-06)
  197 + 2015-12-07T22:22:18: === GModels ===
  198 + 2015-12-07T22:22:18: Number of models ..........: 2
  199 + 2015-12-07T22:22:18: Number of parameters ......: 10
  200 + 2015-12-07T22:22:18: === GModelSky ===
  201 + 2015-12-07T22:22:18: Name ......................: Crab
  202 + 2015-12-07T22:22:18: Instruments ...............: all
  203 + 2015-12-07T22:22:18: Instrument scale factors ..: unity
  204 + 2015-12-07T22:22:18: Observation identifiers ...: all
  205 + 2015-12-07T22:22:18: Model type ................: PointSource
  206 + 2015-12-07T22:22:18: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  207 + 2015-12-07T22:22:18: Number of parameters ......: 6
  208 + 2015-12-07T22:22:18: Number of spatial par's ...: 2
  209 + 2015-12-07T22:22:18: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  210 + 2015-12-07T22:22:18: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  211 + 2015-12-07T22:22:18: Number of spectral par's ..: 3
  212 + 2015-12-07T22:22:18: Prefactor ................: 5.81237e-16 +/- 8.63534e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  213 + 2015-12-07T22:22:18: Index ....................: -2.53954 +/- 0.0137432 [-0,-5] (free,scale=-1,gradient)
  214 + 2015-12-07T22:22:18: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  215 + 2015-12-07T22:22:18: Number of temporal par's ..: 1
  216 + 2015-12-07T22:22:18: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  217 + 2015-12-07T22:22:18: === GCTAModelIrfBackground ===
  218 + 2015-12-07T22:22:18: Name ......................: CTABackgroundModel
  219 + 2015-12-07T22:22:18: Instruments ...............: CTA
  220 + 2015-12-07T22:22:18: Instrument scale factors ..: unity
  221 + 2015-12-07T22:22:18: Observation identifiers ...: all
  222 + 2015-12-07T22:22:18: Model type ................: "PowerLaw" * "Constant"
  223 + 2015-12-07T22:22:18: Number of parameters ......: 4
  224 + 2015-12-07T22:22:18: Number of spectral par's ..: 3
  225 + 2015-12-07T22:22:18: Prefactor ................: 1.01067 +/- 0.0103997 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  226 + 2015-12-07T22:22:18: Index ....................: 0.0135414 +/- 0.0064452 [-5,5] (free,scale=1,gradient)
  227 + 2015-12-07T22:22:18: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  228 + 2015-12-07T22:22:18: Number of temporal par's ..: 1
  229 + 2015-12-07T22:22:18: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
220 230  
221 231 A more fine grained control over the response function can be achieved by
222 232 specifying individual filenames for the various response components.
... ... @@ -228,18 +238,18 @@ This is definitely expert mode, to be used with utmost care.
228 238 <?xml version="1.0" standalone="no"?>
229 239 <observation_list title="observation library">
230 240 <observation name="Crab" id="00001" instrument="CTA">
231   - <parameter name="EventList" file="events1.fits"/>
232   - <parameter name="EffectiveArea" file="$(CALDB)/data/cta/prod2/bcf/North_50h/irf_file.fits.gz"/>
233   - <parameter name="PointSpreadFunction" file="$(CALDB)/data/cta/prod2/bcf/North_50h/irf_file.fits.gz"/>
234   - <parameter name="EnergyDispersion" file="$(CALDB)/data/cta/prod2/bcf/North_50h/irf_file.fits.gz"/>
235   - <parameter name="Background" file="$(CALDB)/data/cta/prod2/bcf/North_50h/irf_file.fits.gz"/>
  241 + <parameter name="EventList" file="north.fits"/>
  242 + <parameter name="EffectiveArea" file="$(CALDB)/data/cta/prod2/bcf/North_0.5h/irf_file.fits.gz"/>
  243 + <parameter name="PointSpreadFunction" file="$(CALDB)/data/cta/prod2/bcf/North_0.5h/irf_file.fits.gz"/>
  244 + <parameter name="EnergyDispersion" file="$(CALDB)/data/cta/prod2/bcf/North_0.5h/irf_file.fits.gz"/>
  245 + <parameter name="Background" file="$(CALDB)/data/cta/prod2/bcf/North_0.5h/irf_file.fits.gz"/>
236 246 </observation>
237 247 <observation name="Crab" id="00002" instrument="CTA">
238   - <parameter name="EventList" file="events2.fits"/>
239   - <parameter name="EffectiveArea" file="$(CALDB)/data/cta/prod2/bcf/South_50h/irf_file.fits.gz"/>
240   - <parameter name="PointSpreadFunction" file="$(CALDB)/data/cta/prod2/bcf/South_50h/irf_file.fits.gz"/>
241   - <parameter name="EnergyDispersion" file="$(CALDB)/data/cta/prod2/bcf/South_50h/irf_file.fits.gz"/>
242   - <parameter name="Background" file="$(CALDB)/data/cta/prod2/bcf/South_50h/irf_file.fits.gz"/>
  248 + <parameter name="EventList" file="south.fits"/>
  249 + <parameter name="EffectiveArea" file="$(CALDB)/data/cta/prod2/bcf/South_0.5h/irf_file.fits.gz"/>
  250 + <parameter name="PointSpreadFunction" file="$(CALDB)/data/cta/prod2/bcf/South_0.5h/irf_file.fits.gz"/>
  251 + <parameter name="EnergyDispersion" file="$(CALDB)/data/cta/prod2/bcf/South_0.5h/irf_file.fits.gz"/>
  252 + <parameter name="Background" file="$(CALDB)/data/cta/prod2/bcf/South_0.5h/irf_file.fits.gz"/>
243 253 </observation>
244 254 </observation_list>
245 255  
... ... @@ -264,5 +274,3 @@ file is given below:
264 274 <parameter name="BkgCube" file="bkgcube2.fits"/>
265 275 </observation>
266 276 </observation_list>
267   -
268   -
... ...
doc/source/user_manual/getting_started/beyond_model.rst
  View file @a4a4190
... ... @@ -26,20 +26,15 @@ specified by the following observation definition XML file:
26 26 </observation>
27 27 </observation_list>
28 28  
29   -Each observation has a **unique identifier string** and we can use this
30   -unique string to connect that observation to a specific model component.
  29 +Each observation has a **unique identifier string** and you can use this
  30 +unique string to connect an observation to a specific model component.
31 31 This is illustrated in the model XML file below that now has two background
32 32 components.
33   -**Model components in a XML file need to have a unique name**, for this
34   -reason we have named the components ``Background_00001`` and
35   -``Background_00002``.
36   -Both components now have an ``id`` attribute that ties the model to
37   -an observation.
38   -In other words, the model is only applicable to a specific observation
39   -(it will be ignored for all other observations).
40   -In our case, model ``Background_00001`` applies to the ``events1.fits``
41   -event list while model ``Background_00002`` applies to the ``events2.fits``
42   -event list.
  33 +Both components have an ``id`` attribute that ties the model to a specific
  34 +observation.
  35 +Using ``id="00001"``, the first background model is tied to the
  36 +``events1.fits`` file, using ``id="00002"``, the second background model is
  37 +tied to the ``events2.fits`` file.
43 38  
44 39 .. code-block:: xml
45 40  
... ... @@ -72,13 +67,21 @@ event list.
72 67 </source>
73 68 </source_library>
74 69  
75   -Note that both background model components distinguish in their event rate;
76   -component ``Background_00002`` has a ten times larger background rate than
77   -component ``Background_00001``.
78   -To illustrate this difference, we simulated two observations offset by
79   -+/- 2 degrees from the Crab nebulae using :ref:`ctobssim`.
80   -We then performed a joint fit of the observations using :ref:`ctlike`
81   -and created a resdiual map using :ref:`csresmap` that is shown below.
  70 +.. note::
  71 +
  72 + **Model components in a XML file need to have a unique name.**
  73 + For this reason the components are named here ``Background_00001``
  74 + and ``Background_00002``.
  75 +
  76 +Note that both background model components distinguish in their event rate.
  77 +``Background_00002`` has a ten times larger background rate than
  78 +``Background_00001``.
  79 +To illustrate this difference, two observations offset by +/- 2 degrees from
  80 +the Crab nebulae have been simulated using :ref:`ctobssim`.
  81 +A joint fit of the observations is then performed using :ref:`ctlike` and
  82 +a residual map is created using :ref:`csresmap`.
  83 +
  84 +The result is shown below.
82 85 Obviously, the upper observation has larger residuals owing to the ten
83 86 times larger background rate that was used in the simulation of the
84 87 associated data.
... ...
doc/source/user_manual/getting_started/beyond_residual.rst
  View file @a4a4190
... ... @@ -22,11 +22,11 @@ Suppose that you have done the following unbinned ``ctlike`` analysis:
22 22 .. code-block:: bash
23 23  
24 24 $ ctlike
25   - Event list, counts cube or observation definition file [events.fits] obs.xml
  25 + Input event list, counts cube or observation definition XML file [events.fits] obs.xml
26 26 Calibration database [prod2]
27   - Instrument response function [South_50h]
28   - Source model [$CTOOLS/share/models/crab.xml]
29   - Source model output file [crab_results.xml]
  27 + Instrument response function [South_0.5h]
  28 + Input model XML file [$CTOOLS/share/models/crab.xml]
  29 + Output model XML file [crab_results.xml]
30 30  
31 31 The :ref:`csresmap` script is then used as follows:
32 32  
... ... @@ -34,18 +34,19 @@ The :ref:`csresmap` script is then used as follows:
34 34  
35 35 $ csresmap
36 36 Parfile csresmap.par not found. Create default parfile.
37   - Event list, counts cube, or observation definition file [events.fits] obs.xml
  37 + Input event list, counts cube, or observation definition XML file [events.fits] obs.xml
38 38 Calibration database [prod2]
39   - Instrument response function [South_50h]
40   - Source model [$CTOOLS/share/models/crab.xml] crab_results.xml
41   - Output residual map [resmap.fits]
42   - First coordinate of image center in degrees (RA or galactic l) [83.63]
43   - Second coordinate of image center in degrees (DEC or galactic b) [22.01]
  39 + Instrument response function [South_0.5h]
  40 + Input model XML file [$CTOOLS/share/models/crab.xml] crab_results.xml
  41 + First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
  42 + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
44 43 Coordinate System (CEL|GAL) [CEL]
45   - Projection method e.g. AIT|AZP|CAR|MER|MOL|STG|TAN (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
  44 + Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
46 45 Size of the X axis in pixels [200]
47 46 Size of the Y axis in pixels [200]
48 47 Pixel size (deg/pixel) [0.02]
  48 + Output residual map file [resmap.fits]
  49 + Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUBDIV]
49 50  
50 51 In our example, the map will cover a field of 4 x 4 degrees centred on the
51 52 Crab nebula at a pixel scale of 0.02 degrees per pixel.
... ...
doc/source/user_manual/getting_started/beyond_stacked.rst
  View file @a4a4190
... ... @@ -6,16 +6,15 @@ Performing a stacked analysis
6 6 A stacked analysis is a binned analysis where all data from multiple
7 7 observations are stacked into a single counts cube.
8 8 The event stacking is done using the :ref:`ctbin` tool.
9   -Instead of providing to :ref:`ctbin` an event list we
10   -now specify the observation definition XML file ``obs.xml``
11   -on input.
  9 +Instead of providing to :ref:`ctbin` an event list you should now
  10 +specify the observation definition XML file ``obs.xml`` on input.
12 11 :ref:`ctbin` will then loop over all observations and collect all events
13 12 into a single counts cube:
14 13  
15 14 .. code-block:: bash
16 15  
17 16 $ ctbin
18   - Event list or observation definition file [events.fits] obs.xml
  17 + Input event list or observation definition XML file [events.fits] obs.xml
19 18 First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
20 19 Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
21 20 Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
... ... @@ -27,37 +26,37 @@ into a single counts cube:
27 26 Start value for first energy bin in TeV [0.1]
28 27 Stop value for last energy bin in TeV [100.0]
29 28 Number of energy bins [20]
30   - Output counts cube [cntcube.fits]
  29 + Output counts cube file [cntcube.fits]
31 30  
32   -We now have a stacked counts cube ``cntcube.fits`` on disk.
33   -Before we can use that counts cube in a maximum likelihood
34   -analysis, we have to compute the instrument response and the
  31 +You now have a stacked counts cube ``cntcube.fits`` on disk.
  32 +Before you can use that counts cube in a maximum likelihood
  33 +analysis, you have to compute the instrument response and the
35 34 background model that are needed to describe the stacked data.
36 35  
37   -For the former, we have to compute the total exposure for the stacked
  36 +For the former, you have to compute the total exposure for the stacked
38 37 cube (i.e. the sum of the effective areas for each observation multiplied
39 38 by the corresponding livetimes) and an effective point spread function
40 39 (i.e. the point spread function of the different observations weighted by
41 40 the corresponding exposures).
42   -To get both informations we use the :ref:`ctexpcube` and
  41 +To get both informations you use the :ref:`ctexpcube` and
43 42 :ref:`ctpsfcube` tools:
44 43  
45 44 .. code-block:: bash
46 45  
47 46 $ ctexpcube
48   - Event list or observation definition file [NONE] obs.xml
  47 + Input event list or observation definition XML file [NONE] obs.xml
49 48 Calibration database [prod2]
50   - Instrument response function [South_50h]
51   - Counts cube for exposure cube definition [NONE] cntcube.fits
  49 + Instrument response function [South_0.5h]
  50 + Input counts cube file to extract exposure cube definition [NONE] cntcube.fits
52 51 Output exposure cube file [expcube.fits]
53 52  
54 53 .. code-block:: bash
55 54  
56 55 $ ctpsfcube
57   - Event list or observation definition file [NONE] obs.xml
  56 + Input event list or observation definition XML file [NONE] obs.xml
58 57 Calibration database [prod2]
59   - Instrument response function [South_50h]
60   - Counts cube for psf cube definition [NONE]
  58 + Instrument response function [South_0.5h]
  59 + Input counts cube file to extract PSF cube definition [NONE]
61 60 First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
62 61 Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
63 62 Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
... ... @@ -68,42 +67,41 @@ To get both informations we use the :ref:`ctexpcube` and
68 67 Lower energy limit (TeV) [0.1]
69 68 Upper energy limit (TeV) [100.0]
70 69 Number of energy bins [20]
71   - Output psf cube file [psfcube.fits]
72   -
73   -We provide the ``obs.xml`` file on input to inform both tools which
74   -observations have been combined.
75   -For :ref:`ctexpcube` we further provide the counts cube so that the
76   -tool can copy the exposure cube definition (number of spatial pixels
77   -and pixel size, number of energy bins) from the counts cube.
78   -This minimises the number of further user parameters that need to be
79   -provided and assures an exposure cube that is compatible with the counts
80   -cube.
81   -For :ref:`ctpsfcube` we do not use the counts cube for the PSF cube
82   -definition as this would lead to a hugh file owing to the fine spatial
  70 + Output PSF cube file [psfcube.fits]
  71 +
  72 +The ``obs.xml`` file has been provided on input to specify for both tools
  73 +which observations have been combined.
  74 +You further provided the counts cube on input so that :ref:`ctexpcube` can
  75 +read the cub definition from that file and apply it to the exposure cube.
  76 +This is a trick to reduce the number of user parameters that you need to
  77 +provide.
  78 +
  79 +You do not apply this trick when using :ref:`ctpsfcube` as this
  80 +would lead to a hugh output file owing to the fine spatial
83 81 pixelisation of the counts cube.
84   -Since the PSF evolves only slowly over the field of fiew, we provide a
85   -rather coarse spatial binning of 1 degree covering a grid of 10 x 10
86   -degrees around the centre of the counts cube.
87   -For the energy binning, we use the same logarithmic binning that has
88   -also been used for the counts cube.
  82 +Such a fine binning is not needed for the PSF cube, as the PSF evolves
  83 +only slowly over the field of view.
  84 +It is thus sufficient to compute a PSF cube with a rather coarse spatial
  85 +binning; here you used a spatial binning of 1 degree covering a grid of
  86 +10 x 10 degrees.
89 87  
90   -As final step of the analysis preparation, we need to generate a
  88 +As final step of the analysis preparation, you need to generate a
91 89 background cube using the :ref:`ctbkgcube` tool:
92 90  
93 91 .. code-block:: bash
94 92  
95 93 $ ctbkgcube
96   - Input event list or observation definition file [NONE] obs.xml
  94 + Input event list or observation definition XML file [NONE] obs.xml
97 95 Calibration database [prod2]
98   - Instrument response function [South_50h]
99   - Counts cube for background cube definition [NONE] cntcube.fits
  96 + Instrument response function [South_0.5h]
  97 + Input counts cube file to extract background cube definition [NONE] cntcube.fits
100 98 Input model XML file [NONE] $CTOOLS/share/models/crab.xml
101 99 Output background cube file [bkgcube.fits]
102 100 Output model XML file [NONE] model.xml
103 101  
104 102 The usage of :ref:`ctbkgcube` is very similar to that of :ref:`ctexpcube`,
105 103 yet it takes the model XML file as an additional input parameter.
106   -We here use the usual ``$CTOOLS/share/models/crab.xml`` model
  104 +You used here the usual ``$CTOOLS/share/models/crab.xml`` model
107 105 file that is shipped with the ctools.
108 106 :ref:`ctbkgcube` provides on output the background cube file
109 107 ``bkgcube.fits`` and the model XML file ``model.xml`` that can
... ... @@ -115,7 +113,7 @@ modelling works:
115 113  
116 114 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
117 115 <source_library title="source library">
118   - <source name="Crab" type="PointSource" tscalc="0">
  116 + <source name="Crab" type="PointSource">
119 117 <spectrum type="PowerLaw">
120 118 <parameter name="Prefactor" value="5.7" error="0" scale="1e-16" min="1e-07" max="1000" free="1" />
121 119 <parameter name="Index" value="2.48" error="0" scale="-1" min="0" max="5" free="1" />
... ... @@ -157,88 +155,88 @@ as an appropriate multiplicator to the background cube.
157 155 Using the same binning for the exposure cube, the background cube and
158 156 the counts cube is only a convenience.
159 157  
160   -Now we have all files at hand to launch a stacked maximum likelihood
  158 +Now you have all files at hand to perform a stacked maximum likelihood
161 159 analysis using the :ref:`ctlike` tool:
162 160  
163 161 .. code-block:: bash
164 162  
165 163 $ ctlike
166   - Event list, counts cube or observation definition file [obs.xml] cntcube.fits
167   - Exposure cube file (only needed for stacked analysis) [NONE] expcube.fits
168   - PSF cube file (only needed for stacked analysis) [NONE] psfcube.fits
169   - Background cube file (only needed for stacked analysis) [NONE] bkgcube.fits
170   - Source model [$CTOOLS/share/models/crab.xml] model.xml
171   - Source model output file [crab_results.xml]
  164 + Input event list, counts cube or observation definition XML file [obs.xml] cntcube.fits
  165 + Input exposure cube file (only needed for stacked analysis) [NONE] expcube.fits
  166 + Input PSF cube file (only needed for stacked analysis) [NONE] psfcube.fits
  167 + Input background cube file (only needed for stacked analysis) [NONE] bkgcube.fits
  168 + Input model XML file [$CTOOLS/share/models/crab.xml] model.xml
  169 + Output model XML file [crab_results.xml]
172 170  
173 171 :ref:`ctlike` recognises that a counts cube should be analysed and queries
174 172 for the exposure cube, the PSF cube, and the background cube file names.
175   -We specified the names of the files produced by the :ref:`ctexpcube`,
  173 +You specified here the names of the files produced by the :ref:`ctexpcube`,
176 174 the :ref:`ctpsfcube` and the :ref:`ctbkgcube` tools.
177   -Furthermore we provided as model the ``model.xml`` file that has been
  175 +Furthermore you provided as model the ``model.xml`` file that has been
178 176 generated by the :ref:`ctbkgcube` tool.
179 177  
180 178 The log file of the :ref:`ctlike` run is shown below.
181 179 Note that the spectral model that is multiplied with the background
182   -cube has a Prefactor of 1.09 +/- 0.02 and an Index of 0.03 +/- 0.01,
  180 +cube has a Prefactor of 0.998 +/- 0.011 and an Index of 0.006 +/- 0.007,
183 181 indicating a very small correction to the actual spectrum of the background
184 182 cube.
185 183 Real life situations may of course require larger correction factors.
186 184  
187 185 .. code-block:: xml
188 186  
189   - 2015-05-22T21:10:09: +=================================+
190   - 2015-05-22T21:10:09: | Maximum likelihood optimisation |
191   - 2015-05-22T21:10:09: +=================================+
192   - 2015-05-22T21:10:10: >Iteration 0: -logL=60663.798, Lambda=1.0e-03
193   - 2015-05-22T21:10:11: >Iteration 1: -logL=60642.413, Lambda=1.0e-03, delta=21.385, max(|grad|)=120.031102 [Index:7]
194   - 2015-05-22T21:10:13: >Iteration 2: -logL=60642.233, Lambda=1.0e-04, delta=0.180, max(|grad|)=1.139187 [Index:7]
195   - 2015-05-22T21:10:14: >Iteration 3: -logL=60642.233, Lambda=1.0e-05, delta=0.000, max(|grad|)=-0.001247 [Index:7]
196   - 2015-05-22T21:10:16:
197   - 2015-05-22T21:10:16: +=========================================+
198   - 2015-05-22T21:10:16: | Maximum likelihood optimization results |
199   - 2015-05-22T21:10:16: +=========================================+
200   - 2015-05-22T21:10:16: === GOptimizerLM ===
201   - 2015-05-22T21:10:16: Optimized function value ..: 60642.233
202   - 2015-05-22T21:10:16: Absolute precision ........: 0.005
203   - 2015-05-22T21:10:16: Acceptable value decrease .: 2
204   - 2015-05-22T21:10:16: Optimization status .......: converged
205   - 2015-05-22T21:10:16: Number of parameters ......: 10
206   - 2015-05-22T21:10:16: Number of free parameters .: 4
207   - 2015-05-22T21:10:16: Number of iterations ......: 3
208   - 2015-05-22T21:10:16: Lambda ....................: 1e-06
209   - 2015-05-22T21:10:16: Maximum log likelihood ....: -60642.233
210   - 2015-05-22T21:10:16: Observed events (Nobs) ...: 25963.000
211   - 2015-05-22T21:10:16: Predicted events (Npred) ..: 25963.000 (Nobs - Npred = 1.5749e-05)
212   - 2015-05-22T21:10:16: === GModels ===
213   - 2015-05-22T21:10:16: Number of models ..........: 2
214   - 2015-05-22T21:10:16: Number of parameters ......: 10
215   - 2015-05-22T21:10:16: === GModelSky ===
216   - 2015-05-22T21:10:16: Name ......................: Crab
217   - 2015-05-22T21:10:16: Instruments ...............: all
218   - 2015-05-22T21:10:16: Instrument scale factors ..: unity
219   - 2015-05-22T21:10:16: Observation identifiers ...: all
220   - 2015-05-22T21:10:16: Model type ................: PointSource
221   - 2015-05-22T21:10:16: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
222   - 2015-05-22T21:10:16: Number of parameters ......: 6
223   - 2015-05-22T21:10:16: Number of spatial par's ...: 2
224   - 2015-05-22T21:10:16: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
225   - 2015-05-22T21:10:16: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
226   - 2015-05-22T21:10:16: Number of spectral par's ..: 3
227   - 2015-05-22T21:10:16: Prefactor ................: 5.8499e-16 +/- 8.02289e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
228   - 2015-05-22T21:10:16: Index ....................: -2.49909 +/- 0.0118976 [-0,-5] (free,scale=-1,gradient)
229   - 2015-05-22T21:10:16: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
230   - 2015-05-22T21:10:16: Number of temporal par's ..: 1
231   - 2015-05-22T21:10:16: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
232   - 2015-05-22T21:10:16: === GCTAModelCubeBackground ===
233   - 2015-05-22T21:10:16: Name ......................: BackgroundModel
234   - 2015-05-22T21:10:16: Instruments ...............: CTA, HESS, MAGIC, VERITAS
235   - 2015-05-22T21:10:16: Instrument scale factors ..: unity
236   - 2015-05-22T21:10:16: Observation identifiers ...: all
237   - 2015-05-22T21:10:16: Model type ................: "PowerLaw" * "Constant"
238   - 2015-05-22T21:10:16: Number of parameters ......: 4
239   - 2015-05-22T21:10:16: Number of spectral par's ..: 3
240   - 2015-05-22T21:10:16: Prefactor ................: 1.08781 +/- 0.0212678 [0,infty[ ph/cm2/s/MeV (free,scale=1,gradient)
241   - 2015-05-22T21:10:16: Index ....................: 0.0269681 +/- 0.0111532 [-10,10] (free,scale=1,gradient)
242   - 2015-05-22T21:10:16: PivotEnergy ..............: 1e+06 MeV (fixed,scale=1e+06,gradient)
243   - 2015-05-22T21:10:16: Number of temporal par's ..: 1
244   - 2015-05-22T21:10:16: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  187 + 2015-12-07T21:37:45: +=================================+
  188 + 2015-12-07T21:37:45: | Maximum likelihood optimisation |
  189 + 2015-12-07T21:37:45: +=================================+
  190 + 2015-12-07T21:37:46: >Iteration 0: -logL=83748.453, Lambda=1.0e-03
  191 + 2015-12-07T21:37:47: >Iteration 1: -logL=83736.039, Lambda=1.0e-03, delta=12.413, max(|grad|)=15.134616 [Index:3]
  192 + 2015-12-07T21:37:48: >Iteration 2: -logL=83736.021, Lambda=1.0e-04, delta=0.018, max(|grad|)=0.108613 [Index:3]
  193 + 2015-12-07T21:37:49: >Iteration 3: -logL=83736.021, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.000570 [Index:3]
  194 + ...
  195 + 2015-12-07T21:37:51: +=========================================+
  196 + 2015-12-07T21:37:51: | Maximum likelihood optimisation results |
  197 + 2015-12-07T21:37:51: +=========================================+
  198 + 2015-12-07T21:37:51: === GOptimizerLM ===
  199 + 2015-12-07T21:37:51: Optimized function value ..: 83736.021
  200 + 2015-12-07T21:37:51: Absolute precision ........: 0.005
  201 + 2015-12-07T21:37:51: Acceptable value decrease .: 2
  202 + 2015-12-07T21:37:51: Optimization status .......: converged
  203 + 2015-12-07T21:37:51: Number of parameters ......: 10
  204 + 2015-12-07T21:37:51: Number of free parameters .: 4
  205 + 2015-12-07T21:37:51: Number of iterations ......: 3
  206 + 2015-12-07T21:37:51: Lambda ....................: 1e-06
  207 + 2015-12-07T21:37:51: Maximum log likelihood ....: -83736.021
  208 + 2015-12-07T21:37:51: Observed events (Nobs) ...: 35198.000
  209 + 2015-12-07T21:37:51: Predicted events (Npred) ..: 35198.000 (Nobs - Npred = 7.6773e-07)
  210 + 2015-12-07T21:37:51: === GModels ===
  211 + 2015-12-07T21:37:51: Number of models ..........: 2
  212 + 2015-12-07T21:37:51: Number of parameters ......: 10
  213 + 2015-12-07T21:37:51: === GModelSky ===
  214 + 2015-12-07T21:37:51: Name ......................: Crab
  215 + 2015-12-07T21:37:51: Instruments ...............: all
  216 + 2015-12-07T21:37:51: Instrument scale factors ..: unity
  217 + 2015-12-07T21:37:51: Observation identifiers ...: all
  218 + 2015-12-07T21:37:51: Model type ................: PointSource
  219 + 2015-12-07T21:37:51: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  220 + 2015-12-07T21:37:51: Number of parameters ......: 6
  221 + 2015-12-07T21:37:51: Number of spatial par's ...: 2
  222 + 2015-12-07T21:37:51: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  223 + 2015-12-07T21:37:51: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  224 + 2015-12-07T21:37:51: Number of spectral par's ..: 3
  225 + 2015-12-07T21:37:51: Prefactor ................: 5.75289e-16 +/- 7.24749e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  226 + 2015-12-07T21:37:51: Index ....................: -2.53122 +/- 0.0113068 [-0,-5] (free,scale=-1,gradient)
  227 + 2015-12-07T21:37:51: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  228 + 2015-12-07T21:37:51: Number of temporal par's ..: 1
  229 + 2015-12-07T21:37:51: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  230 + 2015-12-07T21:37:51: === GCTAModelCubeBackground ===
  231 + 2015-12-07T21:37:51: Name ......................: BackgroundModel
  232 + 2015-12-07T21:37:51: Instruments ...............: CTA, HESS, MAGIC, VERITAS
  233 + 2015-12-07T21:37:51: Instrument scale factors ..: unity
  234 + 2015-12-07T21:37:51: Observation identifiers ...: all
  235 + 2015-12-07T21:37:51: Model type ................: "PowerLaw" * "Constant"
  236 + 2015-12-07T21:37:51: Number of parameters ......: 4
  237 + 2015-12-07T21:37:51: Number of spectral par's ..: 3
  238 + 2015-12-07T21:37:51: Prefactor ................: 0.998055 +/- 0.0114979 [0.01,100] ph/cm2/s/MeV (free,scale=1,gradient)
  239 + 2015-12-07T21:37:51: Index ....................: 0.00648796 +/- 0.00697365 [-5,5] (free,scale=1,gradient)
  240 + 2015-12-07T21:37:51: PivotEnergy ..............: 1e+06 MeV (fixed,scale=1e+06,gradient)
  241 + 2015-12-07T21:37:51: Number of temporal par's ..: 1
  242 + 2015-12-07T21:37:51: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
... ...
doc/source/user_manual/getting_started/beyond_tsmap.rst
  View file @a4a4190
... ... @@ -3,13 +3,14 @@
3 3 Generating a Test Statistic map
4 4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5 5  
6   -In the above examples we were always considering that we knew exactly
  6 +In the above examples you have always considering that you knew exactly
7 7 where the source is located, but in real life situations this may not
8 8 necessarily be the case.
9   -We thus need a means to search for significant excess emission in our data.
  9 +You thus need a means to search for significant excess emission in your data.
10 10 One possibility to accomplish this task is to compute the Test Statistic
11 11 for a specific source at a grid of trial positions.
12 12 The :ref:`cttsmap` tool will exactly do that job.
  13 +
13 14 The Test Statistic is defined as twice the log-likelihood difference
14 15 between fitting a source at a given position on top of a model or fitting
15 16 no source.
... ... @@ -18,7 +19,7 @@ the source detection significance in Gaussian sigmas, although the
18 19 exact relation depends somewhat on the formulation of the statistical
19 20 problem.
20 21  
21   -Here an example where we apply the :ref:`cttsmap` tool to our two
  22 +Here an example of how to apply the :ref:`cttsmap` tool to the two
22 23 simulated observations of the Crab in unbinned mode.
23 24 On input we provide a source model XML file and the name of the source
24 25 in the XML file that should be moved on a grid of test positions.
... ... @@ -31,11 +32,11 @@ nominal position of the Crab nebula with a grid spacing of 0.02 degrees.
31 32 .. code-block:: bash
32 33  
33 34 $ cttsmap
34   - Input event list, counts cube or observation definition file [events.fits] obs.xml
  35 + Input event list, counts cube or observation definition XML file [events.fits] obs.xml
35 36 Calibration database [prod2]
36   - Instrument response function [South_50h]
37   - Source model [$CTOOLS/share/models/crab.xml]
38   - Test source [Crab]
  37 + Instrument response function [South_0.5h]
  38 + Input model XML file [$CTOOLS/share/models/crab.xml]
  39 + Test source name [Crab]
39 40 First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
40 41 Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
41 42 Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
... ... @@ -43,14 +44,14 @@ nominal position of the Crab nebula with a grid spacing of 0.02 degrees.
43 44 Image scale (in degrees/pixel) [0.02]
44 45 Size of the X axis in pixels [200] 10
45 46 Size of the Y axis in pixels [200] 10
46   - Output Test Statistic map [tsmap.fits]
  47 + Output Test Statistic map file [tsmap.fits]
47 48  
48 49 :ref:`cttsmap` writes the Test Statistic map in the ``tsmap.fits`` file
49 50 that contains one extension for the Test Statistic value and further
50 51 extensions for the spectral parameters that have been fitted for the
51 52 source at each position of the grid.
52 53 The figure below show the Test Statistic map which reaches a maximum
53   -value of 37484 near the centre of the map.
  54 +value of 40733 near the centre of the map.
54 55  
55 56 .. figure:: tsmap-crab.png
56 57 :height: 400px
... ...
doc/source/user_manual/getting_started/binning.rst 0 → 100644
  View file @a4a4190
  1 +.. _sec_binning_cta:
  2 +
  3 +Binning CTA data
  4 +~~~~~~~~~~~~~~~~
  5 +
  6 +As next analysis step you will bin the data in a counts cube using
  7 +:ref:`ctbin`.
  8 +A counts cube is a 3 dimensional data cube, spanned by
  9 +Right Ascension (or Galactic longitude), Declination (or Galactic latitude),
  10 +and energy (typically logarithmically spaced, but this is under user
  11 +control).
  12 +
  13 +:ref:`ctbin` is executed by typing:
  14 +
  15 +.. code-block:: bash
  16 +
  17 + $ ctbin
  18 + Input event list or observation definition XML file [events.fits]
  19 + First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
  20 + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
  21 + Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
  22 + Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL]
  23 + Image scale (in degrees/pixel) [0.02]
  24 + Size of the X axis in pixels [200]
  25 + Size of the Y axis in pixels [200]
  26 + Algorithm for defining energy bins (FILE|LIN|LOG) [LOG]
  27 + Start value for first energy bin in TeV [0.1]
  28 + Stop value for last energy bin in TeV [100.0]
  29 + Number of energy bins [20]
  30 + Output counts cube file [cntcube.fits]
  31 +
  32 +The counts cube will be centred on the location of the Crab (Right Ascension
  33 +83.63 degrees, Declination 22.01 degrees) and will be aligned in celestial
  34 +coordinates. A cartesian projection has been selected. The counts cube has
  35 +200 x 200 spatial pixels of 0.02 x 0.02 degrees in size, hence it covers a
  36 +total area of 4 x 4 degrees.
  37 +
  38 +The counts cube will contain 20 maps, which are logarithmically spaced
  39 +in energy, and which cover the energy range from 0.1 TeV to 100 TeV. In this
  40 +example, the counts cube will be saved as ``cntcube.fits`` in the working
  41 +directory. In addition to the counts cube, that is stored as the primary
  42 +image extension, the FITS file also contains an extension named ``EBOUNDS``
  43 +that defines the energy boundaries that were used, and an extension ``GTI``
  44 +that defines the Good Time Intervals that have been used. The following
  45 +image shows the resulting FITS file. The ``EBOUNDS`` table has 20 rows, one
  46 +for each energy bin, while the ``GTI`` table has just a single row, indicating
  47 +the start and stop time of the simulated data.
  48 +
  49 +.. figure:: cntmap-fits.jpg
  50 + :width: 600px
  51 + :align: center
  52 +
  53 + *Counts cube FITS file*
  54 +
  55 +
  56 +An image of the first bin, covering the energy range 100 - 141 GeV, is
  57 +shown below:
  58 +
  59 +.. figure:: cntmap-map.jpg
  60 + :height: 400px
  61 + :align: center
  62 +
  63 + *Counts cube for first energy bin*
  64 +
  65 +For illustration, the last few lines of the log file ``ctbin.log`` are
  66 +reproduced below:
  67 +
  68 +.. code-block:: xml
  69 +
  70 + 2015-12-07T20:52:41: +=================+
  71 + 2015-12-07T20:52:41: | Bin observation |
  72 + 2015-12-07T20:52:41: +=================+
  73 + 2015-12-07T20:52:41: === CTA observation ===
  74 + 2015-12-07T20:52:41: Events in list ............: 22685
  75 + 2015-12-07T20:52:41: Events in cube ............: 18195
  76 + 2015-12-07T20:52:41: Event bins outside RoI ....: 0
  77 + 2015-12-07T20:52:41: Events outside cube area ..: 4490
  78 + 2015-12-07T20:52:41: Events outside energy bins : 0
  79 +
  80 +From the 22685 events that have been simulated and stored in the
  81 +``events.fits`` file, 18195 lie within the cube boundaries and are thus put
  82 +into the resulting counts cube. The counts cube is stored in a cartesian
  83 +projection in a World Coordinate System (WCS) compliant format.
... ...
doc/source/user_manual/getting_started/butterfly.rst 0 → 100644
  View file @a4a4190
  1 +.. _sec_butterfly_cta:
  2 +
  3 +Calculating and visualising a butterfly diagram
  4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  5 +
  6 +To visualise the analysis results you can compute a butterfly diagram
  7 +which shows the confidence band of the spectral fit using the
  8 +:ref:`ctbutterfly` tool.
  9 +The butterfly diagram is the envelope of all power law models
  10 +that are within a given confidence limit compatible with the data.
  11 +By default a confidence level of 68% is used, but the level can be adjusted
  12 +using the hidden ``confidence`` parameter.
  13 +:ref:`ctbutterfly` computes this envelope by evaluating for each energy the
  14 +minimum and maximum intensity of all power law models that fall within the
  15 +error ellipse of the prefactor and index parameters.
  16 +The error ellipse is derived from the covariance matrix of a maximum
  17 +likelihood fit.
  18 +
  19 +The following example illustrates how you can use the :ref:`ctbutterfly`
  20 +tool:
  21 +
  22 +.. code-block:: bash
  23 +
  24 + $ ctbutterfly
  25 + Input event list, counts cube or observation definition XML file [events.fits]
  26 + Calibration database [prod2]
  27 + Instrument response function [South_0.5h]
  28 + Input model XML file [$CTOOLS/share/models/crab.xml] crab_results.xml
  29 + Source of interest [Crab]
  30 + Start value for first energy bin in TeV [0.1]
  31 + Stop value for last energy bin in TeV [100.0]
  32 + Output ASCII file [butterfly.txt]
  33 +
  34 +Now that you have computed the confidence band of the spectral fit and
  35 +that you will have an ASCII file named ``butterfly.txt`` on disk you can
  36 +visualise the butterfly using the script ``show_butterfly.py`` that is
  37 +in the ctools ``example`` folder. You will need matplotlib on your system
  38 +to make this work. To launch the script, type:
  39 +
  40 +.. code-block:: bash
  41 +
  42 + python $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt
  43 +
  44 +This will result in a canvas which should look like the following:
  45 +
  46 +.. figure:: butterfly.jpg
  47 + :height: 400px
  48 + :align: center
  49 +
  50 + *Confidence band of the fit*
  51 +
0 52 \ No newline at end of file
... ...
doc/source/user_manual/getting_started/fitting.rst 0 → 100644
  View file @a4a4190
  1 +.. _sec_fitting_cta:
  2 +
  3 +Fitting CTA data
  4 +~~~~~~~~~~~~~~~~
  5 +
  6 +Now we are ready to fit the simulated data with a model. For simplicity
  7 +we use in this example the same model that we used to simulate the data
  8 +with :ref:`ctobssim`. Model fitting is done using the :ref:`ctlike` tool,
  9 +and we do the fit by typing:
  10 +
  11 +.. code-block:: bash
  12 +
  13 + $ ctlike
  14 + Input event list, counts cube or observation definition XML file [events.fits] cntcube.fits
  15 + Input exposure cube file (only needed for stacked analysis) [NONE]
  16 + Input PSF cube file (only needed for stacked analysis) [NONE]
  17 + Input background cube file (only needed for stacked analysis) [NONE]
  18 + Calibration database [prod2]
  19 + Instrument response function [South_0.5h]
  20 + Input model XML file [$CTOOLS/share/models/crab.xml]
  21 + Output model XML file [crab_results.xml]
  22 +
  23 +The data are fitted in *binned* mode, which means that the events
  24 +have been binned into a counts cube and the fit computes the log-likelihood
  25 +function by summing over all 200 x 200 x 20 bins of the counts cube. There is
  26 +an alternative method, the so called *unbinned* mode, where the events are
  27 +not binned into a counts cube and the log-likelihood is computed directly by
  28 +summing over all events. We will explore the *unbinned* mode later.
  29 +
  30 +One of the parameters of :ref:`ctlike` is a source model output file
  31 +(we specified ``crab_results.xml`` in the example), and this file will be
  32 +a copy of the source model input XML file where the parameter values have
  33 +been replaced by the fit results. In addition, the statistical uncertainties
  34 +are added for each fitted parameter using the attribute ``error``.
  35 +Below we show the XML result file that has been produced by the run:
  36 +
  37 +.. code-block:: xml
  38 +
  39 + <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  40 + <source_library title="source library">
  41 + <source name="Crab" type="PointSource">
  42 + <spectrum type="PowerLaw">
  43 + <parameter name="Prefactor" value="5.78443" error="0.101348" scale="1e-16" min="1e-07" max="1000" free="1" />
  44 + <parameter name="Index" value="2.50664" error="0.0153631" scale="-1" min="0" max="5" free="1" />
  45 + <parameter name="Scale" value="0.3" scale="1e+06" min="0.01" max="1000" free="0" />
  46 + </spectrum>
  47 + <spatialModel type="SkyDirFunction">
  48 + <parameter name="RA" value="83.6331" scale="1" min="-360" max="360" free="0" />
  49 + <parameter name="DEC" value="22.0145" scale="1" min="-90" max="90" free="0" />
  50 + </spatialModel>
  51 + </source>
  52 + <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
  53 + <spectrum type="PowerLaw">
  54 + <parameter name="Prefactor" value="0.993018" error="0.0160113" scale="1" min="0.001" max="1000" free="1" />
  55 + <parameter name="Index" value="0.00269761" error="0.00973921" scale="1" min="-5" max="5" free="1" />
  56 + <parameter name="Scale" value="1" scale="1e+06" min="0.01" max="1000" free="0" />
  57 + </spectrum>
  58 + </source>
  59 + </source_library>
  60 +
  61 +In this example, the ``Prefactor`` and ``Index`` of the spectral model for the
  62 +Crab as well as the ``Prefactor`` and ``Index`` of the background spectral
  63 +model have been fitted (all parameters having the attribute ``free="1"`` are
  64 +fitted). Now we see also the effect of having multiplied the background
  65 +model with a power law. In that way, the amplitude of the background as
  66 +well as it's spectral slope is adjusted by the fit. Obviously, in this
  67 +example the adjustment compensates only for the statistical fluctuations
  68 +of the background, but with real data, the adjustment may account also for
  69 +some of the systematic uncertainties.
  70 +
  71 +.. warning::
  72 +
  73 + As good practice, the amplitude of the background model should always be
  74 + left as a free parameter of the fit. Otherwise, any uncertainty in the
  75 + background rate will immediately propagate into the flux estimate of the
  76 + source.
  77 +
  78 +To get more details about the model fitting you can inspect the log file.
  79 +Below the last lines of the ctlike.log log file that has been produced by
  80 +this run:
  81 +
  82 +.. code-block:: xml
  83 +
  84 + 2015-12-07T20:55:32: +=================================+
  85 + 2015-12-07T20:55:32: | Maximum likelihood optimisation |
  86 + 2015-12-07T20:55:32: +=================================+
  87 + 2015-12-07T20:55:33: >Iteration 0: -logL=54877.412, Lambda=1.0e-03
  88 + 2015-12-07T20:55:35: >Iteration 1: -logL=54875.025, Lambda=1.0e-03, delta=2.387, max(|grad|)=1.856683 [Index:7]
  89 + 2015-12-07T20:55:36: >Iteration 2: -logL=54875.024, Lambda=1.0e-04, delta=0.001, max(|grad|)=-0.024661 [Index:3]
  90 + 2015-12-07T20:55:36:
  91 + ...
  92 + 2015-12-07T20:55:38: +=========================================+
  93 + 2015-12-07T20:55:38: | Maximum likelihood optimisation results |
  94 + 2015-12-07T20:55:38: +=========================================+
  95 + 2015-12-07T20:55:38: === GOptimizerLM ===
  96 + 2015-12-07T20:55:38: Optimized function value ..: 54875.024
  97 + 2015-12-07T20:55:38: Absolute precision ........: 0.005
  98 + 2015-12-07T20:55:38: Acceptable value decrease .: 2
  99 + 2015-12-07T20:55:38: Optimization status .......: converged
  100 + 2015-12-07T20:55:38: Number of parameters ......: 10
  101 + 2015-12-07T20:55:38: Number of free parameters .: 4
  102 + 2015-12-07T20:55:38: Number of iterations ......: 2
  103 + 2015-12-07T20:55:38: Lambda ....................: 1e-05
  104 + 2015-12-07T20:55:38: Maximum log likelihood ....: -54875.024
  105 + 2015-12-07T20:55:38: Observed events (Nobs) ...: 18195.000
  106 + 2015-12-07T20:55:38: Predicted events (Npred) ..: 18194.999 (Nobs - Npred = 0.00146383)
  107 + 2015-12-07T20:55:38: === GModels ===
  108 + 2015-12-07T20:55:38: Number of models ..........: 2
  109 + 2015-12-07T20:55:38: Number of parameters ......: 10
  110 + 2015-12-07T20:55:38: === GModelSky ===
  111 + 2015-12-07T20:55:38: Name ......................: Crab
  112 + 2015-12-07T20:55:38: Instruments ...............: all
  113 + 2015-12-07T20:55:38: Instrument scale factors ..: unity
  114 + 2015-12-07T20:55:38: Observation identifiers ...: all
  115 + 2015-12-07T20:55:38: Model type ................: PointSource
  116 + 2015-12-07T20:55:38: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  117 + 2015-12-07T20:55:38: Number of parameters ......: 6
  118 + 2015-12-07T20:55:38: Number of spatial par's ...: 2
  119 + 2015-12-07T20:55:38: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  120 + 2015-12-07T20:55:38: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  121 + 2015-12-07T20:55:38: Number of spectral par's ..: 3
  122 + 2015-12-07T20:55:38: Prefactor ................: 5.78443e-16 +/- 1.01348e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  123 + 2015-12-07T20:55:38: Index ....................: -2.50664 +/- 0.0153631 [-0,-5] (free,scale=-1,gradient)
  124 + 2015-12-07T20:55:38: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  125 + 2015-12-07T20:55:38: Number of temporal par's ..: 1
  126 + 2015-12-07T20:55:38: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  127 + 2015-12-07T20:55:38: === GCTAModelIrfBackground ===
  128 + 2015-12-07T20:55:38: Name ......................: CTABackgroundModel
  129 + 2015-12-07T20:55:38: Instruments ...............: CTA
  130 + 2015-12-07T20:55:38: Instrument scale factors ..: unity
  131 + 2015-12-07T20:55:38: Observation identifiers ...: all
  132 + 2015-12-07T20:55:38: Model type ................: "PowerLaw" * "Constant"
  133 + 2015-12-07T20:55:38: Number of parameters ......: 4
  134 + 2015-12-07T20:55:38: Number of spectral par's ..: 3
  135 + 2015-12-07T20:55:38: Prefactor ................: 0.993018 +/- 0.0160113 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  136 + 2015-12-07T20:55:38: Index ....................: 0.00269761 +/- 0.00973921 [-5,5] (free,scale=1,gradient)
  137 + 2015-12-07T20:55:38: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  138 + 2015-12-07T20:55:38: Number of temporal par's ..: 1
  139 + 2015-12-07T20:55:38: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  140 +
  141 +The maximum likelihood optimizer required 2 iterations to converge. This
  142 +is pretty fast, but recall that we used the same model file for the simulation
  143 +and for fitting, hence the initial parameter values were already very close
  144 +to the best fitting values. To see the impact of the initial parameters on
  145 +the fit result, you may re-run :ref:`ctlike` using another copy of the model
  146 +XML file where you change the value attributes of the parameters that should be
  147 +fitted. You will see that the optimizer requires a couple of more iterations,
  148 +but it should converge to the same solution (provided that the initial values
  149 +are not too far from the best fitting values).
  150 +
  151 +.. note::
  152 +
  153 + As sanity check you should verify that the predicted number of events
  154 + (Npred) is equal to the observed number of events (Nobs). To facilitate
  155 + this comparison, :ref:`ctlike` provides the difference Nobs - Npred in
  156 + the log file. In real life situations, this difference may not always be
  157 + small, in particular if the source model is too constrained. You may
  158 + then free some of the model parameters so that the fit can correctly
  159 + describe the data.
  160 +
  161 +.. note::
  162 +
  163 + The :ref:`ctlike` tool has the ability to estimate the detection
  164 + significance for sources in the XML model. This is done by computing
  165 + the Test Statistic value which is defined as twice the log-likelihood
  166 + difference between fitting a source at a given position on top of a
  167 + (background) model or fitting no source. Roughly speaken, the square
  168 + root of the Test Statistic value gives the source detection significance
  169 + in Gaussian sigmas, although the exact relation depends somewhat on
  170 + the formulation of the statistical problem.
  171 +
  172 + To instruct :ref:`ctlike` to compute the Test Statistic value for a
  173 + given source you need to add the attribute ``tscalc="1"`` to the XML
  174 + file:
  175 +
  176 + .. code-block:: xml
  177 +
  178 + <source name="Crab" type="PointSource" tscalc="1">
  179 +
  180 + :ref:`ctlike` will then compute the Test Statistic value for that
  181 + source and dump the result in the log file:
  182 +
  183 + .. code-block:: xml
  184 +
  185 + 2015-12-07T20:58:45: === GModelSky ===
  186 + 2015-12-07T20:58:45: Name ......................: Crab
  187 + 2015-12-07T20:58:45: Instruments ...............: all
  188 + 2015-12-07T20:58:45: Test Statistic ............: 21164.4
  189 +
  190 + The Test Statistic value will also be added as new attribute
  191 + ``ts`` to the XML result file:
  192 +
  193 + .. code-block:: xml
  194 +
  195 + <source name="Crab" type="PointSource" ts="21164.384" tscalc="1">
... ...
doc/source/user_manual/getting_started/quickstart.rst
  View file @a4a4190
1 1 .. _quickstart:
2 2  
3   -A quick ctools tutorial
4   ------------------------
5   -
6 3 First steps with ctools
7   -~~~~~~~~~~~~~~~~~~~~~~~
8   -
9   -This section provides a step-by-step description of the CTA data analysis
10   -procedure implemented in ctools. In this example we will simulate data for
11   -the Crab nebula, observed on-axis, as a single source in the CTA field of
12   -view.
13   -
14   -The example consists of the following analysis steps:
15   -
16   -- :ref:`sec_simulating_cta`
17   -
18   -- :ref:`sec_binning_cta`
19   -
20   -- :ref:`sec_fitting_cta`
21   -
22   -- :ref:`sec_unbinned_cta`
23   -
24   -- :ref:`sec_butterfly_cta`
25   -
26   -
27   -.. _sec_simulating_cta:
28   -
29   -Simulating CTA data
30   -~~~~~~~~~~~~~~~~~~~
31   -
32   -CTA data are simulated using the :ref:`ctobssim` tool. To invoke the tool,
33   -type :ref:`ctobssim` at the console prompt (which is denoted by ``$``).
34   -:ref:`ctobssim` will query for a number of parameters:
35   -
36   -.. code-block:: bash
37   -
38   - $ ctobssim
39   - RA of pointing (degrees) (0-360) [83.63]
40   - Dec of pointing (degrees) (-90-90) [22.01]
41   - Radius of FOV (degrees) (0-180) [5.0]
42   - Start time (MET in s) [0.0]
43   - End time (MET in s) [1800.0]
44   - Lower energy limit (TeV) [0.1]
45   - Upper energy limit (TeV) [100.0]
46   - Calibration database [prod2]
47   - Instrument response function [South_50h]
48   - Model [$CTOOLS/share/models/crab.xml]
49   - Output event data file or observation definition file [events.fits]
50   -
51   -Each line represents a query for one parameter value.
52   -The line starts with a short description of the parameter, followed by
53   -the default value proposed by ctobssim in squared brackets ``[ ]``.
54   -**If no parameter is entered the default value will be used**
55   -(which is the case for all parameters shown here).
56   -Otherwise, the specified value will overwrite the default value.
57   -The round brackets ``( )`` indicate the range of possible parameter
58   -values (if applicable).
59   -
60   -
61   -You may have recognised that the environment variable ``$CTOOLS`` has
62   -been used in the path name of the model. ctools will automatically expand
63   -the environment variables in parameter inputs.
64   -
65   -The CTA instrument properties (effective area, PSF width) are taken from
66   -the prod2 database. The response for the southern array using the cuts
67   -optimised for 50 hours of observing time are used.
68   -
69   -.. note::
70   -
71   - ctools comes bundled with CTA response functions for the northern and
72   - the southern array. The response functions are based on a Prod2
73   - analysis with cuts optimised for 0.5 hours, 5 hours and 50 hours of
74   - observing time. The following Instrument Response Functions
75   - (IRFs) are available: ``North_0.5h``, ``North_5h``, ``North_50h``,
76   - ``South_0.5h``, ``South_5h``, and ``South_50h``.
77   -
78   -Events are simulated based on the instrument properties and based on a
79   -source and background model. Only events that fall within the specified
80   -region of interest (ROI), defined as a circle around a sky position in
81   -Right Ascension and Declination (in degrees), will be stored in the output
82   -event data file. The duration of the simulation is taken here to 30 minutes
83   -(or 1800 seconds). Events are simulated for energies between 0.1 and 100 TeV.
84   -
85   -The source and background model is defined by the XML file
86   -``$CTOOLS/share/models/crab.xml``:
87   -
88   -.. code-block:: xml
89   -
90   - <?xml version="1.0" standalone="no"?>
91   - <source_library title="source library">
92   - <source name="Crab" type="PointSource">
93   - <spectrum type="PowerLaw">
94   - <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/>
95   - <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/>
96   - <parameter name="Scale" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/>
97   - </spectrum>
98   - <spatialModel type="SkyDirFunction">
99   - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="0"/>
100   - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="0"/>
101   - </spatialModel>
102   - </source>
103   - <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
104   - <spectrum type="PowerLaw">
105   - <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-3" max="1e+3" free="1"/>
106   - <parameter name="Index" scale="1.0" value="0.0" min="-5.0" max="+5.0" free="1"/>
107   - <parameter name="Scale" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
108   - </spectrum>
109   - </source>
110   - </source_library>
111   -
112   -The model consists of a source library that contains two components:
113   -the Crab nebula and an instrumental background model.
114   -
115   -The Crab nebula is modelled by a factorized sky model that has a spectral
116   -and a spatial component (tags ``<spectrum>`` and ``<spatialModel>``,
117   -respectively). The spectrum is modelled by a power law, which is defined by
118   -three parameters: the ``Prefactor``, the ``Index`` and the ``Scale``.
119   -The spatial model has two parameters: Right Ascension in degrees (``RA``), and
120   -Declination in degrees (``DEC``). Each parameter has a value and a scale factor,
121   -the real value of the parameter being the product ``value * scale``. Typically,
122   -``scale`` is chosen so that ``value`` is of the order of 1 (this is relevant for
123   -model fitting). In addition, ``value`` is bound by a minimum (``min``) and
124   -maximum (``max``) value, and a parameter may be free (``free="1"``) or fixed
125   -(``free="0"``). The ``min``, ``max``, and ``free`` attributes are not
126   -relevant here for the simulations, but they will be important for the model
127   -fitting later.
128   -
129   -The spectral intensity I(E) (in units of photons/cm2/s/MeV) of the power
130   -law is given by
131   -
132   -.. math::
133   - \frac{dN}{dE} = N_0 \left( \frac{E}{E_0} \right)^{\gamma}
134   -
135   -where the parameters in the XML definition have the following mappings:
136   -
137   -* :math:`N_0` = ``Prefactor``
138   -* :math:`\gamma` = ``Index``
139   -* :math:`E_0` = ``Scale``
140   -
141   -.. warning::
142   -
143   - Energies are given in the XML file in MeV units. This is a GammaLib
144   - convention that can not be modified. **So make sure you always use
145   - MeV as energy unit in an XML file.**
146   -
147   -The instrumental background of CTA is modelled using the background
148   -information provided in the IRF (``CTAIrfBackground``) multipled
149   -by a power law. As it is defined here, the power law represents a
150   -constant of 1, hence the background IRF will be used without any
151   -modification. The power law will become active when fitting the data
152   -later and allows a spectral adjustment of the background model that
153   -may account for uncertainties in the background information provided
154   -in the IRF.
155   -
156   -:ref:`ctobssim` has a couple of hidden parameters, the most important one being
157   -certainly ``seed``. ``seed`` is an integer that specifies the seed value
158   -for the random number generator, and changing this parameter will allow to
159   -generate statistically independent Monte Carlo samples of CTA event data.
160   -To use for example a seed value of 41 you should type:
161   -
162   -.. code-block:: bash
163   -
164   - $ ctobssim seed=41
165   -
166   -:ref:`ctobssim` will write 2 files in the working directory: ``events.fits``
167   -and ``ctobssim.log``. The first file contains the simulated events in FITS
168   -format and can be inspected using ``fv`` or ``ds9``. The FITS file will
169   -contain three extensions: an empty primary image, a binary table named
170   -``EVENTS`` that holds the events (one row per event), and a binary table
171   -named ``GTI`` holding the Good Time Intervals (for the moment a single row
172   -with 2 columns providing the start and the stop time of the simulated time
173   -interval).
174   -
175   -The second file produced by :ref:`ctobssim` is a human readable log file that
176   -contains information about the job execution. As example, the last lines
177   -from this file are shown here:
178   -
179   -.. code-block:: xml
180   -
181   - 2015-05-22T19:24:53: +======================+
182   - 2015-05-22T19:24:53: | Simulate observation |
183   - 2015-05-22T19:24:53: +======================+
184   - 2015-05-22T19:24:53: === Observation ===
185   - 2015-05-22T19:24:53: Simulation area ...........: 1.9635e+11 cm2
186   - 2015-05-22T19:24:53: Simulation cone ...........: RA=83.63 deg, Dec=22.01 deg, r=5.5 deg
187   - 2015-05-22T19:24:53: Time interval .............: 0 - 1800 s
188   - 2015-05-22T19:24:53: Photon energy range .......: 100 GeV - 100 TeV
189   - 2015-05-22T19:24:53: Event energy range ........: 100 GeV - 100 TeV
190   - 2015-05-22T19:24:53: MC source photons .........: 207547 [Crab]
191   - 2015-05-22T19:24:53: MC source events ..........: 2961 [Crab]
192   - 2015-05-22T19:24:53: MC source events ..........: 2961 (all source models)
193   - 2015-05-22T19:24:55: MC background events ......: 13003
194   - 2015-05-22T19:24:55: MC events .................: 15964 (all models)
195   -
196   -Each line starts with the UTC time at which the line has been written. In
197   -this run, 207547 Crab photons have been thrown over an area of 19.6 square
198   -kilometres during a time interval of 1800 seconds. 2961 of these photons have
199   -been registered by CTA as events. In the same time interval, 13003 background
200   -events have been registred by CTA.
201   -
202   -You may change the name of the log file using the hidden parameter
203   -``logfile``:
204   -
205   -.. code-block:: bash
206   -
207   - $ ctobssim logfile=my-private-log-file
208   -
209   -Furthermore, you may decide on the amount of information provided in the
210   -log file (the chattiness of the executable) using the hidden parameter
211   -``chatter``:
212   -
213   -.. code-block:: bash
214   -
215   - $ ctobssim chatter=4
216   -
217   -``chatter`` can vary between 0 and 4, 0 providing no information while 4
218   -provides the most detailed information. **By default, all ctools have a
219   -chatter level of 2.**
220   -
221   -You may also duplicate the log file information into the console by setting
222   -the hidden ``debug`` parameter to yes:
223   -
224   -.. code-block:: bash
225   -
226   - $ ctobssim debug=yes
227   -
228   -
229   -.. _sec_binning_cta:
230   -
231   -Binning CTA data
232   -~~~~~~~~~~~~~~~~
233   -
234   -As next analysis step you will bin the data in a counts cube using
235   -:ref:`ctbin`.
236   -A counts cube is a 3 dimensional data cube, spanned by
237   -Right Ascension (or Galactic longitude), Declination (or Galactic latitude),
238   -and energy (typically logarithmically spaced, but this is under user
239   -control).
240   -
241   -:ref:`ctbin` is executed by typing:
242   -
243   -.. code-block:: bash
244   -
245   - $ ctbin
246   - Event list or observation definition file [events.fits]
247   - First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
248   - Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
249   - Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
250   - Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL]
251   - Image scale (in degrees/pixel) [0.02]
252   - Size of the X axis in pixels [200]
253   - Size of the Y axis in pixels [200]
254   - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG]
255   - Start value for first energy bin in TeV [0.1]
256   - Stop value for last energy bin in TeV [100.0]
257   - Number of energy bins [20]
258   - Output counts cube [cntcube.fits]
259   -
260   -The counts cube will be centred on the location of the Crab (Right Ascension
261   -83.63 degrees, Declination 22.01 degrees) and will be aligned in celestial
262   -coordinates. A cartesian projection has been selected. The counts cube has
263   -200 x 200 spatial pixels of 0.02 x 0.02 degrees in size, hence it covers a
264   -total area of 4 x 4 degrees.
265   -
266   -The counts cube will contain 20 maps, which are logarithmically spaced
267   -in energy, and which cover the energy range from 0.1 TeV to 100 TeV. In this
268   -example, the counts cube will be saved as ``cntcube.fits`` in the working
269   -directory. In addition to the counts cube, that is stored as the primary
270   -image extension, the FITS file also contains an extension named ``EBOUNDS``
271   -that defines the energy boundaries that were used, and an extension ``GTI``
272   -that defines the Good Time Intervals that have been used. The following
273   -image shows the resulting FITS file. The ``EBOUNDS`` table has 20 rows, one
274   -for each energy bin, while the ``GTI`` table has just a single row, indicating
275   -the start and stop time of the simulated data.
276   -
277   -.. figure:: cntmap-fits.jpg
278   - :width: 600px
279   - :align: center
280   -
281   - *Counts cube FITS file*
282   -
283   -
284   -An image of the first bin, covering the energy range 100 - 141 GeV, is
285   -shown below:
286   -
287   -.. figure:: cntmap-map.jpg
288   - :height: 400px
289   - :align: center
290   -
291   - *Counts cube for first energy bin*
292   -
293   -
294   -For illustration, the last few lines of the log file ``ctbin.log`` are
295   -reproduced below:
296   -
297   -.. code-block:: xml
298   -
299   - 2015-05-22T19:40:30: +=================+
300   - 2015-05-22T19:40:30: | Bin observation |
301   - 2015-05-22T19:40:30: +=================+
302   - 2015-05-22T19:40:30: === Observation ===
303   - 2015-05-22T19:40:30: Events in list ............: 15964
304   - 2015-05-22T19:40:30: Events in cube ............: 13360
305   - 2015-05-22T19:40:30: Event bins outside RoI ....: 0
306   - 2015-05-22T19:40:30: Events outside cube area ..: 2604
307   - 2015-05-22T19:40:30: Events outside energy bins : 0
308   -
309   -From the 15964 events that have been simulated and stored in the
310   -``events.fits`` file, 13360 lie within the cube boundaries and are thus put
311   -into the resulting counts cube. The counts cube is stored in a cartesian
312   -projection in a World Coordinate System (WCS) compliant format.
313   -
314   -
315   -.. _sec_fitting_cta:
316   -
317   -Fitting CTA data
318   -~~~~~~~~~~~~~~~~
319   -
320   -Now we are ready to fit the simulated data with a model. For simplicity
321   -we use in this example the same model that we used to simulate the data
322   -with :ref:`ctobssim`. Model fitting is done using the :ref:`ctlike` tool,
323   -and we do the fit by typing:
324   -
325   -.. code-block:: bash
326   -
327   - $ ctlike
328   - Event list, counts cube or observation definition file [events.fits] cntcube.fits
329   - Exposure cube file (only needed for stacked analysis) [NONE]
330   - PSF cube file (only needed for stacked analysis) [NONE]
331   - Background cube file (only needed for stacked analysis) [NONE]
332   - Calibration database [prod2]
333   - Instrument response function [South_50h]
334   - Source model [$CTOOLS/share/models/crab.xml]
335   - Source model output file [crab_results.xml]
336   -
337   -The data are fitted in *binned* mode, which means that the events
338   -have been binned into a counts cube and the fit computes the log-likelihood
339   -function by summing over all 200 x 200 x 20 bins of the counts cube. There is
340   -an alternative method, the so called *unbinned* mode, where the events are
341   -not binned into a counts cube and the log-likelihood is computed directly by
342   -summing over all events. We will explore the *unbinned* mode later.
343   -
344   -One of the parameters of :ref:`ctlike` is a source model output file
345   -(we specified ``crab_results.xml`` in the example), and this file will be
346   -a copy of the source model input XML file where the parameter values have
347   -been replaced by the fit results. In addition, the statistical uncertainties
348   -are added for each fitted parameter using the attribute ``error``.
349   -Below we show the XML result file that has been produced by the run:
350   -
351   -.. code-block:: xml
352   -
353   - <?xml version="1.0" encoding="UTF-8" standalone="no"?>
354   - <source_library title="source library">
355   - <source name="Crab" type="PointSource">
356   - <spectrum type="PowerLaw">
357   - <parameter name="Prefactor" value="5.78197" error="0.110889" scale="1e-16" min="1e-07" max="1000" free="1" />
358   - <parameter name="Index" value="2.49174" error="0.0164369" scale="-1" min="0" max="5" free="1" />
359   - <parameter name="Scale" value="0.3" scale="1e+06" min="0.01" max="1000" free="0" />
360   - </spectrum>
361   - <spatialModel type="SkyDirFunction">
362   - <parameter name="RA" value="83.6331" scale="1" min="-360" max="360" free="0" />
363   - <parameter name="DEC" value="22.0145" scale="1" min="-90" max="90" free="0" />
364   - </spatialModel>
365   - </source>
366   - <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
367   - <spectrum type="PowerLaw">
368   - <parameter name="Prefactor" value="1.02048" error="0.0280684" scale="1" min="0.001" max="1000" free="1" />
369   - <parameter name="Index" value="0.0197856" error="0.0156686" scale="1" min="-5" max="5" free="1" />
370   - <parameter name="Scale" value="1" scale="1e+06" min="0.01" max="1000" free="0" />
371   - </spectrum>
372   - </source>
373   - </source_library>
374   -
375   -In this example, the ``Prefactor`` and ``Index`` of the spectral model for the
376   -Crab as well as the ``Prefactor`` and ``Index`` of the background spectral
377   -model have been fitted (all parameters having the attribute ``free="1"`` are
378   -fitted). Now we see also the effect of having multiplied the background
379   -model with a power law. In that way, the amplitude of the background as
380   -well as it's spectral slope is adjusted by the fit. Obviously, in this
381   -example the adjustment compensates only for the statistical fluctuations
382   -of the background, but with real data, the adjustment may account also for
383   -some of the systematic uncertainties.
384   -
385   -.. warning::
386   -
387   - As good practice, the amplitude of the background model should always be
388   - left as a free parameter of the fit. Otherwise, any uncertainty in the
389   - background rate will immediately propagate into the flux estimate of the
390   - source.
391   -
392   -To get more details about the model fitting you can inspect the log file.
393   -Below the last lines of the ctlike.log log file that has been produced by
394   -this run:
395   -
396   -.. code-block:: xml
397   -
398   - 2015-05-22T19:45:15: +=================================+
399   - 2015-05-22T19:45:15: | Maximum likelihood optimisation |
400   - 2015-05-22T19:45:15: +=================================+
401   - 2015-05-22T19:45:16: >Iteration 0: -logL=39910.748, Lambda=1.0e-03
402   - 2015-05-22T19:45:18: >Iteration 1: -logL=39908.788, Lambda=1.0e-03, delta=1.960, max(|grad|)=6.701856 [Index:7]
403   - 2015-05-22T19:45:19: >Iteration 2: -logL=39908.787, Lambda=1.0e-04, delta=0.001, max(|grad|)=-0.057041 [Index:3]
404   - 2015-05-22T19:45:21:
405   - 2015-05-22T19:45:21: +=========================================+
406   - 2015-05-22T19:45:21: | Maximum likelihood optimization results |
407   - 2015-05-22T19:45:21: +=========================================+
408   - 2015-05-22T19:45:21: === GOptimizerLM ===
409   - 2015-05-22T19:45:21: Optimized function value ..: 39908.787
410   - 2015-05-22T19:45:21: Absolute precision ........: 0.005
411   - 2015-05-22T19:45:21: Acceptable value decrease .: 2
412   - 2015-05-22T19:45:21: Optimization status .......: converged
413   - 2015-05-22T19:45:21: Number of parameters ......: 10
414   - 2015-05-22T19:45:21: Number of free parameters .: 4
415   - 2015-05-22T19:45:21: Number of iterations ......: 2
416   - 2015-05-22T19:45:21: Lambda ....................: 1e-05
417   - 2015-05-22T19:45:21: Maximum log likelihood ....: -39908.787
418   - 2015-05-22T19:45:21: Observed events (Nobs) ...: 13360.000
419   - 2015-05-22T19:45:21: Predicted events (Npred) ..: 13359.998 (Nobs - Npred = 0.00180799)
420   - 2015-05-22T19:45:21: === GModels ===
421   - 2015-05-22T19:45:21: Number of models ..........: 2
422   - 2015-05-22T19:45:21: Number of parameters ......: 10
423   - 2015-05-22T19:45:21: === GModelSky ===
424   - 2015-05-22T19:45:21: Name ......................: Crab
425   - 2015-05-22T19:45:21: Instruments ...............: all
426   - 2015-05-22T19:45:21: Instrument scale factors ..: unity
427   - 2015-05-22T19:45:21: Observation identifiers ...: all
428   - 2015-05-22T19:45:21: Model type ................: PointSource
429   - 2015-05-22T19:45:21: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
430   - 2015-05-22T19:45:21: Number of parameters ......: 6
431   - 2015-05-22T19:45:21: Number of spatial par's ...: 2
432   - 2015-05-22T19:45:21: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
433   - 2015-05-22T19:45:21: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
434   - 2015-05-22T19:45:21: Number of spectral par's ..: 3
435   - 2015-05-22T19:45:21: Prefactor ................: 5.78197e-16 +/- 1.10889e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
436   - 2015-05-22T19:45:21: Index ....................: -2.49174 +/- 0.0164369 [-0,-5] (free,scale=-1,gradient)
437   - 2015-05-22T19:45:21: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
438   - 2015-05-22T19:45:21: Number of temporal par's ..: 1
439   - 2015-05-22T19:45:21: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
440   - 2015-05-22T19:45:21: === GCTAModelIrfBackground ===
441   - 2015-05-22T19:45:21: Name ......................: CTABackgroundModel
442   - 2015-05-22T19:45:21: Instruments ...............: CTA
443   - 2015-05-22T19:45:21: Instrument scale factors ..: unity
444   - 2015-05-22T19:45:21: Observation identifiers ...: all
445   - 2015-05-22T19:45:21: Model type ................: "PowerLaw" * "Constant"
446   - 2015-05-22T19:45:21: Number of parameters ......: 4
447   - 2015-05-22T19:45:21: Number of spectral par's ..: 3
448   - 2015-05-22T19:45:21: Prefactor ................: 1.02048 +/- 0.0280684 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
449   - 2015-05-22T19:45:21: Index ....................: 0.0197856 +/- 0.0156686 [-5,5] (free,scale=1,gradient)
450   - 2015-05-22T19:45:21: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
451   - 2015-05-22T19:45:21: Number of temporal par's ..: 1
452   - 2015-05-22T19:45:21: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
453   -
454   -The maximum likelihood optimizer required 2 iterations to converge. This
455   -is pretty fast, but recall that we used the same model file for the simulation
456   -and for fitting, hence the initial parameter values were already very close
457   -to the best fitting values. To see the impact of the initial parameters on
458   -the fit result, you may re-run :ref:`ctlike` using another copy of the model
459   -XML file where you change the value attributes of the parameters that should be
460   -fitted. You will see that the optimizer requires a couple of more iterations,
461   -but it should converge to the same solution (provided that the initial values
462   -are not too far from the best fitting values).
463   -
464   -.. note::
465   -
466   - As sanity check you should verify that the predicted number of events
467   - (Npred) is equal to the observed number of events (Nobs). To facilitate
468   - this comparison, :ref:`ctlike` provides the difference Nobs - Npred in
469   - the log file. In real life situations, this difference may not always be
470   - small, in particular if the source model is too constrained. You may
471   - then free some of the model parameters so that the fit can correctly
472   - describe the data.
473   -
474   -.. note::
475   -
476   - The :ref:`ctlike` tool has the ability to estimate the detection
477   - significance for sources in the XML model. This is done by computing
478   - the Test Statistic value which is defined as twice the log-likelihood
479   - difference between fitting a source at a given position on top of a
480   - (background) model or fitting no source. Roughly speaken, the square
481   - root of the Test Statistic value gives the source detection significance
482   - in Gaussian sigmas, although the exact relation depends somewhat on
483   - the formulation of the statistical problem.
484   -
485   - To instruct :ref:`ctlike` to compute the Test Statistic value for a
486   - given source you need to add the attribute ``tscalc="1"`` to the XML
487   - file:
488   -
489   - .. code-block:: xml
490   -
491   - <source name="Crab" type="PointSource" tscalc="1">
492   -
493   - :ref:`ctlike` will then compute the Test Statistic value for that
494   - source and dump the result in the log file:
495   -
496   - .. code-block:: xml
497   -
498   - 2015-05-22T19:58:43: === GModelSky ===
499   - 2015-05-22T19:58:43: Name ......................: Crab
500   - 2015-05-22T19:58:43: Instruments ...............: all
501   - 2015-05-22T19:58:43: Test Statistic ............: 18662.6
502   -
503   - The Test Statistic value will also be added as new attribute
504   - ``ts`` to the XML result file:
505   -
506   - .. code-block:: xml
507   -
508   - <source name="Crab" type="PointSource" ts="18662.576" tscalc="1">
509   -
510   -
511   -.. _sec_unbinned_cta:
512   -
513   -Doing an unbinned analysis
514   -~~~~~~~~~~~~~~~~~~~~~~~~~~
515   -
516   -As gamma-ray events are rare, the counts cubes generated by :ref:`ctbin`
517   -will in general be sparsly populated, having many empty pixels, in
518   -particular at high energies.
519   -An alternative analysis technique consists of working directly on the event
520   -list without binning the events in a counts cube. We will see the benefit of
521   -such an analysis later once you re-run :ref:`ctlike` in unbinned mode.
522   -
523   -For unbinned analysis you first have to define the data space region over
524   -which the analysis is done. This is similiar to the :ref:`ctbin` step for
525   -a binned analysis where you defined the size of the counts cube, the energy
526   -range, and the time interval. For unbinned analysis you have no such thing
527   -as a counts cube, but you have to define over which region of the data space
528   -the selected events are spread (because the ctools have to integrate over
529   -this region to compute the total number of predicted events in the data space
530   -that you analyse). Furthermore, you have to define what energy range is
531   -covered, and what time interval is spanned by the data. All this is done
532   -by the :ref:`ctselect` tool, which replaces the :ref:`ctbin` step in an
533   -unbinned analysis.
534   -
535   -:ref:`ctselect` performs an event selection by choosing only events within
536   -a given region-of-interest (ROI), within a given energy band, and within a
537   -given time interval from the input event list. The ROI is a circular region on
538   -the sky, for which you define the centre (in celestial coordinates) and the
539   -radius. Such a circular ROI is sometimes also called an acceptance cone. The
540   -following example shows how to run ctselect:
541   -
542   -.. code-block:: bash
543   -
544   - $ ctselect
545   - Input event list or observation definition file [events.fits]
546   - RA for ROI centre (degrees) (0-360) [83.63]
547   - Dec for ROI centre (degrees) (-90-90) [22.01]
548   - Radius of ROI (degrees) (0-180) [3.0]
549   - Start time (CTA MET in seconds) [0.0]
550   - End time (CTA MET in seconds) [0.0]
551   - Lower energy limit (TeV) [0.1]
552   - Upper energy limit (TeV) [100.0]
553   - Output event list or observation definition file [selected_events.fits]
554   -
555   -:ref:`ctselect` takes the input event list ``events.fits``, performs an
556   -event selection, and writes the selected event into the file
557   -``selected_events.fits``. The parameters it will query for are the centre
558   -of the ROI, the radius of the ROI, the start and stop time (in seconds),
559   -and the energy lower and upper limits (in TeV). The event selection information
560   -is also written as a set of data selection keywords to the output events
561   -file ``selected_events.fits``, by respecting the same syntax that has been
562   -implemented for Fermi/LAT. The following image is a screen dump of the data
563   -selection keywords that have been written to the ``EVENTS`` header in the
564   -file ``selected_events.fits``:
565   -
566   -.. figure:: dskeys.jpg
567   - :width: 400px
568   - :align: center
569   -
570   - *Data selection keywords*
571   -
572   -**It is mandatory for an unbinned analysis that these data selection keywords
573   -exist in the FITS file.**
574   -If they don't exist, :ref:`ctlike` will not execute in unbinned mode.
575   -
576   -Below some lines of the ``ctselect.log`` file that show the data selection
577   -part:
578   -
579   -.. code-block:: xml
580   -
581   - 2015-05-22T20:01:46: +=================+
582   - 2015-05-22T20:01:46: | Event selection |
583   - 2015-05-22T20:01:46: +=================+
584   - 2015-05-22T20:01:46: === Observation ===
585   - 2015-05-22T20:01:47: Selected energy range .....: 0.1 - 100 TeV
586   - 2015-05-22T20:01:47: Requested ROI .............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
587   - 2015-05-22T20:01:47: ROI of data ...............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=5 deg
588   - 2015-05-22T20:01:47: Selected ROI ..............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
589   - 2015-05-22T20:01:47: cfitsio selection .........: ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000
590   - 2015-05-22T20:01:47: FITS filename .............: /var/tmp/tmp.0.rRgLpO[EVENTS][ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000]
591   -
592   -.. note::
593   -
594   - :ref:`ctobssim` will also write data selection keywords in the event
595   - list FITS file, hence you can run :ref:`ctlike` directly on a FITS file
596   - produced by :ref:`ctobssim`. Any selection performed by :ref:`ctselect`
597   - needs to be fully enclosed within any previous selection, e.g. the ROI
598   - needs to be fully enclosed in the acceptance cone used for event
599   - simulation, the energy selection must be fully comprised in the
600   - range of simulated energies, the same applies for the temporal selection.
601   - :ref:`ctselect` will automatically adjust
602   - the selection parameters to guarantee full enclosure. To keep track of
603   - this adjustment, the :ref:`ctselect` log file quotes the requested
604   - selection, any existing selections, and the selection that was finally
605   - applied.
606   -
607   -.. warning::
608   -
609   - :ref:`ctselect` may of course also be used for event selection prior to
610   - binned analysis, for example to select events for a given period in
611   - time. **If you use** :ref:`ctselect` **however to make a spatial or energy
612   - selection, make sure that the counts cube is fully enclosed in the
613   - selection intervals.** Otherwise you will get empty zones in the counts
614   - cube of which the ctools are not aware of, and the subsequent analysis
615   - results will be wrong.
616   -
617   -Now that you have selected the events of interest, you can run ctlike in
618   -unbinned mode. To do this you have to specify the selected event list
619   -instead of the counts cube:
620   -
621   -.. code-block:: bash
622   -
623   - $ ctlike
624   - Event list, counts cube or observation definition file [cntcube.fits] selected_events.fits
625   - Calibration database [prod2]
626   - Instrument response function [South_50h]
627   - Source model [$CTOOLS/share/models/crab.xml]
628   - Source model output file [crab_results.xml]
629   -
630   -You will recognise that :ref:`ctlike` runs much faster in unbinned mode
631   -compared to binned mode.
632   -This is understandable as the selected event list contains
633   -only 15312 events, while the binned counts cube we used before had
634   -200 x 200 x 20 = 800000 pixels. As unbinned maximum likelihood fitting loops
635   -over the events (while binned maximum likelihood loops over the pixels),
636   -there are much less operations to perform in unbinned than in binned mode
637   -(there is some additional overhead in unbinned mode that comes from
638   -integrating the models over the region of interest, yet this is negligible
639   -compared to the operations needed when looping over all pixels). So as long
640   -as you work with small event lists, unbinned mode is faster (this
641   -typically holds up to 100 hours of observing time).
642   -Unbinned :ref:`ctlike` should also be more precise as no binning is performed,
643   -hence there is no loss of information due to histogramming.
644   -
645   -Below you see the corresponding output from the ctlike.log file. The fitted
646   -parameters are essentially identical to the ones found in binned mode.
647   -The slight difference with respect to the binned analysis may be explained
648   -by the different event sample that has been used for the analysis: while
649   -binned likelihood works on rectangular counts cubes, unbinned likelihood works
650   -on circular event selection regions. It is thus not possible to select exactly
651   -the same events for both analyses.
652   -
653   -.. code-block:: xml
654   -
655   - 2015-05-22T20:05:54: +=================================+
656   - 2015-05-22T20:05:54: | Maximum likelihood optimisation |
657   - 2015-05-22T20:05:54: +=================================+
658   - 2015-05-22T20:05:54: >Iteration 0: -logL=93854.543, Lambda=1.0e-03
659   - 2015-05-22T20:05:54: >Iteration 1: -logL=93848.595, Lambda=1.0e-03, delta=5.948, max(|grad|)=22.480581 [Index:7]
660   - 2015-05-22T20:05:54: >Iteration 2: -logL=93848.587, Lambda=1.0e-04, delta=0.008, max(|grad|)=-0.081846 [Index:3]
661   - 2015-05-22T20:05:54: >Iteration 3: -logL=93848.587, Lambda=1.0e-05, delta=0.000, max(|grad|)=-0.003485 [Index:3]
662   - 2015-05-22T20:05:54:
663   - 2015-05-22T20:05:54: +=========================================+
664   - 2015-05-22T20:05:54: | Maximum likelihood optimization results |
665   - 2015-05-22T20:05:54: +=========================================+
666   - 2015-05-22T20:05:54: === GOptimizerLM ===
667   - 2015-05-22T20:05:54: Optimized function value ..: 93848.587
668   - 2015-05-22T20:05:54: Absolute precision ........: 0.005
669   - 2015-05-22T20:05:54: Acceptable value decrease .: 2
670   - 2015-05-22T20:05:54: Optimization status .......: converged
671   - 2015-05-22T20:05:54: Number of parameters ......: 10
672   - 2015-05-22T20:05:54: Number of free parameters .: 4
673   - 2015-05-22T20:05:54: Number of iterations ......: 3
674   - 2015-05-22T20:05:54: Lambda ....................: 1e-06
675   - 2015-05-22T20:05:54: Maximum log likelihood ....: -93848.587
676   - 2015-05-22T20:05:54: Observed events (Nobs) ...: 15312.000
677   - 2015-05-22T20:05:54: Predicted events (Npred) ..: 15312.000 (Nobs - Npred = 3.03823e-06)
678   - 2015-05-22T20:05:54: === GModels ===
679   - 2015-05-22T20:05:54: Number of models ..........: 2
680   - 2015-05-22T20:05:54: Number of parameters ......: 10
681   - 2015-05-22T20:05:54: === GModelSky ===
682   - 2015-05-22T20:05:54: Name ......................: Crab
683   - 2015-05-22T20:05:54: Instruments ...............: all
684   - 2015-05-22T20:05:54: Instrument scale factors ..: unity
685   - 2015-05-22T20:05:54: Observation identifiers ...: all
686   - 2015-05-22T20:05:54: Model type ................: PointSource
687   - 2015-05-22T20:05:54: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
688   - 2015-05-22T20:05:54: Number of parameters ......: 6
689   - 2015-05-22T20:05:54: Number of spatial par's ...: 2
690   - 2015-05-22T20:05:54: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
691   - 2015-05-22T20:05:54: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
692   - 2015-05-22T20:05:54: Number of spectral par's ..: 3
693   - 2015-05-22T20:05:54: Prefactor ................: 5.80619e-16 +/- 1.11149e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
694   - 2015-05-22T20:05:54: Index ....................: -2.49282 +/- 0.0163467 [-0,-5] (free,scale=-1,gradient)
695   - 2015-05-22T20:05:54: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
696   - 2015-05-22T20:05:54: Number of temporal par's ..: 1
697   - 2015-05-22T20:05:54: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
698   - 2015-05-22T20:05:54: === GCTAModelIrfBackground ===
699   - 2015-05-22T20:05:54: Name ......................: CTABackgroundModel
700   - 2015-05-22T20:05:54: Instruments ...............: CTA
701   - 2015-05-22T20:05:54: Instrument scale factors ..: unity
702   - 2015-05-22T20:05:54: Observation identifiers ...: all
703   - 2015-05-22T20:05:54: Model type ................: "PowerLaw" * "Constant"
704   - 2015-05-22T20:05:54: Number of parameters ......: 4
705   - 2015-05-22T20:05:54: Number of spectral par's ..: 3
706   - 2015-05-22T20:05:54: Prefactor ................: 1.03511 +/- 0.024311 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
707   - 2015-05-22T20:05:54: Index ....................: 0.0333176 +/- 0.0134386 [-5,5] (free,scale=1,gradient)
708   - 2015-05-22T20:05:54: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
709   - 2015-05-22T20:05:54: Number of temporal par's ..: 1
710   - 2015-05-22T20:05:54: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
711   -
712   -
713   -.. _sec_butterfly_cta:
714   -
715   -Calculating and visualising a butterfly
716   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
717   -
718   -To visualise the analysis results retrieved above, one can calculate the
719   -confidence band of the spectral fit.
720   -The :ref:`ctbutterfly` tool takes the optimised source model as input.
721   -It takes the covariance matrix from the fit to conduct a
722   -Gaussian error propagation for each energy value. It will write the
723   -butterfly information into an ASCII file.
724   -The following example shows how to compute such a butterfly from the command
725   -line.
726   -
727   -.. code-block:: bash
728   -
729   - $ ctbutterfly
730   - Input event list, counts cube or observation definition file [events.fits]
731   - Calibration database [prod2]
732   - Instrument response function [South_50h]
733   - Source model [$CTOOLS/share/models/crab.xml]
734   - Source of interest [Crab]
735   - Start value for first energy bin in TeV [0.1]
736   - Stop value for last energy bin in TeV [100.0]
737   - Output ascii file [butterfly.txt]
738   -
739   -Now that you have computed the confidence band of the spectral fit and
740   -that you will have an ASCII file named ``butterfly.txt`` on disk you can
741   -visualise the butterfly using the script ``show_butterfly.py`` that is
742   -in the ctools ``example`` folder. You will need matplotlib on your system
743   -to make this work. To launch the script, type:
744   -
745   -.. code-block:: bash
746   -
747   - python $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt
748   -
749   -This will result in a canvas which should look like the following:
750   -
751   -.. figure:: butterfly.jpg
752   - :height: 400px
753   - :align: center
  4 +-----------------------
754 5  
755   - *Confidence band of the fit*
756   -
757 6 \ No newline at end of file
  7 +This section provides a step-by-step description of a simple CTA data
  8 +analysis example using the ctools. In this example we will simulate a
  9 +half an hour long CTA observation of the Crab nebula as the single
  10 +point source within the CTA field of view. You will learn how to bin the
  11 +event data into a counts cube and how to fit a spatial and spectral model
  12 +to the data. You will also learn how to analyse directly event lists
  13 +without binning the events into a counts cube. Finally we will show how
  14 +you can create a butterfly diagram that shows the confidence band of the
  15 +fitted spectral model.
  16 +
  17 +.. toctree::
  18 + :maxdepth: 2
  19 +
  20 + simulating
  21 + binning
  22 + fitting
  23 + unbinned
  24 + butterfly
... ...
doc/source/user_manual/getting_started/resmap-crab.png
View file @a4a4190

251 KB | W: | H:

314 KB | W: | H:

  • 2-up
  • Swipe
  • Onion skin
doc/source/user_manual/getting_started/response.rst
  View file @a4a4190
... ... @@ -99,7 +99,7 @@ Specifying the response function as input parameters
99 99 ctools that require instrument response functions have two parameters
100 100 to specify the calibration database name and the response function name.
101 101 The following example shows a ``ctobssim`` run using the ``prod2``
102   -calibration database and the ``South_50h`` response function:
  102 +calibration database and the ``South_0.5h`` response function:
103 103  
104 104 .. code-block:: bash
105 105  
... ... @@ -112,8 +112,9 @@ calibration database and the ``South_50h`` response function:
112 112 Lower energy limit (TeV) [0.1]
113 113 Upper energy limit (TeV) [100.0]
114 114 Calibration database [prod2]
115   - Instrument response function [South_50h]
116   - Model [$CTOOLS/share/models/crab.xml]
  115 + Instrument response function [South_0.5h]
  116 + Input model XML file [$CTOOLS/share/models/crab.xml]
  117 + Output event data file or observation definition XML file [events.fits]
117 118  
118 119 Running the other tools is equivalent.
119 120  
... ... @@ -131,7 +132,7 @@ definition file:
131 132 <observation_list title="observation library">
132 133 <observation name="Crab" id="00001" instrument="CTA">
133 134 <parameter name="EventList" file="events.fits"/>
134   - <parameter name="Calibration" database="prod2" response="South_50h"/>
  135 + <parameter name="Calibration" database="prod2" response="South_0.5h"/>
135 136 </observation>
136 137 </observation_list>
137 138  
... ... @@ -141,9 +142,9 @@ response name. You can then pass this file directly to, e.g., ``ctlike``:
141 142 .. code-block:: bash
142 143  
143 144 $ ctlike
144   - Event list, counts cube or observation definition file [events.fits] obs_irf.xml
145   - Source model [$CTOOLS/share/models/crab.xml]
146   - Source model output file [crab_results.xml]
  145 + Input event list, counts cube or observation definition XML file [events.fits] obs_irf.xml
  146 + Input model XML file [$CTOOLS/share/models/crab.xml]
  147 + Output model XML file [crab_results.xml]
147 148  
148 149 Note that ``ctlike`` does not ask for the calibration database and
149 150 response name as it found the relevant information in the XML file.
... ... @@ -181,11 +182,11 @@ and response name from within Python:
181 182 import gammalib
182 183 obs = gammalib.GCTAObservation()
183 184 caldb = gammalib.GCaldb("cta", "prod2")
184   - irf = "South_50h"
  185 + irf = "South_0.5h"
185 186 obs.response(irf, caldb)
186 187  
187 188 The calibration database is set by creating a ``GCaldb`` object. The
188 189 constructor takes as argument the mission (always ``cta``) and the
189 190 database name, in our case ``prod2``. The response function is then set
190   -by passing the response name (here ``South_50h``) and the calibration
  191 +by passing the response name (here ``South_0.5h``) and the calibration
191 192 database object to the ``response`` method.
... ...
doc/source/user_manual/getting_started/simulating.rst 0 → 100644
  View file @a4a4190
  1 +.. _sec_simulating_cta:
  2 +
  3 +Simulating CTA data
  4 +~~~~~~~~~~~~~~~~~~~
  5 +
  6 +You can simulate a CTA observation with the :ref:`ctobssim` tool.
  7 +
  8 +To invoke the tool, type :ref:`ctobssim` at the console prompt
  9 +(which is denoted by ``$``).
  10 +:ref:`ctobssim` will query for a number of parameters:
  11 +
  12 +.. code-block:: bash
  13 +
  14 + $ ctobssim
  15 + RA of pointing (degrees) (0-360) [83.63]
  16 + Dec of pointing (degrees) (-90-90) [22.01]
  17 + Radius of FOV (degrees) (0-180) [5.0]
  18 + Start time (MET in s) [0.0]
  19 + End time (MET in s) [1800.0]
  20 + Lower energy limit (TeV) [0.1]
  21 + Upper energy limit (TeV) [100.0]
  22 + Calibration database [prod2]
  23 + Instrument response function [South_0.5h]
  24 + Input model XML file [$CTOOLS/share/models/crab.xml]
  25 + Output event data file or observation definition XML file [events.fits]
  26 +
  27 +Each line represents a query for one parameter value.
  28 +The line starts with a short description of the parameter, followed by
  29 +the default value proposed by ctobssim in squared brackets ``[ ]``.
  30 +
  31 +**If no parameter is entered the default value will be used**
  32 +(which is the case for all parameters shown here).
  33 +Otherwise, the specified value will overwrite the default value.
  34 +The round brackets ``( )`` indicate the range of possible parameter
  35 +values (if applicable).
  36 +
  37 +
  38 +You may have recognised that the environment variable ``$CTOOLS`` has
  39 +been used in the path name of the model. ctools will automatically expand
  40 +the environment variables in parameter inputs.
  41 +
  42 +The CTA instrument properties (effective area, PSF width) are taken from
  43 +the prod2 database. The response for the southern array using the cuts
  44 +optimised for 50 hours of observing time are used.
  45 +
  46 +.. note::
  47 +
  48 + ctools comes bundled with CTA response functions for the northern and
  49 + the southern array. The response functions are based on a Prod2
  50 + analysis with cuts optimised for 0.5 hours, 5 hours and 50 hours of
  51 + observing time. The following Instrument Response Functions
  52 + (IRFs) are available: ``North_0.5h``, ``North_5h``, ``North_50h``,
  53 + ``South_0.5h``, ``South_5h``, and ``South_50h``.
  54 +
  55 +Events are simulated based on the instrument properties and based on a
  56 +source and background model. Only events that fall within the specified
  57 +region of interest (ROI), defined as a circle around a sky position in
  58 +Right Ascension and Declination (in degrees), will be stored in the output
  59 +event data file. The duration of the simulation is taken here to 30 minutes
  60 +(or 1800 seconds). Events are simulated for energies between 0.1 and 100 TeV.
  61 +
  62 +The source and background model is defined by the XML file
  63 +``$CTOOLS/share/models/crab.xml``:
  64 +
  65 +.. code-block:: xml
  66 +
  67 + <?xml version="1.0" standalone="no"?>
  68 + <source_library title="source library">
  69 + <source name="Crab" type="PointSource">
  70 + <spectrum type="PowerLaw">
  71 + <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/>
  72 + <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/>
  73 + <parameter name="Scale" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/>
  74 + </spectrum>
  75 + <spatialModel type="SkyDirFunction">
  76 + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="0"/>
  77 + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="0"/>
  78 + </spatialModel>
  79 + </source>
  80 + <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
  81 + <spectrum type="PowerLaw">
  82 + <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-3" max="1e+3" free="1"/>
  83 + <parameter name="Index" scale="1.0" value="0.0" min="-5.0" max="+5.0" free="1"/>
  84 + <parameter name="Scale" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
  85 + </spectrum>
  86 + </source>
  87 + </source_library>
  88 +
  89 +The model consists of a source library that contains two components:
  90 +the Crab nebula and an instrumental background model.
  91 +
  92 +The Crab nebula is modelled by a factorized sky model that has a spectral
  93 +and a spatial component (tags ``<spectrum>`` and ``<spatialModel>``,
  94 +respectively). The spectrum is modelled by a power law, which is defined by
  95 +three parameters: the ``Prefactor``, the ``Index`` and the ``Scale``.
  96 +The spatial model has two parameters: Right Ascension in degrees (``RA``), and
  97 +Declination in degrees (``DEC``). Each parameter has a value and a scale factor,
  98 +the real value of the parameter being the product ``value * scale``. Typically,
  99 +``scale`` is chosen so that ``value`` is of the order of 1 (this is relevant for
  100 +model fitting). In addition, ``value`` is bound by a minimum (``min``) and
  101 +maximum (``max``) value, and a parameter may be free (``free="1"``) or fixed
  102 +(``free="0"``). The ``min``, ``max``, and ``free`` attributes are not
  103 +relevant here for the simulations, but they will be important for the model
  104 +fitting later.
  105 +
  106 +The spectral intensity I(E) (in units of photons/cm2/s/MeV) of the power
  107 +law is given by
  108 +
  109 +.. math::
  110 + \frac{dN}{dE} = N_0 \left( \frac{E}{E_0} \right)^{\gamma}
  111 +
  112 +where the parameters in the XML definition have the following mappings:
  113 +
  114 +* :math:`N_0` = ``Prefactor``
  115 +* :math:`\gamma` = ``Index``
  116 +* :math:`E_0` = ``Scale``
  117 +
  118 +.. warning::
  119 +
  120 + Energies are given in the XML file in MeV units. This is a GammaLib
  121 + convention that can not be modified. **So make sure you always use
  122 + MeV as energy unit in an XML file.**
  123 +
  124 +The instrumental background of CTA is modelled using the background
  125 +information provided in the IRF (``CTAIrfBackground``) multipled
  126 +by a power law. As it is defined here, the power law represents a
  127 +constant of 1, hence the background IRF will be used without any
  128 +modification. The power law will become active when fitting the data
  129 +later and allows a spectral adjustment of the background model that
  130 +may account for uncertainties in the background information provided
  131 +in the IRF.
  132 +
  133 +:ref:`ctobssim` has a couple of hidden parameters, the most important one being
  134 +certainly ``seed``. ``seed`` is an integer that specifies the seed value
  135 +for the random number generator, and changing this parameter will allow to
  136 +generate statistically independent Monte Carlo samples of CTA event data.
  137 +To use for example a seed value of 41 you should type:
  138 +
  139 +.. code-block:: bash
  140 +
  141 + $ ctobssim seed=41
  142 +
  143 +:ref:`ctobssim` will write 2 files in the working directory: ``events.fits``
  144 +and ``ctobssim.log``. The first file contains the simulated events in FITS
  145 +format and can be inspected using ``fv`` or ``ds9``. The FITS file will
  146 +contain three extensions: an empty primary image, a binary table named
  147 +``EVENTS`` that holds the events (one row per event), and a binary table
  148 +named ``GTI`` holding the Good Time Intervals (for the moment a single row
  149 +with 2 columns providing the start and the stop time of the simulated time
  150 +interval).
  151 +
  152 +The second file produced by :ref:`ctobssim` is a human readable log file that
  153 +contains information about the job execution. As example, the last lines
  154 +from this file are shown here:
  155 +
  156 +.. code-block:: xml
  157 +
  158 + 2015-12-07T20:48:30: +======================+
  159 + 2015-12-07T20:48:30: | Simulate observation |
  160 + 2015-12-07T20:48:30: +======================+
  161 + 2015-12-07T20:48:30: === CTA observation ===
  162 + 2015-12-07T20:48:30: Simulation area ...........: 1.9635e+11 cm2
  163 + 2015-12-07T20:48:30: Simulation cone ...........: RA=83.63 deg, Dec=22.01 deg, r=5.5 deg
  164 + 2015-12-07T20:48:30: Time interval .............: 0 - 1800 s
  165 + 2015-12-07T20:48:30: Photon energy range .......: 100 GeV - 100 TeV
  166 + 2015-12-07T20:48:30: Event energy range ........: 100 GeV - 100 TeV
  167 + 2015-12-07T20:48:30: Use model .................: Crab
  168 + 2015-12-07T20:48:30: Normalization .............: 1 [Crab]
  169 + 2015-12-07T20:48:30: Flux ......................: 5.87297e-10 [Crab] photons/cm2/s
  170 + 2015-12-07T20:48:30: Normalized flux ...........: 5.87297e-10 [Crab] photons/cm2/s
  171 + 2015-12-07T20:48:30: Photon rate ...............: 115.316 photons/s [Crab]
  172 + 2015-12-07T20:48:31: MC source photons .........: 207547 [Crab]
  173 + 2015-12-07T20:48:31: MC source events ..........: 3646 [Crab]
  174 + 2015-12-07T20:48:31: MC source events ..........: 3646 (all source models)
  175 + 2015-12-07T20:48:33: MC events outside ROI .....: 0
  176 + 2015-12-07T20:48:33: MC background events ......: 19039
  177 + 2015-12-07T20:48:33: MC events .................: 22685 (all models)
  178 +
  179 +Each line starts with the UTC time at which the line has been written. In
  180 +this run, 207547 Crab photons have been thrown over an area of 19.6 square
  181 +kilometres during a time interval of 1800 seconds. 3646 of these photons have
  182 +been registered by CTA as events. In the same time interval, 19039 background
  183 +events have been registred by CTA.
  184 +
  185 +You may change the name of the log file using the hidden parameter
  186 +``logfile``:
  187 +
  188 +.. code-block:: bash
  189 +
  190 + $ ctobssim logfile=my-private-log-file
  191 +
  192 +Furthermore, you may decide on the amount of information provided in the
  193 +log file (the chattiness of the executable) using the hidden parameter
  194 +``chatter``:
  195 +
  196 +.. code-block:: bash
  197 +
  198 + $ ctobssim chatter=4
  199 +
  200 +``chatter`` can vary between 0 and 4, 0 providing no information while 4
  201 +provides the most detailed information.
  202 +
  203 +**By default, all ctools have a chatter level of 2.**
  204 +
  205 +You may also duplicate the log file information into the console by setting
  206 +the hidden ``debug`` parameter to yes:
  207 +
  208 +.. code-block:: bash
  209 +
  210 + $ ctobssim debug=yes
... ...
doc/source/user_manual/getting_started/tsmap-crab.png
View file @a4a4190

70.7 KB | W: | H:

73.4 KB | W: | H:

  • 2-up
  • Swipe
  • Onion skin
doc/source/user_manual/getting_started/unbinned.rst 0 → 100644
  View file @a4a4190
  1 +.. _sec_unbinned_cta:
  2 +
  3 +Doing an unbinned analysis
  4 +~~~~~~~~~~~~~~~~~~~~~~~~~~
  5 +
  6 +As gamma-ray events are rare, the counts cubes generated by :ref:`ctbin`
  7 +will in general be sparsly populated, having many empty pixels, in
  8 +particular at high energies.
  9 +An alternative analysis technique consists of working directly on the event
  10 +list without binning the events in a counts cube. We will see the benefit of
  11 +such an analysis later once you re-run :ref:`ctlike` in unbinned mode.
  12 +
  13 +For unbinned analysis you first have to define the data space region over
  14 +which the analysis is done. This is similiar to the :ref:`ctbin` step for
  15 +a binned analysis where you defined the size of the counts cube, the energy
  16 +range, and the time interval. For unbinned analysis you have no such thing
  17 +as a counts cube, but you have to define over which region of the data space
  18 +the selected events are spread (because the ctools have to integrate over
  19 +this region to compute the total number of predicted events in the data space
  20 +that you analyse). Furthermore, you have to define what energy range is
  21 +covered, and what time interval is spanned by the data. All this is done
  22 +by the :ref:`ctselect` tool, which replaces the :ref:`ctbin` step in an
  23 +unbinned analysis.
  24 +
  25 +:ref:`ctselect` performs an event selection by choosing only events within
  26 +a given region-of-interest (ROI), within a given energy band, and within a
  27 +given time interval from the input event list. The ROI is a circular region on
  28 +the sky, for which you define the centre (in celestial coordinates) and the
  29 +radius. Such a circular ROI is sometimes also called an acceptance cone. The
  30 +following example shows how to run ctselect:
  31 +
  32 +.. code-block:: bash
  33 +
  34 + $ ctselect
  35 + Input event list or observation definition XML file [events.fits]
  36 + RA for ROI centre (degrees) (0-360) [83.63]
  37 + Dec for ROI centre (degrees) (-90-90) [22.01]
  38 + Radius of ROI (degrees) (0-180) [3.0]
  39 + Start time (CTA MET in seconds) [0.0]
  40 + End time (CTA MET in seconds) [0.0]
  41 + Lower energy limit (TeV) [0.1]
  42 + Upper energy limit (TeV) [100.0]
  43 + Output event list or observation definition XML file [selected_events.fits]
  44 +
  45 +:ref:`ctselect` takes the input event list ``events.fits``, performs an
  46 +event selection, and writes the selected event into the file
  47 +``selected_events.fits``. The parameters it will query for are the centre
  48 +of the ROI, the radius of the ROI, the start and stop time (in seconds),
  49 +and the energy lower and upper limits (in TeV). The event selection information
  50 +is also written as a set of data selection keywords to the output events
  51 +file ``selected_events.fits``, by respecting the same syntax that has been
  52 +implemented for Fermi/LAT. The following image is a screen dump of the data
  53 +selection keywords that have been written to the ``EVENTS`` header in the
  54 +file ``selected_events.fits``:
  55 +
  56 +.. figure:: dskeys.jpg
  57 + :width: 400px
  58 + :align: center
  59 +
  60 + *Data selection keywords*
  61 +
  62 +**It is mandatory for an unbinned analysis that these data selection keywords
  63 +exist in the FITS file.**
  64 +If they don't exist, :ref:`ctlike` will not execute in unbinned mode.
  65 +
  66 +Below some lines of the ``ctselect.log`` file that show the data selection
  67 +part:
  68 +
  69 +.. code-block:: xml
  70 +
  71 + 2015-12-06T23:44:52: +=================+
  72 + 2015-12-06T23:44:52: | Event selection |
  73 + 2015-12-06T23:44:52: +=================+
  74 + 2015-12-06T23:44:52: === CTA observation ===
  75 + 2015-12-06T23:44:52: Selected energy range .....: 0.1 - 100 TeV
  76 + 2015-12-06T23:44:52: Requested ROI .............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
  77 + 2015-12-06T23:44:52: ROI of data ...............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=5 deg
  78 + 2015-12-06T23:44:52: Selected ROI ..............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
  79 + 2015-12-06T23:44:52: cfitsio selection .........: ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000
  80 + 2015-12-06T23:44:52: FITS filename .............: /var/tmp/tmp.0.jHg5hJ[EVENTS][ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000]
  81 +
  82 +.. note::
  83 +
  84 + :ref:`ctobssim` will also write data selection keywords in the event
  85 + list FITS file, hence you can run :ref:`ctlike` directly on a FITS file
  86 + produced by :ref:`ctobssim`. Any selection performed by :ref:`ctselect`
  87 + needs to be fully enclosed within any previous selection, e.g. the ROI
  88 + needs to be fully enclosed in the acceptance cone used for event
  89 + simulation, the energy selection must be fully comprised in the
  90 + range of simulated energies, the same applies for the temporal selection.
  91 + :ref:`ctselect` will automatically adjust
  92 + the selection parameters to guarantee full enclosure. To keep track of
  93 + this adjustment, the :ref:`ctselect` log file quotes the requested
  94 + selection, any existing selections, and the selection that was finally
  95 + applied.
  96 +
  97 +.. warning::
  98 +
  99 + :ref:`ctselect` may of course also be used for event selection prior to
  100 + binned analysis, for example to select events for a given period in
  101 + time. **If you use** :ref:`ctselect` **however to make a spatial or energy
  102 + selection, make sure that the counts cube is fully enclosed in the
  103 + selection intervals.** Otherwise you will get empty zones in the counts
  104 + cube of which the ctools are not aware of, and the subsequent analysis
  105 + results will be wrong.
  106 +
  107 +Now that you have selected the events of interest, you can run ctlike in
  108 +unbinned mode. To do this you have to specify the selected event list
  109 +instead of the counts cube:
  110 +
  111 +.. code-block:: bash
  112 +
  113 + $ ctlike
  114 + Input event list, counts cube or observation definition XML file [cntcube.fits] selected_events.fits
  115 + Calibration database [prod2]
  116 + Instrument response function [South_0.5h]
  117 + Input model XML file [$CTOOLS/share/models/crab.xml]
  118 + Output model XML file [crab_results.xml]
  119 +
  120 +You will recognise that :ref:`ctlike` runs much faster in unbinned mode
  121 +compared to binned mode.
  122 +This is understandable as the selected event list contains
  123 +only 21203 events, while the binned counts cube we used before had
  124 +200 x 200 x 20 = 800000 pixels. As unbinned maximum likelihood fitting loops
  125 +over the events (while binned maximum likelihood loops over the pixels),
  126 +there are much less operations to perform in unbinned than in binned mode
  127 +(there is some additional overhead in unbinned mode that comes from
  128 +integrating the models over the region of interest, yet this is negligible
  129 +compared to the operations needed when looping over all pixels). So as long
  130 +as you work with small event lists, unbinned mode is faster (this
  131 +typically holds up to 100 hours of observing time).
  132 +Unbinned :ref:`ctlike` should also be more precise as no binning is performed,
  133 +hence there is no loss of information due to histogramming.
  134 +
  135 +Below you see the corresponding output from the ctlike.log file. The fitted
  136 +parameters are essentially identical to the ones found in binned mode.
  137 +The slight difference with respect to the binned analysis may be explained
  138 +by the different event sample that has been used for the analysis: while
  139 +binned likelihood works on rectangular counts cubes, unbinned likelihood works
  140 +on circular event selection regions. It is thus not possible to select exactly
  141 +the same events for both analyses.
  142 +
  143 +.. code-block:: xml
  144 +
  145 + 2015-12-07T21:02:17: +=================================+
  146 + 2015-12-07T21:02:17: | Maximum likelihood optimisation |
  147 + 2015-12-07T21:02:17: +=================================+
  148 + 2015-12-07T21:02:17: >Iteration 0: -logL=135278.644, Lambda=1.0e-03
  149 + 2015-12-07T21:02:17: >Iteration 1: -logL=135274.475, Lambda=1.0e-03, delta=4.168, max(|grad|)=5.806873 [Index:7]
  150 + 2015-12-07T21:02:17: >Iteration 2: -logL=135274.474, Lambda=1.0e-04, delta=0.001, max(|grad|)=-0.009463 [Index:7]
  151 + 2015-12-07T21:02:17:
  152 + ...
  153 + 2015-12-07T21:02:17: +=========================================+
  154 + 2015-12-07T21:02:17: | Maximum likelihood optimisation results |
  155 + 2015-12-07T21:02:17: +=========================================+
  156 + 2015-12-07T21:02:17: === GOptimizerLM ===
  157 + 2015-12-07T21:02:17: Optimized function value ..: 135274.474
  158 + 2015-12-07T21:02:17: Absolute precision ........: 0.005
  159 + 2015-12-07T21:02:17: Acceptable value decrease .: 2
  160 + 2015-12-07T21:02:17: Optimization status .......: converged
  161 + 2015-12-07T21:02:17: Number of parameters ......: 10
  162 + 2015-12-07T21:02:17: Number of free parameters .: 4
  163 + 2015-12-07T21:02:17: Number of iterations ......: 2
  164 + 2015-12-07T21:02:17: Lambda ....................: 1e-05
  165 + 2015-12-07T21:02:17: Maximum log likelihood ....: -135274.474
  166 + 2015-12-07T21:02:17: Observed events (Nobs) ...: 21203.000
  167 + 2015-12-07T21:02:17: Predicted events (Npred) ..: 21202.998 (Nobs - Npred = 0.00198937)
  168 + 2015-12-07T21:02:17: === GModels ===
  169 + 2015-12-07T21:02:17: Number of models ..........: 2
  170 + 2015-12-07T21:02:17: Number of parameters ......: 10
  171 + 2015-12-07T21:02:17: === GModelSky ===
  172 + 2015-12-07T21:02:17: Name ......................: Crab
  173 + 2015-12-07T21:02:17: Instruments ...............: all
  174 + 2015-12-07T21:02:17: Instrument scale factors ..: unity
  175 + 2015-12-07T21:02:17: Observation identifiers ...: all
  176 + 2015-12-07T21:02:17: Model type ................: PointSource
  177 + 2015-12-07T21:02:17: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  178 + 2015-12-07T21:02:17: Number of parameters ......: 6
  179 + 2015-12-07T21:02:17: Number of spatial par's ...: 2
  180 + 2015-12-07T21:02:17: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  181 + 2015-12-07T21:02:17: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  182 + 2015-12-07T21:02:17: Number of spectral par's ..: 3
  183 + 2015-12-07T21:02:17: Prefactor ................: 5.81583e-16 +/- 1.01727e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  184 + 2015-12-07T21:02:17: Index ....................: -2.50611 +/- 0.0153542 [-0,-5] (free,scale=-1,gradient)
  185 + 2015-12-07T21:02:17: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  186 + 2015-12-07T21:02:17: Number of temporal par's ..: 1
  187 + 2015-12-07T21:02:17: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  188 + 2015-12-07T21:02:17: === GCTAModelIrfBackground ===
  189 + 2015-12-07T21:02:17: Name ......................: CTABackgroundModel
  190 + 2015-12-07T21:02:17: Instruments ...............: CTA
  191 + 2015-12-07T21:02:17: Instrument scale factors ..: unity
  192 + 2015-12-07T21:02:17: Observation identifiers ...: all
  193 + 2015-12-07T21:02:17: Model type ................: "PowerLaw" * "Constant"
  194 + 2015-12-07T21:02:17: Number of parameters ......: 4
  195 + 2015-12-07T21:02:17: Number of spectral par's ..: 3
  196 + 2015-12-07T21:02:17: Prefactor ................: 0.990866 +/- 0.0136406 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  197 + 2015-12-07T21:02:17: Index ....................: 0.00536014 +/- 0.00839916 [-5,5] (free,scale=1,gradient)
  198 + 2015-12-07T21:02:17: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  199 + 2015-12-07T21:02:17: Number of temporal par's ..: 1
  200 + 2015-12-07T21:02:17: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
... ...
doc/source/user_manual/glossary.rst
  View file @a4a4190
1 1 Glossary
2 2 ========
3 3  
4   -- **GammaLib** (`<http://gammalib.sourceforge.net/>`_)
  4 +- **GammaLib** (`<http://cta.irap.omp.eu/gammalib/>`_)
5 5  
6 6 A versatile toolbox for scientific analysis of astronomical
7 7 gamma-ray data.
... ...
doc/source/user_manual/index.rst
  View file @a4a4190
... ... @@ -8,8 +8,6 @@ User Manual
8 8 introduction
9 9 getting
10 10 getting_started/index
11   - enhancing
12   - expert
13 11 plotting
14 12 glossary
15 13  
... ...
doc/source/user_manual/introduction.rst
  View file @a4a4190
... ... @@ -22,6 +22,13 @@ also be specified as arguments separated by a whitespace to the ctool:
22 22  
23 23 $ ctobssim ra=83.63 dec=22.01 rad=5.0 tmin=0 tmax=1800 emin=0.1 emax=100.0 caldb=prod2 irf=South_50h inmodel=$CTOOLS/share/models/crab.xml outevents=events.fits
24 24  
  25 +If you need help about the usage of a ctool or a cscript, type the name of
  26 +the ctool or cscript followed by the ``--help`` option:
  27 +
  28 +.. code-block:: bash
  29 +
  30 + $ ctobssim --help
  31 +
25 32 ctools includes also a Python module that declares every ctool as a
26 33 Python class. The following example illustrates the usage:
27 34  
... ... @@ -47,7 +54,7 @@ command line or used as Python classes, as illustrated below:
47 54  
48 55 In this User Manual you will now learn how to install and use the ctools
49 56 package.
50   -If you encounter any problems, please read the :ref:`issues` section.
51   -If you're desperate, you may need :ref:`help`.
  57 +If you encounter any problems, please read the :ref:`faq` and :ref:`issues`
  58 +sections. If you're desperate, you may need :ref:`help`.
52 59 And you should read the :ref:`develop` section if you would like to
53 60 contribute to the ctools developments.
... ...
doc/source/user_manual/plotting.rst
  View file @a4a4190
1 1 Plotting
2 2 ========
3 3  
4   -Gammalib and ctools currently do not include classes and scripts to make plots.
  4 +Gammalib and ctools do not include classes and scripts to make plots.
5 5  
6   -This is intentional because creating and maintaining plotting tools that work on most user's machines
7   -and cover most user's needs is a big project in itself, and deciding to support a
8   -plotting package that is popular now as part of the CTA science tools could become very problematic in the future.
  6 +This is intentional because creating and maintaining plotting tools that
  7 +work on most user's machines and cover most user's needs is a big project
  8 +in itself, and deciding to support a plotting package that is popular now
  9 +as part of the CTA science tools could become very problematic in the
  10 +future.
  11 +
  12 +But we realise that most ctools users need to create plots for their
  13 +high-level science results, so on this page we provide a few pointers
  14 +to external packages and tools.
9 15  
10   -But we realise that most ctools users need to create plots for their high-level science results,
11   -so on this page we provide a few pointers to external packages and tools.
12 16  
13 17 General
14 18 -------
15 19  
16   -The most common way to create publication-quality astronomy plots at the moment is to use the `matplotlib`_
17   -Python plotting package. As illustrated by the `matplotlib gallery`_, virtually any plot can be constructed,
18   -but matplotlib doesn't have built-in easy-to-use classes or functions to create the common plots for gamma-ray
19   -astronomy, which are sky maps and spectra, so in the sections below we give some specific pointers for those.
  20 +The most common way to create publication-quality astronomy plots at the
  21 +moment is to use the `matplotlib`_ Python plotting package. As illustrated
  22 +by the `matplotlib gallery`_, virtually any plot can be constructed,
  23 +but matplotlib doesn't have built-in easy-to-use classes or functions to
  24 +create the common plots for gamma-ray astronomy, which are sky maps and
  25 +spectra, so in the sections below we give some specific pointers for those.
  26 +
20 27  
21 28 Sky maps
22 29 --------
23 30  
24   -For creating publication quality sky map plots via a Python script a good choice is to use `APLPy`_, `WCSAxes`_
25   -or `kapteyn`_, which are all based on matplotlib.
  31 +For creating publication quality sky map plots via a Python script a good
  32 +choice is to use `APLPy`_, `WCSAxes`_ or `kapteyn`_, which are all based on
  33 +matplotlib.
26 34  
27   -You can also use interactive astronomy image viewers like `DS9`_, `Aladin`_ or `Ginga`_
28   -which allow you to save the image to a PNG or PDF file after customising it interactively,
29   -but also contain command line options to create the plot, i.e. you can write a bash or Python script
30   -to make the plot reproducible (DS9 and Ginga also feature direct communication with Python,
31   -but that is a bit harder to use and usually used for interactive image analysis, not plotting scripts).
  35 +You can also use interactive astronomy image viewers like `DS9`_, `Aladin`_
  36 +or `Ginga`_ which allow you to save the image to a PNG or PDF file after
  37 +customising it interactively, but also contain command line options to create
  38 +the plot, i.e. you can write a bash or Python script to make the plot
  39 +reproducible (DS9 and Ginga also feature direct communication with Python,
  40 +but that is a bit harder to use and usually used for interactive image
  41 +analysis, not plotting scripts).
32 42  
33 43  
34 44 Spectra and light curves
35 45 ------------------------
36 46  
37   -To plot spectra or spectral energy distributions (including flux model curves, flux model error bands,
38   -flux points and residuals) and light curves, you can use matplotlib directly,
39   -or use the classes and scripts in `Gammapy`_.
40   -
41   -Another option is to use virtual observatory interactive spectrum tools like `IRIS`_, `CASSIS`_ or `VOSpec`_
42   -which allow you to save the plot to a PNG or PDF file after creating it interactively.
  47 +To plot spectra or spectral energy distributions (including flux model curves,
  48 +flux model error bands, flux points and residuals) and light curves, you can
  49 +use matplotlib directly, or use the classes and scripts in `Gammapy`_.
43 50  
  51 +Another option is to use virtual observatory interactive spectrum tools
  52 +like `IRIS`_, `CASSIS`_ or `VOSpec`_ which allow you to save the plot to a
  53 +PNG or PDF file after creating it interactively.
44 54  
45 55 .. _DS9: http://ds9.si.edu/
46 56 .. _Aladin: http://aladin.u-strasbg.fr/
... ...
pyext/ctool.i
  View file @a4a4190
... ... @@ -99,6 +99,8 @@ public:
99 99  
100 100 // Protected methods that check user parameters
101 101 void require_inobs(const std::string& method);
  102 + void require_inobs_nolist(const std::string& method);
  103 + void require_inobs_nocube(const std::string& method);
102 104  
103 105 // Protected support methods
104 106 void set_response(GObservations& obs);
... ...
src/ctbin/ctbin.cpp
  View file @a4a4190
... ... @@ -434,6 +434,9 @@ void ctbin::get_parameters(void)
434 434 // Throw exception if no input observation file is given
435 435 require_inobs(G_GET_PARAMETERS);
436 436  
  437 + // Throw exception if counts cube is given
  438 + require_inobs_nocube(G_GET_PARAMETERS);
  439 +
437 440 // Get observation container without response (not needed)
438 441 m_obs = get_observations(false);
439 442  
... ...
src/ctbin/ctbin.par
  View file @a4a4190
... ... @@ -17,8 +17,9 @@
17 17 #
18 18 # General parameters
19 19 #===================
20   -inobs, f, a, "events.fits",,, "Event list or observation definition file"
21   -outcube, f, a, "cntcube.fits",,, "Output counts cube"
  20 +inobs, f, a, "events.fits",,, "Input event list or observation definition XML file"
  21 +outcube, f, a, "cntcube.fits",,, "Output counts cube file"
  22 +
22 23 #
23 24 # Energy binning parameters
24 25 #==========================
... ... @@ -27,6 +28,7 @@ emin, r, a, 0.1,,, &quot;Start value for first energy bin in TeV&quot;
27 28 emax, r, a, 100.0,,, "Stop value for last energy bin in TeV"
28 29 enumbins, i, a, 20,,, "Number of energy bins"
29 30 ebinfile, f, a, "NONE",,, "Name of the file containing the energy bin definition"
  31 +
30 32 #
31 33 # Spatial binning parameters
32 34 #===========================
... ... @@ -38,6 +40,7 @@ coordsys, s, a, &quot;CEL&quot;, CEL|GAL,,&quot;Coordinate system (CEL - celestial, GAL - galac
38 40 xref, r, a, 83.63,0,360, "First coordinate of image center in degrees (RA or galactic l)"
39 41 yref, r, a, 22.01,-90,90, "Second coordinate of image center in degrees (DEC or galactic b)"
40 42 proj, s, a, "CAR",AIT|AZP|CAR|MER|MOL|STG|TAN,, "Projection method"
  43 +
41 44 #
42 45 # Standard parameters
43 46 #====================
... ...
src/ctbkgcube/ctbkgcube.cpp
  View file @a4a4190
... ... @@ -450,6 +450,9 @@ void ctbkgcube::get_parameters(void)
450 450 // Throw exception if no input observation file is given
451 451 require_inobs(G_GET_PARAMETERS);
452 452  
  453 + // Throw exception if counts cube is given
  454 + require_inobs_nocube(G_GET_PARAMETERS);
  455 +
453 456 // Build observation container
454 457 m_obs = get_observations();
455 458  
... ...
src/ctbkgcube/ctbkgcube.par
  View file @a4a4190
... ... @@ -15,15 +15,16 @@
15 15 # #
16 16 #############################################################################
17 17 #
18   -# Observational parameters
  18 +# General parameters
19 19 #===================
20   -inobs, f, a, "NONE",,, "Input event list or observation definition file"
  20 +inobs, f, a, "NONE",,, "Input event list or observation definition XML file"
21 21 inmodel, f, a, "NONE",,, "Input model XML file"
22   -incube, f, a, "NONE",,, "Counts cube for background cube definition"
  22 +incube, f, a, "NONE",,, "Input counts cube file to extract background cube definition"
  23 +caldb, s, a, "prod2",,, "Calibration database"
  24 +irf, s, a, "South_0.5h",,, "Instrument response function"
23 25 outcube, f, a, "bkgcube.fits",,, "Output background cube file"
24 26 outmodel, f, a, "NONE",,, "Output model XML file"
25   -caldb, s, a, "prod2",,, "Calibration database"
26   -irf, s, a, "South_50h",,, "Instrument response function"
  27 +
27 28 #
28 29 # Energy binning parameters
29 30 #==========================
... ... @@ -32,6 +33,7 @@ emin, r, a, 0.1,,, &quot;Lower energy limit (TeV)&quot;
32 33 emax, r, a, 100.0,,, "Upper energy limit (TeV)"
33 34 enumbins, i, a, 20,,, "Number of energy bins"
34 35 ebinfile, f, h, "NONE",,, "Name of the file containing the energy bin definition"
  36 +
35 37 #
36 38 # Spatial binning parameters
37 39 #===========================
... ... @@ -43,6 +45,7 @@ coordsys, s, a, &quot;CEL&quot;, CEL|GAL,,&quot;Coordinate system (CEL - celestial, GAL - galac
43 45 xref, r, a, 83.63,0,360, "First coordinate of image center in degrees (RA or galactic l)"
44 46 yref, r, a, 22.01,-90,90, "Second coordinate of image center in degrees (DEC or galactic b)"
45 47 proj, s, a, "CAR", AIT|AZP|CAR|MER|MOL|STG|TAN,, "Projection method"
  48 +
46 49 #
47 50 # Standard parameters
48 51 #====================
... ...
src/ctbutterfly/ctbutterfly.cpp
  View file @a4a4190
... ... @@ -241,8 +241,8 @@ void ctbutterfly::run(void)
241 241 log << m_obs << std::endl;
242 242 }
243 243  
244   - // If refit is selected then do maximum likelihood fit
245   - if (m_refit) {
  244 + // If fit is selected then do maximum likelihood fit
  245 + if (m_fit) {
246 246  
247 247 // Write header
248 248 if (logTerse()) {
... ... @@ -267,14 +267,14 @@ void ctbutterfly::run(void)
267 267 log << m_covariance << std::endl;
268 268 }
269 269  
270   - } // endif: refit selected
  270 + } // endif: fit selected
271 271  
272 272 // Get model instance for further computations
273 273 GModels models = m_obs.models();
274 274  
275   - // If no refit is selected and no covariance matrix has been specified
  275 + // If no fit is selected and no covariance matrix has been specified
276 276 // then compute now the covariance matrix
277   - if (!m_refit && m_covariance.size() == 0) {
  277 + if (!m_fit && m_covariance.size() == 0) {
278 278  
279 279 // Write header
280 280 if (logTerse()) {
... ... @@ -542,7 +542,7 @@ void ctbutterfly::init_members(void)
542 542 m_confidence = 0.68;
543 543 m_max_iter = 50;
544 544 m_apply_edisp = false;
545   - m_refit = false;
  545 + m_fit = false;
546 546 m_ebounds.clear();
547 547 m_outfile.clear();
548 548  
... ... @@ -576,7 +576,7 @@ void ctbutterfly::copy_members(const ctbutterfly&amp; app)
576 576 m_confidence = app.m_confidence;
577 577 m_max_iter = app.m_max_iter;
578 578 m_apply_edisp = app.m_apply_edisp;
579   - m_refit = app.m_refit;
  579 + m_fit = app.m_fit;
580 580 m_ebounds = app.m_ebounds;
581 581 m_outfile = app.m_outfile;
582 582  
... ... @@ -668,7 +668,7 @@ void ctbutterfly::get_parameters(void)
668 668  
669 669 // Read other parameters
670 670 m_confidence = (*this)["confidence"].real();
671   - m_refit = (*this)["refit"].boolean();
  671 + m_fit = (*this)["fit"].boolean();
672 672  
673 673 // Optionally read ahead parameters so that they get correctly
674 674 // dumped into the log file
... ...
src/ctbutterfly/ctbutterfly.hpp
  View file @a4a4190
... ... @@ -93,7 +93,7 @@ protected:
93 93 double m_confidence; //!< Confidence level
94 94 int m_max_iter; //!< Maximum number of iterations
95 95 bool m_apply_edisp; //!< Apply energy dispersion?
96   - bool m_refit; //!< Do refit?
  96 + bool m_fit; //!< Do fit?
97 97 GEbounds m_ebounds; //!< Energy binning definition
98 98 std::string m_outfile; //!< Output ascii file
99 99  
... ...
src/ctbutterfly/ctbutterfly.par
  View file @a4a4190
... ... @@ -17,17 +17,21 @@
17 17 #
18 18 # General parameters
19 19 #===================
20   -inobs, f, a, "events.fits",,,"Input event list, counts cube or observation definition file"
21   -inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Source model"
  20 +inobs, f, a, "events.fits",,,"Input event list, counts cube or observation definition XML file"
  21 +inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model XML file"
22 22 srcname, s, a, "Crab",,,"Source of interest"
23   -expcube, f, a, "NONE",,, "Exposure cube file (only needed for stacked analysis)"
24   -psfcube, f, a, "NONE",,, "PSF cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, "NONE",,, "Background cube file (only needed for stacked analysis)"
  23 +expcube, f, a, "NONE",,, "Input exposure cube file (only needed for stacked analysis)"
  24 +psfcube, f, a, "NONE",,, "Input PSF cube file (only needed for stacked analysis)"
  25 +bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
26 26 caldb, s, a, "prod2",,, "Calibration database"
27   -irf, s, a, "South_50h",,, "Instrument response function"
  27 +irf, s, a, "South_0.5h",,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
29   -outfile, f, a, "butterfly.txt",,, "Output ascii file"
30   -refit, b, h, no,,, "Do refitting?"
  29 +outfile, f, a, "butterfly.txt",,, "Output ASCII file"
  30 +
  31 +#
  32 +# Butterfly parameters
  33 +#=====================
  34 +fit, b, h, no,,, "Perform maximum likelihood fitting?"
31 35 confidence, r, h, 0.68,0.0,1.0, "Confidence level"
32 36 matrix, f, h, "NONE",,, "Input covariance Matrix FITS file"
33 37  
... ...
src/ctcubemask/ctcubemask.cpp
  View file @a4a4190
... ... @@ -357,16 +357,11 @@ void ctcubemask::get_parameters(void)
357 357 // parameters
358 358 if (m_obs.size() == 0) {
359 359  
360   - // Throw exception if no infile is given
361   - if ((*this)["inobs"].filename() == "NONE" ||
362   - (*this)["inobs"].filename() == "") {
363   - std::string msg = "A valid file needs to be specified for the "
364   - "\"inobs\" parameter, yet \""+
365   - (*this)["inobs"].filename()+"\" was given."
366   - " Specify a valid observation definition or "
367   - "event list FITS file to proceed.";
368   - throw GException::invalid_value(G_GET_PARAMETERS, msg);
369   - }
  360 + // Throw exception if no input observation file is given
  361 + require_inobs(G_GET_PARAMETERS);
  362 +
  363 + // Throw exception if event list is given
  364 + require_inobs_nolist(G_GET_PARAMETERS);
370 365  
371 366 // Build observation container without response (not needed)
372 367 m_obs = get_observations(false);
... ... @@ -389,7 +384,7 @@ void ctcubemask::get_parameters(void)
389 384 }
390 385 }
391 386  
392   - // Check if radius is vaild for a RoI selection
  387 + // Check if radius is valid for a RoI selection
393 388 if (m_select_roi && (*this)["rad"].is_valid()) {
394 389 m_rad = (*this)["rad"].real();
395 390 }
... ...
src/ctcubemask/ctcubemask.par
  View file @a4a4190
... ... @@ -15,21 +15,23 @@
15 15 # #
16 16 #############################################################################
17 17 #
18   -# File information
19   -#=================
20   -inobs, f, a, "cntmap.fits",,, "Input counts cube or observation definition file"
21   -regfile, f, a, "NONE",,, "Exclusion region file in ds9 format"
22   -outcube, f, a, "filtered_cube.fits",,, "Output counts cube or observation definition file"
23   -prefix, s, h, "filtered_",,, "Prefix for counts cube in observation definition file"
  18 +# General parameters
  19 +#===================
  20 +inobs, f, a, "cntmap.fits",,, "Input counts cube or observation definition XML file"
  21 +outcube, f, a, "filtered_cube.fits",,, "Output counts cube or observation definition XML file"
  22 +prefix, s, h, "filtered_",,, "Prefix for counts cube in observation definition XML file"
  23 +
24 24 #
25 25 # Selection parameters
26 26 #=====================
27   -usepnt, b, h, no,,, "Use pointing instead of RA/DEC parameters?"
28   -ra, r, a, 83.63,0,360, "RA for ROI centre (degrees)"
29   -dec, r, a, 22.01,-90,90, "Dec for ROI centre (degrees)"
30   -rad, r, a, 3.0,0,180, "Radius of ROI (degrees)"
31   -emin, r, a, 0.1,,, "Lower energy limit (TeV)"
32   -emax, r, a, 100.0,,, "Upper energy limit (TeV)"
  27 +usepnt, b, h, no,,, "Use pointing instead of RA/DEC parameters?"
  28 +ra, r, a, 83.63,0,360, "RA for ROI centre (degrees)"
  29 +dec, r, a, 22.01,-90,90, "Dec for ROI centre (degrees)"
  30 +rad, r, a, 3.0,0,180, "Radius of ROI (degrees)"
  31 +regfile, f, a, "NONE",,, "Input exclusion region file in ds9 format"
  32 +emin, r, a, 0.1,,, "Lower energy limit (TeV)"
  33 +emax, r, a, 100.0,,, "Upper energy limit (TeV)"
  34 +
33 35 #
34 36 # Standard parameters
35 37 #====================
... ...
src/cterror/cterror.par
  View file @a4a4190
... ... @@ -18,16 +18,16 @@
18 18 #
19 19 # General parameters
20 20 #===================
21   -inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition file"
22   -inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Source model"
23   -outmodel, f, a, "results.xml",,, "Source model output file"
  21 +inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition XML file"
  22 +inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model XML file"
24 23 srcname, s, a, "Crab",,, "Source of interest"
25   -expcube, f, a, "NONE",,, "Exposure cube file (only needed for stacked analysis)"
26   -psfcube, f, a, "NONE",,, "PSF cube file (only needed for stacked analysis)"
27   -bkgcube, f, a, "NONE",,, "Background cube file (only needed for stacked analysis)"
  24 +expcube, f, a, "NONE",,, "Input exposure cube file (only needed for stacked analysis)"
  25 +psfcube, f, a, "NONE",,, "Input PSF cube file (only needed for stacked analysis)"
  26 +bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
28 27 caldb, s, a, "prod2",,, "Calibration database"
29   -irf, s, a, "South_50h",,, "Instrument response function"
  28 +irf, s, a, "South_0.5h",,, "Instrument response function"
30 29 edisp, b, h, no,,, "Apply energy dispersion?"
  30 +outmodel, f, a, "results.xml",,, "Output model XML file"
31 31  
32 32 #
33 33 # Error calculation parameters
... ...
src/cterror/main.cpp
  View file @a4a4190
... ... @@ -19,7 +19,7 @@
19 19 * *
20 20 ***************************************************************************/
21 21 /**
22   - * @file main.cpp
  22 + * @file cterror/main.cpp
23 23 * @brief CTA parameter error calculation
24 24 * @author Florent Forest
25 25 */
... ...
src/ctexpcube/ctexpcube.cpp
  View file @a4a4190
... ... @@ -354,6 +354,9 @@ void ctexpcube::get_parameters(void)
354 354 // Throw exception if no input observation file is given
355 355 require_inobs(G_GET_PARAMETERS);
356 356  
  357 + // Throw exception if counts cube is given
  358 + require_inobs_nocube(G_GET_PARAMETERS);
  359 +
357 360 // Build observation container
358 361 m_obs = get_observations();
359 362  
... ...
src/ctexpcube/ctexpcube.par
  View file @a4a4190
... ... @@ -15,14 +15,15 @@
15 15 # #
16 16 #############################################################################
17 17 #
18   -# Observational parameters
  18 +# General parameters
19 19 #===================
20   -inobs, f, a, "NONE",,, "Event list or observation definition file"
21   -incube, f, a, "NONE",,, "Counts cube for exposure cube definition"
22   -outcube, f, a, "expcube.fits",,, "Output exposure cube file"
  20 +inobs, f, a, "NONE",,, "Input event list or observation definition XML file"
  21 +incube, f, a, "NONE",,, "Input counts cube file to extract exposure cube definition"
23 22 caldb, s, a, "prod2",,, "Calibration database"
24   -irf, s, a, "South_50h",,, "Instrument response function"
  23 +irf, s, a, "South_0.5h",,, "Instrument response function"
25 24 edisp, b, h, no,,, "Apply energy dispersion?"
  25 +outcube, f, a, "expcube.fits",,, "Output exposure cube file"
  26 +
26 27 #
27 28 # Energy binning parameters
28 29 #==========================
... ... @@ -31,6 +32,7 @@ emin, r, a, 0.1,,,&quot;Lower energy limit (TeV)&quot;
31 32 emax, r, a, 100.0,,, "Upper energy limit (TeV)"
32 33 enumbins, i, a, 20,,, "Number of energy bins"
33 34 ebinfile, f, h, "NONE",,, "Name of the file containing the energy bin definition"
  35 +
34 36 #
35 37 # Spatial binning parameters
36 38 #===========================
... ... @@ -42,6 +44,7 @@ coordsys, s, a, &quot;CEL&quot;, CEL|GAL,,&quot;Coordinate system (CEL - celestial, GAL - galac
42 44 xref, r, a, 83.63,0,360, "First coordinate of image center in degrees (RA or galactic l)"
43 45 yref, r, a, 22.01,-90,90, "Second coordinate of image center in degrees (DEC or galactic b)"
44 46 proj, s, a, "CAR", AIT|AZP|CAR|MER|MOL|STG|TAN,, "Projection method"
  47 +
45 48 #
46 49 # Standard parameters
47 50 #====================
... ...
src/ctlike/ctlike.cpp
  View file @a4a4190
... ... @@ -310,7 +310,7 @@ void ctlike::run(void)
310 310 // Write results into logger
311 311 if (logTerse()) {
312 312 log << std::endl;
313   - log.header1("Maximum likelihood optimization results");
  313 + log.header1("Maximum likelihood optimisation results");
314 314 log << *m_opt << std::endl;
315 315 log << gammalib::parformat("Maximum log likelihood");
316 316 log << gammalib::str(m_logL,3) << std::endl;
... ... @@ -545,7 +545,7 @@ double ctlike::reoptimize_lm(void)
545 545 log.indent(0);
546 546 if (logTerse()) {
547 547 log << std::endl;
548   - log.header1("Maximum likelihood re-optimization results");
  548 + log.header1("Maximum likelihood re-optimisation results");
549 549 log << *m_opt << std::endl;
550 550 }
551 551  
... ...
src/ctlike/ctlike.par
  View file @a4a4190
... ... @@ -17,18 +17,22 @@
17 17 #
18 18 # General parameters
19 19 #===================
20   -inobs, f, a, "events.fits",,, "Event list, counts cube or observation definition file"
21   -inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Source model"
22   -expcube, f, a, "NONE",,, "Exposure cube file (only needed for stacked analysis)"
23   -psfcube, f, a, "NONE",,, "PSF cube file (only needed for stacked analysis)"
24   -bkgcube, f, a, "NONE",,, "Background cube file (only needed for stacked analysis)"
  20 +inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition XML file"
  21 +inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model XML file"
  22 +expcube, f, a, "NONE",,, "Input exposure cube file (only needed for stacked analysis)"
  23 +psfcube, f, a, "NONE",,, "Input PSF cube file (only needed for stacked analysis)"
  24 +bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
25 25 caldb, s, a, "prod2",,, "Calibration database"
26   -irf, s, a, "South_50h",,, "Instrument response function"
27   -outmodel, f, a, "crab_results.xml",,, "Source model output file"
28   -stat, s, h, "POISSON",,, "Optimization statistics"
  26 +irf, s, a, "South_0.5h",,, "Instrument response function"
29 27 edisp, b, h, no,,, "Apply energy dispersion?"
  28 +outmodel, f, a, "crab_results.xml",,, "Output model XML file"
  29 +
  30 +#
  31 +# Maximisation parameters
  32 +#========================
  33 +stat, s, h, "POISSON",,, "Optimization statistics"
30 34 refit, b, h, no,,, "Do refitting?"
31   -fix_spat_for_ts, b, h, no,,,"Fix spatial parameters for TS computation?"
  35 +fix_spat_for_ts, b, h, no,,, "Fix spatial parameters for TS computation?"
32 36  
33 37 #
34 38 # Standard parameters
... ...
src/ctmodel/ctmodel.par
  View file @a4a4190
... ... @@ -17,25 +17,27 @@
17 17 #
18 18 # General parameters
19 19 #===================
20   -incube, f, a, "NONE",,, "Input counts cube"
21   -inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Source model"
22   -outcube, f, a, "modcube.fits",,, "Output model cube"
  20 +inobs, f, a, "NONE",,, "Input event list, counts cube or observation definition XML file"
  21 +incube, f, a, "NONE",,, "Input counts cube file to extract model cube definition"
  22 +inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model XML file"
  23 +expcube, f, a, "NONE",,, "Input exposure cube file (only needed for stacked analysis)"
  24 +psfcube, f, a, "NONE",,, "Input PSF cube file (only needed for stacked analysis)"
  25 +bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
  26 +caldb, s, a, "prod2",,, "Calibration database"
  27 +irf, s, a, "South_0.5h",,, "Instrument response function"
23 28 edisp, b, h, no,,, "Apply energy dispersion?"
  29 +outcube, f, a, "modcube.fits",,, "Output model cube file"
  30 +
24 31 #
25 32 # Observation parameters
26 33 #=======================
27   -inobs, f, a, "NONE",,, "Event list, counts cube or observation definition file"
28   -expcube, f, a, "NONE",,, "Exposure cube file (only needed for stacked analysis)"
29   -psfcube, f, a, "NONE",,, "PSF cube file (only needed for stacked analysis)"
30   -bkgcube, f, a, "NONE",,, "Background cube file (only needed for stacked analysis)"
31   -caldb, s, a, "prod2",,, "Calibration database"
32   -irf, s, a, "South_50h",,, "Instrument response function"
33 34 ra, r, a, 83.63,0,360, "RA of pointing (degrees)"
34 35 dec, r, a, 22.01,-90,90, "Dec of pointing (degrees)"
35 36 rad, r, a, 5.0,0,180, "Radius of FOV (degrees)"
36 37 tmin, r, a, 0.0,,, "Start time (MET in s)"
37 38 tmax, r, a, 1800.0,,, "End time (MET in s)"
38 39 deadc, r, h, 0.95,0,1, "Average deadtime correction factor"
  40 +
39 41 #
40 42 # Energy binning parameters
41 43 #==========================
... ... @@ -44,6 +46,7 @@ emin, r, a, 0.1,,, &quot;Start value for first energy bin in TeV&quot;
44 46 emax, r, a, 100.0,,, "Stop value for last energy bin in TeV"
45 47 enumbins, i, a, 20,,, "Number of energy bins"
46 48 ebinfile, f, h, "NONE",,, "Name of the file containing the energy bin definition"
  49 +
47 50 #
48 51 # Spatial binning parameters
49 52 #===========================
... ... @@ -55,6 +58,7 @@ coordsys, s, a, &quot;CEL&quot;, CEL|GAL,,&quot;Coordinate system (CEL - celestial, GAL - galac
55 58 xref, r, a, 83.63,0,360, "First coordinate of image center in degrees (RA or galactic l)"
56 59 yref, r, a, 22.01,-90,90, "Second coordinate of image center in degrees (DEC or galactic b)"
57 60 proj, s, a, "CAR", AIT|AZP|CAR|MER|MOL|STG|TAN,, "Projection method"
  61 +
58 62 #
59 63 # Standard parameters
60 64 #====================
... ...
src/ctobssim/ctobssim.cpp
  View file @a4a4190
... ... @@ -33,6 +33,7 @@
33 33 #include "GTools.hpp"
34 34  
35 35 /* __ Method name definitions ____________________________________________ */
  36 +#define G_GET_PARAMETERS "ctobssim::get_parameters()"
36 37 #define G_SIMULATE_SOURCE "ctobssim::simulate_source(GCTAObservation*, "\
37 38 "GModels&, GRan&, GLog*)"
38 39  
... ... @@ -577,7 +578,13 @@ void ctobssim::get_parameters(void)
577 578 // If there are no observations in container then load them via user
578 579 // parameters
579 580 if (m_obs.size() == 0) {
  581 +
  582 + // Throw exception if counts cube is given
  583 + require_inobs_nocube(G_GET_PARAMETERS);
  584 +
  585 + // Get observation container
580 586 m_obs = get_observations();
  587 +
581 588 }
582 589  
583 590 // ... otherwise make sure that observation boundaries are set
... ... @@ -984,6 +991,8 @@ void ctobssim::simulate_source(GCTAObservation* obs, const GModels&amp; models,
984 991 * @param[in] emax Maximum energy.
985 992 * @param[in] centre Centre of region for photon rate determination.
986 993 * @param[in] radius Radius of region for photon rate determination (degrees).
  994 + * @param[in] indent Indent for logging.
  995 + * @param[in,out] wrklog Pointer to logger (default: NULL).
987 996 * @return Model flux (photons/cm2/sec).
988 997 ***************************************************************************/
989 998 double ctobssim::get_model_flux(const GModelSky* model,
... ...
src/ctobssim/ctobssim.par
  View file @a4a4190
... ... @@ -15,17 +15,16 @@
15 15 # #
16 16 #############################################################################
17 17 #
18   -# File information
19   -#=================
20   -inobs, f, h, "NONE",,, "Input event list or observation definition file"
21   -inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Model"
22   -outevents, f, a, "events.fits",,, "Output event data file or observation definition file"
23   -prefix, s, h, "sim_events_",,, "Prefix for event lists in observation definition file"
24   -#
25   -# Observation parameters
26   -#=======================
27   -caldb, s, a, "prod2",,, "Calibration database"
28   -irf, s, a, "South_50h",,, "Instrument response function"
  18 +# General parameters
  19 +#===================
  20 +inobs, f, h, "NONE",,, "Input event list or observation definition XML file"
  21 +inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model XML file"
  22 +caldb, s, a, "prod2",,, "Calibration database"
  23 +irf, s, a, "South_0.5h",,, "Instrument response function"
  24 +edisp, b, h, no,,, "Apply energy dispersion?"
  25 +outevents, f, a, "events.fits",,, "Output event data file or observation definition XML file"
  26 +prefix, s, h, "sim_events_",,, "Prefix for event lists in observation definition XML file"
  27 +
29 28 #
30 29 # Simulation parameters
31 30 #======================
... ... @@ -37,9 +36,9 @@ tmin, r, a, 0.0,,, &quot;Start time (MET in s)&quot;
37 36 tmax, r, a, 1800.0,,, "End time (MET in s)"
38 37 emin, r, a, 0.1,,, "Lower energy limit (TeV)"
39 38 emax, r, a, 100.0,,, "Upper energy limit (TeV)"
40   -edisp, b, h, no,,, "Apply energy dispersion?"
41 39 deadc, r, h, 0.95,0,1, "Average deadtime correction factor"
42 40 maxrate, r, h, 1.0e6,,, "Maximum photon rate"
  41 +
43 42 #
44 43 # Standard parameters
45 44 #====================
... ...
src/ctpsfcube/ctpsfcube.cpp
  View file @a4a4190
... ... @@ -353,6 +353,9 @@ void ctpsfcube::get_parameters(void)
353 353 // Throw exception if no input observation file is given
354 354 require_inobs(G_GET_PARAMETERS);
355 355  
  356 + // Throw exception if counts cube is given
  357 + require_inobs_nocube(G_GET_PARAMETERS);
  358 +
356 359 // Build observation container
357 360 m_obs = get_observations();
358 361  
... ...
src/ctpsfcube/ctpsfcube.par
  View file @a4a4190
... ... @@ -17,12 +17,13 @@
17 17 #
18 18 # Observational parameters
19 19 #===================
20   -inobs, f, a, "NONE",,, "Event list or observation definition file"
21   -incube, f, a, "NONE",,, "Counts cube for psf cube definition"
22   -outcube, f, a, "psfcube.fits",,, "Output psf cube file"
  20 +inobs, f, a, "NONE",,, "Input event list or observation definition XML file"
  21 +incube, f, a, "NONE",,, "Input counts cube file to extract PSF cube definition"
23 22 caldb, s, a, "prod2",,, "Calibration database"
24   -irf, s, a, "South_50h",,, "Instrument response function"
  23 +irf, s, a, "South_0.5h",,, "Instrument response function"
25 24 edisp, b, h, no,,, "Apply energy dispersion?"
  25 +outcube, f, a, "psfcube.fits",,, "Output PSF cube file"
  26 +
26 27 #
27 28 # Energy binning parameters
28 29 #==========================
... ... @@ -31,6 +32,7 @@ emin, r, a, 0.1,,, &quot;Lower energy limit (TeV)&quot;
31 32 emax, r, a, 100.0,,, "Upper energy limit (TeV)"
32 33 enumbins, i, a, 20,,, "Number of energy bins"
33 34 ebinfile, f, h, "NONE",,, "Name of the file containing the energy bin definition"
  35 +
34 36 #
35 37 # Spatial binning parameters
36 38 #===========================
... ... @@ -42,11 +44,13 @@ coordsys, s, a, &quot;CEL&quot;, CEL|GAL,,&quot;Coordinate system (CEL - celestial, GAL - galac
42 44 xref, r, a, 83.63,0,360, "First coordinate of image center in degrees (RA or galactic l)"
43 45 yref, r, a, 22.01,-90,90, "Second coordinate of image center in degrees (DEC or galactic b)"
44 46 proj, s, a, "CAR", AIT|AZP|CAR|MER|MOL|STG|TAN,, "Projection method"
  47 +
45 48 #
46 49 # Angular separation binning parameters
47 50 #======================================
48 51 amax, r, h, 0.3,,, "Upper bound of angular separation between true and measued photon direction (degrees)"
49 52 anumbins, i, h, 200,,, "Number of angular separation bins"
  53 +
50 54 #
51 55 # Standard parameters
52 56 #====================
... ...
src/ctselect/ctselect.cpp
  View file @a4a4190
... ... @@ -510,6 +510,9 @@ void ctselect::get_parameters(void)
510 510 // Throw exception if no input observation file is given
511 511 require_inobs(G_GET_PARAMETERS);
512 512  
  513 + // Throw exception if counts cube is given
  514 + require_inobs_nocube(G_GET_PARAMETERS);
  515 +
513 516 // Get observation container without response (not needed)
514 517 m_obs = get_observations(false);
515 518  
... ... @@ -571,14 +574,6 @@ void ctselect::get_parameters(void)
571 574 m_expr = (*this)["expr"].string();
572 575 m_usethres = (*this)["usethres"].string();
573 576  
574   - // Check parameters (Kluge as the parfile interface does not yet check
575   - // parameters; this can be removed once this is done properly)
576   - if (m_usethres != "NONE" && m_usethres != "DEFAULT" && m_usethres != "USER") {
577   - std::string msg = "Parameter \"usethres\" must be one of \"NONE\", "
578   - "\"DEFAULT\" or \"USER\".";
579   - throw GException::invalid_value(G_GET_PARAMETERS, msg);
580   - }
581   -
582 577 // Optionally read ahead parameters so that they get correctly
583 578 // dumped into the log file
584 579 if (read_ahead()) {
... ...
src/ctselect/ctselect.par
  View file @a4a4190
... ... @@ -15,11 +15,12 @@
15 15 # #
16 16 #############################################################################
17 17 #
18   -# File information
19   -#=================
20   -inobs, f, a, "events.fits",,, "Input event list or observation definition file"
21   -outobs, f, a, "selected_events.fits",,, "Output event list or observation definition file"
22   -prefix, s, h, "selected_",,, "Prefix for event lists in observation definition file"
  18 +# General parameters
  19 +#===================
  20 +inobs, f, a, "events.fits",,, "Input event list or observation definition XML file"
  21 +outobs, f, a, "selected_events.fits",,, "Output event list or observation definition XML file"
  22 +prefix, s, h, "selected_",,, "Prefix for event lists in observation definition XML file"
  23 +
23 24 #
24 25 # Selection parameters
25 26 #=====================
... ... @@ -33,6 +34,7 @@ emin, r, a, 0.1,,, &quot;Lower energy limit (TeV)&quot;
33 34 emax, r, a, 100.0,,, "Upper energy limit (TeV)"
34 35 expr, s, h, "",,, "Additional selection expression"
35 36 usethres,s, h, "NONE",NONE|DEFAULT|USER,, "Energy threshold type"
  37 +
36 38 #
37 39 # Standard parameters
38 40 #====================
... ...
src/ctskymap/ctskymap.cpp
  View file @a4a4190
... ... @@ -347,6 +347,9 @@ void ctskymap::get_parameters(void)
347 347 // Throw exception if no input observation file is given
348 348 require_inobs(G_GET_PARAMETERS);
349 349  
  350 + // Throw exception if counts cube is given
  351 + require_inobs_nocube(G_GET_PARAMETERS);
  352 +
350 353 // Get observation container without response (not needed)
351 354 m_obs = get_observations(false);
352 355  
... ...
src/ctskymap/ctskymap.par
  View file @a4a4190
... ... @@ -17,13 +17,15 @@
17 17 #
18 18 # General parameters
19 19 #===================
20   -inobs, f, a, "events.fits",,, "Event list or observation definition file"
21   -outmap, f, a, "skymap.fits",,, "Output file name"
  20 +inobs, f, a, "events.fits",,, "Input event list or observation definition XML file"
  21 +outmap, f, a, "skymap.fits",,, "Output skymap file"
  22 +
22 23 #
23 24 # Event selection parameters
24 25 #===========================
25 26 emin, r, a, 0.1,,, "Lower energy limit (TeV)"
26 27 emax, r, a, 100.0,,, "Upper energy limit (TeV)"
  28 +
27 29 #
28 30 # Spatial binning parameters
29 31 #===========================
... ...
src/cttsmap/cttsmap.par
  View file @a4a4190
... ... @@ -17,16 +17,16 @@
17 17 #
18 18 # General parameters
19 19 #===================
20   -inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition file"
21   -inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Source model"
22   -srcname, s, a, "Crab",,, "Test source"
23   -expcube, f, a, "NONE",,, "Exposure cube file (only needed for stacked analysis)"
24   -psfcube, f, a, "NONE",,, "PSF cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, "NONE",,, "Background cube file (only needed for stacked analysis)"
  20 +inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition XML file"
  21 +inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model XML file"
  22 +srcname, s, a, "Crab",,, "Test source name"
  23 +expcube, f, a, "NONE",,, "Input exposure cube file (only needed for stacked analysis)"
  24 +psfcube, f, a, "NONE",,, "Input PSF cube file (only needed for stacked analysis)"
  25 +bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
26 26 caldb, s, a, "prod2",,, "Calibration database"
27   -irf, s, a, "South_50h",,, "Instrument response function"
  27 +irf, s, a, "South_0.5h",,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
29   -outmap, f, a, "tsmap.fits",,, "Output Test Statistic map"
  29 +outmap, f, a, "tsmap.fits",,, "Output Test Statistic map file"
30 30  
31 31 #
32 32 # Spatial binning parameters
... ... @@ -47,7 +47,6 @@ binmin, i, h, -1,,, &quot;First bin to compute&quot;
47 47 binmax, i, h, -1,,, "Last bin to compute"
48 48 logL0, r, h, 0.0,,, "LogLikelihood value of null hypothesis"
49 49  
50   -
51 50 #
52 51 # Standard parameters
53 52 #====================
... ...
src/ctulimit/ctulimit.par
  View file @a4a4190
... ... @@ -17,14 +17,14 @@
17 17 #
18 18 # General parameters
19 19 #===================
20   -inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition file"
21   -inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Source model"
  20 +inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition XML file"
  21 +inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model XML file"
22 22 srcname, s, a, "Crab",,, "Source of interest"
23   -expcube, f, a, "NONE",,, "Exposure cube file (only needed for stacked analysis)"
24   -psfcube, f, a, "NONE",,, "PSF cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, "NONE",,, "Background cube file (only needed for stacked analysis)"
  23 +expcube, f, a, "NONE",,, "Input exposure cube file (only needed for stacked analysis)"
  24 +psfcube, f, a, "NONE",,, "Input PSF cube file (only needed for stacked analysis)"
  25 +bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
26 26 caldb, s, a, "prod2",,, "Calibration database"
27   -irf, s, a, "South_50h",,, "Instrument response function"
  27 +irf, s, a, "South_0.5h",,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
29 29  
30 30 #
... ... @@ -33,9 +33,9 @@ edisp, b, h, no,,, &quot;Apply energy dispersion?&quot;
33 33 confidence, r, h, 0.95,0.0,1.0, "Confidence level"
34 34 sigma_min, r, h, 0.0,,, "Start minimum value (multiple sigmas above fit value)"
35 35 sigma_max, r, h, 10.0,,, "Start maximum value (multiple sigmas above fit value)"
36   -eref, r, h, 1.0,,, "Reference energy for differential limits (TeV)"
37   -emin, r, h, 1.0,,, "Minimum energy for flux limits (TeV)"
38   -emax, r, h, 100.0,,, "Maximum energy for flux limits (TeV)"
  36 +eref, r, h, 1.0,,, "Reference energy for differential limit (TeV)"
  37 +emin, r, h, 1.0,,, "Minimum energy for integral flux limit (TeV)"
  38 +emax, r, h, 100.0,,, "Maximum energy for integral flux limit (TeV)"
39 39 tol, r, h, 1e-5,,, "Computation tolerance"
40 40 max_iter, i, h, 50,,, "Maximum number of iterations"
41 41  
... ...
src/support/ctool.cpp
  View file @a4a4190
... ... @@ -656,18 +656,23 @@ GCTAObservation ctool::create_cta_obs(void)
656 656  
657 657  
658 658 /***********************************************************************//**
659   - * @brief Throws exception in inobs parameter is not valid
  659 + * @brief Throws exception if inobs parameter is not valid
660 660 *
661 661 * @param[in] method Method name.
  662 + *
  663 + * Throw an exception if the inobs parameter is either NONE or an empty
  664 + * string.
662 665 ***************************************************************************/
663 666 void ctool::require_inobs(const std::string& method)
664 667 {
  668 + // Get inobs filename
  669 + std::string filename = (*this)["inobs"].filename();
  670 +
665 671 // Throw exception if no infile is given
666   - if ((*this)["inobs"].filename() == "NONE" ||
667   - (*this)["inobs"].filename() == "") {
  672 + if (filename == "NONE" || gammalib::strip_whitespace(filename) == "") {
668 673 std::string msg = "A valid file needs to be specified for the "
669   - "\"inobs\" parameter, yet \""+
670   - (*this)["inobs"].filename()+"\" was given."
  674 + "\"inobs\" parameter, yet \""+filename+
  675 + "\" was given."
671 676 " Specify a valid observation definition or "
672 677 "FITS file to proceed.";
673 678 throw GException::invalid_value(method, msg);
... ... @@ -679,6 +684,110 @@ void ctool::require_inobs(const std::string&amp; method)
679 684  
680 685  
681 686 /***********************************************************************//**
  687 + * @brief Throws exception if inobs parameter is an event list
  688 + *
  689 + * @param[in] method Method name.
  690 + *
  691 + * Throw an exception if the inobs parameter is an event list.
  692 + ***************************************************************************/
  693 +void ctool::require_inobs_nolist(const std::string& method)
  694 +{
  695 + // Get inobs filename
  696 + std::string filename = (*this)["inobs"].filename();
  697 +
  698 + // Continue only if we have a FITS file
  699 + if (gammalib::is_fits(filename)) {
  700 +
  701 + // Signal no list
  702 + bool is_list = false;
  703 +
  704 + // Try loading file as counts cube. If this is successful then
  705 + // throw an exception
  706 + try {
  707 +
  708 + // Load list from file
  709 + GCTAEventList list(filename);
  710 +
  711 + // If we're still alive then signal that we have a list
  712 + is_list = true;
  713 +
  714 + }
  715 +
  716 + // Catch any exceptions
  717 + catch (...) {
  718 + ;
  719 + }
  720 +
  721 + // If we have an event list then throw an exception
  722 + if (is_list) {
  723 + std::string msg = "An event list has been specified for the "
  724 + "\"inobs\" parameter, yet no event list "
  725 + "can be specified as input observation."
  726 + " Instead, specify a counts cube or an "
  727 + "observation definition file.";
  728 + throw GException::invalid_value(method, msg);
  729 + }
  730 +
  731 + } // endif: we had a FITS file
  732 +
  733 + // Return
  734 + return;
  735 +}
  736 +
  737 +
  738 +/***********************************************************************//**
  739 + * @brief Throws exception if inobs parameter is a counts cube
  740 + *
  741 + * @param[in] method Method name.
  742 + *
  743 + * Throw an exception if the inobs parameter is a counts cube.
  744 + ***************************************************************************/
  745 +void ctool::require_inobs_nocube(const std::string& method)
  746 +{
  747 + // Get inobs filename
  748 + std::string filename = (*this)["inobs"].filename();
  749 +
  750 + // Continue only if we have a FITS file
  751 + if (gammalib::is_fits(filename)) {
  752 +
  753 + // Signal no cube
  754 + bool is_cube = false;
  755 +
  756 + // Try loading file as counts cube. If this is successful then
  757 + // throw an exception
  758 + try {
  759 +
  760 + // Load cube from file
  761 + GCTAEventCube cube(filename);
  762 +
  763 + // If we're still alive then signal that we have a cube
  764 + is_cube = true;
  765 +
  766 + }
  767 +
  768 + // Catch any exceptions
  769 + catch (...) {
  770 + ;
  771 + }
  772 +
  773 + // If we have a counts cube then throw an exception
  774 + if (is_cube) {
  775 + std::string msg = "A counts cube has been specified for the "
  776 + "\"inobs\" parameter, yet no counts cube "
  777 + "can be specified as input observation."
  778 + " Instead, specify an event list or an "
  779 + "observation definition file.";
  780 + throw GException::invalid_value(method, msg);
  781 + }
  782 +
  783 + } // endif: we had a FITS file
  784 +
  785 + // Return
  786 + return;
  787 +}
  788 +
  789 +
  790 +/***********************************************************************//**
682 791 * @brief Set response for all CTA observations in container
683 792 *
684 793 * @param[in,out] obs Observation container
... ...
src/support/ctool.hpp
  View file @a4a4190
... ... @@ -81,6 +81,8 @@ protected:
81 81  
82 82 // Protected methods that check user parameters
83 83 void require_inobs(const std::string& method);
  84 + void require_inobs_nolist(const std::string& method);
  85 + void require_inobs_nocube(const std::string& method);
84 86  
85 87 // Protected support methods
86 88 void set_response(GObservations& obs);
... ...