Commit c8fd2ec62f2702e2f369ccf8ecaf38becc1a0594
1 parent
03ce9b01
Update ctools User manual
Showing
15 changed files
with
1452 additions
and
1134 deletions
doc/source/users/user_manual/models.rst
| @@ -3,1066 +3,12 @@ | @@ -3,1066 +3,12 @@ | ||
| 3 | Modelling CTA data | 3 | Modelling CTA data |
| 4 | ------------------ | 4 | ------------------ |
| 5 | 5 | ||
| 6 | -.. _sec_model_concept: | ||
| 7 | - | ||
| 8 | -Overall concept | ||
| 9 | -~~~~~~~~~~~~~~~ | ||
| 10 | - | ||
| 11 | -A central element of any data analysis is the modeling of the observed | ||
| 12 | -event distribution. | ||
| 13 | -Generally, the measured events can be separated into two distinct classes: | ||
| 14 | -events being attributed to gamma rays of celestial origin (the "source" | ||
| 15 | -events) or events being attributed to any other kind of trigger (the | ||
| 16 | -"background" events). | ||
| 17 | -In the first case, the :ref:`Instrument Response Functions (IRFs) <sec_response>` | ||
| 18 | -describe how an incident gamma-ray converts into a measured event. | ||
| 19 | -In the second case there is often no general prescription, and the | ||
| 20 | -distribution of background events is commonly modeled directly in the data | ||
| 21 | -space of the observable quantities. | ||
| 22 | -The main difficulty of gamma-ray astronomy is that not all events can be | ||
| 23 | -tagged a priori as being source or background, hence their separation can | ||
| 24 | -only be done on a statistical basis, based on the different morphologies, | ||
| 25 | -spectral characteristics or eventually temporal signatures of both event | ||
| 26 | -categories. | ||
| 27 | - | ||
| 28 | -For this purpose, ctools use a general model that describes the spatial, | ||
| 29 | -spectral and temporal properties of the source and background components. | ||
| 30 | -The model is composed of an arbitrary number of model components that | ||
| 31 | -add up linearly to provide a prediction of the expected number of events. | ||
| 32 | -Model components are generally parametric, and model parameters can be | ||
| 33 | -adjusted through a maximum likelihood procedure to find the set of | ||
| 34 | -parameters that represent best the measured data. | ||
| 35 | -Model components representing celestial sources are convolved with the | ||
| 36 | -:ref:`IRFs <sec_response>` to predict the expected number of source events in | ||
| 37 | -the data. | ||
| 38 | -Background model components will be directly expressed as expected number | ||
| 39 | -of background events without any :ref:`IRF <sec_response>` convolution. | ||
| 40 | - | ||
| 41 | - | ||
| 42 | -.. _sec_model_implementation: | ||
| 43 | - | ||
| 44 | -Implementation | ||
| 45 | -~~~~~~~~~~~~~~ | ||
| 46 | - | ||
| 47 | -The general model is describe in ctools using a model definition XML file. | ||
| 48 | -Below is a simple example of such a file comprising one source and one | ||
| 49 | -background model. | ||
| 50 | -Each model is factorised into | ||
| 51 | -a spectral (tag ``<spectrum>``), | ||
| 52 | -a spatial (tags ``<spatialModel>`` and ``<radialModel>``), and | ||
| 53 | -a temporal component (tag ``<temporal>``). | ||
| 54 | - | ||
| 55 | -.. math:: | ||
| 56 | - M(x,y,E,t) = M_{\rm spatial}(x,y|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) | ||
| 57 | - | ||
| 58 | -In this specific example, the source component ``Crab`` describes | ||
| 59 | -a point source at the location of the Crab nebula with a power law spectral | ||
| 60 | -shape that is constant in time. | ||
| 61 | -The background component ``Background`` is modelled as a radial Gaussian | ||
| 62 | -function in offset angle squared (with the offset angle being defined as | ||
| 63 | -the angle between pointing and measured event direction) and a spectral | ||
| 64 | -function that is tabulated in an ASCII file. | ||
| 65 | - | ||
| 66 | -.. code-block:: xml | ||
| 67 | - | ||
| 68 | - <?xml version="1.0" standalone="no"?> | ||
| 69 | - <source_library title="source library"> | ||
| 70 | - <source name="Crab" type="PointSource"> | ||
| 71 | - <spatialModel type="PointSource"> | ||
| 72 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 73 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 74 | - </spatialModel> | ||
| 75 | - <spectrum type="PowerLaw"> | ||
| 76 | - <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 77 | - <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 78 | - <parameter name="PivotEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/> | ||
| 79 | - </spectrum> | ||
| 80 | - <temporal type="Constant"> | ||
| 81 | - <parameter name="Normalization" scale="1.0" value="1.0" min="0.0" max="1000.0" free="0"/> | ||
| 82 | - </temporal> | ||
| 83 | - </source> | ||
| 84 | - <source name="Background" type="RadialAcceptance" instrument="CTA"> | ||
| 85 | - <spectrum type="FileFunction" file="$CTOOLS/share/models/bkg_dummy.txt"> | ||
| 86 | - <parameter name="Normalization" scale="1.0" value="1.0" min="0.0" max="1000.0" free="1"/> | ||
| 87 | - </spectrum> | ||
| 88 | - <radialModel type="Gaussian"> | ||
| 89 | - <parameter name="Sigma" scale="1.0" value="3.0" min="0.01" max="10.0" free="1"/> | ||
| 90 | - </radialModel> | ||
| 91 | - </source> | ||
| 92 | - </source_library> | ||
| 93 | - | ||
| 94 | -Model parameters are specified by a ``<parameter>`` tag with a certain | ||
| 95 | -number of attributes. | ||
| 96 | -The ``name`` attribute gives the (case-sensitive) parameter name that | ||
| 97 | -needs to be unique within a given model component. | ||
| 98 | -The ``scale`` attribute gives a scaling factor that will be multiplied by | ||
| 99 | -the ``value`` attribute to provide the real (physical) parameter value. | ||
| 100 | -The ``min`` and ``max`` attributes specify boundaries for the ``value`` | ||
| 101 | -term of the parameter. | ||
| 102 | -And the ``free`` attribute specifies whether a parameter should be fitted | ||
| 103 | -(``free="1"``) or kept fixed (``free="0"``) in a maximum likelihood | ||
| 104 | -analysis. | ||
| 105 | -After a maximum likelihood fit using :ref:`ctlike`, an | ||
| 106 | -``error`` attribute giving the statisical uncertainty of the ``value`` | ||
| 107 | -term will be appended to each ``<parameter>`` tag. | ||
| 108 | - | ||
| 109 | -.. note:: | ||
| 110 | - For compatibility reasons with the Fermi/LAT XML format the ``<temporal>`` | ||
| 111 | - tag can be omitted for models that are constant in time. | ||
| 112 | - | ||
| 113 | -.. note:: | ||
| 114 | - | ||
| 115 | - XML files are ASCII files and can be edited by hand using any text | ||
| 116 | - editor. | ||
| 117 | - The indentation of the XML elements is not mandatory. | ||
| 118 | - | ||
| 119 | -.. note:: | ||
| 120 | - | ||
| 121 | - The splitting of parameter values into a ``value`` and ``scale`` factor | ||
| 122 | - is mainly for numerical purposes. | ||
| 123 | - Parameter fitting algorithms can be ill-conditioned if several | ||
| 124 | - parameters of vastly different orders of magnitudes need to be | ||
| 125 | - optimised simultaneously. | ||
| 126 | - Splitting a value into two components allows to "prescale" the | ||
| 127 | - parameters so that the effective parameters to be optimised (the ``value`` terms) | ||
| 128 | - are all of about unity. | ||
| 129 | - | ||
| 130 | -.. note:: | ||
| 131 | - | ||
| 132 | - The syntax of the model definition XML file has been inspired from the | ||
| 133 | - syntax used by the Fermi/LAT ScienceTools, but for reasons of clarity and | ||
| 134 | - homogenity of the various model and parameter names we have made some | ||
| 135 | - modifications. | ||
| 136 | - Nevertheless, the format used by the Fermi/LAT ScienceTools is also | ||
| 137 | - supported. | ||
| 138 | - | ||
| 139 | - | ||
| 140 | -.. _sec_spatial_src_models: | ||
| 141 | - | ||
| 142 | -Spatial source model components | ||
| 143 | -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 144 | - | ||
| 145 | -The following sections present the spatial model components that are available | ||
| 146 | -in ctools for gamma-ray sources. | ||
| 147 | - | ||
| 148 | -Point source | ||
| 149 | -^^^^^^^^^^^^ | ||
| 150 | - | ||
| 151 | - .. code-block:: xml | ||
| 152 | - | ||
| 153 | - <source name="Crab" type="PointSource"> | ||
| 154 | - <spatialModel type="PointSource"> | ||
| 155 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 156 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 157 | - </spatialModel> | ||
| 158 | - <spectrum type="..."> | ||
| 159 | - ... | ||
| 160 | - </spectrum> | ||
| 161 | - </source> | ||
| 162 | - | ||
| 163 | - .. note:: | ||
| 164 | - | ||
| 165 | - For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 166 | - ``PointSource`` can be replaced by ``SkyDirFunction``. | ||
| 167 | - | ||
| 168 | - | ||
| 169 | -Radial source | ||
| 170 | -^^^^^^^^^^^^^ | ||
| 171 | - | ||
| 172 | - .. code-block:: xml | ||
| 173 | - | ||
| 174 | - <source name="Crab" type="ExtendedSource"> | ||
| 175 | - <spatialModel type="RadialDisk"> | ||
| 176 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 177 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 178 | - <parameter name="Radius" scale="1.0" value="0.20" min="0.01" max="10" free="1"/> | ||
| 179 | - </spatialModel> | ||
| 180 | - <spectrum type="..."> | ||
| 181 | - ... | ||
| 182 | - </spectrum> | ||
| 183 | - </source> | ||
| 184 | - | ||
| 185 | - .. code-block:: xml | ||
| 186 | - | ||
| 187 | - <source name="Crab" type="ExtendedSource"> | ||
| 188 | - <spatialModel type="RadialGaussian"> | ||
| 189 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 190 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 191 | - <parameter name="Sigma" scale="1.0" value="0.20" min="0.01" max="10" free="1"/> | ||
| 192 | - </spatialModel> | ||
| 193 | - <spectrum type="..."> | ||
| 194 | - ... | ||
| 195 | - </spectrum> | ||
| 196 | - </source> | ||
| 197 | - | ||
| 198 | - .. code-block:: xml | ||
| 199 | - | ||
| 200 | - <source name="Crab" type="ExtendedSource"> | ||
| 201 | - <spatialModel type="RadialShell"> | ||
| 202 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 203 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 204 | - <parameter name="Radius" scale="1.0" value="0.30" min="0.01" max="10" free="1"/> | ||
| 205 | - <parameter name="Width" scale="1.0" value="0.10" min="0.01" max="10" free="1"/> | ||
| 206 | - </spatialModel> | ||
| 207 | - <spectrum type="..."> | ||
| 208 | - ... | ||
| 209 | - </spectrum> | ||
| 210 | - </source> | ||
| 211 | - | ||
| 212 | - | ||
| 213 | -Elliptical source | ||
| 214 | -^^^^^^^^^^^^^^^^^ | ||
| 215 | - | ||
| 216 | - .. code-block:: xml | ||
| 217 | - | ||
| 218 | - <source name="Crab" type="ExtendedSource"> | ||
| 219 | - <spatialModel type="EllipticalDisk"> | ||
| 220 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 221 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 222 | - <parameter name="PA" scale="1.0" value="45.0" min="-360" max="360" free="1"/> | ||
| 223 | - <parameter name="MinorRadius" scale="1.0" value="0.5" min="0.001" max="10" free="1"/> | ||
| 224 | - <parameter name="MajorRadius" scale="1.0" value="2.0" min="0.001" max="10" free="1"/> | ||
| 225 | - </spatialModel> | ||
| 226 | - <spectrum type="..."> | ||
| 227 | - ... | ||
| 228 | - </spectrum> | ||
| 229 | - </source> | ||
| 230 | - | ||
| 231 | - .. code-block:: xml | ||
| 232 | - | ||
| 233 | - <source name="Crab" type="ExtendedSource"> | ||
| 234 | - <spatialModel type="EllipticalGaussian"> | ||
| 235 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 236 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 237 | - <parameter name="PA" scale="1.0" value="45.0" min="-360" max="360" free="1"/> | ||
| 238 | - <parameter name="MinorRadius" scale="1.0" value="0.5" min="0.001" max="10" free="1"/> | ||
| 239 | - <parameter name="MajorRadius" scale="1.0" value="2.0" min="0.001" max="10" free="1"/> | ||
| 240 | - </spatialModel> | ||
| 241 | - <spectrum type="..."> | ||
| 242 | - ... | ||
| 243 | - </spectrum> | ||
| 244 | - </source> | ||
| 245 | - | ||
| 246 | - | ||
| 247 | -Diffuse source | ||
| 248 | -^^^^^^^^^^^^^^ | ||
| 249 | - | ||
| 250 | - .. code-block:: xml | ||
| 251 | - | ||
| 252 | - <source name="Crab" type="DiffuseSource"> | ||
| 253 | - <spatialModel type="DiffuseIsotropic"> | ||
| 254 | - <parameter name="Value" scale="1" value="1" min="1" max="1" free="0"/> | ||
| 255 | - </spatialModel> | ||
| 256 | - <spectrum type="..."> | ||
| 257 | - ... | ||
| 258 | - </spectrum> | ||
| 259 | - </source> | ||
| 260 | - | ||
| 261 | - .. note:: | ||
| 262 | - | ||
| 263 | - For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 264 | - ``DiffuseIsotropic`` can be replaced by ``ConstantValue``. | ||
| 265 | - | ||
| 266 | - .. code-block:: xml | ||
| 267 | - | ||
| 268 | - <source name="Crab" type="DiffuseSource"> | ||
| 269 | - <spatialModel type="DiffuseMap" file="map.fits"> | ||
| 270 | - <parameter name="Normalization" scale="1" value="1" min="0.001" max="1000.0" free="0"/> | ||
| 271 | - </spatialModel> | ||
| 272 | - <spectrum type="..."> | ||
| 273 | - ... | ||
| 274 | - </spectrum> | ||
| 275 | - </source> | ||
| 276 | - | ||
| 277 | - .. note:: | ||
| 278 | - | ||
| 279 | - For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 280 | - ``DiffuseMap`` can be replaced by ``SpatialMap`` and the parameter | ||
| 281 | - ``Normalization`` can be replaced by ``Prefactor``. | ||
| 282 | - | ||
| 283 | - .. code-block:: xml | ||
| 284 | - | ||
| 285 | - <source name="Crab" type="DiffuseSource"> | ||
| 286 | - <spatialModel type="DiffuseMapCube" file="map_cube.fits"> | ||
| 287 | - <parameter name="Normalization" scale="1" value="1" min="0.001" max="1000.0" free="0"/> | ||
| 288 | - </spatialModel> | ||
| 289 | - <spectrum type="..."> | ||
| 290 | - ... | ||
| 291 | - </spectrum> | ||
| 292 | - </source> | ||
| 293 | - | ||
| 294 | - .. note:: | ||
| 295 | - | ||
| 296 | - For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 297 | - ``DiffuseMapCube`` can be replaced by ``MapCubeFunction`` and the parameter | ||
| 298 | - ``Normalization`` can be replaced by ``Value``. | ||
| 299 | - | ||
| 300 | - | ||
| 301 | -Composite model | ||
| 302 | -^^^^^^^^^^^^^^^ | ||
| 303 | - | ||
| 304 | - .. code-block:: xml | ||
| 305 | - | ||
| 306 | - <source name="Crab" type="CompositeSource"> | ||
| 307 | - <spatialModel type="Composite"> | ||
| 308 | - <spatialModel type="PointSource" component="PointSource"> | ||
| 309 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 310 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 311 | - </spatialModel> | ||
| 312 | - <spatialModel type="RadialGaussian"> | ||
| 313 | - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 314 | - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 315 | - <parameter name="Sigma" scale="1.0" value="0.20" min="0.01" max="10" free="1"/> | ||
| 316 | - </spatialModel> | ||
| 317 | - </spatialModel> | ||
| 318 | - <spectrum type="..."> | ||
| 319 | - ... | ||
| 320 | - </spectrum> | ||
| 321 | - </source> | ||
| 322 | - | ||
| 323 | - This spatial model component implements a composite model that is the | ||
| 324 | - sum of an arbitrary number of spatial models, computed using | ||
| 325 | - | ||
| 326 | - .. math:: | ||
| 327 | - M_{\rm spatial}(x,y|E) = \frac{1}{N} \sum_{i=0}^{N-1} M_{\rm spatial}^{(i)}(x,y|E) | ||
| 328 | - | ||
| 329 | - where :math:`M_{\rm spatial}^{(i)}(x,y|E)` is any spatial model component | ||
| 330 | - (including another composite model), and :math:`N` is the number of | ||
| 331 | - model components that are combined. | ||
| 332 | - | ||
| 333 | - | ||
| 334 | -.. _sec_spatial_bgd_models: | ||
| 335 | - | ||
| 336 | -Spatial background model components | ||
| 337 | -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 338 | - | ||
| 339 | -The following sections present the spatial model components that are available | ||
| 340 | -in ctools for background modelling. | ||
| 341 | - | ||
| 342 | -CTA radial background | ||
| 343 | -^^^^^^^^^^^^^^^^^^^^^ | ||
| 344 | - | ||
| 345 | - .. code-block:: xml | ||
| 346 | - | ||
| 347 | - <source name="Background" type="RadialAcceptance" instrument="CTA"> | ||
| 348 | - <radialModel type="Gaussian"> | ||
| 349 | - <parameter name="Sigma" scale="1.0" value="3.0" min="0.01" max="10.0" free="1"/> | ||
| 350 | - </radialModel> | ||
| 351 | - <spectrum type="..."> | ||
| 352 | - ... | ||
| 353 | - </spectrum> | ||
| 354 | - </source> | ||
| 355 | - | ||
| 356 | - .. code-block:: xml | ||
| 357 | - | ||
| 358 | - <source name="Background" type="RadialAcceptance" instrument="CTA"> | ||
| 359 | - <radialModel type="Profile"> | ||
| 360 | - <parameter name="Width" scale="1.0" value="1.5" min="0.1" max="1000.0" free="1"/> | ||
| 361 | - <parameter name="Core" scale="1.0" value="3.0" min="0.1" max="1000.0" free="1"/> | ||
| 362 | - <parameter name="Tail" scale="1.0" value="5.0" min="0.1" max="1000.0" free="1"/> | ||
| 363 | - </radialModel> | ||
| 364 | - <spectrum type="..."> | ||
| 365 | - ... | ||
| 366 | - </spectrum> | ||
| 367 | - </source> | ||
| 368 | - | ||
| 369 | - .. code-block:: xml | ||
| 370 | - | ||
| 371 | - <source name="Background" type="RadialAcceptance" instrument="CTA"> | ||
| 372 | - <radialModel type="Polynom"> | ||
| 373 | - <parameter name="Coeff0" scale="1.0" value="+1.00000" min="-10.0" max="10.0" free="0"/> | ||
| 374 | - <parameter name="Coeff1" scale="1.0" value="-0.1239176" min="-10.0" max="10.0" free="1"/> | ||
| 375 | - <parameter name="Coeff2" scale="1.0" value="+0.9751791" min="-10.0" max="10.0" free="1"/> | ||
| 376 | - <parameter name="Coeff3" scale="1.0" value="-3.0584577" min="-10.0" max="10.0" free="1"/> | ||
| 377 | - <parameter name="Coeff4" scale="1.0" value="+2.9089535" min="-10.0" max="10.0" free="1"/> | ||
| 378 | - <parameter name="Coeff5" scale="1.0" value="-1.3535372" min="-10.0" max="10.0" free="1"/> | ||
| 379 | - <parameter name="Coeff6" scale="1.0" value="+0.3413752" min="-10.0" max="10.0" free="1"/> | ||
| 380 | - <parameter name="Coeff7" scale="1.0" value="-0.0449642" min="-10.0" max="10.0" free="1"/> | ||
| 381 | - <parameter name="Coeff8" scale="1.0" value="+0.0024321" min="-10.0" max="10.0" free="1"/> | ||
| 382 | - </radialModel> | ||
| 383 | - <spectrum type="..."> | ||
| 384 | - ... | ||
| 385 | - </spectrum> | ||
| 386 | - </source> | ||
| 387 | - | ||
| 388 | - | ||
| 389 | -CTA IRF background | ||
| 390 | -^^^^^^^^^^^^^^^^^^ | ||
| 391 | - | ||
| 392 | - .. code-block:: xml | ||
| 393 | - | ||
| 394 | - <source name="Background" type="CTAIrfBackground" instrument="CTA"> | ||
| 395 | - <spectrum type="..."> | ||
| 396 | - ... | ||
| 397 | - </spectrum> | ||
| 398 | - </source> | ||
| 399 | - | ||
| 400 | - | ||
| 401 | -CTA cube background | ||
| 402 | -^^^^^^^^^^^^^^^^^^^ | ||
| 403 | - | ||
| 404 | - .. code-block:: xml | ||
| 405 | - | ||
| 406 | - <source name="Background" type="CTACubeBackground" instrument="CTA"> | ||
| 407 | - <spectrum type="..."> | ||
| 408 | - ... | ||
| 409 | - </spectrum> | ||
| 410 | - </source> | ||
| 411 | - | ||
| 412 | - | ||
| 413 | - | ||
| 414 | -.. _sec_spectral_models: | ||
| 415 | - | ||
| 416 | -Spectral model components | ||
| 417 | -~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 418 | - | ||
| 419 | -The following sections present the spectral model components that are available | ||
| 420 | -in ctools. | ||
| 421 | - | ||
| 422 | -.. warning:: | ||
| 423 | - | ||
| 424 | - Source intensities are generally given in units of | ||
| 425 | - :math:`{\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1}`. | ||
| 426 | - | ||
| 427 | - An exception to this rule exists for the ``DiffuseMapCube`` spatial | ||
| 428 | - model where intensities are unitless and the spectral model presents a | ||
| 429 | - relative scaling of the diffuse model cube values. | ||
| 430 | - | ||
| 431 | - If spectral models are used for a background model component, intensity | ||
| 432 | - units are generally given in | ||
| 433 | - :math:`{\rm counts}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1}\,{\rm sr}^{-1}` | ||
| 434 | - and correspond to the on-axis count rate. | ||
| 435 | - | ||
| 436 | - Exceptions to this rule exist for the ``CTAIrfBackground`` and | ||
| 437 | - ``CTACubeBackground`` models where intensities are unitless and the spectral | ||
| 438 | - model presents a relative scaling of the background model values. | ||
| 439 | - | ||
| 440 | - | ||
| 441 | -Constant | ||
| 442 | -^^^^^^^^ | ||
| 443 | - | ||
| 444 | - .. code-block:: xml | ||
| 445 | - | ||
| 446 | - <spectrum type="Constant"> | ||
| 447 | - <parameter name="Normalization" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 448 | - </spectrum> | ||
| 449 | - | ||
| 450 | - This spectral model component implements the constant function | ||
| 451 | - | ||
| 452 | - .. math:: | ||
| 453 | - M_{\rm spectral}(E) = N_0 | ||
| 454 | - | ||
| 455 | - where | ||
| 456 | - | ||
| 457 | - * :math:`N_0` = ``Normalization`` | ||
| 458 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 459 | - | ||
| 460 | - .. note:: | ||
| 461 | - | ||
| 462 | - For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 463 | - ``Constant`` can be replaced by ``ConstantValue`` and the parameter | ||
| 464 | - ``Normalization`` by ``Value``. | ||
| 465 | - | ||
| 466 | - | ||
| 467 | -Power law | ||
| 468 | -^^^^^^^^^ | ||
| 469 | - | ||
| 470 | - .. code-block:: xml | ||
| 471 | - | ||
| 472 | - <spectrum type="PowerLaw"> | ||
| 473 | - <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 474 | - <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 475 | - <parameter name="PivotEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/> | ||
| 476 | - </spectrum> | ||
| 477 | - | ||
| 478 | - This spectral model component implements the power law function | ||
| 479 | - | ||
| 480 | - .. math:: | ||
| 481 | - M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma} | ||
| 482 | - | ||
| 483 | - where | ||
| 484 | - | ||
| 485 | - * :math:`k_0` = ``Prefactor`` | ||
| 486 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 487 | - * :math:`\gamma` = ``Index`` | ||
| 488 | - * :math:`E_0` = ``PivotEnergy`` | ||
| 489 | - :math:`({\rm MeV})` | ||
| 490 | - | ||
| 491 | - .. warning:: | ||
| 492 | - | ||
| 493 | - The ``PivotEnergy`` parameter is not intended to be fitted. | ||
| 494 | - | ||
| 495 | - .. note:: | ||
| 496 | - | ||
| 497 | - For compatibility with the Fermi/LAT ScienceTools the parameter | ||
| 498 | - ``PivotEnergy`` can be replaced by ``Scale``. | ||
| 499 | - | ||
| 500 | - An alternative power law function that uses the integral photon flux as | ||
| 501 | - parameter rather than the Prefactor is specified by | ||
| 502 | - | ||
| 503 | - .. code-block:: xml | ||
| 504 | - | ||
| 505 | - <spectrum type="PowerLaw"> | ||
| 506 | - <parameter scale="1e-07" name="PhotonFlux" min="1e-07" max="1000.0" value="1.0" free="1"/> | ||
| 507 | - <parameter scale="1.0" name="Index" min="-5.0" max="+5.0" value="-2.0" free="1"/> | ||
| 508 | - <parameter scale="1.0" name="LowerLimit" min="10.0" max="1000000.0" value="100.0" free="0"/> | ||
| 509 | - <parameter scale="1.0" name="UpperLimit" min="10.0" max="1000000.0" value="500000.0" free="0"/> | ||
| 510 | - </spectrum> | ||
| 511 | - | ||
| 512 | - This spectral model component implements the power law function | ||
| 513 | - | ||
| 514 | - .. math:: | ||
| 515 | - M_{\rm spectral}(E) = \frac{N(\gamma+1)E^{\gamma}} | ||
| 516 | - {E_{\rm max}^{\gamma+1} - E_{\rm min}^{\gamma+1}} | ||
| 517 | - | ||
| 518 | - where | ||
| 519 | - | ||
| 520 | - * :math:`N` = ``PhotonFlux`` | ||
| 521 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1})` | ||
| 522 | - * :math:`\gamma` = ``Index`` | ||
| 523 | - * :math:`E_{\rm min}` = ``LowerLimit`` | ||
| 524 | - :math:`({\rm MeV})` | ||
| 525 | - * :math:`E_{\rm max}` = ``UpperLimit`` | ||
| 526 | - :math:`({\rm MeV})` | ||
| 527 | - | ||
| 528 | - .. warning:: | ||
| 529 | - | ||
| 530 | - The ``LowerLimit`` and ``UpperLimit`` parameters are always treated as fixed | ||
| 531 | - and the flux given by the ``PhotonFlux`` parameter is computed over the | ||
| 532 | - range set by these two parameters. | ||
| 533 | - Use of this model allows the errors on the integral flux to be evaluated directly | ||
| 534 | - by :ref:`ctlike`. | ||
| 535 | - | ||
| 536 | - .. note:: | ||
| 537 | - | ||
| 538 | - For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 539 | - ``PowerLaw`` can be replaced by ``PowerLaw2`` and the parameter | ||
| 540 | - ``PhotonFlux`` by ``Integral``. | ||
| 541 | - | ||
| 542 | - | ||
| 543 | -Exponentially cut-off power law | ||
| 544 | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| 545 | - | ||
| 546 | - .. code-block:: xml | ||
| 547 | - | ||
| 548 | - <spectrum type="ExponentialCutoffPowerLaw"> | ||
| 549 | - <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 550 | - <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 551 | - <parameter name="CutoffEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | ||
| 552 | - <parameter name="PivotEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/> | ||
| 553 | - </spectrum> | ||
| 554 | - | ||
| 555 | - This spectral model component implements the exponentially cut-off power law | ||
| 556 | - function | ||
| 557 | - | ||
| 558 | - .. math:: | ||
| 559 | - M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma} | ||
| 560 | - \exp \left( \frac{-E}{E_{\rm cut}} \right) | ||
| 561 | - | ||
| 562 | - where | ||
| 563 | - | ||
| 564 | - * :math:`k_0` = ``Prefactor`` | ||
| 565 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 566 | - * :math:`\gamma` = ``Index`` | ||
| 567 | - * :math:`E_0` = ``PivotEnergy`` | ||
| 568 | - :math:`({\rm MeV})` | ||
| 569 | - * :math:`E_{\rm cut}` = ``CutoffEnergy`` | ||
| 570 | - :math:`({\rm MeV})` | ||
| 571 | - | ||
| 572 | - .. warning:: | ||
| 573 | - | ||
| 574 | - The ``PivotEnergy`` parameter is not intended to be fitted. | ||
| 575 | - | ||
| 576 | - .. note:: | ||
| 577 | - | ||
| 578 | - For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 579 | - ``ExponentialCutoffPowerLaw`` can be replaced by ``ExpCutoff`` and | ||
| 580 | - the parameters ``CutoffEnergy`` by ``Cutoff`` and ``PivotEnergy`` | ||
| 581 | - by ``Scale``. | ||
| 582 | - | ||
| 583 | - | ||
| 584 | -Super exponentially cut-off power law | ||
| 585 | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| 586 | - | ||
| 587 | - .. code-block:: xml | ||
| 588 | - | ||
| 589 | - <spectrum type="SuperExponentialCutoffPowerLaw"> | ||
| 590 | - <parameter name="Prefactor" scale="1e-16" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 591 | - <parameter name="Index1" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> | ||
| 592 | - <parameter name="CutoffEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | ||
| 593 | - <parameter name="Index2" scale="1.0" value="1.5" min="0.1" max="5.0" free="1"/> | ||
| 594 | - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 595 | - </spectrum> | ||
| 596 | - | ||
| 597 | - This spectral model component implements the super exponentially cut-off power | ||
| 598 | - law function | ||
| 599 | - | ||
| 600 | - .. math:: | ||
| 601 | - M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma} | ||
| 602 | - \exp \left( | ||
| 603 | - -\left( \frac{E}{E_{\rm cut}} \right)^{\alpha} | ||
| 604 | - \right) | ||
| 605 | - | ||
| 606 | - where | ||
| 607 | - | ||
| 608 | - * :math:`k_0` = ``Prefactor`` | ||
| 609 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 610 | - * :math:`\gamma` = ``Index1`` | ||
| 611 | - * :math:`\alpha` = ``Index2`` | ||
| 612 | - * :math:`E_0` = ``PivotEnergy`` | ||
| 613 | - :math:`({\rm MeV})` | ||
| 614 | - * :math:`E_{\rm cut}` = ``CutoffEnergy`` | ||
| 615 | - :math:`({\rm MeV})` | ||
| 616 | - | ||
| 617 | - .. warning:: | ||
| 618 | - | ||
| 619 | - The ``PivotEnergy`` parameter is not intended to be fitted. | ||
| 620 | - | ||
| 621 | - An alternative XML format is supported for compatibility with the Fermi/LAT | ||
| 622 | - XML format: | ||
| 623 | - | ||
| 624 | - .. code-block:: xml | ||
| 625 | - | ||
| 626 | - <spectrum type="PLSuperExpCutoff"> | ||
| 627 | - <parameter name="Prefactor" scale="1e-16" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 628 | - <parameter name="Index1" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> | ||
| 629 | - <parameter name="Cutoff" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | ||
| 630 | - <parameter name="Index2" scale="1.0" value="1.5" min="0.1" max="5.0" free="1"/> | ||
| 631 | - <parameter name="Scale" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 632 | - </spectrum> | ||
| 633 | - | ||
| 634 | - | ||
| 635 | -Broken power law | ||
| 636 | -^^^^^^^^^^^^^^^^ | ||
| 637 | - | ||
| 638 | - .. code-block:: xml | ||
| 639 | - | ||
| 640 | - <spectrum type="BrokenPowerLaw"> | ||
| 641 | - <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 642 | - <parameter name="Index1" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 643 | - <parameter name="BreakEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="1"/> | ||
| 644 | - <parameter name="Index2" scale="-1" value="2.70" min="0.01" max="1000.0" free="1"/> | ||
| 645 | - </spectrum> | ||
| 646 | - | ||
| 647 | - This spectral model component implements the broken power law function | ||
| 648 | - | ||
| 649 | - .. math:: | ||
| 650 | - | ||
| 651 | - M_{\rm spectral}(E) = k_0 \times \left \{ | ||
| 652 | - \begin{eqnarray} | ||
| 653 | - \left( \frac{E}{E_b} \right)^{\gamma_1} & {\rm if\,\,} E < E_b \\ | ||
| 654 | - \left( \frac{E}{E_b} \right)^{\gamma_2} & {\rm otherwise} | ||
| 655 | - \end{eqnarray} | ||
| 656 | - \right . | ||
| 657 | - | ||
| 658 | - where | ||
| 659 | - | ||
| 660 | - * :math:`k_0` = ``Prefactor`` | ||
| 661 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 662 | - * :math:`\gamma_1` = ``Index1`` | ||
| 663 | - * :math:`\gamma_2` = ``Index2`` | ||
| 664 | - * :math:`E_b` = ``BreakEnergy`` | ||
| 665 | - :math:`({\rm MeV})` | ||
| 666 | - | ||
| 667 | - .. warning:: | ||
| 668 | - | ||
| 669 | - Note that the ``BreakEnergy`` parameter may be poorly constrained if | ||
| 670 | - there is no clear spectral cut-off in the spectrum. | ||
| 671 | - This model may lead to complications in the maximum likelihood fitting. | ||
| 672 | - | ||
| 673 | - .. note:: | ||
| 674 | - | ||
| 675 | - For compatibility with the Fermi/LAT ScienceTools the parameters | ||
| 676 | - ``BreakEnergy`` can be replaced by ``BreakValue``. | ||
| 677 | - | ||
| 678 | - | ||
| 679 | -Smoothly broken power law | ||
| 680 | -^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| 681 | - | ||
| 682 | - .. code-block:: xml | ||
| 683 | - | ||
| 684 | - <spectrum type="SmoothBrokenPowerLaw"> | ||
| 685 | - <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 686 | - <parameter name="Index1" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 687 | - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 688 | - <parameter name="Index2" scale="-1" value="2.70" min="0.01" max="+5.0" free="1"/> | ||
| 689 | - <parameter name="BreakEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="1"/> | ||
| 690 | - <parameter name="BreakSmoothness" scale="1.0" value="0.2" min="0.01" max="10.0" free="0"/> | ||
| 691 | - </spectrum> | ||
| 692 | - | ||
| 693 | - This spectral model component implements the smoothly broken power law function | ||
| 694 | - | ||
| 695 | - .. math:: | ||
| 696 | - | ||
| 697 | - M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma_1} | ||
| 698 | - \left[ 1 + | ||
| 699 | - \left( \frac{E}{E_b} \right)^{\frac{\gamma_1 - \gamma_2}{\beta}} | ||
| 700 | - \right]^{-\beta} | ||
| 701 | - | ||
| 702 | - where | ||
| 703 | - | ||
| 704 | - * :math:`k_0` = ``Prefactor`` | ||
| 705 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 706 | - * :math:`\gamma_1` = ``Index1`` | ||
| 707 | - * :math:`E_0` = ``PivotEnergy`` | ||
| 708 | - * :math:`\gamma_2` = ``Index2`` | ||
| 709 | - * :math:`E_b` = ``BreakEnergy`` | ||
| 710 | - :math:`({\rm MeV})` | ||
| 711 | - * :math:`\beta` = ``BreakSmoothness`` | ||
| 712 | - | ||
| 713 | - .. warning:: | ||
| 714 | - | ||
| 715 | - The pivot energy should be set far away from the expected break energy | ||
| 716 | - value. | ||
| 717 | - | ||
| 718 | - .. warning:: | ||
| 719 | - | ||
| 720 | - When the two indices are close together, the :math:`\beta` parameter | ||
| 721 | - becomes poorly constrained. Since the :math:`\beta` parameter also scales | ||
| 722 | - the indices, this can cause very large errors in the estimates of the | ||
| 723 | - various spectral parameters. In this case, consider fixing :math:`\beta`. | ||
| 724 | - | ||
| 725 | - .. note:: | ||
| 726 | - | ||
| 727 | - For compatibility with the Fermi/LAT ScienceTools the parameters | ||
| 728 | - ``PivotEnergy`` can be replaced by ``Scale``, | ||
| 729 | - ``BreakEnergy`` by ``BreakValue`` and | ||
| 730 | - ``BreakSmoothness`` by ``Beta``. | ||
| 731 | - | ||
| 732 | - | ||
| 733 | -Log parabola | ||
| 734 | -^^^^^^^^^^^^ | ||
| 735 | - | ||
| 736 | - .. code-block:: xml | ||
| 737 | - | ||
| 738 | - <spectrum type="LogParabola"> | ||
| 739 | - <parameter name="Prefactor" scale="1e-17" value="5.878" min="1e-07" max="1000.0" free="1"/> | ||
| 740 | - <parameter name="Index" scale="-1" value="2.32473" min="0.0" max="+5.0" free="1"/> | ||
| 741 | - <parameter name="Curvature" scale="-1" value="0.074" min="-5.0" max="+5.0" free="1"/> | ||
| 742 | - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 743 | - </spectrum> | ||
| 744 | - | ||
| 745 | - This spectral model component implements the log parabola function | ||
| 746 | - | ||
| 747 | - .. math:: | ||
| 748 | - M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma+\eta \ln(E/E_0)} | ||
| 749 | - | ||
| 750 | - where | ||
| 751 | - | ||
| 752 | - * :math:`k_0` = ``Prefactor`` | ||
| 753 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 754 | - * :math:`\gamma` = ``Index`` | ||
| 755 | - * :math:`\eta` = ``Curvature`` | ||
| 756 | - * :math:`E_0` = ``PivotEnergy`` | ||
| 757 | - :math:`({\rm MeV})` | ||
| 758 | - | ||
| 759 | - .. warning:: | ||
| 760 | - | ||
| 761 | - The ``PivotEnergy`` parameter is not intended to be fitted. | ||
| 762 | - | ||
| 763 | - An alternative XML format is supported for compatibility with the Fermi/LAT | ||
| 764 | - XML format: | ||
| 765 | - | ||
| 766 | - .. code-block:: xml | ||
| 767 | - | ||
| 768 | - <spectrum type="LogParabola"> | ||
| 769 | - <parameter name="norm" scale="1e-17" value="5.878" min="1e-07" max="1000.0" free="1"/> | ||
| 770 | - <parameter name="alpha" scale="1" value="2.32473" min="0.0" max="+5.0" free="1"/> | ||
| 771 | - <parameter name="beta" scale="1" value="0.074" min="-5.0" max="+5.0" free="1"/> | ||
| 772 | - <parameter name="Eb" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 773 | - </spectrum> | ||
| 774 | - | ||
| 775 | - where | ||
| 776 | - | ||
| 777 | - * ``alpha`` = -``Index`` | ||
| 778 | - * ``beta`` = -``Curvature`` | ||
| 779 | - | ||
| 780 | - | ||
| 781 | -Gaussian | ||
| 782 | -^^^^^^^^ | ||
| 783 | - | ||
| 784 | - .. code-block:: xml | ||
| 785 | - | ||
| 786 | - <spectrum type="Gaussian"> | ||
| 787 | - <parameter name="Normalization" scale="1e-10" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 788 | - <parameter name="Mean" scale="1e6" value="5.0" min="0.01" max="100.0" free="1"/> | ||
| 789 | - <parameter name="Sigma" scale="1e6" value="1.0" min="0.01" max="100.0" free="1"/> | ||
| 790 | - </spectrum> | ||
| 791 | - | ||
| 792 | - This spectral model component implements the gaussian function | ||
| 793 | - | ||
| 794 | - .. math:: | ||
| 795 | - M_{\rm spectral}(E) = \frac{N_0}{\sqrt{2\pi}\sigma} | ||
| 796 | - \exp \left( \frac{-(E-\bar{E})^2}{2 \sigma^2} \right) | ||
| 797 | - | ||
| 798 | - where | ||
| 799 | - | ||
| 800 | - * :math:`N_0` = ``Normalization`` | ||
| 801 | - :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1})` | ||
| 802 | - * :math:`\bar{E}` = ``Mean`` | ||
| 803 | - :math:`({\rm MeV})` | ||
| 804 | - * :math:`\sigma` = ``Sigma`` | ||
| 805 | - :math:`({\rm MeV})` | ||
| 806 | - | ||
| 807 | - | ||
| 808 | -File function | ||
| 809 | -^^^^^^^^^^^^^ | ||
| 810 | - | ||
| 811 | - .. code-block:: xml | ||
| 812 | - | ||
| 813 | - <spectrum type="FileFunction" file="data/filefunction.txt"> | ||
| 814 | - <parameter scale="1.0" name="Normalization" min="0.0" max="1000.0" value="1.0" free="1"/> | ||
| 815 | - </spectrum> | ||
| 816 | - | ||
| 817 | - This spectral model component implements an arbitrary function | ||
| 818 | - that is defined by intensity values at specific energies. | ||
| 819 | - The energy and intensity values are defined using an ASCII file with | ||
| 820 | - columns of energy and differential flux values. | ||
| 821 | - Energies are given in units of | ||
| 822 | - :math:`{\rm MeV}`, | ||
| 823 | - intensities are given in units of | ||
| 824 | - :math:`{\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1}`. | ||
| 825 | - The only parameter is a multiplicative normalization: | ||
| 826 | - | ||
| 827 | - .. math:: | ||
| 828 | - M_{\rm spectral}(E) = N_0 \left. \frac{dN}{dE} \right\rvert_{\rm file} | ||
| 829 | - | ||
| 830 | - where | ||
| 831 | - | ||
| 832 | - * :math:`N_0` = ``Normalization`` | ||
| 833 | - | ||
| 834 | - .. warning:: | ||
| 835 | - | ||
| 836 | - If the file name is given without a path it is expected that the file | ||
| 837 | - resides in the same directory than the XML file. | ||
| 838 | - If the file resides in a different directory, an absolute path name should | ||
| 839 | - be specified. | ||
| 840 | - Any environment variable present in the path name will be expanded. | ||
| 841 | - | ||
| 842 | - | ||
| 843 | -Node function | ||
| 844 | -^^^^^^^^^^^^^ | ||
| 845 | - | ||
| 846 | - .. code-block:: xml | ||
| 847 | - | ||
| 848 | - <spectrum type="NodeFunction"> | ||
| 849 | - <node> | ||
| 850 | - <parameter name="Energy" scale="1.0" value="1.0" min="0.1" max="1.0e20" free="0"/> | ||
| 851 | - <parameter name="Intensity" scale="1e-07" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 852 | - </node> | ||
| 853 | - <node> | ||
| 854 | - <parameter name="Energy" scale="10.0" value="1.0" min="0.1" max="1.0e20" free="0"/> | ||
| 855 | - <parameter name="Intensity" scale="1e-08" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 856 | - </node> | ||
| 857 | - </spectrum> | ||
| 858 | - | ||
| 859 | - This spectral model component implements a generalised broken | ||
| 860 | - power law which is defined by a set of energy and intensity values | ||
| 861 | - (the so called nodes) that are piecewise connected by power laws. | ||
| 862 | - Energies are given in units of | ||
| 863 | - :math:`{\rm MeV}`, | ||
| 864 | - intensities are given in units of | ||
| 865 | - :math:`{\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1}`. | ||
| 866 | - | ||
| 867 | - .. warning:: | ||
| 868 | - | ||
| 869 | - An arbitrary number of energy-intensity nodes can be defined in a node | ||
| 870 | - function. | ||
| 871 | - The nodes need to be sorted by increasing energy. | ||
| 872 | - Although the fitting of the ``Energy`` parameters is formally possible | ||
| 873 | - it may lead to numerical complications. | ||
| 874 | - If ``Energy`` parameters are to be fitted make sure that the ``min`` | ||
| 875 | - and ``max`` attributes are set in a way that avoids inversion of the energy | ||
| 876 | - ordering. | ||
| 877 | - | ||
| 878 | - | ||
| 879 | -Composite model | ||
| 880 | -^^^^^^^^^^^^^^^ | ||
| 881 | - | ||
| 882 | - .. code-block:: xml | ||
| 883 | - | ||
| 884 | - <spectrum type="Composite"> | ||
| 885 | - <spectrum type="PowerLaw" component="SoftComponent"> | ||
| 886 | - <parameter name="Prefactor" scale="1e-17" value="3" min="1e-07" max="1000.0" free="1"/> | ||
| 887 | - <parameter name="Index" scale="-1" value="3.5" min="0.0" max="+5.0" free="1"/> | ||
| 888 | - <parameter name="PivotEnergy" scale="1e6" value="1" min="0.01" max="1000.0" free="0"/> | ||
| 889 | - </spectrum> | ||
| 890 | - <spectrum type="PowerLaw" component="HardComponent"> | ||
| 891 | - <parameter name="Prefactor" scale="1e-17" value="5" min="1e-07" max="1000.0" free="1"/> | ||
| 892 | - <parameter name="Index" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> | ||
| 893 | - <parameter name="PivotEnergy" scale="1e6" value="1" min="0.01" max="1000.0" free="0"/> | ||
| 894 | - </spectrum> | ||
| 895 | - </spectrum> | ||
| 896 | - | ||
| 897 | - This spectral model component implements a composite model that is the | ||
| 898 | - sum of an arbitrary number of spectral models, computed using | ||
| 899 | - | ||
| 900 | - .. math:: | ||
| 901 | - M_{\rm spectral}(E) = \sum_{i=0}^{N-1} M_{\rm spectral}^{(i)}(E) | ||
| 902 | - | ||
| 903 | - where :math:`M_{\rm spectral}^{(i)}(E)` is any spectral model component | ||
| 904 | - (including another composite model), and :math:`N` is the number of | ||
| 905 | - model components that are combined. | ||
| 906 | - | ||
| 907 | - | ||
| 908 | -Multiplicative model | ||
| 909 | -^^^^^^^^^^^^^^^^^^^^ | ||
| 910 | - | ||
| 911 | - .. code-block:: xml | ||
| 912 | - | ||
| 913 | - <spectrum type="Multiplicative"> | ||
| 914 | - <spectrum type="PowerLaw" component="PowerLawComponent"> | ||
| 915 | - <parameter name="Prefactor" scale="1e-17" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 916 | - <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 917 | - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 918 | - </spectrum> | ||
| 919 | - <spectrum type="ExponentialCutoffPowerLaw" component="CutoffComponent"> | ||
| 920 | - <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-07" max="1000.0" free="0"/> | ||
| 921 | - <parameter name="Index" scale="1.0" value="0.0" min="-2.0" max="+2.0" free="0"/> | ||
| 922 | - <parameter name="CutoffEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | ||
| 923 | - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 924 | - </spectrum> | ||
| 925 | - </spectrum> | ||
| 926 | - | ||
| 927 | - This spectral model component implements a composite model that is the | ||
| 928 | - product of an arbitrary number of spectral models, computed using | ||
| 929 | - | ||
| 930 | - .. math:: | ||
| 931 | - M_{\rm spectral}(E) = \prod_{i=0}^{N-1} M_{\rm spectral}^{(i)}(E) | ||
| 932 | - | ||
| 933 | - where :math:`M_{\rm spectral}^{(i)}(E)` is any spectral model component | ||
| 934 | - (including another composite model), and :math:`N` is the number of | ||
| 935 | - model components that are multiplied. | ||
| 936 | - | ||
| 937 | - | ||
| 938 | -.. _sec_temporal_models: | ||
| 939 | - | ||
| 940 | -Temporal model components | ||
| 941 | -~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 942 | - | ||
| 943 | -The following sections present the temporal model components that are available | ||
| 944 | -in ctools. | ||
| 945 | - | ||
| 946 | -Constant | ||
| 947 | -^^^^^^^^ | ||
| 948 | - | ||
| 949 | - .. code-block:: xml | ||
| 950 | - | ||
| 951 | - <temporal type="Constant"> | ||
| 952 | - <parameter name="Normalization" scale="1.0" value="1.0" min="0.1" max="10.0" free="0"/> | ||
| 953 | - </temporal> | ||
| 954 | - | ||
| 955 | - This temporal model component implements a constant source | ||
| 956 | - | ||
| 957 | - .. math:: | ||
| 958 | - | ||
| 959 | - M_{\rm temporal}(t) = N_0 | ||
| 960 | - | ||
| 961 | - where | ||
| 962 | - | ||
| 963 | - * :math:`N_0` = ``Normalization`` | ||
| 964 | - | ||
| 965 | - | ||
| 966 | -Light Curve | ||
| 967 | -^^^^^^^^^^^ | ||
| 968 | - | ||
| 969 | - .. code-block:: xml | ||
| 970 | - | ||
| 971 | - <temporal type="LightCurve" file="model_temporal_lightcurve.fits"> | ||
| 972 | - <parameter name="Normalization" scale="1" value="1.0" min="0.0" max="1000.0" free="0"/> | ||
| 973 | - </temporal> | ||
| 974 | - | ||
| 975 | - This temporal model component implements a light curve :math:`r(t)` | ||
| 976 | - | ||
| 977 | - .. math:: | ||
| 978 | - M_{\rm temporal}(t) = N_0 \times r(t) | ||
| 979 | - | ||
| 980 | - where | ||
| 981 | - | ||
| 982 | - * :math:`N_0` = ``Normalization`` | ||
| 983 | - | ||
| 984 | - The light curve is defined by nodes in a FITS file that specify the relative | ||
| 985 | - flux normalization as function of time (file ``model_temporal_lightcurve.fits`` | ||
| 986 | - in the example above). The structure of the light curve FITS | ||
| 987 | - file is shown in the figure below. The light curve is defined in the first | ||
| 988 | - extension of the FITS file and consists of a binary table with the columns | ||
| 989 | - ``TIME`` and ``NORM``. Times in the ``TIME`` columns are given in seconds | ||
| 990 | - and are counted with respect to a time reference that is defined in the | ||
| 991 | - header of the binary table. Times need to be specified in ascending order. | ||
| 992 | - The values in the ``NORM`` column specify :math:`r(t)` at times :math:`t`, | ||
| 993 | - and should be comprised between 0 and 1. | ||
| 994 | - | ||
| 995 | - .. _fig_model_lightcurve: | ||
| 996 | - | ||
| 997 | - .. figure:: model_lightcurve.png | ||
| 998 | - :align: center | ||
| 999 | - :width: 100% | ||
| 1000 | - | ||
| 1001 | - *Structure of light curve FITS file* | ||
| 1002 | - | ||
| 1003 | - .. warning:: | ||
| 1004 | - Fitting of light curves only makes sense for an unbinned maximum likelihood | ||
| 1005 | - analysis, since in a binned or stacked analysis the times of individual | ||
| 1006 | - events are dropped. | ||
| 1007 | - | ||
| 1008 | - | ||
| 1009 | -Phase Curve | ||
| 1010 | -^^^^^^^^^^^ | ||
| 1011 | - | ||
| 1012 | - .. code-block:: xml | ||
| 1013 | - | ||
| 1014 | - <temporal type="PhaseCurve" file="model_temporal_phasecurve.fits"> | ||
| 1015 | - <parameter name="Normalization" scale="1" value="1.0" min="0.0" max="1000.0" free="0"/> | ||
| 1016 | - <parameter name="MJD" scale="1" value="51544.5" min="0.0" max="100000.0" free="0"/> | ||
| 1017 | - <parameter name="Phase" scale="1" value="0.0" min="0.0" max="1.0" free="0"/> | ||
| 1018 | - <parameter name="F0" scale="1" value="1.0" min="0.0" max="1000.0" free="0"/> | ||
| 1019 | - <parameter name="F1" scale="1" value="0.1" min="0.0" max="1000.0" free="0"/> | ||
| 1020 | - <parameter name="F2" scale="1" value="0.01" min="0.0" max="1000.0" free="0"/> | ||
| 1021 | - </temporal> | ||
| 1022 | - | ||
| 1023 | - This temporal model component implements a phase curve :math:`r(\Phi(t))` | ||
| 1024 | - | ||
| 1025 | - .. math:: | ||
| 1026 | - M_{\rm temporal}(t) = N_0 \times r(\Phi(t)) | ||
| 1027 | - | ||
| 1028 | - where the phase as function of time is computed using | ||
| 1029 | - | ||
| 1030 | - .. math:: | ||
| 1031 | - \Phi(t) = \Phi_0 + f(t-t_0) + \frac{1}{2}\dot{f} (t-t_0)^2 + | ||
| 1032 | - \frac{1}{6}\ddot{f} (t-t_0)^3 | ||
| 1033 | - | ||
| 1034 | - and | ||
| 1035 | - | ||
| 1036 | - * :math:`N_0` = ``Normalization`` | ||
| 1037 | - * :math:`t_0` = ``MJD`` | ||
| 1038 | - * :math:`\Phi_0` = ``Phase`` | ||
| 1039 | - * :math:`f` = ``F0`` | ||
| 1040 | - * :math:`\dot{f}` = ``F1`` | ||
| 1041 | - * :math:`\ddot{f}` = ``F2`` | ||
| 1042 | - | ||
| 1043 | - The phase curve is defined by nodes in a FITS file that specify the relative | ||
| 1044 | - flux normalization as function of phase (file ``model_temporal_phasecurve.fits`` | ||
| 1045 | - in the example above). The structure of the phase curve | ||
| 1046 | - FITS file is shown in the figure below. The phase curve is defined in the | ||
| 1047 | - first extension of the FITS file and consists of a binary table with the | ||
| 1048 | - columns ``PHASE`` and ``NORM``. Phase values in the ``PHASE`` column need to | ||
| 1049 | - be comprised between 0 and 1 and need to be given in ascending order. The | ||
| 1050 | - values in the ``NORM`` column specify :math:`r(\Phi(t))` at phases | ||
| 1051 | - :math:`\Phi(t)`, and should be comprised between 0 and 1. | ||
| 1052 | - | ||
| 1053 | - .. _fig_model_phasecurve: | ||
| 1054 | - | ||
| 1055 | - .. figure:: model_phasecurve.png | ||
| 1056 | - :align: center | ||
| 1057 | - :width: 40% | ||
| 1058 | - | ||
| 1059 | - *Structure of phase curve FITS file* | ||
| 1060 | - | ||
| 1061 | - .. warning:: | ||
| 1062 | - Fitting of phase curves only makes sense for an unbinned maximum likelihood | ||
| 1063 | - analysis, since in a binned or stacked analysis the times of individual | ||
| 1064 | - events are dropped. | ||
| 1065 | - | ||
| 1066 | - .. warning:: | ||
| 1067 | - Fitting of phase curve parameters may not properly work for pulsar | ||
| 1068 | - frequencies. | 6 | +.. toctree:: |
| 7 | + :maxdepth: 1 | ||
| 8 | + | ||
| 9 | + models_concept | ||
| 10 | + models_implementation | ||
| 11 | + models_spatial_src | ||
| 12 | + models_spatial_bgd | ||
| 13 | + models_spectral | ||
| 14 | + models_temporal |
doc/source/users/user_manual/models_concept.rst
0 → 100644
| 1 | +.. _sec_models_concept: | ||
| 2 | + | ||
| 3 | +Overall concept | ||
| 4 | +------------------ | ||
| 5 | + | ||
| 6 | +A central element of any data analysis is the modeling of the observed | ||
| 7 | +event distribution. | ||
| 8 | +Generally, the measured events can be separated into two distinct classes: | ||
| 9 | +events being attributed to gamma rays of celestial origin (the "source" | ||
| 10 | +events) or events being attributed to any other kind of trigger (the | ||
| 11 | +"background" events). | ||
| 12 | +In the first case, the :ref:`Instrument Response Functions (IRFs) <sec_response>` | ||
| 13 | +describe how an incident gamma-ray converts into a measured event. | ||
| 14 | +In the second case there is often no general prescription, and the | ||
| 15 | +distribution of background events is commonly modeled directly in the data | ||
| 16 | +space of the observable quantities. | ||
| 17 | +The main difficulty of gamma-ray astronomy is that not all events can be | ||
| 18 | +tagged a priori as being source or background, hence their separation can | ||
| 19 | +only be done on a statistical basis, based on the different morphologies, | ||
| 20 | +spectral characteristics or eventually temporal signatures of both event | ||
| 21 | +categories. | ||
| 22 | + | ||
| 23 | +For this purpose, ctools use a general model that describes the spatial, | ||
| 24 | +spectral and temporal properties of the source and background components. | ||
| 25 | +The model is composed of an arbitrary number of model components that | ||
| 26 | +add up linearly to provide a prediction of the expected number of events. | ||
| 27 | +Model components are generally parametric, and model parameters can be | ||
| 28 | +adjusted through a maximum likelihood procedure to find the set of | ||
| 29 | +parameters that represent best the measured data. | ||
| 30 | +Model components representing celestial sources are convolved with the | ||
| 31 | +:ref:`IRFs <sec_response>` to predict the expected number of source events in | ||
| 32 | +the data. | ||
| 33 | +Background model components will be directly expressed as expected number | ||
| 34 | +of background events without any :ref:`IRF <sec_response>` convolution. |
doc/source/users/user_manual/models_implementation.rst
0 → 100644
| 1 | +.. _sec_models_implementation: | ||
| 2 | + | ||
| 3 | +Implementation | ||
| 4 | +-------------- | ||
| 5 | + | ||
| 6 | +The general model is describe in ctools using a model definition XML file. | ||
| 7 | +Below is a simple example of such a file comprising one source and one | ||
| 8 | +background model. | ||
| 9 | +Each model is factorised into | ||
| 10 | +a spectral (tag ``<spectrum>``), | ||
| 11 | +a spatial (tags ``<spatialModel>`` and ``<radialModel>``), and | ||
| 12 | +a temporal component (tag ``<temporal>``). | ||
| 13 | + | ||
| 14 | +.. math:: | ||
| 15 | + M(x,y,E,t) = M_{\rm spatial}(x,y|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) | ||
| 16 | + | ||
| 17 | +In this specific example, the source component ``Crab`` describes | ||
| 18 | +a point source at the location of the Crab nebula with a power law spectral | ||
| 19 | +shape that is constant in time. | ||
| 20 | +The background component ``Background`` is modelled using the template that is | ||
| 21 | +provided with the | ||
| 22 | +:ref:`Instrument Response Functions (IRFs) <sec_response>` | ||
| 23 | +and that is multiplied by a spectral power law function. | ||
| 24 | + | ||
| 25 | +.. code-block:: xml | ||
| 26 | + | ||
| 27 | + <?xml version="1.0" standalone="no"?> | ||
| 28 | + <source_library title="source library"> | ||
| 29 | + <source name="Crab" type="PointSource"> | ||
| 30 | + <spatialModel type="PointSource"> | ||
| 31 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 32 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 33 | + </spatialModel> | ||
| 34 | + <spectrum type="PowerLaw"> | ||
| 35 | + <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 36 | + <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 37 | + <parameter name="PivotEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/> | ||
| 38 | + </spectrum> | ||
| 39 | + <temporal type="Constant"> | ||
| 40 | + <parameter name="Normalization" scale="1.0" value="1.0" min="0.0" max="1000.0" free="0"/> | ||
| 41 | + </temporal> | ||
| 42 | + </source> | ||
| 43 | + <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA"> | ||
| 44 | + <spectrum type="PowerLaw"> | ||
| 45 | + <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-3" max="1e+3" free="1"/> | ||
| 46 | + <parameter name="Index" scale="1.0" value="0.0" min="-5.0" max="+5.0" free="1"/> | ||
| 47 | + <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 48 | + </spectrum> | ||
| 49 | + </source> | ||
| 50 | + </source_library> | ||
| 51 | + | ||
| 52 | +Model parameters are specified by a ``<parameter>`` tag with a certain | ||
| 53 | +number of attributes. | ||
| 54 | +The ``name`` attribute gives the (case-sensitive) parameter name that | ||
| 55 | +needs to be unique within a given model component. | ||
| 56 | +The ``scale`` attribute gives a scaling factor that will be multiplied by | ||
| 57 | +the ``value`` attribute to provide the real (physical) parameter value. | ||
| 58 | +The ``min`` and ``max`` attributes specify boundaries for the ``value`` | ||
| 59 | +term of the parameter. | ||
| 60 | +And the ``free`` attribute specifies whether a parameter should be fitted | ||
| 61 | +(``free="1"``) or kept fixed (``free="0"``) in a maximum likelihood | ||
| 62 | +analysis. | ||
| 63 | +After a maximum likelihood fit using :ref:`ctlike`, an | ||
| 64 | +``error`` attribute giving the statisical uncertainty of the ``value`` | ||
| 65 | +term will be appended to each ``<parameter>`` tag. | ||
| 66 | + | ||
| 67 | +.. note:: | ||
| 68 | + For compatibility reasons with the Fermi/LAT XML format the ``<temporal>`` | ||
| 69 | + tag can be omitted for models that are constant in time. | ||
| 70 | + | ||
| 71 | +.. note:: | ||
| 72 | + | ||
| 73 | + XML files are ASCII files and can be edited by hand using any text | ||
| 74 | + editor. | ||
| 75 | + The indentation of the XML elements is not mandatory. | ||
| 76 | + | ||
| 77 | +.. note:: | ||
| 78 | + | ||
| 79 | + The splitting of parameter values into a ``value`` and ``scale`` factor | ||
| 80 | + is mainly for numerical purposes. | ||
| 81 | + Parameter fitting algorithms can be ill-conditioned if several | ||
| 82 | + parameters of vastly different orders of magnitudes need to be | ||
| 83 | + optimised simultaneously. | ||
| 84 | + Splitting a value into two components allows to "prescale" the | ||
| 85 | + parameters so that the effective parameters to be optimised (the ``value`` terms) | ||
| 86 | + are all of about unity. | ||
| 87 | + | ||
| 88 | +.. note:: | ||
| 89 | + | ||
| 90 | + The syntax of the model definition XML file has been inspired from the | ||
| 91 | + syntax used by the Fermi/LAT ScienceTools, but for reasons of clarity and | ||
| 92 | + homogenity of the various model and parameter names we have made some | ||
| 93 | + modifications. | ||
| 94 | + Nevertheless, the format used by the Fermi/LAT ScienceTools is also | ||
| 95 | + supported. |
doc/source/users/user_manual/models_spatial_bgd.rst
0 → 100644
| 1 | +.. _sec_models_spatial_bgd: | ||
| 2 | + | ||
| 3 | +Spatial background model components | ||
| 4 | +----------------------------------- | ||
| 5 | + | ||
| 6 | +The following sections present the spatial model components that are available | ||
| 7 | +in ctools for instrumental background modelling for CTA. | ||
| 8 | + | ||
| 9 | +CTA radial background | ||
| 10 | +^^^^^^^^^^^^^^^^^^^^^ | ||
| 11 | + | ||
| 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. | ||
| 17 | + | ||
| 18 | + The first radial model is of type ``Gaussian`` | ||
| 19 | + | ||
| 20 | + .. code-block:: xml | ||
| 21 | + | ||
| 22 | + <source name="Background" type="RadialAcceptance" instrument="CTA"> | ||
| 23 | + <radialModel type="Gaussian"> | ||
| 24 | + <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"/> | ||
| 30 | + </spectrum> | ||
| 31 | + </source> | ||
| 32 | + | ||
| 33 | + and implements | ||
| 34 | + | ||
| 35 | + .. math:: | ||
| 36 | + M_{\rm spatial}(\theta) = \exp \left(-\frac{1}{2} | ||
| 37 | + \left( \frac{\theta^2}{\sigma} \right)^2 \right) | ||
| 38 | + | ||
| 39 | + where | ||
| 40 | + | ||
| 41 | + * :math:`\sigma` = ``Sigma`` (degrees) | ||
| 42 | + | ||
| 43 | + The second radial model is of type ``Profile`` | ||
| 44 | + | ||
| 45 | + .. code-block:: xml | ||
| 46 | + | ||
| 47 | + <source name="Background" type="RadialAcceptance" instrument="CTA"> | ||
| 48 | + <radialModel type="Profile"> | ||
| 49 | + <parameter name="Width" scale="1.0" value="1.5" min="0.1" max="1000.0" free="1"/> | ||
| 50 | + <parameter name="Core" scale="1.0" value="3.0" min="0.1" max="1000.0" free="1"/> | ||
| 51 | + <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> | ||
| 58 | + </source> | ||
| 59 | + | ||
| 60 | + and implements | ||
| 61 | + | ||
| 62 | + .. math:: | ||
| 63 | + M_{\rm spatial}(\theta) = (1 + (\theta/c_0)^{c_1})^{-c_2/c_1} | ||
| 64 | + | ||
| 65 | + where | ||
| 66 | + | ||
| 67 | + * :math:`c_0` = ``Width`` (degrees) | ||
| 68 | + * :math:`c_1` = ``Core`` | ||
| 69 | + * :math:`c_2` = ``Tail`` | ||
| 70 | + | ||
| 71 | + The third radial model is of type ``Polynom`` | ||
| 72 | + | ||
| 73 | + .. code-block:: xml | ||
| 74 | + | ||
| 75 | + <source name="Background" type="RadialAcceptance" instrument="CTA"> | ||
| 76 | + <radialModel type="Polynom"> | ||
| 77 | + <parameter name="Coeff0" scale="1.0" value="+1.00000" min="-10.0" max="10.0" free="0"/> | ||
| 78 | + <parameter name="Coeff1" scale="1.0" value="-0.1239176" min="-10.0" max="10.0" free="1"/> | ||
| 79 | + <parameter name="Coeff2" scale="1.0" value="+0.9751791" min="-10.0" max="10.0" free="1"/> | ||
| 80 | + <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"/> | ||
| 91 | + </spectrum> | ||
| 92 | + </source> | ||
| 93 | + | ||
| 94 | + and implements | ||
| 95 | + | ||
| 96 | + .. math:: | ||
| 97 | + M_{\rm spatial}(\theta) = \sum_{i=0}^m c_i \theta^i | ||
| 98 | + | ||
| 99 | + where | ||
| 100 | + | ||
| 101 | + * :math:`c_0` = ``Coeff0`` | ||
| 102 | + * :math:`c_1` = ``Coeff1`` | ||
| 103 | + * ... | ||
| 104 | + | ||
| 105 | + (the number of polynomial coefficients is arbitrary). | ||
| 106 | + | ||
| 107 | + | ||
| 108 | +CTA IRF background | ||
| 109 | +^^^^^^^^^^^^^^^^^^ | ||
| 110 | + | ||
| 111 | + The :ref:`Instrument Response Functions (IRFs) <sec_response>` contain a template | ||
| 112 | + that predicts the background rate as function of position in the field of view | ||
| 113 | + and measured energy in units of | ||
| 114 | + :math:`{\rm events} \, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. This template | ||
| 115 | + can be used by specifying a model of type ``CTAIrfBackground``. No spatial component | ||
| 116 | + will be specified explicitly since the spatial (and spectral) information is | ||
| 117 | + 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 | + | ||
| 122 | + .. code-block:: xml | ||
| 123 | + | ||
| 124 | + <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"/> | ||
| 129 | + </spectrum> | ||
| 130 | + </source> | ||
| 131 | + | ||
| 132 | + If the observation is an On/Off observation, do not forget to switch the instrument | ||
| 133 | + to ``CTAOnOff``: | ||
| 134 | + | ||
| 135 | + .. code-block:: xml | ||
| 136 | + | ||
| 137 | + <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"/> | ||
| 142 | + </spectrum> | ||
| 143 | + </source> | ||
| 144 | + | ||
| 145 | + | ||
| 146 | +CTA effective area background | ||
| 147 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| 148 | + | ||
| 149 | + Instead of using the background template the effective area for gamma rays can | ||
| 150 | + 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: | ||
| 153 | + | ||
| 154 | + .. code-block:: xml | ||
| 155 | + | ||
| 156 | + <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"/> | ||
| 161 | + </spectrum> | ||
| 162 | + </source> | ||
| 163 | + | ||
| 164 | + | ||
| 165 | +CTA cube background | ||
| 166 | +^^^^^^^^^^^^^^^^^^^ | ||
| 167 | + | ||
| 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. | ||
| 172 | + | ||
| 173 | + .. code-block:: xml | ||
| 174 | + | ||
| 175 | + <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"/> | ||
| 180 | + </spectrum> | ||
| 181 | + </source> |
doc/source/users/user_manual/models_spatial_src.rst
0 → 100644
| 1 | +.. _sec_models_spatial_src: | ||
| 2 | + | ||
| 3 | +Spatial source model components | ||
| 4 | +------------------------------- | ||
| 5 | + | ||
| 6 | +The following sections present the spatial model components that are available | ||
| 7 | +in ctools for gamma-ray sources. | ||
| 8 | + | ||
| 9 | +.. note:: | ||
| 10 | + Except of the ``DiffuseMapCube`` model, all spatial models are normalized | ||
| 11 | + so that when integrated over the sphere the result is unity. For clarify, | ||
| 12 | + the spatial normalisation is omitted in the formulae below. | ||
| 13 | + | ||
| 14 | +Point source | ||
| 15 | +^^^^^^^^^^^^ | ||
| 16 | + | ||
| 17 | + The ``PointSource`` model describes a point source | ||
| 18 | + | ||
| 19 | + .. code-block:: xml | ||
| 20 | + | ||
| 21 | + <source name="Crab" type="PointSource"> | ||
| 22 | + <spatialModel type="PointSource"> | ||
| 23 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 24 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 25 | + </spatialModel> | ||
| 26 | + <spectrum type="..."> | ||
| 27 | + ... | ||
| 28 | + </spectrum> | ||
| 29 | + </source> | ||
| 30 | + | ||
| 31 | + where | ||
| 32 | + | ||
| 33 | + * ``RA`` is the Right Ascension (degrees) | ||
| 34 | + * ``DEC`` is the Declination (degrees) | ||
| 35 | + | ||
| 36 | + The ``RA`` and ``DEC`` parameters can be remplaced by ``GLON`` and ``GLAT`` | ||
| 37 | + for Galactic coordinates | ||
| 38 | + | ||
| 39 | + .. code-block:: xml | ||
| 40 | + | ||
| 41 | + <source name="Crab" type="PointSource"> | ||
| 42 | + <spatialModel type="PointSource"> | ||
| 43 | + <parameter name="GLON" scale="1.0" value="184.5575" min="-360" max="360" free="1"/> | ||
| 44 | + <parameter name="GLAT" scale="1.0" value="-5.7844" min="-90" max="90" free="1"/> | ||
| 45 | + </spatialModel> | ||
| 46 | + <spectrum type="..."> | ||
| 47 | + ... | ||
| 48 | + </spectrum> | ||
| 49 | + </source> | ||
| 50 | + | ||
| 51 | + where | ||
| 52 | + | ||
| 53 | + * ``GLON`` is the Galactic longitude (degrees) | ||
| 54 | + * ``GLAT`` is the Galactic latitude (degrees) | ||
| 55 | + | ||
| 56 | + .. note:: | ||
| 57 | + For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 58 | + ``PointSource`` can be replaced by ``SkyDirFunction``. | ||
| 59 | + | ||
| 60 | + | ||
| 61 | +Radial source | ||
| 62 | +^^^^^^^^^^^^^ | ||
| 63 | + | ||
| 64 | + The ``RadialDisk`` model describes a uniform intensity distribution within | ||
| 65 | + a given radius | ||
| 66 | + | ||
| 67 | + .. code-block:: xml | ||
| 68 | + | ||
| 69 | + <source name="Crab" type="ExtendedSource"> | ||
| 70 | + <spatialModel type="RadialDisk"> | ||
| 71 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 72 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 73 | + <parameter name="Radius" scale="1.0" value="0.20" min="0.01" max="10" free="1"/> | ||
| 74 | + </spatialModel> | ||
| 75 | + <spectrum type="..."> | ||
| 76 | + ... | ||
| 77 | + </spectrum> | ||
| 78 | + </source> | ||
| 79 | + | ||
| 80 | + where | ||
| 81 | + | ||
| 82 | + * ``RA`` is the Right Ascension (degrees) | ||
| 83 | + * ``DEC`` is the Declination (degrees) | ||
| 84 | + * ``Radius`` is the disk radius (degrees) | ||
| 85 | + | ||
| 86 | + The ``RadialGaussian`` model describes a Gaussian intensity distribution | ||
| 87 | + | ||
| 88 | + .. code-block:: xml | ||
| 89 | + | ||
| 90 | + <source name="Crab" type="ExtendedSource"> | ||
| 91 | + <spatialModel type="RadialGaussian"> | ||
| 92 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 93 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 94 | + <parameter name="Sigma" scale="1.0" value="0.20" min="0.01" max="10" free="1"/> | ||
| 95 | + </spatialModel> | ||
| 96 | + <spectrum type="..."> | ||
| 97 | + ... | ||
| 98 | + </spectrum> | ||
| 99 | + </source> | ||
| 100 | + | ||
| 101 | + and implements | ||
| 102 | + | ||
| 103 | + .. math:: | ||
| 104 | + M_{\rm spatial}(\theta) = \frac{1}{2 \pi \sigma^2} \exp | ||
| 105 | + \left(-\frac{1}{2}\frac{\theta^2}{\sigma^2} \right), | ||
| 106 | + | ||
| 107 | + where | ||
| 108 | + | ||
| 109 | + * ``RA`` is the Right Ascension (degrees) | ||
| 110 | + * ``DEC`` is the Declination (degrees) | ||
| 111 | + * :math:`\sigma` == ``Sigma`` (degrees) | ||
| 112 | + | ||
| 113 | + The ``RadialShell`` model describes a spherical shell projected on the sky | ||
| 114 | + | ||
| 115 | + .. code-block:: xml | ||
| 116 | + | ||
| 117 | + <source name="Crab" type="ExtendedSource"> | ||
| 118 | + <spatialModel type="RadialShell"> | ||
| 119 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 120 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 121 | + <parameter name="Radius" scale="1.0" value="0.30" min="0.01" max="10" free="1"/> | ||
| 122 | + <parameter name="Width" scale="1.0" value="0.10" min="0.01" max="10" free="1"/> | ||
| 123 | + </spatialModel> | ||
| 124 | + <spectrum type="..."> | ||
| 125 | + ... | ||
| 126 | + </spectrum> | ||
| 127 | + </source> | ||
| 128 | + | ||
| 129 | + and implements | ||
| 130 | + | ||
| 131 | + .. math:: | ||
| 132 | + M_{\rm spatial}(\theta) = n_0 \left \{ | ||
| 133 | + \begin{array}{l l} | ||
| 134 | + \displaystyle | ||
| 135 | + \sqrt{ \theta_{\rm out}^2 - \theta^2 } - \sqrt{ \theta_{\rm in}^2 - \theta^2 } | ||
| 136 | + & \mbox{if $\theta \le \theta_{\rm in}$} \\ | ||
| 137 | + \\ | ||
| 138 | + \displaystyle | ||
| 139 | + \sqrt{ \theta_{\rm out}^2 - \theta^2 } | ||
| 140 | + & \mbox{if $\theta_{\rm in} < \theta \le \theta_{\rm out}$} \\ | ||
| 141 | + \\ | ||
| 142 | + \displaystyle | ||
| 143 | + 0 & \mbox{if $\theta > \theta_{\rm out}$} | ||
| 144 | + \end{array} | ||
| 145 | + \right . | ||
| 146 | + | ||
| 147 | + where | ||
| 148 | + | ||
| 149 | + * ``RA`` is the Right Ascension (degrees) | ||
| 150 | + * ``DEC`` is the Declination (degrees) | ||
| 151 | + * :math:`\theta_{\rm out}` = ``Radius`` + ``Width`` (degrees) | ||
| 152 | + * :math:`\theta_{\rm in}` = ``Radius`` (degrees) | ||
| 153 | + | ||
| 154 | + .. note:: | ||
| 155 | + For all radial source models the ``RA`` and ``DEC`` parameters can be | ||
| 156 | + remplaced by ``GLON`` and ``GLAT`` for Galactic coordinates. | ||
| 157 | + | ||
| 158 | + | ||
| 159 | +Elliptical source | ||
| 160 | +^^^^^^^^^^^^^^^^^ | ||
| 161 | + | ||
| 162 | + The ``EllipticalDisk`` model describes a uniform intensity distribution within | ||
| 163 | + an elliptical circumference: | ||
| 164 | + | ||
| 165 | + .. code-block:: xml | ||
| 166 | + | ||
| 167 | + <source name="Crab" type="ExtendedSource"> | ||
| 168 | + <spatialModel type="EllipticalDisk"> | ||
| 169 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 170 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 171 | + <parameter name="PA" scale="1.0" value="45.0" min="-360" max="360" free="1"/> | ||
| 172 | + <parameter name="MinorRadius" scale="1.0" value="0.5" min="0.001" max="10" free="1"/> | ||
| 173 | + <parameter name="MajorRadius" scale="1.0" value="2.0" min="0.001" max="10" free="1"/> | ||
| 174 | + </spatialModel> | ||
| 175 | + <spectrum type="..."> | ||
| 176 | + ... | ||
| 177 | + </spectrum> | ||
| 178 | + </source> | ||
| 179 | + | ||
| 180 | + where | ||
| 181 | + | ||
| 182 | + * ``RA`` is the Right Ascension (degrees) | ||
| 183 | + * ``DEC`` is the Declination (degrees) | ||
| 184 | + * ``PA`` is the position angle, counted counterclockwise from North (degrees) | ||
| 185 | + * ``MinorRadius`` is the minor radius of the ellipse (degrees) | ||
| 186 | + * ``MajorRadius`` is the major radius of the ellipse (degrees) | ||
| 187 | + | ||
| 188 | + The ``EllipticalGaussian`` model describes a Gaussian intensity distribution | ||
| 189 | + | ||
| 190 | + .. code-block:: xml | ||
| 191 | + | ||
| 192 | + <source name="Crab" type="ExtendedSource"> | ||
| 193 | + <spatialModel type="EllipticalGaussian"> | ||
| 194 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 195 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 196 | + <parameter name="PA" scale="1.0" value="45.0" min="-360" max="360" free="1"/> | ||
| 197 | + <parameter name="MinorRadius" scale="1.0" value="0.5" min="0.001" max="10" free="1"/> | ||
| 198 | + <parameter name="MajorRadius" scale="1.0" value="2.0" min="0.001" max="10" free="1"/> | ||
| 199 | + </spatialModel> | ||
| 200 | + <spectrum type="..."> | ||
| 201 | + ... | ||
| 202 | + </spectrum> | ||
| 203 | + </source> | ||
| 204 | + | ||
| 205 | + and implements | ||
| 206 | + | ||
| 207 | + .. math:: | ||
| 208 | + M_{\rm spatial}(\theta, \phi) = \exp \left( -\frac{\theta^2}{2 r_\mathrm{eff}^2} \right), | ||
| 209 | + | ||
| 210 | + with | ||
| 211 | + | ||
| 212 | + .. math:: | ||
| 213 | + r_\mathrm{eff} = \frac{ab} {\sqrt{\left( a \sin (\phi - \phi_0) \right)^2 + | ||
| 214 | + \sqrt{\left( b \cos (\phi - \phi_0) \right)^2}}} | ||
| 215 | + | ||
| 216 | + where | ||
| 217 | + | ||
| 218 | + * ``RA`` is the Right Ascension (degrees) | ||
| 219 | + * ``DEC`` is the Declination (degrees) | ||
| 220 | + * ``PA`` is the position angle, counted counterclockwise from North (degrees) | ||
| 221 | + * :math:`a` = ``MinorRadius`` (degrees) | ||
| 222 | + * :math:`b` = ``MajorRadius`` (degrees) | ||
| 223 | + * :math:`\phi_0` is the position angle of the ellipse, counted counterclockwise | ||
| 224 | + from North | ||
| 225 | + * :math:`\phi` is the azimuth angle with respect to North. | ||
| 226 | + | ||
| 227 | + .. note:: | ||
| 228 | + For all elliptical source models the ``RA`` and ``DEC`` parameters can be | ||
| 229 | + remplaced by ``GLON`` and ``GLAT`` for Galactic coordinates. | ||
| 230 | + | ||
| 231 | + | ||
| 232 | +Diffuse source | ||
| 233 | +^^^^^^^^^^^^^^ | ||
| 234 | + | ||
| 235 | + The ``DiffuseIsotropic`` model describes an isotropic intensity distribution | ||
| 236 | + | ||
| 237 | + .. code-block:: xml | ||
| 238 | + | ||
| 239 | + <source name="Crab" type="DiffuseSource"> | ||
| 240 | + <spatialModel type="DiffuseIsotropic"> | ||
| 241 | + <parameter name="Value" scale="1" value="1" min="1" max="1" free="0"/> | ||
| 242 | + </spatialModel> | ||
| 243 | + <spectrum type="..."> | ||
| 244 | + ... | ||
| 245 | + </spectrum> | ||
| 246 | + </source> | ||
| 247 | + | ||
| 248 | + where | ||
| 249 | + | ||
| 250 | + * ``Value`` is isotropic intensity | ||
| 251 | + | ||
| 252 | + .. note:: | ||
| 253 | + For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 254 | + ``DiffuseIsotropic`` can be replaced by ``ConstantValue``. | ||
| 255 | + | ||
| 256 | + The ``DiffuseMap`` model describes an arbitrary intensity distribution in | ||
| 257 | + form of a sky map | ||
| 258 | + | ||
| 259 | + .. code-block:: xml | ||
| 260 | + | ||
| 261 | + <source name="Crab" type="DiffuseSource"> | ||
| 262 | + <spatialModel type="DiffuseMap" file="map.fits"> | ||
| 263 | + <parameter name="Normalization" scale="1" value="1" min="0.001" max="1000.0" free="0"/> | ||
| 264 | + </spatialModel> | ||
| 265 | + <spectrum type="..."> | ||
| 266 | + ... | ||
| 267 | + </spectrum> | ||
| 268 | + </source> | ||
| 269 | + | ||
| 270 | + where | ||
| 271 | + | ||
| 272 | + * ``Normalization`` is a normalization value | ||
| 273 | + | ||
| 274 | + and the ``file`` attribute specifies a sky map FITS file name. If a file name | ||
| 275 | + without path is specified it is assumed that the FITS file resides in the same | ||
| 276 | + directory as the model definition XML file. | ||
| 277 | + | ||
| 278 | + .. note:: | ||
| 279 | + For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 280 | + ``DiffuseMap`` can be replaced by ``SpatialMap`` and the parameter | ||
| 281 | + ``Normalization`` can be replaced by ``Prefactor``. | ||
| 282 | + | ||
| 283 | + .. note:: | ||
| 284 | + You may add the ``normalize="0"``to the spatial model tag to avoid the | ||
| 285 | + normalization of the diffuse map to an integral of unity | ||
| 286 | + | ||
| 287 | + .. code-block:: xml | ||
| 288 | + | ||
| 289 | + <source name="Crab" type="DiffuseSource"> | ||
| 290 | + <spatialModel type="DiffuseMap" file="map.fits" normalize="0"> | ||
| 291 | + <parameter name="Normalization" scale="1" value="1" min="0.001" max="1000.0" free="0"/> | ||
| 292 | + </spatialModel> | ||
| 293 | + <spectrum type="..."> | ||
| 294 | + ... | ||
| 295 | + </spectrum> | ||
| 296 | + </source> | ||
| 297 | + | ||
| 298 | + The ``DiffuseMapCube`` model describes an arbitrary energy-dependent intensity | ||
| 299 | + distribution in form of a map cube | ||
| 300 | + | ||
| 301 | + .. code-block:: xml | ||
| 302 | + | ||
| 303 | + <source name="Crab" type="DiffuseSource"> | ||
| 304 | + <spatialModel type="DiffuseMapCube" file="map_cube.fits"> | ||
| 305 | + <parameter name="Normalization" scale="1" value="1" min="0.001" max="1000.0" free="0"/> | ||
| 306 | + </spatialModel> | ||
| 307 | + <spectrum type="..."> | ||
| 308 | + ... | ||
| 309 | + </spectrum> | ||
| 310 | + </source> | ||
| 311 | + | ||
| 312 | + where | ||
| 313 | + | ||
| 314 | + * ``Normalization`` is a normalization value | ||
| 315 | + | ||
| 316 | + .. note:: | ||
| 317 | + For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 318 | + ``DiffuseMapCube`` can be replaced by ``MapCubeFunction`` and the parameter | ||
| 319 | + ``Normalization`` can be replaced by ``Value``. | ||
| 320 | + | ||
| 321 | + | ||
| 322 | +Composite model | ||
| 323 | +^^^^^^^^^^^^^^^ | ||
| 324 | + | ||
| 325 | + The ``Composite`` model implements a composite model that is the sum of an | ||
| 326 | + arbitrary number of spatial models | ||
| 327 | + | ||
| 328 | + .. code-block:: xml | ||
| 329 | + | ||
| 330 | + <source name="Crab" type="CompositeSource"> | ||
| 331 | + <spatialModel type="Composite"> | ||
| 332 | + <spatialModel type="PointSource" component="PointSource"> | ||
| 333 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 334 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 335 | + </spatialModel> | ||
| 336 | + <spatialModel type="RadialGaussian"> | ||
| 337 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | ||
| 338 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | ||
| 339 | + <parameter name="Sigma" scale="1.0" value="0.20" min="0.01" max="10" free="1"/> | ||
| 340 | + </spatialModel> | ||
| 341 | + </spatialModel> | ||
| 342 | + <spectrum type="..."> | ||
| 343 | + ... | ||
| 344 | + </spectrum> | ||
| 345 | + </source> | ||
| 346 | + | ||
| 347 | + which implements | ||
| 348 | + | ||
| 349 | + .. math:: | ||
| 350 | + M_{\rm spatial}(x,y|E) = \frac{1}{N} \sum_{i=0}^{N-1} M_{\rm spatial}^{(i)}(x,y|E) | ||
| 351 | + | ||
| 352 | + where :math:`M_{\rm spatial}^{(i)}(x,y|E)` is any spatial model component | ||
| 353 | + (including another composite model), and :math:`N` is the number of | ||
| 354 | + model components that are combined. |
doc/source/users/user_manual/models_spectral.rst
0 → 100644
| 1 | +.. _sec_models_spectral: | ||
| 2 | + | ||
| 3 | +Spectral model components | ||
| 4 | +------------------------- | ||
| 5 | + | ||
| 6 | +The following sections present the spectral model components that are available | ||
| 7 | +in ctools. | ||
| 8 | + | ||
| 9 | +.. warning:: | ||
| 10 | + | ||
| 11 | + Source intensities are generally given in units of | ||
| 12 | + :math:`{\rm photons}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1}`. | ||
| 13 | + | ||
| 14 | + **An exception to this rule exists for the** ``DiffuseMapCube`` **spatial | ||
| 15 | + model where intensities are unitless** and the spectral model presents a | ||
| 16 | + relative scaling of the diffuse model cube values. | ||
| 17 | + | ||
| 18 | + If spectral models are used in combination with ``RadialAcceptance`` CTA | ||
| 19 | + background models, intensity units are given in | ||
| 20 | + :math:`{\rm events}\,\,{\rm s}^{-1}\,{\rm MeV}^{-1}\,{\rm sr}^{-1}` | ||
| 21 | + and correspond to the on-axis count rate. | ||
| 22 | + | ||
| 23 | + For other CTA background models intensities are unitless and the spectral | ||
| 24 | + model presents a relative scaling of the background model values. | ||
| 25 | + | ||
| 26 | + | ||
| 27 | +Constant | ||
| 28 | +^^^^^^^^ | ||
| 29 | + | ||
| 30 | + .. code-block:: xml | ||
| 31 | + | ||
| 32 | + <spectrum type="Constant"> | ||
| 33 | + <parameter name="Normalization" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 34 | + </spectrum> | ||
| 35 | + | ||
| 36 | + This spectral model component implements the constant function | ||
| 37 | + | ||
| 38 | + .. math:: | ||
| 39 | + M_{\rm spectral}(E) = N_0 | ||
| 40 | + | ||
| 41 | + where | ||
| 42 | + | ||
| 43 | + * :math:`N_0` = ``Normalization`` | ||
| 44 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 45 | + | ||
| 46 | + .. note:: | ||
| 47 | + For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 48 | + ``Constant`` can be replaced by ``ConstantValue`` and the parameter | ||
| 49 | + ``Normalization`` by ``Value``. | ||
| 50 | + | ||
| 51 | + | ||
| 52 | +Power law | ||
| 53 | +^^^^^^^^^ | ||
| 54 | + | ||
| 55 | + .. code-block:: xml | ||
| 56 | + | ||
| 57 | + <spectrum type="PowerLaw"> | ||
| 58 | + <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 59 | + <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 60 | + <parameter name="PivotEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/> | ||
| 61 | + </spectrum> | ||
| 62 | + | ||
| 63 | + This spectral model component implements the power law function | ||
| 64 | + | ||
| 65 | + .. math:: | ||
| 66 | + M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma} | ||
| 67 | + | ||
| 68 | + where | ||
| 69 | + | ||
| 70 | + * :math:`k_0` = ``Prefactor`` | ||
| 71 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 72 | + * :math:`\gamma` = ``Index`` | ||
| 73 | + * :math:`E_0` = ``PivotEnergy`` | ||
| 74 | + :math:`({\rm MeV})` | ||
| 75 | + | ||
| 76 | + .. warning:: | ||
| 77 | + The ``PivotEnergy`` parameter is not intended to be fitted. | ||
| 78 | + | ||
| 79 | + .. note:: | ||
| 80 | + For compatibility with the Fermi/LAT ScienceTools the parameter | ||
| 81 | + ``PivotEnergy`` can be replaced by ``Scale``. | ||
| 82 | + | ||
| 83 | + An alternative power law function that uses the integral photon flux as | ||
| 84 | + parameter rather than the Prefactor is specified by | ||
| 85 | + | ||
| 86 | + .. code-block:: xml | ||
| 87 | + | ||
| 88 | + <spectrum type="PowerLaw"> | ||
| 89 | + <parameter scale="1e-07" name="PhotonFlux" min="1e-07" max="1000.0" value="1.0" free="1"/> | ||
| 90 | + <parameter scale="1.0" name="Index" min="-5.0" max="+5.0" value="-2.0" free="1"/> | ||
| 91 | + <parameter scale="1.0" name="LowerLimit" min="10.0" max="1000000.0" value="100.0" free="0"/> | ||
| 92 | + <parameter scale="1.0" name="UpperLimit" min="10.0" max="1000000.0" value="500000.0" free="0"/> | ||
| 93 | + </spectrum> | ||
| 94 | + | ||
| 95 | + This spectral model component implements the power law function | ||
| 96 | + | ||
| 97 | + .. math:: | ||
| 98 | + M_{\rm spectral}(E) = \frac{N(\gamma+1)E^{\gamma}} | ||
| 99 | + {E_{\rm max}^{\gamma+1} - E_{\rm min}^{\gamma+1}} | ||
| 100 | + | ||
| 101 | + where | ||
| 102 | + | ||
| 103 | + * :math:`N` = ``PhotonFlux`` | ||
| 104 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1})` | ||
| 105 | + * :math:`\gamma` = ``Index`` | ||
| 106 | + * :math:`E_{\rm min}` = ``LowerLimit`` | ||
| 107 | + :math:`({\rm MeV})` | ||
| 108 | + * :math:`E_{\rm max}` = ``UpperLimit`` | ||
| 109 | + :math:`({\rm MeV})` | ||
| 110 | + | ||
| 111 | + .. warning:: | ||
| 112 | + The ``LowerLimit`` and ``UpperLimit`` parameters are always treated as fixed | ||
| 113 | + and the flux given by the ``PhotonFlux`` parameter is computed over the | ||
| 114 | + range set by these two parameters. | ||
| 115 | + Use of this model allows the errors on the integral flux to be evaluated directly | ||
| 116 | + by :ref:`ctlike`. | ||
| 117 | + | ||
| 118 | + .. note:: | ||
| 119 | + For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 120 | + ``PowerLaw`` can be replaced by ``PowerLaw2`` and the parameter | ||
| 121 | + ``PhotonFlux`` by ``Integral``. | ||
| 122 | + | ||
| 123 | + | ||
| 124 | +Exponentially cut-off power law | ||
| 125 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| 126 | + | ||
| 127 | + .. code-block:: xml | ||
| 128 | + | ||
| 129 | + <spectrum type="ExponentialCutoffPowerLaw"> | ||
| 130 | + <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 131 | + <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 132 | + <parameter name="CutoffEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | ||
| 133 | + <parameter name="PivotEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/> | ||
| 134 | + </spectrum> | ||
| 135 | + | ||
| 136 | + This spectral model component implements the exponentially cut-off power law | ||
| 137 | + function | ||
| 138 | + | ||
| 139 | + .. math:: | ||
| 140 | + M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma} | ||
| 141 | + \exp \left( \frac{-E}{E_{\rm cut}} \right) | ||
| 142 | + | ||
| 143 | + where | ||
| 144 | + | ||
| 145 | + * :math:`k_0` = ``Prefactor`` | ||
| 146 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 147 | + * :math:`\gamma` = ``Index`` | ||
| 148 | + * :math:`E_0` = ``PivotEnergy`` | ||
| 149 | + :math:`({\rm MeV})` | ||
| 150 | + * :math:`E_{\rm cut}` = ``CutoffEnergy`` | ||
| 151 | + :math:`({\rm MeV})` | ||
| 152 | + | ||
| 153 | + .. warning:: | ||
| 154 | + The ``PivotEnergy`` parameter is not intended to be fitted. | ||
| 155 | + | ||
| 156 | + .. note:: | ||
| 157 | + For compatibility with the Fermi/LAT ScienceTools the model type | ||
| 158 | + ``ExponentialCutoffPowerLaw`` can be replaced by ``ExpCutoff`` and | ||
| 159 | + the parameters ``CutoffEnergy`` by ``Cutoff`` and ``PivotEnergy`` | ||
| 160 | + by ``Scale``. | ||
| 161 | + | ||
| 162 | + | ||
| 163 | +Super exponentially cut-off power law | ||
| 164 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| 165 | + | ||
| 166 | + .. code-block:: xml | ||
| 167 | + | ||
| 168 | + <spectrum type="SuperExponentialCutoffPowerLaw"> | ||
| 169 | + <parameter name="Prefactor" scale="1e-16" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 170 | + <parameter name="Index1" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> | ||
| 171 | + <parameter name="CutoffEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | ||
| 172 | + <parameter name="Index2" scale="1.0" value="1.5" min="0.1" max="5.0" free="1"/> | ||
| 173 | + <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 174 | + </spectrum> | ||
| 175 | + | ||
| 176 | + This spectral model component implements the super exponentially cut-off power | ||
| 177 | + law function | ||
| 178 | + | ||
| 179 | + .. math:: | ||
| 180 | + M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma} | ||
| 181 | + \exp \left( | ||
| 182 | + -\left( \frac{E}{E_{\rm cut}} \right)^{\alpha} | ||
| 183 | + \right) | ||
| 184 | + | ||
| 185 | + where | ||
| 186 | + | ||
| 187 | + * :math:`k_0` = ``Prefactor`` | ||
| 188 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 189 | + * :math:`\gamma` = ``Index1`` | ||
| 190 | + * :math:`\alpha` = ``Index2`` | ||
| 191 | + * :math:`E_0` = ``PivotEnergy`` | ||
| 192 | + :math:`({\rm MeV})` | ||
| 193 | + * :math:`E_{\rm cut}` = ``CutoffEnergy`` | ||
| 194 | + :math:`({\rm MeV})` | ||
| 195 | + | ||
| 196 | + .. warning:: | ||
| 197 | + The ``PivotEnergy`` parameter is not intended to be fitted. | ||
| 198 | + | ||
| 199 | + An alternative XML format is supported for compatibility with the Fermi/LAT | ||
| 200 | + XML format: | ||
| 201 | + | ||
| 202 | + .. code-block:: xml | ||
| 203 | + | ||
| 204 | + <spectrum type="PLSuperExpCutoff"> | ||
| 205 | + <parameter name="Prefactor" scale="1e-16" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 206 | + <parameter name="Index1" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> | ||
| 207 | + <parameter name="Cutoff" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | ||
| 208 | + <parameter name="Index2" scale="1.0" value="1.5" min="0.1" max="5.0" free="1"/> | ||
| 209 | + <parameter name="Scale" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 210 | + </spectrum> | ||
| 211 | + | ||
| 212 | + | ||
| 213 | +Broken power law | ||
| 214 | +^^^^^^^^^^^^^^^^ | ||
| 215 | + | ||
| 216 | + .. code-block:: xml | ||
| 217 | + | ||
| 218 | + <spectrum type="BrokenPowerLaw"> | ||
| 219 | + <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 220 | + <parameter name="Index1" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 221 | + <parameter name="BreakEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="1"/> | ||
| 222 | + <parameter name="Index2" scale="-1" value="2.70" min="0.01" max="1000.0" free="1"/> | ||
| 223 | + </spectrum> | ||
| 224 | + | ||
| 225 | + This spectral model component implements the broken power law function | ||
| 226 | + | ||
| 227 | + .. math:: | ||
| 228 | + M_{\rm spectral}(E) = k_0 \times \left \{ | ||
| 229 | + \begin{eqnarray} | ||
| 230 | + \left( \frac{E}{E_b} \right)^{\gamma_1} & {\rm if\,\,} E < E_b \\ | ||
| 231 | + \left( \frac{E}{E_b} \right)^{\gamma_2} & {\rm otherwise} | ||
| 232 | + \end{eqnarray} | ||
| 233 | + \right . | ||
| 234 | + | ||
| 235 | + where | ||
| 236 | + | ||
| 237 | + * :math:`k_0` = ``Prefactor`` | ||
| 238 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 239 | + * :math:`\gamma_1` = ``Index1`` | ||
| 240 | + * :math:`\gamma_2` = ``Index2`` | ||
| 241 | + * :math:`E_b` = ``BreakEnergy`` | ||
| 242 | + :math:`({\rm MeV})` | ||
| 243 | + | ||
| 244 | + .. warning:: | ||
| 245 | + Note that the ``BreakEnergy`` parameter may be poorly constrained if | ||
| 246 | + there is no clear spectral cut-off in the spectrum. | ||
| 247 | + This model may lead to complications in the maximum likelihood fitting. | ||
| 248 | + | ||
| 249 | + .. note:: | ||
| 250 | + For compatibility with the Fermi/LAT ScienceTools the parameters | ||
| 251 | + ``BreakEnergy`` can be replaced by ``BreakValue``. | ||
| 252 | + | ||
| 253 | + | ||
| 254 | +Smoothly broken power law | ||
| 255 | +^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| 256 | + | ||
| 257 | + .. code-block:: xml | ||
| 258 | + | ||
| 259 | + <spectrum type="SmoothBrokenPowerLaw"> | ||
| 260 | + <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/> | ||
| 261 | + <parameter name="Index1" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 262 | + <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 263 | + <parameter name="Index2" scale="-1" value="2.70" min="0.01" max="+5.0" free="1"/> | ||
| 264 | + <parameter name="BreakEnergy" scale="1e6" value="0.3" min="0.01" max="1000.0" free="1"/> | ||
| 265 | + <parameter name="BreakSmoothness" scale="1.0" value="0.2" min="0.01" max="10.0" free="0"/> | ||
| 266 | + </spectrum> | ||
| 267 | + | ||
| 268 | + This spectral model component implements the smoothly broken power law function | ||
| 269 | + | ||
| 270 | + .. math:: | ||
| 271 | + M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma_1} | ||
| 272 | + \left[ 1 + | ||
| 273 | + \left( \frac{E}{E_b} \right)^{\frac{\gamma_1 - \gamma_2}{\beta}} | ||
| 274 | + \right]^{-\beta} | ||
| 275 | + | ||
| 276 | + where | ||
| 277 | + | ||
| 278 | + * :math:`k_0` = ``Prefactor`` | ||
| 279 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 280 | + * :math:`\gamma_1` = ``Index1`` | ||
| 281 | + * :math:`E_0` = ``PivotEnergy`` | ||
| 282 | + * :math:`\gamma_2` = ``Index2`` | ||
| 283 | + * :math:`E_b` = ``BreakEnergy`` | ||
| 284 | + :math:`({\rm MeV})` | ||
| 285 | + * :math:`\beta` = ``BreakSmoothness`` | ||
| 286 | + | ||
| 287 | + .. warning:: | ||
| 288 | + The pivot energy should be set far away from the expected break energy | ||
| 289 | + value. | ||
| 290 | + | ||
| 291 | + .. warning:: | ||
| 292 | + When the two indices are close together, the :math:`\beta` parameter | ||
| 293 | + becomes poorly constrained. Since the :math:`\beta` parameter also scales | ||
| 294 | + the indices, this can cause very large errors in the estimates of the | ||
| 295 | + various spectral parameters. In this case, consider fixing :math:`\beta`. | ||
| 296 | + | ||
| 297 | + .. note:: | ||
| 298 | + For compatibility with the Fermi/LAT ScienceTools the parameters | ||
| 299 | + ``PivotEnergy`` can be replaced by ``Scale``, | ||
| 300 | + ``BreakEnergy`` by ``BreakValue`` and | ||
| 301 | + ``BreakSmoothness`` by ``Beta``. | ||
| 302 | + | ||
| 303 | + | ||
| 304 | +Log parabola | ||
| 305 | +^^^^^^^^^^^^ | ||
| 306 | + | ||
| 307 | + .. code-block:: xml | ||
| 308 | + | ||
| 309 | + <spectrum type="LogParabola"> | ||
| 310 | + <parameter name="Prefactor" scale="1e-17" value="5.878" min="1e-07" max="1000.0" free="1"/> | ||
| 311 | + <parameter name="Index" scale="-1" value="2.32473" min="0.0" max="+5.0" free="1"/> | ||
| 312 | + <parameter name="Curvature" scale="-1" value="0.074" min="-5.0" max="+5.0" free="1"/> | ||
| 313 | + <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 314 | + </spectrum> | ||
| 315 | + | ||
| 316 | + This spectral model component implements the log parabola function | ||
| 317 | + | ||
| 318 | + .. math:: | ||
| 319 | + M_{\rm spectral}(E) = k_0 \left( \frac{E}{E_0} \right)^{\gamma+\eta \ln(E/E_0)} | ||
| 320 | + | ||
| 321 | + where | ||
| 322 | + | ||
| 323 | + * :math:`k_0` = ``Prefactor`` | ||
| 324 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1})` | ||
| 325 | + * :math:`\gamma` = ``Index`` | ||
| 326 | + * :math:`\eta` = ``Curvature`` | ||
| 327 | + * :math:`E_0` = ``PivotEnergy`` | ||
| 328 | + :math:`({\rm MeV})` | ||
| 329 | + | ||
| 330 | + .. warning:: | ||
| 331 | + The ``PivotEnergy`` parameter is not intended to be fitted. | ||
| 332 | + | ||
| 333 | + An alternative XML format is supported for compatibility with the Fermi/LAT | ||
| 334 | + XML format: | ||
| 335 | + | ||
| 336 | + .. code-block:: xml | ||
| 337 | + | ||
| 338 | + <spectrum type="LogParabola"> | ||
| 339 | + <parameter name="norm" scale="1e-17" value="5.878" min="1e-07" max="1000.0" free="1"/> | ||
| 340 | + <parameter name="alpha" scale="1" value="2.32473" min="0.0" max="+5.0" free="1"/> | ||
| 341 | + <parameter name="beta" scale="1" value="0.074" min="-5.0" max="+5.0" free="1"/> | ||
| 342 | + <parameter name="Eb" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 343 | + </spectrum> | ||
| 344 | + | ||
| 345 | + where | ||
| 346 | + | ||
| 347 | + * ``alpha`` = -``Index`` | ||
| 348 | + * ``beta`` = -``Curvature`` | ||
| 349 | + | ||
| 350 | + | ||
| 351 | +Gaussian | ||
| 352 | +^^^^^^^^ | ||
| 353 | + | ||
| 354 | + .. code-block:: xml | ||
| 355 | + | ||
| 356 | + <spectrum type="Gaussian"> | ||
| 357 | + <parameter name="Normalization" scale="1e-10" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 358 | + <parameter name="Mean" scale="1e6" value="5.0" min="0.01" max="100.0" free="1"/> | ||
| 359 | + <parameter name="Sigma" scale="1e6" value="1.0" min="0.01" max="100.0" free="1"/> | ||
| 360 | + </spectrum> | ||
| 361 | + | ||
| 362 | + This spectral model component implements the gaussian function | ||
| 363 | + | ||
| 364 | + .. math:: | ||
| 365 | + M_{\rm spectral}(E) = \frac{N_0}{\sqrt{2\pi}\sigma} | ||
| 366 | + \exp \left( \frac{-(E-\bar{E})^2}{2 \sigma^2} \right) | ||
| 367 | + | ||
| 368 | + where | ||
| 369 | + | ||
| 370 | + * :math:`N_0` = ``Normalization`` | ||
| 371 | + :math:`({\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1})` | ||
| 372 | + * :math:`\bar{E}` = ``Mean`` | ||
| 373 | + :math:`({\rm MeV})` | ||
| 374 | + * :math:`\sigma` = ``Sigma`` | ||
| 375 | + :math:`({\rm MeV})` | ||
| 376 | + | ||
| 377 | + | ||
| 378 | +File function | ||
| 379 | +^^^^^^^^^^^^^ | ||
| 380 | + | ||
| 381 | + .. code-block:: xml | ||
| 382 | + | ||
| 383 | + <spectrum type="FileFunction" file="data/filefunction.txt"> | ||
| 384 | + <parameter scale="1.0" name="Normalization" min="0.0" max="1000.0" value="1.0" free="1"/> | ||
| 385 | + </spectrum> | ||
| 386 | + | ||
| 387 | + This spectral model component implements an arbitrary function | ||
| 388 | + that is defined by intensity values at specific energies. | ||
| 389 | + The energy and intensity values are defined using an ASCII file with | ||
| 390 | + columns of energy and differential flux values. | ||
| 391 | + Energies are given in units of | ||
| 392 | + :math:`{\rm MeV}`, | ||
| 393 | + intensities are given in units of | ||
| 394 | + :math:`{\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1}`. | ||
| 395 | + The only parameter is a multiplicative normalization: | ||
| 396 | + | ||
| 397 | + .. math:: | ||
| 398 | + M_{\rm spectral}(E) = N_0 \left. \frac{dN}{dE} \right\rvert_{\rm file} | ||
| 399 | + | ||
| 400 | + where | ||
| 401 | + | ||
| 402 | + * :math:`N_0` = ``Normalization`` | ||
| 403 | + | ||
| 404 | + .. warning:: | ||
| 405 | + If the file name is given without a path it is expected that the file | ||
| 406 | + resides in the same directory than the XML file. | ||
| 407 | + If the file resides in a different directory, an absolute path name should | ||
| 408 | + be specified. | ||
| 409 | + Any environment variable present in the path name will be expanded. | ||
| 410 | + | ||
| 411 | + | ||
| 412 | +Node function | ||
| 413 | +^^^^^^^^^^^^^ | ||
| 414 | + | ||
| 415 | + .. code-block:: xml | ||
| 416 | + | ||
| 417 | + <spectrum type="NodeFunction"> | ||
| 418 | + <node> | ||
| 419 | + <parameter name="Energy" scale="1.0" value="1.0" min="0.1" max="1.0e20" free="0"/> | ||
| 420 | + <parameter name="Intensity" scale="1e-07" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 421 | + </node> | ||
| 422 | + <node> | ||
| 423 | + <parameter name="Energy" scale="10.0" value="1.0" min="0.1" max="1.0e20" free="0"/> | ||
| 424 | + <parameter name="Intensity" scale="1e-08" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 425 | + </node> | ||
| 426 | + </spectrum> | ||
| 427 | + | ||
| 428 | + This spectral model component implements a generalised broken | ||
| 429 | + power law which is defined by a set of energy and intensity values | ||
| 430 | + (the so called nodes) that are piecewise connected by power laws. | ||
| 431 | + Energies are given in units of | ||
| 432 | + :math:`{\rm MeV}`, | ||
| 433 | + intensities are given in units of | ||
| 434 | + :math:`{\rm ph}\,\,{\rm cm}^{-2}\,{\rm s}^{-1}\,{\rm MeV}^{-1}`. | ||
| 435 | + | ||
| 436 | + .. warning:: | ||
| 437 | + An arbitrary number of energy-intensity nodes can be defined in a node | ||
| 438 | + function. | ||
| 439 | + The nodes need to be sorted by increasing energy. | ||
| 440 | + Although the fitting of the ``Energy`` parameters is formally possible | ||
| 441 | + it may lead to numerical complications. | ||
| 442 | + If ``Energy`` parameters are to be fitted make sure that the ``min`` | ||
| 443 | + and ``max`` attributes are set in a way that avoids inversion of the energy | ||
| 444 | + ordering. | ||
| 445 | + | ||
| 446 | + | ||
| 447 | +Composite model | ||
| 448 | +^^^^^^^^^^^^^^^ | ||
| 449 | + | ||
| 450 | + .. code-block:: xml | ||
| 451 | + | ||
| 452 | + <spectrum type="Composite"> | ||
| 453 | + <spectrum type="PowerLaw" component="SoftComponent"> | ||
| 454 | + <parameter name="Prefactor" scale="1e-17" value="3" min="1e-07" max="1000.0" free="1"/> | ||
| 455 | + <parameter name="Index" scale="-1" value="3.5" min="0.0" max="+5.0" free="1"/> | ||
| 456 | + <parameter name="PivotEnergy" scale="1e6" value="1" min="0.01" max="1000.0" free="0"/> | ||
| 457 | + </spectrum> | ||
| 458 | + <spectrum type="PowerLaw" component="HardComponent"> | ||
| 459 | + <parameter name="Prefactor" scale="1e-17" value="5" min="1e-07" max="1000.0" free="1"/> | ||
| 460 | + <parameter name="Index" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> | ||
| 461 | + <parameter name="PivotEnergy" scale="1e6" value="1" min="0.01" max="1000.0" free="0"/> | ||
| 462 | + </spectrum> | ||
| 463 | + </spectrum> | ||
| 464 | + | ||
| 465 | + This spectral model component implements a composite model that is the | ||
| 466 | + sum of an arbitrary number of spectral models, computed using | ||
| 467 | + | ||
| 468 | + .. math:: | ||
| 469 | + M_{\rm spectral}(E) = \sum_{i=0}^{N-1} M_{\rm spectral}^{(i)}(E) | ||
| 470 | + | ||
| 471 | + where :math:`M_{\rm spectral}^{(i)}(E)` is any spectral model component | ||
| 472 | + (including another composite model), and :math:`N` is the number of | ||
| 473 | + model components that are combined. | ||
| 474 | + | ||
| 475 | + | ||
| 476 | +Multiplicative model | ||
| 477 | +^^^^^^^^^^^^^^^^^^^^ | ||
| 478 | + | ||
| 479 | + .. code-block:: xml | ||
| 480 | + | ||
| 481 | + <spectrum type="Multiplicative"> | ||
| 482 | + <spectrum type="PowerLaw" component="PowerLawComponent"> | ||
| 483 | + <parameter name="Prefactor" scale="1e-17" value="1.0" min="1e-07" max="1000.0" free="1"/> | ||
| 484 | + <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/> | ||
| 485 | + <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 486 | + </spectrum> | ||
| 487 | + <spectrum type="ExponentialCutoffPowerLaw" component="CutoffComponent"> | ||
| 488 | + <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-07" max="1000.0" free="0"/> | ||
| 489 | + <parameter name="Index" scale="1.0" value="0.0" min="-2.0" max="+2.0" free="0"/> | ||
| 490 | + <parameter name="CutoffEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | ||
| 491 | + <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | ||
| 492 | + </spectrum> | ||
| 493 | + </spectrum> | ||
| 494 | + | ||
| 495 | + This spectral model component implements a composite model that is the | ||
| 496 | + product of an arbitrary number of spectral models, computed using | ||
| 497 | + | ||
| 498 | + .. math:: | ||
| 499 | + M_{\rm spectral}(E) = \prod_{i=0}^{N-1} M_{\rm spectral}^{(i)}(E) | ||
| 500 | + | ||
| 501 | + where :math:`M_{\rm spectral}^{(i)}(E)` is any spectral model component | ||
| 502 | + (including another composite model), and :math:`N` is the number of | ||
| 503 | + model components that are multiplied. |
doc/source/users/user_manual/models_temporal.rst
0 → 100644
| 1 | +.. _sec_models_temporal: | ||
| 2 | + | ||
| 3 | +Temporal model components | ||
| 4 | +------------------------- | ||
| 5 | + | ||
| 6 | +The following sections present the temporal model components that are available | ||
| 7 | +in ctools. | ||
| 8 | + | ||
| 9 | +Constant | ||
| 10 | +^^^^^^^^ | ||
| 11 | + | ||
| 12 | + .. code-block:: xml | ||
| 13 | + | ||
| 14 | + <temporal type="Constant"> | ||
| 15 | + <parameter name="Normalization" scale="1.0" value="1.0" min="0.1" max="10.0" free="0"/> | ||
| 16 | + </temporal> | ||
| 17 | + | ||
| 18 | + This temporal model component implements a constant source | ||
| 19 | + | ||
| 20 | + .. math:: | ||
| 21 | + M_{\rm temporal}(t) = N_0 | ||
| 22 | + | ||
| 23 | + where | ||
| 24 | + | ||
| 25 | + * :math:`N_0` = ``Normalization`` | ||
| 26 | + | ||
| 27 | + | ||
| 28 | +Light Curve | ||
| 29 | +^^^^^^^^^^^ | ||
| 30 | + | ||
| 31 | + .. code-block:: xml | ||
| 32 | + | ||
| 33 | + <temporal type="LightCurve" file="model_temporal_lightcurve.fits"> | ||
| 34 | + <parameter name="Normalization" scale="1" value="1.0" min="0.0" max="1000.0" free="0"/> | ||
| 35 | + </temporal> | ||
| 36 | + | ||
| 37 | + This temporal model component implements a light curve :math:`r(t)` | ||
| 38 | + | ||
| 39 | + .. math:: | ||
| 40 | + M_{\rm temporal}(t) = N_0 \times r(t) | ||
| 41 | + | ||
| 42 | + where | ||
| 43 | + | ||
| 44 | + * :math:`N_0` = ``Normalization`` | ||
| 45 | + | ||
| 46 | + The light curve is defined by nodes in a FITS file that specify the relative | ||
| 47 | + flux normalization as function of time (file ``model_temporal_lightcurve.fits`` | ||
| 48 | + in the example above). The structure of the light curve FITS | ||
| 49 | + file is shown in the figure below. The light curve is defined in the first | ||
| 50 | + extension of the FITS file and consists of a binary table with the columns | ||
| 51 | + ``TIME`` and ``NORM``. Times in the ``TIME`` columns are given in seconds | ||
| 52 | + and are counted with respect to a time reference that is defined in the | ||
| 53 | + header of the binary table. Times need to be specified in ascending order. | ||
| 54 | + The values in the ``NORM`` column specify :math:`r(t)` at times :math:`t`, | ||
| 55 | + and should be comprised between 0 and 1. | ||
| 56 | + | ||
| 57 | + .. _fig_model_lightcurve: | ||
| 58 | + | ||
| 59 | + .. figure:: model_lightcurve.png | ||
| 60 | + :align: center | ||
| 61 | + :width: 100% | ||
| 62 | + | ||
| 63 | + *Structure of light curve FITS file* | ||
| 64 | + | ||
| 65 | + .. warning:: | ||
| 66 | + Fitting of light curves only makes sense for an unbinned maximum likelihood | ||
| 67 | + analysis, since in a binned or stacked analysis the times of individual | ||
| 68 | + events are dropped. | ||
| 69 | + | ||
| 70 | + | ||
| 71 | +Phase Curve | ||
| 72 | +^^^^^^^^^^^ | ||
| 73 | + | ||
| 74 | + .. code-block:: xml | ||
| 75 | + | ||
| 76 | + <temporal type="PhaseCurve" file="model_temporal_phasecurve.fits"> | ||
| 77 | + <parameter name="Normalization" scale="1" value="1.0" min="0.0" max="1000.0" free="0"/> | ||
| 78 | + <parameter name="MJD" scale="1" value="51544.5" min="0.0" max="100000.0" free="0"/> | ||
| 79 | + <parameter name="Phase" scale="1" value="0.0" min="0.0" max="1.0" free="0"/> | ||
| 80 | + <parameter name="F0" scale="1" value="1.0" min="0.0" max="1000.0" free="0"/> | ||
| 81 | + <parameter name="F1" scale="1" value="0.1" min="0.0" max="1000.0" free="0"/> | ||
| 82 | + <parameter name="F2" scale="1" value="0.01" min="0.0" max="1000.0" free="0"/> | ||
| 83 | + </temporal> | ||
| 84 | + | ||
| 85 | + This temporal model component implements a phase curve :math:`r(\Phi(t))` | ||
| 86 | + | ||
| 87 | + .. math:: | ||
| 88 | + M_{\rm temporal}(t) = N_0 \times r(\Phi(t)) | ||
| 89 | + | ||
| 90 | + where the phase as function of time is computed using | ||
| 91 | + | ||
| 92 | + .. math:: | ||
| 93 | + \Phi(t) = \Phi_0 + f(t-t_0) + \frac{1}{2}\dot{f} (t-t_0)^2 + | ||
| 94 | + \frac{1}{6}\ddot{f} (t-t_0)^3 | ||
| 95 | + | ||
| 96 | + and | ||
| 97 | + | ||
| 98 | + * :math:`N_0` = ``Normalization`` | ||
| 99 | + * :math:`t_0` = ``MJD`` | ||
| 100 | + * :math:`\Phi_0` = ``Phase`` | ||
| 101 | + * :math:`f` = ``F0`` | ||
| 102 | + * :math:`\dot{f}` = ``F1`` | ||
| 103 | + * :math:`\ddot{f}` = ``F2`` | ||
| 104 | + | ||
| 105 | + The phase curve is defined by nodes in a FITS file that specify the relative | ||
| 106 | + flux normalization as function of phase (file ``model_temporal_phasecurve.fits`` | ||
| 107 | + in the example above). The structure of the phase curve | ||
| 108 | + FITS file is shown in the figure below. The phase curve is defined in the | ||
| 109 | + first extension of the FITS file and consists of a binary table with the | ||
| 110 | + columns ``PHASE`` and ``NORM``. Phase values in the ``PHASE`` column need to | ||
| 111 | + be comprised between 0 and 1 and need to be given in ascending order. The | ||
| 112 | + values in the ``NORM`` column specify :math:`r(\Phi(t))` at phases | ||
| 113 | + :math:`\Phi(t)`, and should be comprised between 0 and 1. | ||
| 114 | + | ||
| 115 | + .. _fig_model_phasecurve: | ||
| 116 | + | ||
| 117 | + .. figure:: model_phasecurve.png | ||
| 118 | + :align: center | ||
| 119 | + :width: 40% | ||
| 120 | + | ||
| 121 | + *Structure of phase curve FITS file* | ||
| 122 | + | ||
| 123 | + .. warning:: | ||
| 124 | + Fitting of phase curves only makes sense for an unbinned maximum likelihood | ||
| 125 | + analysis, since in a binned or stacked analysis the times of individual | ||
| 126 | + events are dropped. | ||
| 127 | + | ||
| 128 | + .. warning:: | ||
| 129 | + Fitting of phase curve parameters may not properly work for pulsar | ||
| 130 | + frequencies. |
doc/source/users/user_manual/plotting.rst
| 1 | Plotting | 1 | Plotting |
| 2 | ======== | 2 | ======== |
| 3 | 3 | ||
| 4 | -Gammalib and ctools do not include classes and scripts to make plots. | 4 | +ctools and GammaLib do not include classes and scripts to make plots. |
| 5 | 5 | ||
| 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. | 6 | +This is intentional because creating and maintaining plotting tools that work |
| 7 | +on all platforms and cover all needs is a big project in itself, and deciding | ||
| 8 | +to support a plotting package that is popular now as part of the CTA science | ||
| 9 | +tools could become very problematic in the future. | ||
| 11 | 10 | ||
| 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. | 11 | +But we realise that most ctools users need to create plots for their high-level |
| 12 | +science results, so on this page we provide a few pointers to external packages | ||
| 13 | +and tools. | ||
| 15 | 14 | ||
| 15 | +Nevertheless, for your convenience several scripts for graphical display are | ||
| 16 | +included in the ctools package that rely on the | ||
| 17 | +`matplotlib <http://matplotlib.org>`_ | ||
| 18 | +Python module. You can find these scripts in the | ||
| 19 | +``$CTOOLS/share/examples/python`` folder. The following scripts are available: | ||
| 16 | 20 | ||
| 17 | -General | ||
| 18 | -------- | 21 | + +------------------------+-----------------------------+ |
| 22 | + | Script | Usage | | ||
| 23 | + +========================+=============================+ | ||
| 24 | + | ``show_butterfly.py`` | Display a butterfly diagram | | ||
| 25 | + +------------------------+-----------------------------+ | ||
| 26 | + | ``show_lightcurve.py`` | Display a light curve | | ||
| 27 | + +------------------------+-----------------------------+ | ||
| 28 | + | ``show_obs.py`` | Display observation summary | | ||
| 29 | + +------------------------+-----------------------------+ | ||
| 30 | + | ``show_pointings.py`` | Display pointing directions | | ||
| 31 | + +------------------------+-----------------------------+ | ||
| 32 | + | ``show_phases.py`` | Display event phases | | ||
| 33 | + +------------------------+-----------------------------+ | ||
| 34 | + | ``show_spectrum.py`` | Display a spectrum | | ||
| 35 | + +------------------------+-----------------------------+ | ||
| 19 | 36 | ||
| 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. | 37 | +Below some usage examples and the expected output. |
| 26 | 38 | ||
| 39 | +show_butterfly.py | ||
| 40 | +^^^^^^^^^^^^^^^^^ | ||
| 27 | 41 | ||
| 28 | -Sky maps | ||
| 29 | --------- | 42 | +.. code-block:: bash |
| 30 | 43 | ||
| 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. | 44 | + $ $CTOOLS/share/examples/python/show_butterfly.py butterfly_src001.txt |
| 34 | 45 | ||
| 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). | 46 | +.. figure:: plotting_butterfly.png |
| 47 | + :width: 600px | ||
| 48 | + :align: center | ||
| 42 | 49 | ||
| 50 | + *Butterfly diagram displayed with show_butterfly.py* | ||
| 43 | 51 | ||
| 44 | -Spectra and light curves | ||
| 45 | ------------------------- | ||
| 46 | 52 | ||
| 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`_. | 53 | +show_lightcurve.py |
| 54 | +^^^^^^^^^^^^^^^^^^ | ||
| 50 | 55 | ||
| 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. | 56 | +.. code-block:: bash |
| 54 | 57 | ||
| 55 | -.. _DS9: http://ds9.si.edu/ | ||
| 56 | -.. _Aladin: http://aladin.u-strasbg.fr/ | ||
| 57 | -.. _Ginga: http://ejeschke.github.io/ginga/ | ||
| 58 | -.. _matplotlib: http://matplotlib.org/ | ||
| 59 | -.. _matplotlib gallery: http://matplotlib.org/gallery.html | ||
| 60 | -.. _WCSAxes: http://wcsaxes.readthedocs.org/ | ||
| 61 | -.. _APLPy: http://aplpy.github.io/ | ||
| 62 | -.. _kapteyn: https://www.astro.rug.nl/software/kapteyn/ | ||
| 63 | -.. _Gammapy: https://gammapy.readthedocs.org/ | ||
| 64 | -.. _IRIS: http://cxc.cfa.harvard.edu/iris/ | ||
| 65 | -.. _CASSIS: http://cassis.irap.omp.eu/ | ||
| 66 | -.. _VOSpec: http://www.sciops.esa.int/index.php?project=SAT&page=vospec | 58 | + $ $CTOOLS/share/examples/python/show_lightcurve.py lightcurve.fits |
| 67 | 59 | ||
| 68 | -.. raw:: html | 60 | +.. figure:: plotting_lightcurve.png |
| 61 | + :width: 600px | ||
| 62 | + :align: center | ||
| 69 | 63 | ||
| 70 | - <iframe src="http://nbviewer.jupyter.org/github/davidchall/random-direction/blob/master/Generate_Beam_Directions.ipynb" width="100%" height="800"></iframe> | 64 | + *Light curve displayed with show_lightcurve.py* |
| 65 | + | ||
| 66 | + | ||
| 67 | +show_obs.py | ||
| 68 | +^^^^^^^^^^^ | ||
| 69 | + | ||
| 70 | +.. code-block:: bash | ||
| 71 | + | ||
| 72 | + $ $CTOOLS/share/examples/python/show_obs.py obs_selected.xml | ||
| 73 | + | ||
| 74 | +.. figure:: plotting_obs.png | ||
| 75 | + :width: 600px | ||
| 76 | + :align: center | ||
| 77 | + | ||
| 78 | + *Observation summary displayed with show_obs.py* | ||
| 79 | + | ||
| 80 | + | ||
| 81 | +show_pointings.py | ||
| 82 | +^^^^^^^^^^^^^^^^^ | ||
| 83 | + | ||
| 84 | +.. code-block:: bash | ||
| 85 | + | ||
| 86 | + $ $CTOOLS/share/examples/python/show_pointings.py obs_selected.xml | ||
| 87 | + | ||
| 88 | +.. figure:: plotting_pointings.png | ||
| 89 | + :width: 600px | ||
| 90 | + :align: center | ||
| 91 | + | ||
| 92 | + *Observation summary displayed with show_pointings.py (zoomed in)* | ||
| 93 | + | ||
| 94 | + | ||
| 95 | +show_phases.py | ||
| 96 | +^^^^^^^^^^^^^^ | ||
| 97 | + | ||
| 98 | +.. code-block:: bash | ||
| 99 | + | ||
| 100 | + $ $CTOOLS/share/examples/python/show_phases.py -n 50 events_phased.fits | ||
| 101 | + | ||
| 102 | +.. figure:: plotting_phases.png | ||
| 103 | + :width: 600px | ||
| 104 | + :align: center | ||
| 105 | + | ||
| 106 | + *Event phases displayed with show_phases.py* | ||
| 107 | + | ||
| 108 | + | ||
| 109 | +show_spectrum.py | ||
| 110 | +^^^^^^^^^^^^^^^^ | ||
| 111 | + | ||
| 112 | +.. code-block:: bash | ||
| 113 | + | ||
| 114 | + $ $CTOOLS/share/examples/python/show_spectrum.py spectrum_src001.fits | ||
| 115 | + | ||
| 116 | +.. figure:: plotting_spectrum.png | ||
| 117 | + :width: 600px | ||
| 118 | + :align: center | ||
| 119 | + | ||
| 120 | + *Observation summary displayed with show_spectrum.py* |
doc/source/users/user_manual/plotting_butterfly.png
0 → 100644
33.2 KB
doc/source/users/user_manual/plotting_lightcurve.png
0 → 100644
24.2 KB
doc/source/users/user_manual/plotting_obs.png
0 → 100644
72.1 KB
doc/source/users/user_manual/plotting_phases.png
0 → 100644
18 KB
doc/source/users/user_manual/plotting_pointings.png
0 → 100644
26.6 KB
doc/source/users/user_manual/plotting_spectrum.png
0 → 100644
22.5 KB
doc/source/users/user_manual/response.rst
| @@ -48,13 +48,38 @@ following: | @@ -48,13 +48,38 @@ following: | ||
| 48 | PSF(p' | p, E, t) \times | 48 | PSF(p' | p, E, t) \times |
| 49 | E_{\rm disp}(E' | p, E, t) | 49 | E_{\rm disp}(E' | p, E, t) |
| 50 | 50 | ||
| 51 | -ctools are shipped with response functions for the northern and southern | ||
| 52 | -arrays, and variants are available that have been optimised for exposure | ||
| 53 | -times of 0.5 hours, 5 hours and 50 hours. | 51 | +ctools are shipped with so called ``prod2`` response functions for the northern |
| 52 | +and southern arrays, and variants are available that have been optimised for | ||
| 53 | +exposure times of 0.5 hours, 5 hours and 50 hours. | ||
| 54 | In total, the following six instrument response functions are available: | 54 | In total, the following six instrument response functions are available: |
| 55 | ``North_0.5h``, ``North_5h``, ``North_50h``, ``South_0.5h``, | 55 | ``North_0.5h``, ``North_5h``, ``North_50h``, ``South_0.5h``, |
| 56 | ``South_5h``, and ``South_50h``. | 56 | ``South_5h``, and ``South_50h``. |
| 57 | 57 | ||
| 58 | +.. note:: | ||
| 59 | + In cases for which the CTA instrument response functions are used in a | ||
| 60 | + research project, we ask to add the following acknowledgement in any | ||
| 61 | + resulting publication: | ||
| 62 | + | ||
| 63 | + *This research has made use of the CTA instrument response functions | ||
| 64 | + provided by the CTA Consortium and Observatory.* | ||
| 65 | + | ||
| 66 | + The latest CTA reponse function (prod3b-v1) can be downloaded from | ||
| 67 | + `this link <http://www.cta-observatory.org/wp-content/uploads/2017/12/CTA-Performance-prod3b-v1-FITS1.tar.gz>`_. To install the response function, type | ||
| 68 | + | ||
| 69 | + .. code-block:: bash | ||
| 70 | + | ||
| 71 | + $ tar xvfz CTA-Performance-prod3b-v1-FITS1.tar.gz -C $CTOOLS/share | ||
| 72 | + | ||
| 73 | + or | ||
| 74 | + | ||
| 75 | + .. code-block:: bash | ||
| 76 | + | ||
| 77 | + $ sudo tar xvfz CTA-Performance-prod3b-v1-FITS1.tar.gz -C $CTOOLS/share | ||
| 78 | + | ||
| 79 | + if you need root priviledges to install in your ``$CTOOLS`` directory. | ||
| 80 | + To use the prod3b-v1 response functions, specify ``prod3b-v1`` if a tool | ||
| 81 | + or script queries for the calibration database. | ||
| 82 | + | ||
| 58 | Each response is stored in a single FITS file, and each component of | 83 | Each response is stored in a single FITS file, and each component of |
| 59 | the response factorisation is stored in a binary table of that FITS | 84 | the response factorisation is stored in a binary table of that FITS |
| 60 | file. | 85 | file. |
| @@ -103,18 +128,18 @@ calibration database and the ``South_0.5h`` response function: | @@ -103,18 +128,18 @@ calibration database and the ``South_0.5h`` response function: | ||
| 103 | 128 | ||
| 104 | .. code-block:: bash | 129 | .. code-block:: bash |
| 105 | 130 | ||
| 106 | - $ ctobssim | ||
| 107 | - RA of pointing (degrees) (0-360) [83.63] | ||
| 108 | - Dec of pointing (degrees) (-90-90) [22.51] | ||
| 109 | - Radius of FOV (degrees) (0-180) [5.0] | ||
| 110 | - Start time (MET in s) [0.0] | ||
| 111 | - End time (MET in s) [1800.0] | ||
| 112 | - Lower energy limit (TeV) [0.1] | ||
| 113 | - Upper energy limit (TeV) [100.0] | ||
| 114 | - Calibration database [prod2] | ||
| 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] | 131 | + $ ctobssim |
| 132 | + RA of pointing (degrees) (0-360) [83.63] | ||
| 133 | + Dec of pointing (degrees) (-90-90) [22.51] | ||
| 134 | + Radius of FOV (degrees) (0-180) [5.0] | ||
| 135 | + Start time (MET in s) [0.0] | ||
| 136 | + End time (MET in s) [1800.0] | ||
| 137 | + Lower energy limit (TeV) [0.1] | ||
| 138 | + Upper energy limit (TeV) [100.0] | ||
| 139 | + Calibration database [prod2] | ||
| 140 | + Instrument response function [South_0.5h] | ||
| 141 | + Input model XML file [$CTOOLS/share/models/crab.xml] | ||
| 142 | + Output event data file or observation definition XML file [events.fits] | ||
| 118 | 143 | ||
| 119 | Running the other tools is equivalent. | 144 | Running the other tools is equivalent. |
| 120 | 145 | ||
| @@ -179,11 +204,11 @@ and response name from within Python: | @@ -179,11 +204,11 @@ and response name from within Python: | ||
| 179 | 204 | ||
| 180 | .. code-block:: python | 205 | .. code-block:: python |
| 181 | 206 | ||
| 182 | - import gammalib | ||
| 183 | - obs = gammalib.GCTAObservation() | ||
| 184 | - caldb = gammalib.GCaldb("cta", "prod2") | ||
| 185 | - irf = "South_0.5h" | ||
| 186 | - obs.response(irf, caldb) | 207 | + >>> import gammalib |
| 208 | + >>> obs = gammalib.GCTAObservation() | ||
| 209 | + >>> caldb = gammalib.GCaldb("cta", "prod2") | ||
| 210 | + >>> irf = "South_0.5h" | ||
| 211 | + >>> obs.response(irf, caldb) | ||
| 187 | 212 | ||
| 188 | The calibration database is set by creating a ``GCaldb`` object. The | 213 | The calibration database is set by creating a ``GCaldb`` object. The |
| 189 | constructor takes as argument the mission (always ``cta``) and the | 214 | constructor takes as argument the mission (always ``cta``) and the |