Veronika Vodeb / ctools

Commit 2c17597d0a05c24f1ad7a758b508fad88bf58ae3

Authored by Jürgen Knödlseder
1 parent ec483d11

Update model section of User Manual

Inline Side-by-side
Showing 6 changed files with 197 additions and 71 deletions
doc/source/users/user_manual/models_concept.rst
  View file @2c17597
1   -.. _sec_models_concept:
  1 +.. _um_models_concept:
2 2  
3 3 Overall concept
4 4 ------------------
... ...
doc/source/users/user_manual/models_implementation.rst
  View file @2c17597
1   -.. _sec_models_implementation:
  1 +.. _um_models_implementation:
2 2  
3 3 Implementation
4 4 --------------
... ... @@ -8,7 +8,7 @@ Below is a simple example of such a file comprising one source and one
8 8 background model.
9 9 Each model is factorised into
10 10 a spectral (tag ``<spectrum>``),
11   -a spatial (tags ``<spatialModel>`` and ``<radialModel>``), and
  11 +a spatial (tags ``<spatialModel>`` or ``<radialModel>``), and
12 12 a temporal component (tag ``<temporal>``).
13 13  
14 14 .. math::
... ...
doc/source/users/user_manual/models_spatial_bgd.rst
  View file @2c17597
1   -.. _sec_models_spatial_bgd:
  1 +.. _um_models_spatial_bgd:
2 2  
3 3 Spatial background model components
4 4 -----------------------------------
5 5  
6 6 The following sections present the spatial model components that are available
7   -in ctools for instrumental background modelling for CTA.
  7 +in ctools for instrumental background modelling for Imaging Air Cherenkov
  8 +Telescopes (IACTs) such as H.E.S.S., VERITAS, MAGIC and CTA.
8 9  
9   -CTA radial background
10   -^^^^^^^^^^^^^^^^^^^^^
11 10  
12   - There exist a number of radial CTA background models that factorise into a
13   - spatial and spectral component, and that model the spatial component as a
14   - function that only dependends on the offset angle :math:`\theta` from the
15   - pointing direction. These models have the type ``RadialAcceptance`` and
16   - require a ``<radialModel>`` tag as the spatial component.
  11 +General IACT background
  12 +^^^^^^^^^^^^^^^^^^^^^^^
17 13  
18   - The first radial model is of type ``Gaussian``
  14 + The general IACT background model is factorised in a spatial and spectral
  15 + component and has the type ``CTABackground``. It has the following XML
  16 + structure:
19 17  
20 18 .. code-block:: xml
21 19  
22   - <source name="Background" type="RadialAcceptance" instrument="CTA">
23   - <radialModel type="Gaussian">
  20 + <source name="Background" type="CTABackground" instrument="CTA">
  21 + <spatialModel type="...">
  22 + ...
  23 + </spatialModel>
  24 + <spectrum type="...">
  25 + ...
  26 + </spectrum>
  27 + </source>
  28 +
  29 + .. note::
  30 + Please speficy the ``instrument`` label in the XML file that corresponds
  31 + to the ``instrument`` label of the data. Otherwise the model will not be used
  32 + for your data. Valid ``instrument`` labels are ``HESS``, ``VERITAS``,
  33 + ``MAGIC`` and ``CTA``.
  34 +
  35 + The following sections describe the spatial model components that are
  36 + available.
  37 +
  38 +
  39 +Gaussian
  40 +~~~~~~~~
  41 +
  42 + The ``Gaussian`` model describes a 2D Gaussian shape in offset angle squared
  43 +
  44 + .. code-block:: xml
  45 +
  46 + <source name="Background" type="CTABackground" instrument="CTA">
  47 + <spatialModel type="Gaussian">
24 48 <parameter name="Sigma" scale="1.0" value="3.0" min="0.01" max="10.0" free="1"/>
25   - </radialModel>
26   - <spectrum type="PowerLaw">
27   - <parameter name="Prefactor" scale="1e-6" value="61.8" min="0.0" max="1000.0" free="1"/>
28   - <parameter name="Index" scale="-1" value="1.85" min="0.0" max="+5.0" free="1"/>
29   - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
  49 + </spatialModel>
  50 + <spectrum type="...">
  51 + ...
30 52 </spectrum>
31 53 </source>
32 54  
... ... @@ -40,21 +62,31 @@ CTA radial background
40 62  
41 63 * :math:`\sigma` = ``Sigma`` (degrees)
42 64  
43   - The second radial model is of type ``Profile``
  65 + and
  66 +
  67 + .. math::
  68 + \theta = \sqrt{\mathrm{DETX} \times \mathrm{DETX} + \mathrm{DETY} \times\mathrm{DETY}}
  69 +
  70 + with :math:`\mathrm{DETX}` and :math:`\mathrm{DETY}` being the detector
  71 + coordinates in the nominal system.
  72 +
  73 +
  74 +Profile
  75 +~~~~~~~
  76 +
  77 + The ``Profile`` model describes a radial profile
44 78  
45 79 .. code-block:: xml
46 80  
47   - <source name="Background" type="RadialAcceptance" instrument="CTA">
48   - <radialModel type="Profile">
  81 + <source name="Background" type="CTABackground" instrument="CTA">
  82 + <spatialModel type="Profile">
49 83 <parameter name="Width" scale="1.0" value="1.5" min="0.1" max="1000.0" free="1"/>
50 84 <parameter name="Core" scale="1.0" value="3.0" min="0.1" max="1000.0" free="1"/>
51 85 <parameter name="Tail" scale="1.0" value="5.0" min="0.1" max="1000.0" free="1"/>
52   - </radialModel>
53   - <spectrum type="PowerLaw">
54   - <parameter name="Prefactor" scale="1e-6" value="61.8" min="0.0" max="1000.0" free="1"/>
55   - <parameter name="Index" scale="-1" value="1.85" min="0.0" max="+5.0" free="1"/>
56   - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
57   - </spectrum>
  86 + </spatialModel>
  87 + <spectrum type="...">
  88 + ...
  89 + </spectrum>
58 90 </source>
59 91  
60 92 and implements
... ... @@ -68,26 +100,25 @@ CTA radial background
68 100 * :math:`c_1` = ``Core``
69 101 * :math:`c_2` = ``Tail``
70 102  
71   - The third radial model is of type ``Polynom``
  103 +
  104 +Polynom
  105 +~~~~~~~
  106 +
  107 + The ``Polynom`` model describes a polynomial with an arbitrary number of
  108 + coefficients
72 109  
73 110 .. code-block:: xml
74 111  
75   - <source name="Background" type="RadialAcceptance" instrument="CTA">
76   - <radialModel type="Polynom">
  112 + <source name="Background" type="CTABackground" instrument="CTA">
  113 + <spatialModel type="Polynom">
77 114 <parameter name="Coeff0" scale="1.0" value="+1.00000" min="-10.0" max="10.0" free="0"/>
78 115 <parameter name="Coeff1" scale="1.0" value="-0.1239176" min="-10.0" max="10.0" free="1"/>
79 116 <parameter name="Coeff2" scale="1.0" value="+0.9751791" min="-10.0" max="10.0" free="1"/>
80 117 <parameter name="Coeff3" scale="1.0" value="-3.0584577" min="-10.0" max="10.0" free="1"/>
81   - <parameter name="Coeff4" scale="1.0" value="+2.9089535" min="-10.0" max="10.0" free="1"/>
82   - <parameter name="Coeff5" scale="1.0" value="-1.3535372" min="-10.0" max="10.0" free="1"/>
83   - <parameter name="Coeff6" scale="1.0" value="+0.3413752" min="-10.0" max="10.0" free="1"/>
84   - <parameter name="Coeff7" scale="1.0" value="-0.0449642" min="-10.0" max="10.0" free="1"/>
85   - <parameter name="Coeff8" scale="1.0" value="+0.0024321" min="-10.0" max="10.0" free="1"/>
86   - </radialModel>
87   - <spectrum type="PowerLaw">
88   - <parameter name="Prefactor" scale="1e-6" value="61.8" min="0.0" max="1000.0" free="1"/>
89   - <parameter name="Index" scale="-1" value="1.85" min="0.0" max="+5.0" free="1"/>
90   - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
  118 + ...
  119 + </spatialModel>
  120 + <spectrum type="...">
  121 + ...
91 122 </spectrum>
92 123 </source>
93 124  
... ... @@ -100,9 +131,116 @@ CTA radial background
100 131  
101 132 * :math:`c_0` = ``Coeff0``
102 133 * :math:`c_1` = ``Coeff1``
  134 + * :math:`c_2` = ``Coeff2``
  135 + * :math:`c_3` = ``Coeff3``
103 136 * ...
104 137  
105   - (the number of polynomial coefficients is arbitrary).
  138 +
  139 +Gradient
  140 +~~~~~~~~
  141 +
  142 + The ``Gradient`` model describes a bilinear gradient over the field of
  143 + view
  144 +
  145 + .. code-block:: xml
  146 +
  147 + <source name="Background" type="CTABackground" instrument="CTA">
  148 + <spatialModel type="Gradient">
  149 + <parameter name="Grad_DETX" scale="1.0" value="0.0" min="-10.0" max="10.0" free="1"/>
  150 + <parameter name="Grad_DETY" scale="1.0" value="0.0" min="-10.0" max="10.0" free="1"/>
  151 + </spatialModel>
  152 + <spectrum type="...">
  153 + ...
  154 + </spectrum>
  155 + </source>
  156 +
  157 + and implements
  158 +
  159 + .. math::
  160 + M_{\rm spatial}(\mathrm{DETX},\mathrm{DETY}) =
  161 + 1 + \nabla_\mathrm{x} \mathrm{DETX} + \nabla_\mathrm{y} \mathrm{DETY}
  162 +
  163 + where
  164 +
  165 + * :math:`\nabla_\mathrm{x}` = ``Grad_DETX`` (per degree)
  166 + * :math:`\nabla_\mathrm{y}` = ``Grad_DETY`` (per degree)
  167 +
  168 +
  169 +
  170 +Multiplicative
  171 +~~~~~~~~~~~~~~
  172 +
  173 + The ``Multiplicative`` model describes a multiplication of spatial models
  174 +
  175 + .. code-block:: xml
  176 +
  177 + <source name="Background" type="CTABackground" instrument="CTA">
  178 + <spatialModel type="Multiplicative">
  179 + <spatialModel type="...">
  180 + ...
  181 + </spatialModel>
  182 + <spatialModel type="...">
  183 + ...
  184 + </spatialModel>
  185 + ...
  186 + </spatialModel>
  187 + <spectrum type="...">
  188 + ...
  189 + </spectrum>
  190 + </source>
  191 +
  192 + and implements
  193 +
  194 + .. math::
  195 + M_{\rm spatial}(\mathrm{DETX},\mathrm{DETY}) =
  196 + \prod_{i=0}^{N-1} M^{(i)}_{\rm spatial}(\mathrm{DETX},\mathrm{DETY})
  197 +
  198 + where :math:`M^{(i)}_{\rm spatial}(\mathrm{DETX},\mathrm{DETY})` is any
  199 + spatial model component, including another multiplicative model, and
  200 + :math:`N` is the number of model components that are multiplied.
  201 + For example, the default model for a H.E.S.S. data analysis is specified
  202 + by
  203 +
  204 + .. code-block:: xml
  205 +
  206 + <source name="Background" type="CTABackground" instrument="CTA">
  207 + <spatialModel type="Multiplicative">
  208 + <spatialModel type="Gaussian">
  209 + <parameter name="Sigma" scale="1.0" value="3.0" min="0.01" max="10.0" free="1"/>
  210 + </spatialModel>
  211 + <spatialModel type="Gradient">
  212 + <parameter name="Grad_DETX" scale="1.0" value="0.0" min="-10.0" max="10.0" free="1"/>
  213 + <parameter name="Grad_DETY" scale="1.0" value="0.0" min="-10.0" max="10.0" free="1"/>
  214 + </spatialModel>
  215 + </spatialModel>
  216 + <spectrum type="...">
  217 + ...
  218 + </spectrum>
  219 + </source>
  220 +
  221 +
  222 +Radial acceptance background
  223 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  224 +
  225 + For legacy reasons, there exists a class of radially symmetric background
  226 + models of the type ``RadialAcceptance`` with the following XML structure:
  227 +
  228 + .. code-block:: xml
  229 +
  230 + <source name="Background" type="RadialAcceptance" instrument="CTA">
  231 + <radialModel type="Gaussian">
  232 + ...
  233 + </radialModel>
  234 + <spectrum type="...">
  235 + ...
  236 + </spectrum>
  237 + </source>
  238 +
  239 + These models require a ``<radialModel>`` tag as the spatial component and
  240 + accept all spatial model types that take the offset angle :math:`\theta`
  241 + as variable, such as ``Gaussian``, ``Profile`` and ``Polynom``. The use
  242 + of the radial acceptance model is deprecated, and the ``CTABackground``
  243 + model should be used instead.
106 244  
107 245  
108 246 CTA IRF background
... ... @@ -115,17 +253,12 @@ CTA IRF background
115 253 can be used by specifying a model of type ``CTAIrfBackground``. No spatial component
116 254 will be specified explicitly since the spatial (and spectral) information is
117 255 already contained in the template. The model will be multiplied by a spectral law.
118   - In the example below, the template is multiplied by a power law with normalization
119   - of 1 and slope 0 (i.e. the template is taken as is, but a fit can adjust the model
120   - to compensate for inaccuracies):
121 256  
122 257 .. code-block:: xml
123 258  
124 259 <source name="Background" type="CTAIrfBackground" instrument="CTA">
125   - <spectrum type="PowerLaw">
126   - <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-3" max="1e3" free="1"/>
127   - <parameter name="Index" scale="1.0" value="0.0" min="-5.0" max="+5.0" free="1"/>
128   - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
  260 + <spectrum type="...">
  261 + ...
129 262 </spectrum>
130 263 </source>
131 264  
... ... @@ -135,10 +268,8 @@ CTA IRF background
135 268 .. code-block:: xml
136 269  
137 270 <source name="Background" type="CTAIrfBackground" instrument="CTAOnOff">
138   - <spectrum type="PowerLaw">
139   - <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-3" max="1e3" free="1"/>
140   - <parameter name="Index" scale="1.0" value="0.0" min="-5.0" max="+5.0" free="1"/>
141   - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
  271 + <spectrum type="...">
  272 + ...
142 273 </spectrum>
143 274 </source>
144 275  
... ... @@ -148,16 +279,13 @@ CTA effective area background
148 279  
149 280 Instead of using the background template the effective area for gamma rays can
150 281 also be used to model the instrumental background. Note that in this case the
151   - effective area has to be scaled to a reasonable background rate. An example is
152   - given below:
  282 + effective area has to be scaled to a reasonable background rate.
153 283  
154 284 .. code-block:: xml
155 285  
156 286 <source name="Background" type="CTAAeffBackground" instrument="CTA">
157   - <spectrum type="PowerLaw">
158   - <parameter name="Prefactor" scale="1e-14" value="1.0" min="1e-3" max="1e3" free="1"/>
159   - <parameter name="Index" scale="1.0" value="-2.4" min="-5.0" max="+5.0" free="1"/>
160   - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
  287 + <spectrum type="...">
  288 + ...
161 289 </spectrum>
162 290 </source>
163 291  
... ... @@ -165,17 +293,15 @@ CTA effective area background
165 293 CTA cube background
166 294 ^^^^^^^^^^^^^^^^^^^
167 295  
168   - For a stacked analysis, the background rate is predicted by a so called background
169   - cube. The background cube is used by specifying a model of type ``CTACubeBackground``.
170   - Similar to the ``CTAIrfBackground`` model, the background cube is multplied by
171   - a spectral model.
  296 + For a stacked analysis, the background rate is predicted by a so called
  297 + background cube. The background cube is used by specifying a model of type
  298 + ``CTACubeBackground``. Similar to the ``CTAIrfBackground`` model, the
  299 + background cube is multplied by a spectral model.
172 300  
173 301 .. code-block:: xml
174 302  
175 303 <source name="Background" type="CTACubeBackground" instrument="CTA">
176   - <spectrum type="PowerLaw">
177   - <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-3" max="1e3" free="1"/>
178   - <parameter name="Index" scale="1.0" value="0.0" min="-5.0" max="+5.0" free="1"/>
179   - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
  304 + <spectrum type="...">
  305 + ...
180 306 </spectrum>
181 307 </source>
... ...
doc/source/users/user_manual/models_spatial_src.rst
  View file @2c17597
1   -.. _sec_models_spatial_src:
  1 +.. _um_models_spatial_src:
2 2  
3 3 Spatial source model components
4 4 -------------------------------
... ...
doc/source/users/user_manual/models_spectral.rst
  View file @2c17597
1   -.. _sec_models_spectral:
  1 +.. _um_models_spectral:
2 2  
3 3 Spectral model components
4 4 -------------------------
... ...
doc/source/users/user_manual/models_temporal.rst
  View file @2c17597
1   -.. _sec_models_temporal:
  1 +.. _um_models_temporal:
2 2  
3 3 Temporal model components
4 4 -------------------------
... ...