diff --git a/doc/source/users/tutorials/1dc/data_organisation.rst b/doc/source/users/tutorials/1dc/data_organisation.rst index 1ca8d6a..f5bfe74 100644 --- a/doc/source/users/tutorials/1dc/data_organisation.rst +++ b/doc/source/users/tutorials/1dc/data_organisation.rst @@ -46,7 +46,7 @@ Instrument Response Functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``caldb`` folder contains the -:ref:`Instrument Response Functions ` +:ref:`instrument response functions ` that are necessary for the analysis of the simulated CTA data. The folder contains the ``1dc`` response that should be used for the :ref:`first CTA Data Challenge `. @@ -102,7 +102,7 @@ Each event file contains the events for an :ref:`observation ` and comprises an :ref:`event list ` and a -:ref:`Good Time Intervals ` +:ref:`good time intervals ` binary table extension (see figure below). .. figure:: event_file.png @@ -205,7 +205,7 @@ Observation Definition Files The files ``obs_egal_baseline.xml``, ``obs_gc_baseline.xml``, and ``obs_gps_baseline.xml`` are so called -:ref:`Observation Definition Files ` +:ref:`observation definition files ` containing the information (or metadata) of a list of observations. The file is a plain ASCII files in XML format that can be inspected and manipulated by any text editor. @@ -218,7 +218,7 @@ The ``models`` folder contains the definitions of all source and background models that were used for simulating the data. The files ``models_egal.xml``, ``models_gc.xml`` and ``models_gps.xml`` are so called -:ref:`Model Definition Files ` +:ref:`model definition files ` collecting the definition of all model components used for the three surveys. Since the same sky model was used for all surveys the three files are identical. diff --git a/doc/source/users/tutorials/1dc/first.rst b/doc/source/users/tutorials/1dc/first.rst index 815fb65..abe2546 100644 --- a/doc/source/users/tutorials/1dc/first.rst +++ b/doc/source/users/tutorials/1dc/first.rst @@ -6,13 +6,13 @@ First analysis steps The following sections describe how to analyse data from the :ref:`first CTA Data Challenge ` using ctools. -If you have never used ctools before or if you have never analysed data from the +**If you have never used ctools before or if you have never analysed data from the** :ref:`first CTA Data Challenge `, -this is the place where you should start. +**this is the place where you should start.** We assume that you have downloaded the data of the :ref:`first CTA Data Challenge ` -and that you have successfully installed the ctools package. +and that you have successfully installed and configured the ctools package. If this is not the case, please read :ref:`how to get the tools <1dc_getting_tools>` and :ref:`how to get the data <1dc_getting_data>`. diff --git a/doc/source/users/tutorials/1dc/first_detect.rst b/doc/source/users/tutorials/1dc/first_detect.rst index 9b60081..b6ffb7b 100644 --- a/doc/source/users/tutorials/1dc/first_detect.rst +++ b/doc/source/users/tutorials/1dc/first_detect.rst @@ -59,9 +59,8 @@ There are three model components in the file and each model component is identified using a unique ``name`` attribute. The first two components, ``"Src001"`` and ``"Src002"``, are the two point sources detected by :ref:`cssrcdetect`, the third component, ``"Background"``, is a -background model component of type ``"CTAIrfBackground"``. -The latter component was added because the background model type was set to -``IRF`` in the :ref:`cssrcdetect` run. +background model component of type ``"CTAIrfBackground"`` that was added because +``IRF`` was specified for the ``Background model type`` when running the script. Having a background model component added allows to directly use the :ref:`model definition file ` for a model fitting with :ref:`ctlike`. diff --git a/doc/source/users/tutorials/1dc/first_select_events.rst b/doc/source/users/tutorials/1dc/first_select_events.rst index 72160fe..4b82969 100644 --- a/doc/source/users/tutorials/1dc/first_select_events.rst +++ b/doc/source/users/tutorials/1dc/first_select_events.rst @@ -8,6 +8,10 @@ Selecting the relevant events ... how to **select a subset of events** from the selected observations for your analysis. + The event selection is useful to restrict for example the energy range of + the events or the time interval covered, but also to select only events + within a given radial acceptance region (also called region of interest). + As next step, you have to select the relevant events from the selected observations. You do this with the :ref:`ctselect` tool by typing: @@ -67,7 +71,7 @@ displays a summary of the content of this new There are still 57 observations in the :ref:`observation definition file ` but now the events are restricted to the energy interval 100 GeV - 100 TeV. In -total there are 3 348 255 within this interval in the selected observations. +total there are 3 348 255 events within this interval in the selected observations. The content of ``obs_selected.xml`` will look similar to the content of ``obs.xml`` with the original event list file names replaced by the names of diff --git a/doc/source/users/tutorials/1dc/first_select_obs.rst b/doc/source/users/tutorials/1dc/first_select_obs.rst index d4fb756..8e13919 100644 --- a/doc/source/users/tutorials/1dc/first_select_obs.rst +++ b/doc/source/users/tutorials/1dc/first_select_obs.rst @@ -27,8 +27,8 @@ For the following, make sure that you have set the ``CTADATA`` and ``CALDB`` environment variables as desribed :ref:`here <1dc_getting_data>`. The first step of the analysis consists in selecting the observations from the -:ref:`Observation Definition File ` -``obs_gc_baseline.xml`` that have pointing directions close to the Galactic +:ref:`observation definition file ` +``obs_gps_baseline.xml`` that have pointing directions close to the Galactic Centre. You do this with the :ref:`csobsselect` script by typing: @@ -95,7 +95,7 @@ The output of :ref:`csobsinfo` is shown below. :ref:`csobsselect` selected 2017-06-02T08:10:00: Total livetime ............: 100548.00 s = 1675.80 min = 27.93 h The resulting -:ref:`Observation Definition File ` +:ref:`observation definition file ` will look as follows: .. code-block:: xml @@ -123,5 +123,5 @@ An ```` element contains two parameters: the ``EventList`` parameter that specifies the name of the corresponding event file, and the ``Calibration`` parameter that specifies the -:ref:`Instrument Response Function ` that applies to the +:ref:`instrument response function ` that applies to the event file. diff --git a/doc/source/users/tutorials/1dc/first_skymap.rst b/doc/source/users/tutorials/1dc/first_skymap.rst index f783709..ffd95d4 100644 --- a/doc/source/users/tutorials/1dc/first_skymap.rst +++ b/doc/source/users/tutorials/1dc/first_skymap.rst @@ -53,7 +53,7 @@ is shown below: *Sky map of the events recorded around the Galactic Centre during the Galactic Plane Survey* -The sky map shows a wide-spread distribution of events with a number of sources +The sky map shows a wide-spread distribution of events with several sources superimposed. Many of the events originate from an irreducable background that hampers the recognition of the gamma-ray sources. diff --git a/doc/source/users/tutorials/1dc/first_stacked.rst b/doc/source/users/tutorials/1dc/first_stacked.rst index 7f34c8e..fbf0ac4 100644 --- a/doc/source/users/tutorials/1dc/first_stacked.rst +++ b/doc/source/users/tutorials/1dc/first_stacked.rst @@ -71,11 +71,12 @@ that are queried by the tool. .. note:: - The binning of an exposure cube does not need to correspond to the binning - of a counts cube. In any case, exposure values will be determined by + The binning of the exposure cube does not need to correspond to the binning + of the counts cube. In any case, exposure values will be determined by interpolation from the values stored in the exposure cube file. The same - is true for the point spread function and background cubes described - below. + is true for the point spread function and background cubes that are + described below, or the energy dispersion cube that is described + :ref:`here<1dc_howto_edisp>`. Next, :ref:`ctpsfcube` computes the weighted Point Spread Function of the stacked counts cube. diff --git a/doc/source/users/tutorials/1dc/first_tsmap.png b/doc/source/users/tutorials/1dc/first_tsmap.png index 6f0256e..1761fe4 100644 --- a/doc/source/users/tutorials/1dc/first_tsmap.png +++ b/doc/source/users/tutorials/1dc/first_tsmap.png diff --git a/doc/source/users/tutorials/1dc/getting_data.rst b/doc/source/users/tutorials/1dc/getting_data.rst index fefe497..7c38f2c 100644 --- a/doc/source/users/tutorials/1dc/getting_data.rst +++ b/doc/source/users/tutorials/1dc/getting_data.rst @@ -11,11 +11,11 @@ You need your usual CTA credentials to download the data. The release contains simulated data for the Galactic Plane Survey, the Galactic Centre Survey and the Extragalactic Survey, -:ref:`Instrument Response Functions (IRFs) `, and the +:ref:`instrument response functions (IRFs) `, and the :ref:`model definition files ` that were used for the simulation. In addition, ctools metadata, including -:ref:`Observation Definition Files ` +:ref:`observation definition files ` are available. The data were split into the separate files that can be downloaded diff --git a/doc/source/users/tutorials/1dc/howto_display.rst b/doc/source/users/tutorials/1dc/howto_display.rst index 7f18c73..b548218 100644 --- a/doc/source/users/tutorials/1dc/howto_display.rst +++ b/doc/source/users/tutorials/1dc/howto_display.rst @@ -5,7 +5,8 @@ How to display the results? .. admonition:: You will learn ... - ... how to **display results**. + ... how to **display results** using some example scripts written in + Python and requiring the ``matplotlib`` module. The ctools package does not contain any tools or scripts for graphical display of results since results are generally written into standard FITS @@ -17,19 +18,19 @@ included in the ctools package that rely on the Python module. You can find these scripts in the ``$CTOOLS/share/examples/python`` folder. The following scripts are available: -+------------------------+-----------------------------+ -| Script | Usage | -+========================+=============================+ -| ``show_butterfly.py`` | Display a butterfly diagram | -+------------------------+-----------------------------+ -| ``show_lightcurve.py`` | Display a light curve | -+------------------------+-----------------------------+ -| ``show_obs.py`` | Display observation summary | -+------------------------+-----------------------------+ -| ``show_pointings.py`` | Display pointing directions | -+------------------------+-----------------------------+ -| ``show_spectrum.py`` | Display a spectrum | -+------------------------+-----------------------------+ + +------------------------+-----------------------------+ + | Script | Usage | + +========================+=============================+ + | ``show_butterfly.py`` | Display a butterfly diagram | + +------------------------+-----------------------------+ + | ``show_lightcurve.py`` | Display a light curve | + +------------------------+-----------------------------+ + | ``show_obs.py`` | Display observation summary | + +------------------------+-----------------------------+ + | ``show_pointings.py`` | Display pointing directions | + +------------------------+-----------------------------+ + | ``show_spectrum.py`` | Display a spectrum | + +------------------------+-----------------------------+ Below some usage examples and the expected output: @@ -45,6 +46,16 @@ Below some usage examples and the expected output: .. code-block:: bash + $ $CTOOLS/share/examples/python/show_lightcurve.py lightcurve.fits + +.. figure:: howto_lightcurve.png + :width: 600px + :align: center + + *Light curve displayed with show_lightcurve.py* + +.. code-block:: bash + $ $CTOOLS/share/examples/python/show_obs.py obs_selected.xml .. figure:: howto_display_obs.png diff --git a/doc/source/users/tutorials/1dc/howto_exclude.rst b/doc/source/users/tutorials/1dc/howto_exclude.rst index 5236d3c..cfe97fd 100644 --- a/doc/source/users/tutorials/1dc/howto_exclude.rst +++ b/doc/source/users/tutorials/1dc/howto_exclude.rst @@ -3,6 +3,11 @@ How to exclude pixels from a counts cube? ----------------------------------------- +.. admonition:: You will learn ... + + ... how to **exclude pixels of a counts cube** from an analysis using + the :ref:`ctcubemask` tool. + You can exclude bins in an analysis from a counts cube by using the :ref:`ctcubemask` tool. diff --git a/doc/source/users/tutorials/1dc/howto_extent.rst b/doc/source/users/tutorials/1dc/howto_extent.rst index 2dd67f5..ca44b3e 100644 --- a/doc/source/users/tutorials/1dc/howto_extent.rst +++ b/doc/source/users/tutorials/1dc/howto_extent.rst @@ -3,6 +3,11 @@ How to determine the extension of a source? ------------------------------------------- +.. admonition:: You will learn ... + + ... how you **determine the spatial extent of a source** by fitting an + extended source model to the data. + To determine the spatial extension of a source, an extended source model has to be used in the :ref:`model definition file ` @@ -15,15 +20,16 @@ Note that at the same time the source type has been set to .. code-block:: xml - - - - - + + + + + + - - + + diff --git a/doc/source/users/tutorials/1dc/howto_filtered.png b/doc/source/users/tutorials/1dc/howto_filtered.png index f5ebb2c..8c8f89e 100644 --- a/doc/source/users/tutorials/1dc/howto_filtered.png +++ b/doc/source/users/tutorials/1dc/howto_filtered.png diff --git a/doc/source/users/tutorials/1dc/howto_lightcurve.png b/doc/source/users/tutorials/1dc/howto_lightcurve.png index e6a79c2..68118fb 100644 --- a/doc/source/users/tutorials/1dc/howto_lightcurve.png +++ b/doc/source/users/tutorials/1dc/howto_lightcurve.png diff --git a/doc/source/users/tutorials/1dc/howto_lightcurve.rst b/doc/source/users/tutorials/1dc/howto_lightcurve.rst index 376ad90..2a91283 100644 --- a/doc/source/users/tutorials/1dc/howto_lightcurve.rst +++ b/doc/source/users/tutorials/1dc/howto_lightcurve.rst @@ -3,6 +3,11 @@ How to generate a light curve? ------------------------------ +.. admonition:: You will learn ... + + ... how to **generate a light curve** for a source using the + :ref:`cslightcrv` script. + You can generate a light curve using the :ref:`cslightcrv` script which takes on input an :ref:`event list ` @@ -16,8 +21,8 @@ performs a maximum likelihood analyse for each of the intervals. The analysis results are writted into a light curve FITS file. The following example illustrates how you can generate a light curve for -``Src001`` for the time interval from 59236.810 to 59245.742 (MJD), -corresponding to the dates from 2021-01-22 (19:26:51) to 2021-01-31 (17:48:51) +``Src001`` for the time interval from 59235.5 to 59236.0 (MJD), +corresponding to the dates from 2021-01-21 (12:00:00) to 2021-01-22 (00:00:00) (to convert dates to MJD and vice versa we suggest to use the `xTime Date and Time Conversion Utility `_). The time interval is linearly divided into 100 time bins. @@ -29,22 +34,21 @@ The time interval is linearly divided into 100 time bins. Input model definition XML file [$CTOOLS/share/models/crab.xml] models.xml Source name [Crab] Src001 Algorithm for defining time bins (FILE|LIN|GTI) [GTI] LIN - Lightcurve start time (MJD) [51544.5] 59236.810 - Lightcurve stop time (MJD) [51544.6] 59245.742 - Number of time bins (1-10000) [5] 100 + Lightcurve start time (MJD) [51544.5] 59235.5 + Lightcurve stop time (MJD) [51544.6] 59236.0 + Number of time bins (1-10000) [5] 20 Number of energy bins for binned (0=unbinned) (0-100) [0] Lower energy limit of events (TeV) [0.1] Upper energy limit of events (TeV) [100.0] Output light curve file [lightcurve.fits] -The resulting light curve is shown in the figure below. The gaps in the light -curve correspond to time periods during which ``Src001`` has not been observed. +The resulting light curve is shown in the figure below. .. figure:: howto_lightcurve.png :width: 600px :align: center - *Light curve from 59236.810 to 59245.742 (MJD) for Src001* + *Light curve from 59235.5 to 59236.0 (MJD) for Src001* .. note:: The plot was created using the ``show_lightcurve.py`` script that is diff --git a/doc/source/users/tutorials/1dc/howto_ts.rst b/doc/source/users/tutorials/1dc/howto_ts.rst index 1e6214a..7d17e10 100644 --- a/doc/source/users/tutorials/1dc/howto_ts.rst +++ b/doc/source/users/tutorials/1dc/howto_ts.rst @@ -3,8 +3,13 @@ How to compute the signifiance of a source? ------------------------------------------- -To compute the significance of a given source you need to add the attribute -``tscalc="1"`` to the ```` tag in the +.. admonition:: You will learn ... + + ... how to **compute the significance of a source detection** using the + :ref:`ctlike` tool. + +To compute the detection significance of a given source you need to add the +attribute ``tscalc="1"`` to the ```` tag in the :ref:`model definition file ` and execute :ref:`ctlike` using this file. The structure of the XML file with significance computation requested for @@ -15,14 +20,16 @@ The structure of the XML file with significance computation requested for - - - - + + + + + - - - + + + + ... @@ -37,26 +44,20 @@ For :math:`p=1`, the source significance is the square root of the Test Statistic. An excerpt of the :ref:`ctlike` log file is shown below where signifance -computation was requested for ``Src001`` and ``Src002`` and the diffuse -Galactic emission component ``IEM``. The computation has been done using -a stacked analysis. +computation was requested for ``Src001`` and ``Src002``. The computation was +done using a stacked analysis. .. code-block:: bash - 2017-03-03T23:36:07: === GModelSky === - 2017-03-03T23:36:07: Name ......................: Src001 - 2017-03-03T23:36:07: Instruments ...............: all - 2017-03-03T23:36:07: Test Statistic ............: 12650.600597267 - ... - 2017-03-03T23:36:07: === GModelSky === - 2017-03-03T23:36:07: Name ......................: Src002 - 2017-03-03T23:36:07: Instruments ...............: all - 2017-03-03T23:36:07: Test Statistic ............: 2154.31897658715 + 2017-06-02T10:54:10: === GModelSky === + 2017-06-02T10:54:10: Name ......................: Src001 + 2017-06-02T10:54:10: Instruments ...............: all + 2017-06-02T10:54:10: Test Statistic ............: 8845.82638467156 ... - 2017-03-03T23:36:07: === GModelSky === - 2017-03-03T23:36:07: Name ......................: IEM - 2017-03-03T23:36:07: Instruments ...............: all - 2017-03-03T23:36:07: Test Statistic ............: 43070.3063685261 + 2017-06-02T10:54:10: === GModelSky === + 2017-06-02T10:54:10: Name ......................: Src002 + 2017-06-02T10:54:10: Instruments ...............: all + 2017-06-02T10:54:10: Test Statistic ............: 1437.33551948087 The Test Statistic values are also written into the :ref:`model definition file ` @@ -66,13 +67,10 @@ created by :ref:`ctlike`: - - ... - - + ... - + ... ... diff --git a/doc/source/users/tutorials/1dc/howto_tsmap.rst b/doc/source/users/tutorials/1dc/howto_tsmap.rst index 4637c7d..eaa06ae 100644 --- a/doc/source/users/tutorials/1dc/howto_tsmap.rst +++ b/doc/source/users/tutorials/1dc/howto_tsmap.rst @@ -3,6 +3,11 @@ How to generate a Test Statistic map? ------------------------------------- +.. admonition:: You will learn ... + + ... how to **generate a map of source detection significances** using the + :ref:`cttsmap` tool. + If you want to know how the Test Statistic changes with source position you can create a Test Statistic map using the :ref:`cttsmap` tool. A Test Statistic map is for example useful to study the precise error contours of @@ -21,14 +26,14 @@ map of size 0.5 x 0.5 degrees, centred on the Galactic Centre. Input background cube file (only needed for stacked analysis) [NONE] bkgcube.fits Test source name [Crab] Src001 Input model definition XML file [$CTOOLS/share/models/crab.xml] stacked_models.xml - First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 0 - Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 0 - Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] + First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 0.0 + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 0.0 + Projection method (AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN) [CAR] Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] GAL Image scale (in degrees/pixel) [0.02] 0.05 Size of the X axis in pixels [200] 10 Size of the Y axis in pixels [200] 10 - Output Test Statistic map file [tsmap.fits] tsmap_stacked.fits + Output Test Statistic map file [tsmap.fits] The :ref:`cttsmap` tool creates a FITS file containing for each pixel the Test Statistic value as well as the fit parameters for the test source. @@ -85,16 +90,16 @@ The figure below shows the resulting Test Statistic map. .. code-block:: bash - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=0 binmax=10 outmap=tsmap_split_0.fits logfile=tsmap_split_0.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=10 binmax=20 outmap=tsmap_split_1.fits logfile=tsmap_split_1.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=20 binmax=30 outmap=tsmap_split_2.fits logfile=tsmap_split_2.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=30 binmax=40 outmap=tsmap_split_3.fits logfile=tsmap_split_3.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=40 binmax=50 outmap=tsmap_split_4.fits logfile=tsmap_split_4.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=50 binmax=60 outmap=tsmap_split_5.fits logfile=tsmap_split_5.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=60 binmax=70 outmap=tsmap_split_6.fits logfile=tsmap_split_6.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=70 binmax=80 outmap=tsmap_split_7.fits logfile=tsmap_split_7.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=80 binmax=90 outmap=tsmap_split_8.fits logfile=tsmap_split_8.log & - cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL xref=0.0 yref=0.0 proj=CAR publish=no chatter=2 clobber=yes debug=no mode=ql logL0=1082619.2527136307 binmin=90 binmax=100 outmap=tsmap_split_9.fits logfile=tsmap_split_9.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=0 binmax=10 outmap=tsmap_split_0.fits logfile=tsmap_split_0.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=10 binmax=20 outmap=tsmap_split_1.fits logfile=tsmap_split_1.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=20 binmax=30 outmap=tsmap_split_2.fits logfile=tsmap_split_2.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=30 binmax=40 outmap=tsmap_split_3.fits logfile=tsmap_split_3.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=40 binmax=50 outmap=tsmap_split_4.fits logfile=tsmap_split_4.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=50 binmax=60 outmap=tsmap_split_5.fits logfile=tsmap_split_5.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=60 binmax=70 outmap=tsmap_split_6.fits logfile=tsmap_split_6.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=70 binmax=80 outmap=tsmap_split_7.fits logfile=tsmap_split_7.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=80 binmax=90 outmap=tsmap_split_8.fits logfile=tsmap_split_8.log & + cttsmap inobs=cntcube.fits inmodel=stacked_models.xml srcname=Src001 expcube=expcube.fits psfcube=psfcube.fits bkgcube=bkgcube.fits edisp=no errors=no usepnt=no nxpix=10 nypix=10 binsz=0.05 coordsys=GAL proj=CAR xref=0.0 yref=0.0 publish=no chatter=2 clobber=yes debug=no mode=ql logL0=-227629.3114637738 binmin=90 binmax=100 outmap=tsmap_split_9.fits logfile=tsmap_split_9.log & Now run the ASCII file by typing @@ -111,6 +116,3 @@ The figure below shows the resulting Test Statistic map. $ cstsmapmerge Input TS map FITS files [tsmap.fits] tsmap_split_*.fits Output TS map FITS file [NONE] tsmap_split.fits - - - diff --git a/doc/source/users/tutorials/1dc/howto_ulimit.rst b/doc/source/users/tutorials/1dc/howto_ulimit.rst index e61f079..b49f1a8 100644 --- a/doc/source/users/tutorials/1dc/howto_ulimit.rst +++ b/doc/source/users/tutorials/1dc/howto_ulimit.rst @@ -3,6 +3,11 @@ How to compute upper limits? ---------------------------- +.. admonition:: You will learn ... + + ... how to **determine the upper flux limit for a source** using the + :ref:`ctulimit` tool. + You determine upper limits for gamma-ray sources using the :ref:`ctulimit` tool. @@ -39,7 +44,7 @@ and then run the :ref:`ctulimit` as follows: Input PSF cube file (only needed for stacked analysis) [NONE] psfcube.fits Input background cube file (only needed for stacked analysis) [NONE] bkgcube.fits Source of interest [Crab] Test - Input model definition XML file [$CTOOLS/share/models/crab.xml] stacked_models_iem_ul.xml + Input model definition XML file [$CTOOLS/share/models/crab.xml] stacked_models-cutoff-iem-up.xml After the run, the upper gamma-ray flux limit for this test source can be extracted from the :ref:`ctulimit` log file: diff --git a/doc/source/users/tutorials/1dc/howto_vo.rst b/doc/source/users/tutorials/1dc/howto_vo.rst index 9bac9e1..7eb0950 100644 --- a/doc/source/users/tutorials/1dc/howto_vo.rst +++ b/doc/source/users/tutorials/1dc/howto_vo.rst @@ -3,6 +3,13 @@ How to use Virtual Observatory tools with ctools? ------------------------------------------------- +.. admonition:: You will learn ... + + ... how to interaction with Virtual Observatory tools such as + `Aladin `_ + or + `Topcat `_. + Several ctools can interact with Virtual Observatory tools such as `Aladin `_ or @@ -15,7 +22,7 @@ Let's take the example of generating a sky map, as explained application on your desktop: .. figure:: howto_vo_aladin_before.png - :width: 400px + :width: 600px :align: center *Aladin application after start-up* @@ -45,7 +52,7 @@ appear in the application (see below). .. figure:: howto_vo_aladin_after.png - :width: 400px + :width: 600px :align: center *Aladin application after ctskymap finished execution* @@ -58,47 +65,90 @@ catalogue which allows us to identify ``Src001`` with a Fermi/LAT source at the Galactic centre. .. figure:: howto_vo_aladin_catalog.png - :width: 400px + :width: 600px :align: center *Overlay of the Fermi/LAT 3FGL catalogue over the sky map* -Below the list of tools and scripts that interact with Virtual Observatory -tools. Some tools or scripts publish tables instead of images, and the tables -can for example by displayed and explored using +Another example is the display of an event list using `Topcat `_. +Start with launching the +`Topcat `_ +application on your desktop: -+-------------------+--------+-------------------+ -| Tool or script | Object | VO tool (example) | -+===================+========+===================+ -| :ref:`cslightcrv` | Table | Topcat | -+-------------------+--------+-------------------+ -| :ref:`csresmap` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`csspec` | Table | Topcat | -+-------------------+--------+-------------------+ -| :ref:`csviscube` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`ctbin` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`ctbkgcube` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`ctcubemask` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`ctexpcube` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`ctmapcube` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`ctmodel` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`ctobssim` | Table | Topcat | -+-------------------+--------+-------------------+ -| :ref:`ctselect` | Table | Topcat | -+-------------------+--------+-------------------+ -| :ref:`ctskymap` | Image | Aladin | -+-------------------+--------+-------------------+ -| :ref:`cttsmap` | Image | Aladin | -+-------------------+--------+-------------------+ +.. figure:: howto_vo_topcat_before.png + :width: 600px + :align: center + + *Topcat application after start-up* +Then run :ref:`ctselect` for event selection and specify ``publish=yes`` as +argument after the tool name: + +.. code-block:: bash + $ ctselect publish=yes + Input event list or observation definition XML file [selected_gps_baseline_120380.fits] + RA for ROI centre (degrees) (0-360) [UNDEFINED] + Start time (CTA MET in seconds) [UNDEFINED] + Lower energy limit (TeV) [0.2] + Upper energy limit (TeV) [50.0] + Output event list or observation definition XML file [selected_gps_baseline_120380_0.2-50TeV.fits] + +Once :ref:`ctselect` has terminated, the resulting event list will automatically +appear in the +`Topcat `_ +application (see below). + +.. figure:: howto_vo_topcat_after.png + :width: 600px + :align: center + + *Topcat application after ctselect finished execution* + +You can now open the 3-dimensional display tab and visualise the data in +a coordinate system that is spanned by Right Ascension, Declination and +energy (see below). + +.. figure:: howto_vo_topcat_scatter.png + :width: 600px + :align: center + + *Display of event list in 3-dimensional representation* + +Below the list of tools and scripts that interact with Virtual Observatory +tools. Some tools or scripts publish tables instead of images, and the tables +can for example by displayed and explored using +`Topcat `_. + +-------------------+--------+-------------------+ + | Tool or script | Object | VO tool (example) | + +===================+========+===================+ + | :ref:`cslightcrv` | Table | Topcat | + +-------------------+--------+-------------------+ + | :ref:`csresmap` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`csspec` | Table | Topcat | + +-------------------+--------+-------------------+ + | :ref:`csviscube` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`ctbin` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`ctbkgcube` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`ctcubemask` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`ctexpcube` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`ctmapcube` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`ctmodel` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`ctobssim` | Table | Topcat | + +-------------------+--------+-------------------+ + | :ref:`ctselect` | Table | Topcat | + +-------------------+--------+-------------------+ + | :ref:`ctskymap` | Image | Aladin | + +-------------------+--------+-------------------+ + | :ref:`cttsmap` | Image | Aladin | + +-------------------+--------+-------------------+ diff --git a/doc/source/users/tutorials/1dc/howto_vo_aladin_after.png b/doc/source/users/tutorials/1dc/howto_vo_aladin_after.png index 1ceb1fb..8611126 100644 --- a/doc/source/users/tutorials/1dc/howto_vo_aladin_after.png +++ b/doc/source/users/tutorials/1dc/howto_vo_aladin_after.png diff --git a/doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png b/doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png index 77c4358..9fdbf75 100644 --- a/doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png +++ b/doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png diff --git a/doc/source/users/tutorials/1dc/howto_vo_topcat_after.png b/doc/source/users/tutorials/1dc/howto_vo_topcat_after.png new file mode 100644 index 0000000..62cb9fb --- /dev/null +++ b/doc/source/users/tutorials/1dc/howto_vo_topcat_after.png diff --git a/doc/source/users/tutorials/1dc/howto_vo_topcat_before.png b/doc/source/users/tutorials/1dc/howto_vo_topcat_before.png new file mode 100644 index 0000000..7dbfcef --- /dev/null +++ b/doc/source/users/tutorials/1dc/howto_vo_topcat_before.png diff --git a/doc/source/users/tutorials/1dc/howto_vo_topcat_scatter.png b/doc/source/users/tutorials/1dc/howto_vo_topcat_scatter.png new file mode 100644 index 0000000..07aac72 --- /dev/null +++ b/doc/source/users/tutorials/1dc/howto_vo_topcat_scatter.png diff --git a/doc/source/users/tutorials/1dc/scope.rst b/doc/source/users/tutorials/1dc/scope.rst index f80344a..f4882fc 100644 --- a/doc/source/users/tutorials/1dc/scope.rst +++ b/doc/source/users/tutorials/1dc/scope.rst @@ -6,7 +6,7 @@ Scope of the first CTA Data Challenge The goal of the :ref:`first CTA Data Challenge ` is to enable the CTA Consortium Science Working Groups to derive **science -benchmarks** for the CTA Key Science objectives. +benchmarks** for the CTA Key Science Projects. The :ref:`first CTA Data Challenge ` @@ -27,26 +27,30 @@ The data distributed in the are high-level data in form of :ref:`event lists ` and -:ref:`Instrument Response Functions ` +:ref:`instrument response functions ` (data level 3). The :ref:`event lists ` -have been simulated from high-level -:ref:`Instrument Response Functions ` +were simulated from high-level +:ref:`instrument response functions ` that correspond to an ideal CTA with good and stable atmosphere and instrument -conditions; only zenith angles of 20 degrees and 40 degrees have been +conditions; only zenith angles of 20 degrees and 40 degrees were simulated. Data are provided for the baseline arrays. So far only data for the South array -were simulated. +were simulated, data for the North array will be provided once the +:ref:`instrument response functions ` +for the North array are available. Three Key Science Projects (KSPs) were simulated using realistic pointing patterns as defined in the CTA Science Case document: * the Galactic Plane Scan (GPS) * the Galactic Centre Survey (GC) -* the extragalactic survey +* the Extragalactic Survey (EGAL) The source model used for the simulations is distributed together with the data to the CTA Consortium Science Working Groups, so that analysis results -can be compared to the Monte Carlo truth. +can be compared to the Monte Carlo truth. The same source model was used for +the simulation of all three surveys. +