Andreas Specovius / ctools

Commit ff3e361559a32d90506d59e483940ca7cdc94203

Authored by Jürgen Knödlseder
1 parent f9f30490

Update quickstart documentation

Inline Side-by-side
Showing 36 changed files with 637 additions and 148 deletions
cscripts/csresmap.par
  View file @ff3e361
... ... @@ -19,10 +19,10 @@
19 19 inobs, f, a, events.fits,,, "Input event list, counts cube, or observation definition XML file"
20 20 inmodel, f, a, $CTOOLS/share/models/crab.xml,,, "Input model definition XML file"
21 21 modcube, f, a, NONE,,, "Input model cube file (generated with ctmodel)"
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   -edispcube, f, a, NONE,,, "Input energy dispersion cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, NONE,,, "Input background cube file (only needed for stacked analysis)"
  22 +expcube, f, a, NONE,,, "Input exposure cube file"
  23 +psfcube, f, a, NONE,,, "Input PSF cube file"
  24 +edispcube, f, a, NONE,,, "Input energy dispersion cube file"
  25 +bkgcube, f, a, NONE,,, "Input background cube file"
26 26 caldb, s, a, prod2,,, "Calibration database"
27 27 irf, s, a, South_0.5h,,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
... ... @@ -43,7 +43,7 @@ yref, r, a, 22.01,-90,90, "Second coordinate of image center in degrees (DE
43 43 nxpix, i, a, 200,,, "Size of the X axis in pixels"
44 44 nypix, i, a, 200,,, "Size of the Y axis in pixels"
45 45 binsz, r, a, 0.02,,, "Pixel size (deg/pixel)"
46   -algorithm, s, a, SUBDIV,SUB|SUBDIV|SUBDIVSQRT|SIGNIFICANCE,, "Residual map computation algorithm"
  46 +algorithm, s, a, SIGNIFICANCE,SUB|SUBDIV|SUBDIVSQRT|SIGNIFICANCE,, "Residual map computation algorithm"
47 47  
48 48 #
49 49 # Standard parameters
... ...
cscripts/csspec.par
  View file @ff3e361
... ... @@ -19,10 +19,10 @@
19 19 inobs, f, a, events.fits,,, "Input event list, counts cube, or observation definition XML file"
20 20 inmodel, f, a, $CTOOLS/share/models/crab.xml,,, "Input model definition XML file"
21 21 srcname, s, a, Crab,,, "Source name"
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   -edispcube, f, a, NONE,,, "Input energy dispersion cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, NONE,,, "Input background cube file (only needed for stacked analysis)"
  22 +expcube, f, a, NONE,,, "Input exposure cube file"
  23 +psfcube, f, a, NONE,,, "Input PSF cube file"
  24 +edispcube, f, a, NONE,,, "Input energy dispersion cube file"
  25 +bkgcube, f, a, NONE,,, "Input background cube file"
26 26 caldb, s, a, prod2,,, "Calibration database"
27 27 irf, s, a, South_0.5h,,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
... ...
cscripts/cstsdist.par
  View file @ff3e361
... ... @@ -19,10 +19,10 @@
19 19 inobs, f, h, NONE,,, "Input event list, counts cube, or observation definition XML file"
20 20 inmodel, f, a, $CTOOLS/share/models/crab.xml,,, "Input model definition XML file"
21 21 srcname, s, a, Crab,,, "Source name"
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   -edispcube, f, a, NONE,,, "Input energy dispersion cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, NONE,,, "Input background cube file (only needed for stacked analysis)"
  22 +expcube, f, a, NONE,,, "Input exposure cube file"
  23 +psfcube, f, a, NONE,,, "Input PSF cube file"
  24 +edispcube, f, a, NONE,,, "Input energy dispersion cube file"
  25 +bkgcube, f, a, NONE,,, "Input background cube file"
26 26 caldb, s, a, prod2,,, "Calibration database"
27 27 irf, s, a, South_0.5h,,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
... ...
cscripts/cstsmapsplit.par
  View file @ff3e361
... ... @@ -19,10 +19,10 @@
19 19 inobs, f, a, events.fits,,, "Input event list, counts cube or observation definition XML file"
20 20 inmodel, f, a, $CTOOLS/share/models/crab.xml,,, "Input model definition XML file"
21 21 srcname, s, a, Crab,,, "Test source name"
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   -edispcube, f, a, NONE,,, "Input energy dispersion cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, NONE,,, "Input background cube file (only needed for stacked analysis)"
  22 +expcube, f, a, NONE,,, "Input exposure cube file"
  23 +psfcube, f, a, NONE,,, "Input PSF cube file"
  24 +edispcube, f, a, NONE,,, "Input energy dispersion cube file"
  25 +bkgcube, f, a, NONE,,, "Input background cube file"
26 26 caldb, s, a, prod2,,, "Calibration database"
27 27 irf, s, a, South_0.5h,,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
... ...
doc/source/users/reference_manual/csresmap.rst
  View file @ff3e361
... ... @@ -36,13 +36,16 @@ General parameters
36 36 Input model cube file (generated with ctmodel).
37 37  
38 38 ``expcube [file]``
39   - Input exposure cube file (only needed for stacked analysis).
  39 + Input exposure cube file.
40 40  
41 41 ``psfcube [file]``
42   - Input PSF cube file (only needed for stacked analysis).
  42 + Input PSF cube file.
  43 +
  44 +``edispcube [file]``
  45 + Input energy dispersion cube file.
43 46  
44 47 ``bkgcube [file]``
45   - Input background cube file (only needed for stacked analysis).
  48 + Input background cube file.
46 49  
47 50 ``inmodel [file]``
48 51 Input model XML file.
... ... @@ -61,48 +64,48 @@ General parameters
61 64  
62 65 ``(ebinalg = LOG) <FILE|LIN|LOG> [string]``
63 66 Algorithm for defining energy bins.
64   -
  67 +
65 68 ``emin [real]``
66 69 Lower energy value for first energy bin (in TeV).
67   -
  70 +
68 71 ``emax [real]``
69 72 Upper energy value for last energy bin (in TeV).
70   -
  73 +
71 74 ``(enumbins = 20) [integer]``
72 75 Number of model cube energy bins.
73   -
  76 +
74 77 ``ebinfile [file]``
75 78 Name of the file containing the energy bin definition.
76   -
  79 +
77 80 ``coordsys <CEL|GAL> [string]``
78 81 Coordinate system (CEL - celestial, GAL - galactic).
79   -
  82 +
80 83 ``proj <AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN> [string]``
81 84 Projection method.
82 85  
83 86 ``xref [real]``
84 87 Right Ascension / Galactic longitude of cube centre (J2000, in degrees).
85   -
  88 +
86 89 ``yref [real]``
87 90 Declination / Galactic latitude of cube centre (J2000, in degrees).
88   -
  91 +
89 92 ``nxpix [integer]``
90 93 Number of cube bins in Right Ascension or Galactic longitude.
91   -
  94 +
92 95 ``nypix [integer]``
93 96 Number of cube bins in Declination or Galactic latitude.
94   -
  97 +
95 98 ``binsz [real]``
96 99 Cube bin size (in degrees/pixel).
97   -
98   -``(algorithm = SUBDIV) <SUB|SUBDIV|SUBDIVSQRT|SIGNIF> [string]``
  100 +
  101 +``algorithm <SUB|SUBDIV|SUBDIVSQRT|SIGNIFICANCE> [string]``
99 102 Algorithm used to generate the residual map:
100 103  
101 104 ``SUB``: :math:`DATA - MODEL`
102 105  
103   - ``SUBDIV``: :math:`\frac{DATA - MODEL}{MODEL}`
  106 + ``SUBDIV``: :math:`(DATA - MODEL) / MODEL`
104 107  
105   - ``SUBDIVSQRT``: :math:`\frac{DATA - MODEL}{\sqrt{MODEL}}`
  108 + ``SUBDIVSQRT``: :math:`(DATA - MODEL) / \sqrt{MODEL}`
106 109  
107 110 ``SIGNIFICANCE``: :math:`{\rm sign}(DATA-MODEL) \times \sqrt{ 2 \times ( DATA \times \ln \left(\frac{DATA}{MODEL} \right) + MODEL - DATA ) }`
108 111  
... ... @@ -116,21 +119,21 @@ Standard parameters
116 119 ``(chatter = 2) [integer]``
117 120 Verbosity of the executable:
118 121 ``chatter = 0``: no information will be logged
119   -
  122 +
120 123 ``chatter = 1``: only errors will be logged
121   -
  124 +
122 125 ``chatter = 2``: errors and actions will be logged
123   -
  126 +
124 127 ``chatter = 3``: report about the task execution
125   -
  128 +
126 129 ``chatter = 4``: detailed report about the task execution
127   -
  130 +
128 131 ``(clobber = yes) [boolean]``
129 132 Specifies whether an existing residual map file should be overwritten.
130   -
  133 +
131 134 ``(debug = no) [boolean]``
132 135 Enables debug mode. In debug mode the executable will dump any log file output to the console.
133   -
  136 +
134 137 ``(mode = ql) [string]``
135 138 Mode of automatic parameters (default is "ql", i.e. "query and learn").
136 139  
... ...
doc/source/users/reference_manual/csspec.rst
  View file @ff3e361
... ... @@ -54,21 +54,17 @@ General parameters
54 54 ``inmodel [file]``
55 55 Input model XML file.
56 56  
57   -``srcname [string]``
58   - Name of the source in the source model XML file which should be used
59   - for sensitivity computation.
60   -
61   -``outfile [file]``
62   - Name of the source spectrum output file.
63   -
64 57 ``expcube [file]``
65   - Exposure cube file (only needed for stacked analysis).
  58 + Input exposure cube file.
66 59  
67 60 ``psfcube [file]``
68   - PSF cube file (only needed for stacked analysis).
  61 + Input PSF cube file.
  62 +
  63 +``edispcube [file]``
  64 + Input energy dispersion cube file.
69 65  
70 66 ``bkgcube [file]``
71   - Background cube file (only needed for stacked analysis).
  67 + Input background cube file.
72 68  
73 69 ``caldb [string]``
74 70 Calibration database.
... ... @@ -79,6 +75,13 @@ General parameters
79 75 ``(edisp = no) [boolean]``
80 76 Apply energy dispersion to response computation?
81 77  
  78 +``srcname [string]``
  79 + Name of the source in the source model XML file which should be used
  80 + for sensitivity computation.
  81 +
  82 +``outfile [file]``
  83 + Output source spectrum file.
  84 +
82 85 ``emin [real]``
83 86 Lower energy limit of events (in TeV).
84 87  
... ...
doc/source/users/reference_manual/cstsdist.rst
  View file @ff3e361
... ... @@ -43,16 +43,19 @@ General parameters
43 43 for Test Statistics computation.
44 44  
45 45 ``outfile [file]``
46   - ASCII file containing the TS distribution values.
  46 + Output ASCII file containing the TS distribution values.
47 47  
48 48 ``expcube [file]``
49   - Exposure cube file (only needed for stacked analysis).
  49 + Input exposure cube file.
50 50  
51 51 ``psfcube [file]``
52   - PSF cube file (only needed for stacked analysis).
  52 + Input PSF cube file.
  53 +
  54 +``edispcube [file]``
  55 + Input energy dispersion cube file.
53 56  
54 57 ``bkgcube [file]``
55   - Background cube file (only needed for stacked analysis).
  58 + Input background cube file.
56 59  
57 60 ``caldb [string]``
58 61 Calibration database.
... ...
doc/source/users/reference_manual/cstsmapsplit.rst
  View file @ff3e361
... ... @@ -30,13 +30,16 @@ General parameters
30 30 Name of source model for which the TS map should be computed.
31 31  
32 32 ``expcube [file]``
33   - Input exposure cube file (only needed for stacked analysis).
  33 + Input exposure cube file.
34 34  
35 35 ``psfcube [file]``
36   - Input PSF cube file (only needed for stacked analysis).
  36 + Input PSF cube file.
  37 +
  38 +``edispcube [file]``
  39 + Input energy dispersion cube file.
37 40  
38 41 ``bkgcube [file]``
39   - Input background cube file (only needed for stacked analysis).
  42 + Input background cube file.
40 43  
41 44 ``caldb [string]``
42 45 Calibration database.
... ...
doc/source/users/reference_manual/ctbutterfly.rst
  View file @ff3e361
... ... @@ -53,13 +53,16 @@ General parameters
53 53 Name of source model for which the butterfly diagram should be computed.
54 54  
55 55 ``expcube [file]``
56   - Input exposure cube file (only needed for stacked analysis).
  56 + Input exposure cube file.
57 57  
58 58 ``psfcube [file]``
59   - Input PSF cube file (only needed for stacked analysis).
  59 + Input PSF cube file.
  60 +
  61 +``edispcube [file]``
  62 + Input energy dispersion cube file.
60 63  
61 64 ``bkgcube [file]``
62   - Input background cube file (only needed for stacked analysis).
  65 + Input background cube file.
63 66  
64 67 ``caldb [string]``
65 68 Calibration database.
... ... @@ -79,7 +82,7 @@ General parameters
79 82  
80 83 ``(method = "GAUSSIAN") <GAUSSIAN|ENVELOPE> [string]``
81 84 Computation method.
82   -
  85 +
83 86 ``(confidence = 0.68) [real]``
84 87 Confidence level for error computation.
85 88  
... ... @@ -88,16 +91,16 @@ General parameters
88 91  
89 92 ``(ebinalg = "LOG") <FILE|LIN|LOG> [string]``
90 93 Butterfly energy binning algorithm.
91   -
  94 +
92 95 ``emin [real]``
93 96 Minimum energy of butterfly (in TeV).
94   -
  97 +
95 98 ``emax [real]``
96 99 Maximum energy of butterfly (in TeV).
97   -
  100 +
98 101 ``(enumbins = 100) [string]``
99 102 Number of energy bins of butterfly.
100   -
  103 +
101 104 ``(ebinfile = "NONE") [string]``
102 105 File for energy binning algorithm.
103 106  
... ...
doc/source/users/reference_manual/cterror.rst
  View file @ff3e361
... ... @@ -38,13 +38,16 @@ General parameters
38 38 Name of source model for which the parameter errors should be computed.
39 39  
40 40 ``expcube [file]``
41   - Input exposure cube file (only needed for stacked analysis).
  41 + Input exposure cube file.
42 42  
43 43 ``psfcube [file]``
44   - Input PSF cube file (only needed for stacked analysis).
  44 + Input PSF cube file.
  45 +
  46 +``edispcube [file]``
  47 + Input energy dispersion cube file.
45 48  
46 49 ``bkgcube [file]``
47   - Input background cube file (only needed for stacked analysis).
  50 + Input background cube file.
48 51  
49 52 ``caldb [string]``
50 53 Calibration database.
... ...
doc/source/users/reference_manual/ctmodel.rst
  View file @ff3e361
... ... @@ -57,13 +57,16 @@ General parameters
57 57 Input counts cube file to extract model cube definition.
58 58  
59 59 ``expcube [file]``
60   - Input exposure cube file (only needed for stacked analysis).
  60 + Input exposure cube file.
61 61  
62 62 ``psfcube [file]``
63   - Input PSF cube file (only needed for stacked analysis).
  63 + Input PSF cube file.
  64 +
  65 +``edispcube [file]``
  66 + Input energy dispersion cube file.
64 67  
65 68 ``bkgcube [file]``
66   - Input background cube file (only needed for stacked analysis).
  69 + Input background cube file.
67 70  
68 71 ``caldb [string]``
69 72 Calibration database.
... ...
doc/source/users/reference_manual/cttsmap.rst
  View file @ff3e361
... ... @@ -40,13 +40,16 @@ General parameters
40 40 Name of source model for which the TS map should be computed.
41 41  
42 42 ``expcube [file]``
43   - Input exposure cube file (only needed for stacked analysis).
  43 + Input exposure cube file.
44 44  
45 45 ``psfcube [file]``
46   - Input PSF cube file (only needed for stacked analysis).
  46 + Input PSF cube file.
  47 +
  48 +``edispcube [file]``
  49 + Input energy dispersion cube file.
47 50  
48 51 ``bkgcube [file]``
49   - Input background cube file (only needed for stacked analysis).
  52 + Input background cube file.
50 53  
51 54 ``caldb [string]``
52 55 Calibration database.
... ...
doc/source/users/reference_manual/ctulimit.rst
  View file @ff3e361
... ... @@ -36,13 +36,16 @@ General parameters
36 36 Name of source model for which the upper flux limit should be computed.
37 37  
38 38 ``expcube [file]``
39   - Input exposure cube file (only needed for stacked analysis).
  39 + Input exposure cube file.
40 40  
41 41 ``psfcube [file]``
42   - Input PSF cube file (only needed for stacked analysis).
  42 + Input PSF cube file.
  43 +
  44 +``edispcube [file]``
  45 + Input energy dispersion cube file.
43 46  
44 47 ``bkgcube [file]``
45   - Input background cube file (only needed for stacked analysis).
  48 + Input background cube file.
46 49  
47 50 ``caldb [string]``
48 51 Calibration database.
... ...
doc/source/users/tutorials/quickstart/binning.rst
  View file @ff3e361
1   -.. _sec_binning_cta:
  1 +.. _start_binning:
2 2  
3   -Binning CTA data
4   -----------------
  3 +Binning event data
  4 +------------------
5 5  
6 6 .. admonition:: What you will learn
7 7  
8 8 You will learn how to use the :ref:`ctbin` tool to **bin the selected
9   - CTA event data into a counts cube**.
  9 + event data into a counts cube**.
10 10  
11 11 A counts cube is a 3-dimensional data cube that is spanned by Right
12 12 Ascension (or Galactic longitude), Declination (or Galactic latitude),
... ...
doc/source/users/tutorials/quickstart/butterfly.jpg 0 → 100644
View file @ff3e361

120 KB
doc/source/users/tutorials/quickstart/butterfly.rst 0 → 100644
  View file @ff3e361
  1 +.. _start_butterfly:
  2 +
  3 +Generating a butterfly diagram of the source spectrum
  4 +-----------------------------------------------------
  5 +
  6 + .. admonition:: What you will learn
  7 +
  8 + You will learn how to use the :ref:`ctbutterfly` tool to **generate a
  9 + butterfly diagram for the source spectrum**.
  10 +
  11 +The :ref:`ctlike` tool returns the statistic uncertainties for all fitted
  12 +parameters of the spectral model, but you may be interested in the manifold
  13 +of spectral models that are statistically compatible with the data. For this
  14 +purpose you should generate a butterfly diagram. You do this using the
  15 +:ref:`ctbutterfly` tool as follows:
  16 +
  17 +.. code-block:: bash
  18 +
  19 + $ ctbutterfly
  20 + Input event list, counts cube or observation definition XML file [events.fits] cntcube.fits
  21 + Input exposure cube file [NONE] expcube.fits
  22 + Input PSF cube file [NONE] psfcube.fits
  23 + Input background cube file [NONE] bkgcube.fits
  24 + Source of interest [Crab]
  25 + Input model definition XML file [$CTOOLS/share/models/crab.xml] crab_results.xml
  26 + Lower energy limit (TeV) [0.1]
  27 + Upper energy limit (TeV) [100.0]
  28 + Output ASCII file [butterfly.txt]
  29 +
  30 +The :ref:`ctbutterfly` tool creates an ASCII file ``butterfly.txt`` that
  31 +contains for each energy in MeV (column 1) the best fitted intensity
  32 +(column 2), the minimum intensity (column 3) and the maximum intensity
  33 +(column 4) that is compatible with the data, all in units of
  34 +:math:`{\rm photons} \, {\rm cm}^{-2} \, {\rm s}^{-1} \, {\rm MeV}^{-1}`.
  35 +The number of energies is given by the hidden ``enumbins`` parameter which by
  36 +default is set to 100. Below an excerpt of the first lines of the
  37 +``butterfly.txt`` file:
  38 +
  39 +.. code-block:: none
  40 +
  41 + 103514.216667934 7.65729960995773e-15 7.45677281959723e-15 7.85782640031824e-15
  42 + 110917.48152624 6.46256412586182e-15 6.2982352355303e-15 6.62689301619334e-15
  43 + 118850.222743702 5.45423807455102e-15 5.3195999976704e-15 5.58887615143164e-15
  44 + 127350.308101666 4.6032367949486e-15 4.49293900723421e-15 4.71353458266298e-15
  45 + 136458.313658893 3.88501358040058e-15 3.7946590323386e-15 3.97536812846257e-15
  46 + ...
  47 +
  48 +A graphical display of the results is shown below:
  49 +
  50 +.. figure:: butterfly.jpg
  51 + :width: 600px
  52 + :align: center
  53 +
  54 + *Butterfly diagram of the Crab nebula*
  55 +
  56 +..
  57 +
  58 + .. note::
  59 +
  60 + The ctools package does not contain any tools or scripts for graphical
  61 + display of results since results are generally written into standard FITS
  62 + files that are readily displayed by existing astronomical tools.
  63 +
  64 + Nevertheless, for your convenience several scripts for graphical display
  65 + are included in the ctools package that rely on the
  66 + `matplotlib <http://matplotlib.org>`_
  67 + Python module. You can find these scripts in the
  68 + ``$CTOOLS/share/examples/python`` folder.
  69 +
  70 + Read the section :ref:`1dc_howto_display` to learn more about the
  71 + available scripts. The plot above was generated using:
  72 +
  73 + .. code-block:: bash
  74 +
  75 + $ $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt
... ...
doc/source/users/tutorials/quickstart/energy_dispersion.rst
  View file @ff3e361
1   -.. _sec_edisp_cta:
  1 +.. _start_edisp:
2 2  
3 3 Taking the energy dispersion into account
4 4 -----------------------------------------
... ... @@ -15,7 +15,7 @@ Taking the energy dispersion into account
15 15 .. warning::
16 16 Energy dispersion is fully implemented in ctools but is computationally
17 17 intensive. So be aware that the **tools and scripts will take a substantial
18   - amount of computing time**.
  18 + amount of computing time if energy dispersion is considered**.
19 19  
20 20 You may not have recognised, but the examples you have exercised so far
21 21 have neglected the impact of the energy dispersion on the analysis. In reality,
... ... @@ -39,7 +39,7 @@ To simulate events taking the energy dispersion into account you run the
39 39 Calibration database [prod2]
40 40 Instrument response function [South_0.5h]
41 41 Input model definition XML file [$CTOOLS/share/models/crab.xml]
42   - Output event data file or observation definition XML file [events.fits]
  42 + Output event data file or observation definition XML file [events.fits] events_edisp.fits
43 43  
44 44 You then select events from the simulated data as before using the
45 45 :ref:`ctselect` tool:
... ... @@ -47,7 +47,7 @@ You then select events from the simulated data as before using the
47 47 .. code-block:: bash
48 48  
49 49 $ ctselect
50   - Input event list or observation definition XML file [events.fits]
  50 + Input event list or observation definition XML file [events.fits] events_edisp.fits
51 51 RA for ROI centre (degrees) (0-360) [83.63]
52 52 Dec for ROI centre (degrees) (-90-90) [22.01]
53 53 Radius of ROI (degrees) (0-180) [3.0]
... ... @@ -55,7 +55,7 @@ You then select events from the simulated data as before using the
55 55 Stop time (UTC string, JD, MJD or MET in seconds) [NONE] 2020-01-01T00:40:00
56 56 Lower energy limit (TeV) [0.1]
57 57 Upper energy limit (TeV) [100.0]
58   - Output event list or observation definition XML file [selected_events.fits]
  58 + Output event list or observation definition XML file [selected_events.fits] selected_events_edisp.fits
59 59  
60 60 Then you bin as before the selected events into a counts cube using the
61 61 :ref:`ctbin` tool:
... ... @@ -63,7 +63,7 @@ Then you bin as before the selected events into a counts cube using the
63 63 .. code-block:: bash
64 64  
65 65 $ ctbin
66   - Input event list or observation definition XML file [events.fits] selected_events.fits
  66 + Input event list or observation definition XML file [selected_events.fits] selected_events_edisp.fits
67 67 First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
68 68 Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
69 69 Projection method (AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN) [CAR]
... ... @@ -75,7 +75,7 @@ Then you bin as before the selected events into a counts cube using the
75 75 Start value for first energy bin in TeV [0.1]
76 76 Stop value for last energy bin in TeV [100.0]
77 77 Number of energy bins (1-200) [20]
78   - Output counts cube file [cntcube.fits]
  78 + Output counts cube file [cntcube.fits] cntcube_edisp.fits
79 79  
80 80 As next step you need to compute the
81 81 :ref:`energy dispersion cube <glossary_edispcube>`
... ... @@ -84,7 +84,7 @@ using the :ref:`ctexpcube` tool. You run the tool as follows:
84 84 .. code-block:: bash
85 85  
86 86 $ ctedispcube
87   - Input event list or observation definition XML file [NONE] selected_events.fits
  87 + Input event list or observation definition XML file [NONE] selected_events_edisp.fits
88 88 Calibration database [prod2]
89 89 Instrument response function [South_0.5h]
90 90 Input counts cube file to extract energy dispersion cube definition [NONE]
... ... @@ -108,13 +108,13 @@ energy dispersion cube:
108 108 .. code-block:: bash
109 109  
110 110 $ ctlike edisp=yes
111   - Input event list, counts cube or observation definition XML file [selected_events.fits] cntcube.fits
  111 + Input event list, counts cube or observation definition XML file [selected_events.fits] cntcube_edisp.fits
112 112 Input exposure cube file [expcube.fits]
113 113 Input PSF cube file [psfcube.fits]
114 114 Input energy dispersion cube file [NONE] edispcube.fits
115 115 Input background cube file [bkgcube.fits]
116 116 Input model definition XML file [$CTOOLS/share/models/crab.xml] models.xml
117   - Output model definition XML file [crab_results.xml]
  117 + Output model definition XML file [crab_results.xml] crab_results_edisp.xml
118 118  
119 119 You can also perform an unbinned maximum likelihood analysis taking the energy
120 120 dispersion into account. In that case the energy dispersion information will be
... ... @@ -125,8 +125,8 @@ and no energy dispersion cube is required:
125 125 .. code-block:: bash
126 126  
127 127 $ ctlike edisp=yes
128   - Input event list, counts cube or observation definition XML file [cntcube.fits] selected_events.fits
  128 + Input event list, counts cube or observation definition XML file [cntcube_edisp.fits] selected_events_edisp.fits
129 129 Calibration database [prod2]
130 130 Instrument response function [South_0.5h]
131 131 Input model definition XML file [models.xml] $CTOOLS/share/models/crab.xml
132   - Output model definition XML file [crab_results.xml]
  132 + Output model definition XML file [crab_results_edisp.xml]
... ...
doc/source/users/tutorials/quickstart/fitting.rst
  View file @ff3e361
1   -.. _sec_fitting_cta:
  1 +.. _start_fitting:
2 2  
3   -Fitting CTA data
4   -----------------
  3 +Fitting binned data
  4 +-------------------
5 5  
6 6 .. admonition:: What you will learn
7 7  
... ... @@ -28,8 +28,8 @@ have been binned into a counts cube and the fit computes the log-likelihood
28 28 function by summing over all 200 x 200 x 20 bins of the counts cube. There is
29 29 an alternative method, the so called *unbinned* mode, where the events are
30 30 not binned into a counts cube and the log-likelihood is computed directly by
31   -summing over all events. We will explore the *unbinned* mode later (see
32   -:ref:`here <sec_unbinned_cta>`).
  31 +summing over all events.
  32 +:ref:`We will explore the unbinned mode later <start_unbinned>`.
33 33  
34 34 The :ref:`ctlike` tool produced a
35 35 :ref:`model definition XML output file <glossary_moddef>`
... ...
doc/source/users/tutorials/quickstart/index.rst
  View file @ff3e361
1   -.. _quickstart:
  1 +.. _start:
2 2  
3 3 First steps with ctools
4 4 -----------------------
5 5  
6   -This section provides a step-by-step description of a simple CTA data simulation
7   -and analysis example using the ctools.
  6 +This section provides a hands-on introduction of ctools. By means of an
  7 +example you will learn how to simulate and analyse CTA event data. This
  8 +section is intended to be read by newcomers. The reading and executing of the
  9 +examples should take about an hour, so grab some coffee before you start.
8 10  
9 11 .. toctree::
10 12 :maxdepth: 1
... ... @@ -15,5 +17,9 @@ and analysis example using the ctools.
15 17 binning
16 18 response
17 19 fitting
  20 + residuals
  21 + butterfly
  22 + spectrum
18 23 unbinned
19 24 energy_dispersion
  25 + python
... ...
doc/source/users/tutorials/quickstart/python.rst 0 → 100644
  View file @ff3e361
  1 +.. _start_python:
  2 +
  3 +Using ctools from Python
  4 +------------------------
  5 +
  6 + .. admonition:: What you will learn
  7 +
  8 + You will learn how to **use the ctools and cscripts from Python** instead
  9 + of typing the commands in the console.
  10 +
  11 +ctools provides two Python modules that allow using all tools and scripts as
  12 +Python classes. To use ctools from Python you have to import the ``ctools``
  13 +and ``cscripts`` modules into Python. You should also import the ``gammalib``
  14 +module, as ctools without GammaLib is generally not very useful.
  15 +
  16 + .. warning::
  17 +
  18 + Always import ``gammalib`` before you import ``ctools`` and ``cscripts``.
  19 +
  20 +To simulate the event data from Python you have to type the following (recall
  21 +:ref:`how to simulate event data from the command line <start_simulating>` for
  22 +comparison) :
  23 +
  24 +.. code-block:: python
  25 +
  26 + >>> import gammalib
  27 + >>> import ctools
  28 + >>> import cscripts
  29 + >>> sim = ctools.ctobssim()
  30 + >>> sim['inmodel'] = '${CTOOLS}/share/models/crab.xml'
  31 + >>> sim['outevents'] = 'events.fits'
  32 + >>> sim['caldb'] = 'prod2'
  33 + >>> sim['irf'] = 'South_0.5h'
  34 + >>> sim['ra'] = 83.63
  35 + >>> sim['dec'] = 22.01
  36 + >>> sim['rad'] = 5.0
  37 + >>> sim['tmin'] = '2020-01-01T00:00:00'
  38 + >>> sim['tmax'] = '2020-01-01T01:00:00'
  39 + >>> sim['emin'] = 0.03
  40 + >>> sim['emax'] = 200.0
  41 + >>> sim.execute()
  42 +
  43 +The first line after the ``import`` statements generates an instance of the
  44 +:ref:`ctobssim` tool as a Python class. User parameters are then set using the
  45 +``[ ]`` operator. After setting all parameters the ``execute()`` method is called to
  46 +execute the :ref:`ctobssim` tool. On output the ``events.fits`` FITS file is
  47 +created. Until now everything is identical to running the tool from the command
  48 +line.
  49 +
  50 + .. note::
  51 +
  52 + See the :ref:`reference` for a list of parameters and their types for
  53 + all tools and scripts. You can also inspect all parameters of a specific
  54 + tool by calling the tool follwed by ``--help`` from the command line, e.g.
  55 +
  56 + .. code-block:: bash
  57 +
  58 + $ ctobssim --help
  59 +
  60 +Instead of executing the tool you may also *run* the tool using
  61 +
  62 +.. code-block:: python
  63 +
  64 + >>> sim.run()
  65 +
  66 +The main difference to the ``execute()`` method is that the ``run()`` method
  67 +will not write the simulated event file to disk. Why is this useful? Well,
  68 +after having typed ``sim.run()`` the :ref:`ctobssim` class still exists as an
  69 +object in memory, including all the simulated events. The :ref:`ctobssim`
  70 +class has an ``obs()`` method that returns an observation container that holds
  71 +the simulated CTA observation with its associated events. To visualise this
  72 +container, type:
  73 +
  74 +.. code-block:: python
  75 +
  76 + >>> print(sim.obs())
  77 + === GObservations ===
  78 + Number of observations ....: 1
  79 + Number of models ..........: 2
  80 + Number of observed events .: 202766
  81 + Number of predicted events : 0
  82 +
  83 +There is one CTA observation in the container and to visualise that observation
  84 +type:
  85 +
  86 +.. code-block:: python
  87 +
  88 + >>> print(sim.obs()[0])
  89 + === GCTAObservation ===
  90 + Name ......................:
  91 + Identifier ................:
  92 + Instrument ................: CTA
  93 + Event file ................: events.fits
  94 + Event type ................: EventList
  95 + Statistics ................: Poisson
  96 + Ontime ....................: 3599.99999976158 s
  97 + Livetime ..................: 3527.99999976635 s
  98 + Deadtime correction .......: 0.98
  99 + User energy range .........: undefined
  100 + === GCTAPointing ===
  101 + Pointing direction ........: (RA,Dec)=(83.63,22.01)
  102 + === GCTAResponseIrf ===
  103 + Caldb mission .............: cta
  104 + Caldb instrument ..........: prod2
  105 + Response name .............: South_0.5h
  106 + Energy dispersion .........: Not used
  107 + Save energy range .........: undefined
  108 + === GCTAEventList ===
  109 + Number of events ..........: 202766 (disposed in "events.fits")
  110 + Time interval .............: 58849.0008007407 - 58849.0424674074 days
  111 + Energy interval ...........: 0.03 - 200 TeV
  112 + Region of interest ........: RA=83.63, DEC=22.01 [0,0] Radius=5 deg
  113 +
  114 +The observation contains a CTA event list that is implement by the GammaLib
  115 +class ``GCTAEventList``. You can access the event list using the ``events()``
  116 +method. To visualise the individual events you can iterate over the events
  117 +using a for loop. This will show the simulated celestial coordinates (RA, DEC),
  118 +the coordinate in the camera system [DETX, DETY], the energies and the
  119 +terrestrial times (TT) of all events. To do this, type:
  120 +
  121 +.. code-block:: python
  122 +
  123 + >>> events = sim.obs()[0].events()
  124 + >>> for event in events:
  125 + ... print(event)
  126 + ...
  127 + Dir=RA=83.6182556152344, DEC=22.2843074798584 [0.00478756989312195,-0.000189682185722814] Energy=63.157357275486 GeV Time=315532804.699509 s (TT)
  128 + Dir=RA=83.8212127685547, DEC=21.9629154205322 [-0.000819836781619686,0.0030950360932479] Energy=53.25997620821 GeV Time=315532805.889628 s (TT)
  129 + Dir=RA=83.6474838256836, DEC=22.0208301544189 [0.000189049359871014,0.000282857291220907] Energy=69.6808248758316 GeV Time=315532806.050809 s (TT)
  130 + ...
  131 +
  132 +You can now benefit from the fact that you have some simulated events in
  133 +memory to fit a model to these events using the :ref:`ctlike` class.
  134 +You will do this in unbinned mode. Here is what you have to type:
  135 +
  136 +.. code-block:: python
  137 +
  138 + >>> like = ctools.ctlike(sim.obs())
  139 + >>> like.run()
  140 +
  141 +This is pretty compact. Where are the user parameters?
  142 +:ref:`ctlike` doesn't in fact need any parameters as all the relevant
  143 +information is already contained in the observation container produced by the
  144 +:ref:`ctobssim` class.
  145 +And you may have recognised that you constructed the :ref:`ctlike`
  146 +instance by using the :ref:`ctobssim` observation container as constructor
  147 +argument.
  148 +
  149 + .. note::
  150 +
  151 + An observation container, implemented by the ``GObservations`` class
  152 + of GammaLib, is the fundamental brick of any ctools analysis. Many tools
  153 + and scripts handle observation containers, and accept them upon
  154 + construction and return them after running the tool via the ``obs()``
  155 + method.
  156 +
  157 + Passing observation containers between ctools classes is a very
  158 + convenient and powerful way of building in-memory analysis pipelines.
  159 + However, this implies that you need some computing ressources when
  160 + dealing with large observation containers (for example if you want to
  161 + analyse a few 100 hours of data at once). Also, if the script crashes
  162 + the information is lost.
  163 +
  164 +To check how the fit went you can inspect the optimiser used by
  165 +:ref:`ctlike` by typing:
  166 +
  167 +.. code-block:: python
  168 +
  169 + >>> print(like.opt())
  170 + === GOptimizerLM ===
  171 + Optimized function value ..: 757618.425
  172 + Absolute precision ........: 0.005
  173 + Acceptable value decrease .: 2
  174 + Optimization status .......: converged
  175 + Number of parameters ......: 10
  176 + Number of free parameters .: 4
  177 + Number of iterations ......: 2
  178 + Lambda ....................: 1e-05
  179 +
  180 +You see that the fit converged after 2 iterations. Out of 10 parameters in the
  181 +model 4 have been fitted (the others were kept fixed). To inspect the fit
  182 +results you can print the model container that can be access using the
  183 +``models()`` method of the observation container:
  184 +
  185 +.. code-block:: python
  186 +
  187 + >>> print(like.obs().models())
  188 + === GModels ===
  189 + Number of models ..........: 2
  190 + Number of parameters ......: 10
  191 + === GModelSky ===
  192 + Name ......................: Crab
  193 + Instruments ...............: all
  194 + Instrument scale factors ..: unity
  195 + Observation identifiers ...: all
  196 + Model type ................: PointSource
  197 + Model components ..........: "PointSource" * "PowerLaw" * "Constant"
  198 + Number of parameters ......: 6
  199 + Number of spatial par's ...: 2
  200 + RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  201 + DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  202 + Number of spectral par's ..: 3
  203 + Prefactor ................: 5.73901839854211e-16 +/- 5.75150678022232e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  204 + Index ....................: -2.46442704108736 +/- 0.00738985717701118 [-0,-5] (free,scale=-1,gradient)
  205 + PivotEnergy ..............: 300000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)
  206 + Number of temporal par's ..: 1
  207 + Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  208 + === GCTAModelIrfBackground ===
  209 + Name ......................: CTABackgroundModel
  210 + Instruments ...............: CTA
  211 + Instrument scale factors ..: unity
  212 + Observation identifiers ...: all
  213 + Model type ................: "PowerLaw" * "Constant"
  214 + Number of parameters ......: 4
  215 + Number of spectral par's ..: 3
  216 + Prefactor ................: 0.995734795709415 +/- 0.00725726198557001 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  217 + Index ....................: -0.00198344390952578 +/- 0.00257263793207067 [-5,5] (free,scale=1,gradient)
  218 + PivotEnergy ..............: 1000000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)
  219 + Number of temporal par's ..: 1
  220 + Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  221 +
  222 +Suppose you want to repeat the fit by optimising also the position of the
  223 +point source. This is easy from Python. Type the following:
  224 +
  225 +.. code-block:: python
  226 +
  227 + >>> like.obs().models()['Crab']['RA'].free()
  228 + >>> like.obs().models()['Crab']['DEC'].free()
  229 + >>> like.run()
  230 + >>> print(like.obs().models())
  231 + ...
  232 + RA .......................: 83.6334964430607 +/- 0.000614768905318078 [-360,360] deg (free,scale=1)
  233 + DEC ......................: 22.0149467750683 +/- 0.000559548446961086 [-90,90] deg (free,scale=1)
  234 +
  235 +
  236 +The ``like.obs().models()`` method provides the model container, using the
  237 +``['Crab']`` operator you access the Crab model in that container and using
  238 +the ``['RA']`` and ``['DEC']`` operators you access the relevant model
  239 +parameters. The ``free()`` method frees a parameter, the opposite would be a
  240 +call to the ``fix()`` method.
... ...
doc/source/users/tutorials/quickstart/residuals.jpg 0 → 100644
View file @ff3e361

366 KB
doc/source/users/tutorials/quickstart/residuals.rst 0 → 100644
  View file @ff3e361
  1 +.. _start_residuals:
  2 +
  3 +Inspecting the fit residuals
  4 +----------------------------
  5 +
  6 + .. admonition:: What you will learn
  7 +
  8 + You will learn how to use the :ref:`csresmap` script to **inspect the
  9 + fit residuals**.
  10 +
  11 +After having done a maximum likelihood fit it is good practice to inspect the
  12 +fit residuals. You do this with the :ref:`csresmap` script that creates a
  13 +residual sky map of the events from which the fitted model components were
  14 +subtracted. You run the :ref:`csresmap` script as follows:
  15 +
  16 +.. code-block:: bash
  17 +
  18 + $ csresmap
  19 + Input event list, counts cube, or observation definition XML file [events.fits] cntcube.fits
  20 + Input model cube file (generated with ctmodel) [NONE]
  21 + Input exposure cube file [NONE] expcube.fits
  22 + Input PSF cube file [NONE] psfcube.fits
  23 + Input background cube file [NONE] bkgcube.fits
  24 + Input model definition XML file [$CTOOLS/share/models/crab.xml] crab_results.xml
  25 + Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT|SIGNIFICANCE) [SIGNIFICANCE]
  26 + Output residual map file [resmap.fits]
  27 +
  28 +..
  29 +
  30 + .. note::
  31 +
  32 + :ref:`csresmap` is a Python script while the other tools that you have
  33 + used so far are C++ binary executables. From the User perspective, Python
  34 + scripts and C++ binary executables behave the same way, but to distinguish
  35 + both all Python scripts names start with ``cs`` while all C++ binary
  36 + executables names start with ``ct``.
  37 +
  38 +The :ref:`csresmap` script produces the FITS file ``resmap.fits`` that contains
  39 +the residual counts map. The image is displayed below using
  40 +`ds9 <http://ds9.si.edu>`_ with a linear color scale and with a small Gaussian
  41 +kernel smoothing applied. Obviously, there are no significant residuals, which
  42 +indicates that the model fit was satisfactory.
  43 +
  44 +.. figure:: residuals.jpg
  45 + :width: 400px
  46 + :align: center
  47 +
  48 + *Residual sky map of the selected events with all model components subtracted*
  49 +
  50 +..
  51 +
  52 + .. note::
  53 +
  54 + :ref:`csresmap` implements different algorithms for the computation of the
  55 + residuals. These are:
  56 +
  57 + * ``SUB``: :math:`DATA - MODEL`
  58 + * ``SUBDIV``: :math:`(DATA - MODEL) / MODEL`
  59 + * ``SUBDIVSQRT``: :math:`(DATA - MODEL) / \sqrt{MODEL}`
  60 + * ``SIGNIFICANCE``: :math:`{\rm sign}(DATA-MODEL) \times \sqrt{ 2 \times ( DATA \times \ln \left(\frac{DATA}{MODEL} \right) + MODEL - DATA ) }`
  61 +
  62 + By default the ``SIGNIFICANCE`` algorithm is used.
... ...
doc/source/users/tutorials/quickstart/response.rst
  View file @ff3e361
1   -.. _sec_stacked_reponse:
  1 +.. _start_binned_reponse:
2 2  
3   -Pre-computing the response
4   ---------------------------
  3 +Pre-computing the binned response
  4 +---------------------------------
5 5  
6 6 .. admonition:: What you will learn
7 7  
... ...
doc/source/users/tutorials/quickstart/selecting.rst
  View file @ff3e361
1   -.. _sec_selecting_cta:
  1 +.. _start_selecting:
2 2  
3   -Selecting CTA data
4   -------------------
  3 +Selecting event data
  4 +--------------------
5 5  
6 6 .. admonition:: What you will learn
7 7  
8 8 You will learn how to use the :ref:`ctselect` tool to **select relevant
9   - events from the simulated CTA event data**.
  9 + events from the simulated event data**.
10 10  
11   -As next step you may want to select some events from the simulated CTA data.
  11 +As next step you may want to select some events from the simulated event data.
12 12 You may want to restrict the events to a region of interest (ROI) of 3 degrees
13 13 around the Crab nebula, you may want to extract a 30 minutes time slice
14 14 from the data, and you may want to limit the energy range of the events
... ... @@ -28,7 +28,7 @@ You do this event selection using the :ref:`ctselect` tool as follows:
28 28 Upper energy limit (TeV) [100.0]
29 29 Output event list or observation definition XML file [selected_events.fits]
30 30  
31   -This created a new CTA event list FITS file ``selected_events.fits``
  31 +This created a new event list FITS file ``selected_events.fits``
32 32 that contains the selected data.
33 33 Below an excerpt of the ``ctselect.log`` log file that illustrates the
34 34 event selection:
... ...
doc/source/users/tutorials/quickstart/simulating.rst
  View file @ff3e361
1   -.. _sec_simulating_cta:
  1 +.. _start_simulating:
2 2  
3   -Simulating CTA data
4   --------------------
  3 +Simulating event data
  4 +---------------------
5 5  
6 6 .. admonition:: What you will learn
7 7  
8 8 You will learn how to use the :ref:`ctobssim` tool from the command
9   - line to **simulate CTA event data**.
  9 + line to **simulate event data**.
10 10  
11 11 :ref:`ctobssim` draws random events using a model of the celestial
12 12 gamma-ray intensity distribution that was convolved with the
... ... @@ -39,7 +39,7 @@ characteristics of the simulation:
39 39  
40 40 Each line represents a query for one parameter value.
41 41 The line starts with a short description of the parameter, followed by
42   -the default value proposed by ctobssim in squared brackets ``[ ]``.
  42 +the default value proposed by :ref:`ctobssim` in squared brackets ``[ ]``.
43 43  
44 44 **If no parameter value is entered the default value will be used**.
45 45 Otherwise, the specified value will overwrite the default value.
... ... @@ -181,13 +181,22 @@ To use for example a seed value of 41 you should type:
181 181  
182 182 $ ctobssim seed=41
183 183  
184   -:ref:`ctobssim` will write 2 files in the working directory: ``events.fits``
  184 +..
  185 +
  186 + .. note::
  187 +
  188 + Hidden parameters are parameters that are not queried by a tool since
  189 + in general their values is not expected to change frequently. To change
  190 + hidden parameters they have to be given as arguments on the command line.
  191 + Multiple hidden parameters need to be separated by a white space.
  192 +
  193 +:ref:`ctobssim` will write two files in the working directory: ``events.fits``
185 194 and ``ctobssim.log``. The first file contains the simulated events in FITS
186 195 format and can be inspected using ``fv`` or ``ds9``. The FITS file will
187 196 contain three extensions: an empty primary image, a binary table named
188 197 ``EVENTS`` that holds the events (one row per event), and a binary table
189 198 named ``GTI`` holding the Good Time Intervals (for the moment a single row
190   -with 2 columns providing the start and the stop time of the simulated time
  199 +with two columns providing the start and the stop time of the simulated time
191 200 interval).
192 201  
193 202 The second file produced by :ref:`ctobssim` is a human readable log file that
... ... @@ -271,6 +280,6 @@ the hidden ``debug`` parameter to yes:
271 280 ``debug`` and you can use these parameters to control the log file
272 281 output. In addition, all tools have the hidden parameter ``clobber``
273 282 that allows to overwrite existing files (set to ``yes`` by default)
274   - and ``mode`` that defines the mode of automatic tool parameters (set to
275   - ``ql`` by default).
  283 + and ``mode`` that defines the mode of automatic parameters (set to
  284 + ``ql`` for *query and learn* by default).
276 285  
... ...
doc/source/users/tutorials/quickstart/skymap.rst
  View file @ff3e361
1   -.. _sec_skymap:
  1 +.. _start_skymap:
2 2  
3 3 Generating a sky map
4 4 --------------------
... ... @@ -6,7 +6,7 @@ Generating a sky map
6 6 .. admonition:: What you will learn
7 7  
8 8 You will learn how to use the :ref:`ctskymap` tool to **generate a sky
9   - map from the selected CTA event data**.
  9 + map from the selected event data**.
10 10  
11 11 Now let's have a look into the selected data by generating a sky map. You do
12 12 this with the :ref:`ctskymap` tool as follows:
... ... @@ -68,6 +68,8 @@ example:
68 68 Lower energy limit (TeV) [0.1]
69 69 Upper energy limit (TeV) [100.0]
70 70 Background subtraction method (NONE|IRF) [NONE] IRF
  71 + Calibration database [prod2]
  72 + Instrument response function [South_0.5h]
71 73 Output skymap file [skymap.fits] skymap_subtracted.fits
72 74  
73 75 The resulting sky map, displayed using
... ...
doc/source/users/tutorials/quickstart/spectrum.jpg 0 → 100644
View file @ff3e361

117 KB
doc/source/users/tutorials/quickstart/spectrum.rst 0 → 100644
  View file @ff3e361
  1 +.. _start_spectrum:
  2 +
  3 +Deriving a source spectrum
  4 +--------------------------
  5 +
  6 + .. admonition:: What you will learn
  7 +
  8 + You will learn how to use the :ref:`csspec` script to **derive the spectral
  9 + energy distribution (SED) of a gamma-ray source**.
  10 +
  11 +You may also be interested in the determination of the spectral energy
  12 +distribution (SED) of the Crab nebula that is independent of an assumed
  13 +spectral shape. This can be achieved by the :ref:`csspec` script.
  14 +
  15 +The :ref:`csspec` script divides the energy range into a number of indepedent
  16 +energy bins and performs in each of the energy bins a maximum likelihood fit
  17 +of the source model. Since the spectral shape is generally poorly constrained
  18 +within a narrow energy bin, all spectral parameters except of the scaling
  19 +factor of the source model will be fixed for the fitting. The fit results will
  20 +be converted into a flux value per energy bin. The script also determines
  21 +upper flux limits as well as the Test Statistic value of the source in each
  22 +of the bins.
  23 +
  24 +Below an example how of you can determine the SED of the Crab for 10 energy
  25 +bins between 100 GeV and 100 TeV:
  26 +
  27 +.. code-block:: bash
  28 +
  29 + $ csspec
  30 + Input event list, counts cube, or observation definition XML file [events.fits] cntcube.fits
  31 + Input exposure cube file [NONE] expcube.fits
  32 + Input PSF cube file [NONE] psfcube.fits
  33 + Input background cube file [NONE] bkgcube.fits
  34 + Input model definition XML file [$CTOOLS/share/models/crab.xml] models.xml
  35 + Source name [Crab]
  36 + Binning algorithm (LIN|LOG|FILE) [LOG]
  37 + Lower energy limit (TeV) [0.1]
  38 + Upper energy limit (TeV) [100.0]
  39 + Number of energy bins (0=unbinned) [20] 10
  40 + Output spectrum file [spectrum.fits]
  41 +
  42 +The :ref:`csspec` script creates the FITS file ``spectrum.fits`` that contains
  43 +the results of the SED fitting. A graphical display of the fit results is
  44 +shown below.
  45 +
  46 +.. figure:: spectrum.jpg
  47 + :width: 600px
  48 + :align: center
  49 +
  50 + *Spectral energy distribution of the Crab nebula*
  51 +
  52 +..
  53 +
  54 + .. note::
  55 +
  56 + The figure was created by typing:
  57 +
  58 + .. code-block:: bash
  59 +
  60 + $ $CTOOLS/share/examples/python/show_spectrum.py spectrum.fits
... ...
doc/source/users/tutorials/quickstart/unbinned.rst
  View file @ff3e361
1   -.. _sec_unbinned_cta:
  1 +.. _start_unbinned:
2 2  
3 3 Doing an unbinned analysis
4 4 --------------------------
... ... @@ -53,7 +53,7 @@ hence there is no loss of information due to histogramming.
53 53 Below you see the corresponding output from the ``ctlike.log`` file. The fitted
54 54 parameters are essentially identical to the ones found in binned mode.
55 55 The slight difference with respect to the binned analysis may be explained
56   -by the different event sample that has been used for the analysis: while
  56 +by the different event sample that were used for the analysis: while
57 57 binned likelihood works on rectangular counts cubes, unbinned likelihood works
58 58 on circular event selection regions. It is thus not possible to select exactly
59 59 the same events for both analyses.
... ... @@ -115,3 +115,12 @@ the same events for both analyses.
115 115 2017-08-08T20:56:28: PivotEnergy ..............: 1000000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)
116 116 2017-08-08T20:56:28: Number of temporal par's ..: 1
117 117 2017-08-08T20:56:28: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  118 +
  119 +..
  120 +
  121 + .. note::
  122 +
  123 + Many tools or scripts can also be used in unbinned mode, including
  124 + :ref:`csresmap`, :ref:`ctbutterfly` and :ref:`csspec` that were used
  125 + earlier. It is sufficient to replace the input counts cube by an event
  126 + list to activate unbinned mode for these tools.
... ...
doc/source/users/user_manual/index.rst
  View file @ff3e361
... ... @@ -10,4 +10,3 @@ User Manual
10 10 response
11 11 models
12 12 plotting
13   - python
... ...
doc/source/users/user_manual/python.rst
  View file @ff3e361
... ... @@ -22,7 +22,7 @@ To illustrate how to use ctools from Python, below is a working example
22 22 of an event list simulation using the :ref:`ctobssim` class.
23 23 An instance ``sim`` of the :ref:`ctobssim` class is generated and user
24 24 parameters are set for this instance using the ``[ ]`` operator.
25   -See the :ref:`reference` for a list of parameters and their types).
  25 +See the :ref:`reference` for a list of parameters and their types.
26 26 The ``execute()`` method executes the :ref:`ctobssim` class in the same
27 27 way as if it were executed from the command line.
28 28  
... ...
src/ctbutterfly/ctbutterfly.par
  View file @ff3e361
... ... @@ -19,10 +19,10 @@
19 19 inobs, f, a, "events.fits",,,"Input event list, counts cube or observation definition XML file"
20 20 inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model definition XML file"
21 21 srcname, s, a, "Crab",,,"Source of interest"
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   -edispcube, f, a, "NONE",,, "Input energy dispersion cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
  22 +expcube, f, a, "NONE",,, "Input exposure cube file"
  23 +psfcube, f, a, "NONE",,, "Input PSF cube file"
  24 +edispcube, f, a, "NONE",,, "Input energy dispersion cube file"
  25 +bkgcube, f, a, "NONE",,, "Input background cube file"
26 26 caldb, s, a, "prod2",,, "Calibration database"
27 27 irf, s, a, "South_0.5h",,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
... ... @@ -40,8 +40,8 @@ matrix, f, h, &quot;NONE&quot;,,, &quot;Input covariance Matrix FITS file&quot;
40 40 # Energy binning parameters
41 41 #==========================
42 42 ebinalg, s, h, "LOG", FILE|LIN|LOG,,"Algorithm for defining energy bins"
43   -emin, r, a, 0.1,,,"Start value for first energy bin in TeV"
44   -emax, r, a, 100.0,,,"Stop value for last energy bin in TeV"
  43 +emin, r, a, 0.1,,,"Lower energy limit (TeV)"
  44 +emax, r, a, 100.0,,,"Upper energy limit (TeV)"
45 45 enumbins, i, h, 100,,,"Number of energy bins"
46 46 ebinfile, f, h, "NONE",,,"Name of the file containing the energy bin definition"
47 47  
... ...
src/cterror/cterror.par
  View file @ff3e361
... ... @@ -20,10 +20,10 @@
20 20 inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition XML file"
21 21 inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model definiton XML file"
22 22 srcname, s, a, "Crab",,, "Source of interest"
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   -edispcube,f, a, "NONE",,, "Input energy dispersion cube file (only needed for stacked analysis)"
26   -bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
  23 +expcube, f, a, "NONE",,, "Input exposure cube file"
  24 +psfcube, f, a, "NONE",,, "Input PSF cube file"
  25 +edispcube,f, a, "NONE",,, "Input energy dispersion cube file"
  26 +bkgcube, f, a, "NONE",,, "Input background cube file"
27 27 caldb, s, a, "prod2",,, "Calibration database"
28 28 irf, s, a, "South_0.5h",,, "Instrument response function"
29 29 edisp, b, h, no,,, "Apply energy dispersion?"
... ...
src/ctmodel/ctmodel.par
  View file @ff3e361
... ... @@ -19,10 +19,10 @@
19 19 inobs, f, a, "NONE",,, "Input event list, counts cube or observation definition XML file"
20 20 incube, f, a, "NONE",,, "Input counts cube file to extract model cube definition"
21 21 inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model definition 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   -edispcube,f, a, "NONE",,, "Input energy dispersion cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
  22 +expcube, f, a, "NONE",,, "Input exposure cube file"
  23 +psfcube, f, a, "NONE",,, "Input PSF cube file"
  24 +edispcube,f, a, "NONE",,, "Input energy dispersion cube file"
  25 +bkgcube, f, a, "NONE",,, "Input background cube file"
26 26 caldb, s, a, "prod2",,, "Calibration database"
27 27 irf, s, a, "South_0.5h",,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
... ...
src/cttsmap/cttsmap.par
  View file @ff3e361
... ... @@ -19,10 +19,10 @@
19 19 inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition XML file"
20 20 inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model definition XML file"
21 21 srcname, s, a, "Crab",,, "Test source name"
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   -edispcube, f, a, "NONE",,, "Input energy dispersion cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
  22 +expcube, f, a, "NONE",,, "Input exposure cube file"
  23 +psfcube, f, a, "NONE",,, "Input PSF cube file"
  24 +edispcube, f, a, "NONE",,, "Input energy dispersion cube file"
  25 +bkgcube, f, a, "NONE",,, "Input background cube file"
26 26 caldb, s, a, "prod2",,, "Calibration database"
27 27 irf, s, a, "South_0.5h",,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
... ...
src/ctulimit/ctulimit.par
  View file @ff3e361
... ... @@ -19,10 +19,10 @@
19 19 inobs, f, a, "events.fits",,, "Input event list, counts cube or observation definition XML file"
20 20 inmodel, f, a, "$CTOOLS/share/models/crab.xml",,, "Input model definition XML file"
21 21 srcname, s, a, "Crab",,, "Source of interest"
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   -edispcube,f, a, "NONE",,, "Input energy dispersion cube file (only needed for stacked analysis)"
25   -bkgcube, f, a, "NONE",,, "Input background cube file (only needed for stacked analysis)"
  22 +expcube, f, a, "NONE",,, "Input exposure cube file"
  23 +psfcube, f, a, "NONE",,, "Input PSF cube file"
  24 +edispcube,f, a, "NONE",,, "Input energy dispersion cube file"
  25 +bkgcube, f, a, "NONE",,, "Input background cube file"
26 26 caldb, s, a, "prod2",,, "Calibration database"
27 27 irf, s, a, "South_0.5h",,, "Instrument response function"
28 28 edisp, b, h, no,,, "Apply energy dispersion?"
... ...