Update 1DC documentation introduction

Jürgen Knödlseder
1 parent c8af36c9
Showing 6 changed files with 84 additions and 35 deletions
doc/source/users/glossary.rst
doc/source/users/tutorials/1dc/data_organisation.rst
doc/source/users/tutorials/1dc/first.rst
doc/source/users/tutorials/1dc/getting_data.rst
doc/source/users/tutorials/1dc/getting_tools.rst
doc/source/users/tutorials/1dc/scope.rst
@@ -11,7 +11,19 @@ Glossary
 .. topic:: First CTA Data Challenge
-   Bla bla ...
+   The goal of the first CTA Data Challenge is to enable the CTA Consortium
+   Science Working Groups to derive science benchmarks for the CTA Key Science
+   objectives.
+
+   The first CTA Data Challenge should provide quantitative estimates of CTA's
+   science capabilities that will enable the CTA Consortium Science Working
+   Groups to evaluate science trade-offs in the future. The first CTA Data
+   Challenge should also result in numerous show cases, including for example
+   images, spectra and light curves, that can be used to illustrate CTA's
+   science case, and that should enrich the CTA outreach material. And the
+   first CTA Data Challenge should also stimulate the enrichment of the CTA
+   Science Case.
+
 .. _glossary_gti:
@@ -3,6 +3,9 @@
 Data organisation
 -----------------
+Layout
+^^^^^^
+
 The content of the ``1dc`` folder should be as follows:
 .. code-block:: bash
@@ -51,11 +54,15 @@ The content of the ``1dc`` folder should be as follows:
    models/map_ics.fits.gz
    models/map_pi0.fits.gz
+
+Instrument Response Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The ``caldb`` folder contains the
 :ref:`Instrument Response Functions <glossary_irf>`
 that are necessary for the analysis of the simulated CTA data.
 The folder contains the ``prod3b`` response that should be used for the
-:ref:`First CTA Data Challenge <glossary_1dc>`.
+:ref:`first CTA Data Challenge <glossary_1dc>`.
 The following response functions are available:
  +-----------------------+-------+---------------+--------+----------+
@@ -110,16 +117,30 @@ The following response functions are available:
  | ``North_TS_z40_0.5h`` | North | Threshold     | 40 deg | 30 min   |
  +-----------------------+-------+---------------+--------+----------+
+.. warning::
+   The **50 hours**
+   :ref:`Instrument Response Functions <glossary_irf>`
+   were used for the **simulation** of the
+   :ref:`first CTA Data Challenge <glossary_1dc>`
+   data. Please use only these response functions for the analysis. If you use
+   :ref:`Observation Definition Files <glossary_obsdef>`
+   for the analysis (see below) the appropriate 50 hours response functions
+   will be used automatically.
+
+
+Event data
+^^^^^^^^^^
+
 The ``data`` folder contains the calibrated, reconstructed and background
 reduced event data that were procuded for the
-:ref:`First CTA Data Challenge <glossary_1dc>`
+:ref:`first CTA Data Challenge <glossary_1dc>`
 and that were stored into FITS files.
 Each event file contains the events for an
 :ref:`observation <glossary_obs>`
 (or run) of 30 minutes duration and comprises an
-:ref:`event lists <glossary_eventlist>`
+:ref:`event list <glossary_eventlist>`
 and a
-:ref:`Good Time Interval <glossary_gti>`
+:ref:`Good Time Intervals <glossary_gti>`
 binary table extension (see figure below).
 .. figure:: event_file.png
@@ -145,7 +166,8 @@ the pointing direction in Right Ascension and Declination (see figure below).
    The pointing direction during an observation is fixed.
 .. warning::
-   Only the following header keywords have meaningful values:
+   Only the following header keywords in the ``EVENTS`` table have meaningful
+   values:
    * ``DATE_OBS`` - start date of observation (UTC)
    * ``TIME_OBS`` - start time of observation (UTC)
@@ -218,12 +240,16 @@ Event files exist for
  | Extragalactic   | Threshold     | ``egal_threshold`` |
  +-----------------+---------------+--------------------+
+
+Observation Definition Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The files ``obs_XXX_YYYYY.xml`` are so called
 :ref:`Observation Definition Files <glossary_obsdef>`
 that contain the information (or metadata) of a list of observations.
-The files are plain ASCII files in XML format that be inspected and
+The files are plain ASCII files in XML format that can be inspected and
 manipulated by any text editor.
-The following files are included in the data distribution:
+The following files are included in the distribution:
  +----------------------------+--------------------------------------------------------+
  | File                       | Purpose                                                |
@@ -245,8 +271,12 @@ The following files are included in the data distribution:
  | ``obs_all_threshold.xml``  | All surveys combined performed with threshold arrays   |
  +----------------------------+--------------------------------------------------------+
+
+Models
+^^^^^^
+
 The ``models`` folder contains the definitions of all source and background
-models that have been used for simulating the data.
+models that were used for simulating the data.
 The file ``models_gc.xml`` is a so called
 :ref:`Model Definition File <glossary_moddef>`
 that collects the definition of all model components used for the Galactic
@@ -255,9 +285,11 @@ The files ``models_gps.xml`` and ``models_egal.xml`` are the equivalent files
 for the Galactic Plane Survey and the Extragalactic Survey.
 The other files in the folder are FITS files containing sky maps that were
 used as spatial templates for modelling extended or diffuse emission components.
-There files are reference in the
-:ref:`Model Definition File <glossary_moddef>`
-files.
+
+.. warning::
+   The FITS template files should always reside in the same folder as the
+   :ref:`model definition XML files <glossary_moddef>`
+   since the latter reference the former.
@@ -4,18 +4,20 @@ First analysis steps
 ====================
 The following sections describe how to analyse data from the
-:ref:`First CTA Data Challenge <glossary_1dc>`
+:ref:`first CTA Data Challenge <glossary_1dc>`
 using ctools.
 If you have never used ctools before or if you have never analysed data from the
-:ref:`First CTA Data Challenge <glossary_1dc>`,
+:ref:`first CTA Data Challenge <glossary_1dc>`,
 this is the place where you should start.
 We assume that you have downloaded the data of the
-:ref:`First CTA Data Challenge <glossary_1dc>`
+:ref:`first CTA Data Challenge <glossary_1dc>`
 and that you have successfully installed the ctools package.
-If this is not the case, please read :ref:`1dc_getting`.
+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>`.
 We also assume that you have read the section about
-:ref:`1dc_data_organisation`.
+:ref:`the data organisation <1dc_data_organisation>`.
 .. toctree::
    :maxdepth: 2
@@ -4,7 +4,7 @@ Getting the data
 ================
 The data for the
-:ref:`First CTA Data Challenge <glossary_1dc>`
+:ref:`first CTA Data Challenge <glossary_1dc>`
 are bundled with the
 :ref:`Instrument Response Functions <glossary_irf>`
 into a single tarball.
@@ -22,7 +22,8 @@ You can then uncompress and deploy the data at any place by typing
    should be typed on the command line of a console.
 After deploying you should have the folder ``1dc`` in your current working
-directory. Within that directory, please set the following environment variables:
+directory. In your current working directory, please type the following to
+set the ``CALDB`` and ``CTADATA`` environment variables:
 .. code-block:: bash
@@ -4,6 +4,7 @@ Getting the analysis tools
 ==========================
 We recommend that you use ctools to analyse the data from the
-:ref:`First CTA Data Challenge <glossary_1dc>`.
+:ref:`first CTA Data Challenge <glossary_1dc>`.
+
 Please read :ref:`getting the ctools <sec_getting>` to learn how to
 install and configure the ctools package.
 .. _1dc_scope:
-Scope of the First CTA Data Challenge
+Scope of the first CTA Data Challenge
 =====================================
 The goal of the
-:ref:`First CTA Data Challenge <glossary_1dc>`
-is to enable the CTA Consortium Science Working Groups to derive science
-benchmarks for the CTA Key Science objectives.
+:ref:`first CTA Data Challenge <glossary_1dc>`
+is to enable the CTA Consortium Science Working Groups to derive **science
+benchmarks** for the CTA Key Science objectives.
+
 The
-:ref:`First CTA Data Challenge <glossary_1dc>`
-should provide quantitative estimates of CTA's science capabilities that
+:ref:`first CTA Data Challenge <glossary_1dc>`
+should provide **quantitative estimates** of CTA's science capabilities that
 will enable the CTA Consortium Science Working Groups to evaluate science
-trade offs in the future.
+trade-offs in the future.
 The
-:ref:`First CTA Data Challenge <glossary_1dc>`
-should also result in numerous show cases, including for example images,
+:ref:`first CTA Data Challenge <glossary_1dc>`
+should also result in numerous **show cases**, including for example images,
 spectra and light curves, that can be used to illustrate CTA's science case,
 and that should enrich the CTA outreach material.
-Last but not least, the
-:ref:`First CTA Data Challenge <glossary_1dc>`
-should also stimulate the enrichment of the CTA Science Case.
+And the
+:ref:`first CTA Data Challenge <glossary_1dc>`
+should also stimulate the **enrichment of the CTA Science Case**.
 The data distributed in the
-:ref:`First CTA Data Challenge <glossary_1dc>`
+:ref:`first CTA Data Challenge <glossary_1dc>`
 are high-level data in form of
 :ref:`event lists <glossary_eventlist>`
 and
@@ -36,10 +37,10 @@ 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
 simulated.
-Data are provided for the Baseline arrays and the Threshold Implementation.
+Data are provided for the baseline arrays and the threshold implementation.
 Three Key Science Projects (KSPs) have been simulated using realistic pointing
-patterns:
+patterns as defined in the CTA Science Case document:
 * the Galactic Plane Scan (GPS)
 * the Galactic Centre Survey (GC)