diff --git a/doc/source/help/faq.rst b/doc/source/help/faq.rst index c57b4b0..9ae0a35 100755 --- a/doc/source/help/faq.rst +++ b/doc/source/help/faq.rst @@ -17,6 +17,7 @@ asked. - :ref:`I want to upgrade ctools, do I have to upgrade GammaLib? ` - :ref:`Should I used binned or unbinned analysis? ` - :ref:`How precise are ctools? ` +- :ref:`How to get a ctools log file when running the tool from Python? ` .. _faq_ctools_gammalib: @@ -45,77 +46,97 @@ asked. .. topic:: Are ctools and GammaLib specific to CTA? - The short answer is: ctools yes, GammaLib no. - - ctools have been specifically designed to provide the functionalities that - are required to analyse CTA data. - This does not mean that ctools can not be used for analysing data from - other Imaging Air Cherenkov Telescopes; the sole requirement is that the - data and response files are provided in a CTA compliant format. - However, ctools are not designed to analyse data from Fermi/LAT, - INTEGRAL, COMPTEL or other gamma-ray telescopes. - Nevertheless, some joint multi-telescope analysis is supported by ctools. - - GammaLib, however, is a universal framework with a core that is completely - independent of any telescope. - Plugins are used to interface GammaLib with the data and response files of - specific telescopes. - For every new instrument that shall be supported a new plugin needs to be - developed. - So far, plugins exists for CTA (and Imaging Air Cherenkov Telescopes in - general), Fermi/LAT, and COMPTEL. - Some support for integration of any arbitrary multi-wavelength data - exists. + The short answer is: ctools yes, GammaLib no. + + ctools have been specifically designed to provide the functionalities that + are required to analyse CTA data. + This does not mean that ctools can not be used for analysing data from + other Imaging Air Cherenkov Telescopes; the sole requirement is that the + data and response files are provided in a CTA compliant format. + However, ctools are not designed to analyse data from Fermi/LAT, + INTEGRAL, COMPTEL or other gamma-ray telescopes. + Nevertheless, some joint multi-telescope analysis is supported by ctools. + + GammaLib, however, is a universal framework with a core that is completely + independent of any telescope. + Plugins are used to interface GammaLib with the data and response files of + specific telescopes. + For every new instrument that shall be supported a new plugin needs to be + developed. + So far, plugins exists for CTA (and Imaging Air Cherenkov Telescopes in + general), Fermi/LAT, and COMPTEL. + Some support for integration of any arbitrary multi-wavelength data + exists. .. _faq_upgrade: .. topic:: I want to upgrade ctools, do I have to upgrade GammaLib? - For the moment yes. + For the moment yes. - The GammaLib interface is still not fully stabilised, hence ctools is - continuously adapted to match the interface evolution - (see the :ref:`sec_download` section for a correspondance of versions). - We plan however to put the GammaLib interface under change control. - ctools should then become more independent from GammaLib. + The GammaLib interface is still not fully stabilised, hence ctools is + continuously adapted to match the interface evolution + (see the :ref:`sec_download` section for a correspondance of versions). + We plan however to put the GammaLib interface under change control. + ctools should then become more independent from GammaLib. .. _faq_analysis: .. topic:: Should I used binned or unbinned analysis? - This depends on the amount of data you want to analyse and to some extent - on the question you want to answer with your analysis. - For an unbinned analysis, the computation time increases about linearly - with the number of events and hence with the duration of the observation, - while for binned analysis the computation time depends only on the number - of bins that is used. - Consequently, for short observation times (below 30 hours), unbinned - analysis is faster, while for longer times it is advantageous to use - a binned analysis. - If you go to very low energies, either make sure that you have enough - energy bins in a binned analysis to sample properly the strong drop in the - effective area towards small energies, or better, use unbinned analysis. - If you'd like to fit a Gaussian line to your data you may also prefer - unbinned over binned analysis, as the fine sampling required to resolve - the line may require a prohibitive large number of energy bins for a binned - analysis. + This depends on the amount of data you want to analyse and to some extent + on the question you want to answer with your analysis. + For an unbinned analysis, the computation time increases about linearly + with the number of events and hence with the duration of the observation, + while for binned analysis the computation time depends only on the number + of bins that is used. + Consequently, for short observation times (below 30 hours), unbinned + analysis is faster, while for longer times it is advantageous to use + a binned analysis. + If you go to very low energies, either make sure that you have enough + energy bins in a binned analysis to sample properly the strong drop in the + effective area towards small energies, or better, use unbinned analysis. + If you'd like to fit a Gaussian line to your data you may also prefer + unbinned over binned analysis, as the fine sampling required to resolve + the line may require a prohibitive large number of energy bins for a binned + analysis. .. _faq_precision: .. topic:: How precise are ctools? - The ctools and gammalib codes have a numerical accuracy of better than 1%. - This means that if you use ctools to determine for example the flux - received from a source or the spectral points of an SED, the relative - precision of the flux or the spectral points is better than 1%. - The same is true for spatial parameters, such as source position or - source extension. - For many cases the actual numerical precision is in fact much better - than 1%, but in any case, it should never be worse. - Note, however, that this does not imply that source parameters can be - determined with CTA with an accuracy of 1%. The accuracy depends in the - end on the precision to which the instrument response function is known, - which should be more in the 10% range. + The ctools and gammalib codes have a numerical accuracy of better than 1%. + This means that if you use ctools to determine for example the flux + received from a source or the spectral points of an SED, the relative + precision of the flux or the spectral points is better than 1%. + The same is true for spatial parameters, such as source position or + source extension. + For many cases the actual numerical precision is in fact much better + than 1%, but in any case, it should never be worse. + Note, however, that this does not imply that source parameters can be + determined with CTA with an accuracy of 1%. The accuracy depends in the + end on the precision to which the instrument response function is known, + which should be more in the 10% range. + + +.. _faq_python_logging: + +.. topic:: How to get a ctools log file when running the tool from Python? + + By default, tools and scripts run from Python will not generate a log file. + The reason for this is that Python scripts are often used to build ctools + analysis pipelines and workflows, and one generally does not want that such + a script pollutes the workspace with log files. You can however instruct a + ctool or cscript to generate a log file by invoking the ``logFileOpen()`` + method before running the tool, for example + + .. code-block:: python + + >>> import ctools + >>> sim = ctools.ctobssim() + >>> sim.logFileOpen() + >>> sim.run() + diff --git a/doc/source/users/glossary.rst b/doc/source/users/glossary.rst index 8c22e04..9a381d3 100755 --- a/doc/source/users/glossary.rst +++ b/doc/source/users/glossary.rst @@ -48,7 +48,7 @@ Glossary .. math:: E_{\rm disp}(E'| p, E) = \frac{\sum_i E_{\rm disp,i}(E'| p, E) \times A_{\rm eff,i}(p, E) \times \tau_i} - {\sum_i E_{\rm disp,i}(E'| p, E) \times \tau_i} + {\sum_i A_{\rm eff,i}(p, E) \times \tau_i} where :math:`E_{\rm disp,i}(E'| p, E)` is the energy dispersion for observation :math:`i`, diff --git a/doc/source/users/tutorials/quickstart/ctools-from-python.ipynb b/doc/source/users/tutorials/quickstart/ctools-from-python.ipynb index cf7114a..9269357 100644 --- a/doc/source/users/tutorials/quickstart/ctools-from-python.ipynb +++ b/doc/source/users/tutorials/quickstart/ctools-from-python.ipynb @@ -381,7 +381,7 @@ "data": { "image/png": "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\n", "text/plain": [ - "" + "" ] }, "metadata": {}, @@ -491,8 +491,8 @@ " RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)\n", " DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)\n", " Number of spectral par's ..: 3\n", - " Prefactor ................: 5.71641985530777e-16 +/- 6.16044729438793e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)\n", - " Index ....................: -2.47207574641491 +/- 0.00792255648868446 [-0,-5] (free,scale=-1,gradient)\n", + " Prefactor ................: 5.71641983396841e-16 +/- 6.16044728001869e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)\n", + " Index ....................: -2.47207578184696 +/- 0.00792255637026554 [-0,-5] (free,scale=-1,gradient)\n", " PivotEnergy ..............: 300000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)\n", " Number of temporal par's ..: 1\n", " Normalization ............: 1 (relative value) (fixed,scale=1,gradient)\n", @@ -504,8 +504,8 @@ " Model type ................: \"PowerLaw\" * \"Constant\"\n", " Number of parameters ......: 4\n", " Number of spectral par's ..: 3\n", - " Prefactor ................: 0.999546835049722 +/- 0.00722086200687532 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)\n", - " Index ....................: -0.000149670672999089 +/- 0.00255125105704583 [-5,5] (free,scale=1,gradient)\n", + " Prefactor ................: 0.999547413672001 +/- 0.00722086618569711 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)\n", + " Index ....................: -0.000149454940530402 +/- 0.00255125105744512 [-5,5] (free,scale=1,gradient)\n", " PivotEnergy ..............: 1000000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)\n", " Number of temporal par's ..: 1\n", " Normalization ............: 1 (relative value) (fixed,scale=1,gradient)\n" @@ -568,11 +568,11 @@ " Model components ..........: \"PointSource\" * \"PowerLaw\" * \"Constant\"\n", " Number of parameters ......: 6\n", " Number of spatial par's ...: 2\n", - " RA .......................: 83.6321512928169 +/- 0.000642709898034108 [-360,360] deg (free,scale=1)\n", - " DEC ......................: 22.0153650383811 +/- 0.000605599763935102 [-90,90] deg (free,scale=1)\n", + " RA .......................: 83.6321513539243 +/- 0.000642709906923956 [-360,360] deg (free,scale=1)\n", + " DEC ......................: 22.015365038759 +/- 0.000605599773766818 [-90,90] deg (free,scale=1)\n", " Number of spectral par's ..: 3\n", - " Prefactor ................: 5.71414829573802e-16 +/- 6.15917758147358e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)\n", - " Index ....................: -2.47211135009306 +/- 0.0079230681070739 [-0,-5] (free,scale=-1,gradient)\n", + " Prefactor ................: 5.71414829301837e-16 +/- 6.15917760942954e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)\n", + " Index ....................: -2.47211138483201 +/- 0.0079230679574118 [-0,-5] (free,scale=-1,gradient)\n", " PivotEnergy ..............: 300000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)\n", " Number of temporal par's ..: 1\n", " Normalization ............: 1 (relative value) (fixed,scale=1,gradient)\n", @@ -584,8 +584,8 @@ " Model type ................: \"PowerLaw\" * \"Constant\"\n", " Number of parameters ......: 4\n", " Number of spectral par's ..: 3\n", - " Prefactor ................: 0.999542788067004 +/- 0.00722079542969056 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)\n", - " Index ....................: -0.00014887248036908 +/- 0.00255123898184119 [-5,5] (free,scale=1,gradient)\n", + " Prefactor ................: 0.999543391635431 +/- 0.0072207997895289 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)\n", + " Index ....................: -0.000148647508899144 +/- 0.0025512389825989 [-5,5] (free,scale=1,gradient)\n", " PivotEnergy ..............: 1000000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)\n", " Number of temporal par's ..: 1\n", " Normalization ............: 1 (relative value) (fixed,scale=1,gradient)\n" @@ -615,7 +615,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "4.2173620963\n" + "4.21736054635\n" ] } ], @@ -633,11 +633,32 @@ ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": {}, + "source": [ + "## Generating a log file\n", + "\n", + "By default, tools and scripts run from Python will not generate a log file. The reason for this is that Python scripts are often used to build ctools analysis pipelines and workflows, and one generally does not want that such a script pollutes the workspace with log files. You can however instruct a ctool or cscript to generate a log file as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": { + "scrolled": true + }, "outputs": [], - "source": [] + "source": [ + "like.logFileOpen()\n", + "like.run()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This creates a log file named ``ctlike.log`` in your local work space that you can visualise using any editor." + ] } ], "metadata": { diff --git a/doc/source/users/user_manual/introduction.rst b/doc/source/users/user_manual/introduction.rst index a9f244a..0899f4e 100755 --- a/doc/source/users/user_manual/introduction.rst +++ b/doc/source/users/user_manual/introduction.rst @@ -103,7 +103,7 @@ example .. code-block:: bash - $ ctobssim seed=41 + $ ctobssim seed=41 will run :ref:`ctobssim` with a seed value of 41. Multiple hidden parameters specified on the command line need to be separated by a white space. In the @@ -116,3 +116,32 @@ values of queried parameters, e.g. >>> sim = ctools.ctobssim() >>> sim["seed"] = 41 ... + + +Log files +--------- + +Each ctool and cscript will produce a log file that is written in the working +directory. The log file is in ASCII file format and can be read by any editor. +By default, the name of the ASCII file is the name of the tool or script, +suffixed by ``.log``. You can change the log file name using the hidden +``logfile`` parameter, for example + +.. code-block:: bash + + $ ctobssim logfile=my_first_simulation.log + +When calling a ctool or cscript from Python, no log file will be written by +default. The reason for this is that Python scripts are often used to build +ctools analysis pipelines and workflows, and one generally does not want that +such a script pollutes the workspace with log files. You can however instruct +a ctool or cscript to generate a log file by invoking the ``logFileOpen()`` +method before running the tool, for example + +.. code-block:: python + + >>> import ctools + >>> sim = ctools.ctobssim() + ... + >>> sim.logFileOpen() + >>> sim.run() diff --git a/doc/source/users/user_manual/models_implementation.rst b/doc/source/users/user_manual/models_implementation.rst index 9477968..5ee3ae6 100644 --- a/doc/source/users/user_manual/models_implementation.rst +++ b/doc/source/users/user_manual/models_implementation.rst @@ -15,6 +15,42 @@ a temporal component (tag ````). .. math:: M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) +where :math:`M(p,E,t)` is given in units of +:math:`photons \,\, cm^{-2} s^{-1} MeV^{-1} sr^{-1}`. + +The spatial model component describes the energy dependent morphology of the +source. +It satisfies + +.. math:: + \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega = 1 + +for all :math:`E`, hence the spatial component does not +impact the spatially integrated spectral and temporal properties of the +source (the integration is done here over the spatial parameters +:math:`p` in a spherical coordinate system). +The units of the spatial model component are +:math:`[M_{\rm spatial}] = {\rm sr}^{-1}` +(but see the exception of the +:ref:`DiffuseMapCube spatial model component `). + +The spectral model component describes the spatially integrated spectral +distribution of the source. +It satisfies + +.. math:: + \int_{E} M_{\rm spectral}(E) \, dE = \Phi + +where :math:`\Phi` is the spatially and spectrally integrated total source +flux. +The units of the spectral model component +are :math:`[M_{\rm spectral}] = {\rm cm}^{-2} {\rm s}^{-1} {\rm MeV}^{-1}`. + +The temporal model component describes the relative variation of the +source flux with respect to the mean value given by the spectral model +component. +The temporal model component is unit less. + In this specific example, the source component ``Crab`` describes a point source at the location of the Crab nebula with a power law spectral shape that is constant in time. diff --git a/doc/source/users/user_manual/models_spatial_src.rst b/doc/source/users/user_manual/models_spatial_src.rst index b51dc0f..2964a9f 100644 --- a/doc/source/users/user_manual/models_spatial_src.rst +++ b/doc/source/users/user_manual/models_spatial_src.rst @@ -61,6 +61,9 @@ Point source Radial source ^^^^^^^^^^^^^ +RadialDisk +~~~~~~~~~~ + The ``RadialDisk`` model describes a uniform intensity distribution within a given radius @@ -83,6 +86,9 @@ Radial source * ``DEC`` is the Declination (degrees) * ``Radius`` is the disk radius (degrees) +RadialGaussian +~~~~~~~~~~~~~~ + The ``RadialGaussian`` model describes a Gaussian intensity distribution .. code-block:: xml @@ -108,7 +114,10 @@ Radial source * ``RA`` is the Right Ascension (degrees) * ``DEC`` is the Declination (degrees) - * :math:`\sigma` == ``Sigma`` (degrees) + * :math:`\sigma` = ``Sigma`` (degrees) + +RadialShell +~~~~~~~~~~~ The ``RadialShell`` model describes a spherical shell projected on the sky @@ -159,6 +168,9 @@ Radial source Elliptical source ^^^^^^^^^^^^^^^^^ +EllipticalDisk +~~~~~~~~~~~~~~ + The ``EllipticalDisk`` model describes a uniform intensity distribution within an elliptical circumference: @@ -185,6 +197,9 @@ Elliptical source * ``MinorRadius`` is the minor radius of the ellipse (degrees) * ``MajorRadius`` is the major radius of the ellipse (degrees) +EllipticalGaussian +~~~~~~~~~~~~~~~~~~ + The ``EllipticalGaussian`` model describes a Gaussian intensity distribution .. code-block:: xml @@ -232,6 +247,9 @@ Elliptical source Diffuse source ^^^^^^^^^^^^^^ +DiffuseIsotropic +~~~~~~~~~~~~~~~~ + The ``DiffuseIsotropic`` model describes an isotropic intensity distribution .. code-block:: xml @@ -253,6 +271,9 @@ Diffuse source For compatibility with the Fermi/LAT ScienceTools the model type ``DiffuseIsotropic`` can be replaced by ``ConstantValue``. +DiffuseMap +~~~~~~~~~~ + The ``DiffuseMap`` model describes an arbitrary intensity distribution in form of a sky map @@ -281,8 +302,15 @@ Diffuse source ``Normalization`` can be replaced by ``Prefactor``. .. note:: - You may add the ``normalize="0"`` to the spatial model tag to avoid the - normalization of the diffuse map to an integral of unity + By default, the diffuse map is normalised so that + + .. math:: + \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega = 1 + + which means that the units of the spatial model component are + :math:`[M_{\rm spatial}] = {\rm sr}^{-1}`. + To avoid the normalisation you may add the ``normalize="0"`` attribute + to the spatial model tag. .. code-block:: xml @@ -295,6 +323,19 @@ Diffuse source + In that case, generally + + .. math:: + \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega \neq 1 + + and the spectral component cannot be directly interpreted as a physical + source intensity. + + .. _um_models_spatial_src_diffuse_cube: + +DiffuseMapCube +~~~~~~~~~~~~~~ + The ``DiffuseMapCube`` model describes an arbitrary energy-dependent intensity distribution in form of a map cube @@ -313,6 +354,18 @@ Diffuse source * ``Normalization`` is a normalization value + Note that the map cube is not normalised to unit, hence generally + + .. math:: + \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega \neq 1 + + To compute the flux in a given energy band for a ``DiffuseMapCube`` model + you have to integrated both the spatial and spectral components, i.e. + + .. math:: + \Phi = \int_{\Omega} \int_{E} M_{\rm spatial}(p|E) \times + M_{\rm spectral}(E)\, d\Omega \, dE + .. note:: For compatibility with the Fermi/LAT ScienceTools the model type ``DiffuseMapCube`` can be replaced by ``MapCubeFunction`` and the parameter