diff --git a/cscripts/Makefile.am b/cscripts/Makefile.am index 52ce856..8cc586c 100644 --- a/cscripts/Makefile.am +++ b/cscripts/Makefile.am @@ -112,6 +112,7 @@ testscripts = $(srcdir)/tests/__init__.py \ $(top_srcdir)/test/test_csobs2caldb.py \ $(top_srcdir)/test/test_csobsdef.py \ $(top_srcdir)/test/test_csobsinfo.py \ + $(top_srcdir)/test/test_csobsselect.py \ $(top_srcdir)/test/test_cslightcrv.py \ $(top_srcdir)/test/test_cspull.py \ $(top_srcdir)/test/test_csresmap.py \ diff --git a/doc/source/_templates/index.html b/doc/source/_templates/index.html index 9e0d866..266b7d0 100644 --- a/doc/source/_templates/index.html +++ b/doc/source/_templates/index.html @@ -48,10 +48,12 @@ and next steps, and advance with the coding of the software. {%endtrans%}

{%trans%}Documentation{%endtrans%}

@@ -59,8 +61,8 @@ and next steps, and advance with the coding of the software. {%endtrans%}

{%trans%}Links{%endtrans%}

diff --git a/doc/source/users/glossary.rst b/doc/source/users/glossary.rst new file mode 100644 index 0000000..c31e721 --- /dev/null +++ b/doc/source/users/glossary.rst @@ -0,0 +1,38 @@ +Glossary +======== + +.. _glossary_eventlist: + +.. topic:: Event list + + Bla bla ... + +.. _glossary_1dc: + +.. topic:: First CTA Data Challenge + + Bla bla ... + +.. _glossary_irf: + +.. topic:: Instrument Response Functions + + Bla bla ... + +.. _glossary_moddef: + +.. topic:: Model definition file + + Bla bla ... + +.. _glossary_obs: + +.. topic:: Observation + + Bla bla ... + +.. _glossary_obsdef: + +.. topic:: Observation definition file + + Bla bla ... diff --git a/doc/source/users/index.rst b/doc/source/users/index.rst index 5da0e8e..0a5c683 100644 --- a/doc/source/users/index.rst +++ b/doc/source/users/index.rst @@ -6,9 +6,11 @@ User Documentation .. toctree:: :maxdepth: 2 + tutorials/index user_manual/index reference_manual/index faq issues + glossary release_history/index help diff --git a/doc/source/users/tutorials/1dc/first.rst b/doc/source/users/tutorials/1dc/first.rst new file mode 100644 index 0000000..568b5b9 --- /dev/null +++ b/doc/source/users/tutorials/1dc/first.rst @@ -0,0 +1,27 @@ +.. _1dc_first: + +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 +:ref:`First CTA Data Challenge `, +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. +If this is not the case, please read :ref:`1dc_getting`. + +.. toctree:: + :maxdepth: 2 + + first_data + first_select_obs + first_skymap + first_select_models + first_fitting + first_residuals + first_stacked diff --git a/doc/source/users/tutorials/1dc/first_data.rst b/doc/source/users/tutorials/1dc/first_data.rst new file mode 100644 index 0000000..17363fa --- /dev/null +++ b/doc/source/users/tutorials/1dc/first_data.rst @@ -0,0 +1,109 @@ +.. _1dc_first_data: + +Data organisation +----------------- + +After downloading the +:ref:`First CTA Data Challenge ` +data from **TBD** and uncompressing the tarball using + +.. code-block:: bash + + $ tar xfvz 1dc.tar.gz + +you will have a directory ``1dc`` on your disk with the following content: + +.. code-block:: bash + + caldb/ + caldb/data + caldb/data/cta + caldb/data/cta/prod2 + ... + caldb/data/cta/prod3 + caldb/data/cta/prod3/caldb.indx + caldb/data/cta/prod3/bcf + ... + data/ + data/gps_baseline_000001.fits + data/gps_baseline_000002.fits + data/gps_baseline_000003.fits + ... + data/gps_threshold_000001.fits + data/gps_threshold_000002.fits + data/gps_threshold_000003.fits + ... + data/egal_baseline_000001.fits + data/egal_baseline_000002.fits + data/egal_baseline_000003.fits + ... + data/egal_threshold_000001.fits + data/egal_threshold_000002.fits + data/egal_threshold_000003.fits + ... + data/obs_gps_baseline.xml + data/obs_gps_threshold.xml + data/obs_egal_baseline.xml + data/obs_egal_threshold.xml + data/obs_all_baseline.xml + data/obs_all_threshold.xml + models/ + models/models_gps.xml + models/models_egal.xml + models/map_RXJ1713.fits.gz + models/map_VelaJunior.fits.gz + models/map_ics.fits.gz + models/map_pi0.fits.gz + +The ``caldb`` folder contains the +:ref:`Instrument Response Functions ` +that are necessary for the analysis of the simulated CTA data. +The folder contains the ``prod3`` response that should be used for the +:ref:`First CTA Data Challenge `. +For legacy reasons, also the ``prod2`` response functions are shipped with +the tarball. + +The ``data`` folder contains the calibrated, reconstructed and background +reduced event data that were procuded for the +:ref:`First CTA Data Challenge `. +Each event file corresponds to the +:ref:`event lists ` +for an +:ref:`observation (or run) `, and contains for each event a +time stamp, the reconstructued photon arrival direction, and the reconstructed +photon energy. +The pointing direction during an observation is fixed. +Event files exist for the Galactic Plane Survey (starting with ``gps_``) and +for the extragalactic survey (starting with ``egal_``) for both +the ``baseline`` configuration and the ``threshold`` implementation. + +The files ``obs_XXX_YYYYY.xml`` are so called +:ref:`Observation Definition Files ` +that contain the information (or metadata) of a list of observations. +The files are plain ASCII files in XML format that be inspected and +manipulated by any text editor. +The following files are included in the data distribution: + +* ``obs_gps_baseline.xml``: Galactic Plane Survey performed with baseline arrays +* ``obs_gps_threshold.xml``: Galactic Plane Survey performed with threshold implementation +* ``obs_egal_baseline.xml``: Extragalactic Survey performed with baseline arrays +* ``obs_egal_threshold.xml``: Extragalactic Survey performed with threshold implementation +* ``obs_all_baseline.xml``: Both surveys performed with baseline arrays +* ``obs_all_threshold.xml``: Both surveys performed with threshold implementation + +The ``models`` folder contains the definitions of all source and background +models that have been used for simulating the data. +The file ``models_gps.xml`` is a so called +:ref:`Model Definition File ` +that collects the definition of all model components used for the Galactic +Plane Survey simulation. +The file ``models_egal.xml`` is the equivalent file for 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 ` +files. + + + diff --git a/doc/source/users/tutorials/1dc/first_fitting.rst b/doc/source/users/tutorials/1dc/first_fitting.rst new file mode 100644 index 0000000..d5cc60a --- /dev/null +++ b/doc/source/users/tutorials/1dc/first_fitting.rst @@ -0,0 +1,11 @@ +.. _1dc_first_fitting: + +Fitting the model components to the data +---------------------------------------- + +.. code-block:: bash + + $ ctlike + Input event list, counts cube or observation definition XML file [events.fits] obs.xml + Input model XML file [$CTOOLS/share/models/crab.xml] models.xml + Output model XML file [crab_results.xml] results.xml diff --git a/doc/source/users/tutorials/1dc/first_residuals.rst b/doc/source/users/tutorials/1dc/first_residuals.rst new file mode 100644 index 0000000..59550af --- /dev/null +++ b/doc/source/users/tutorials/1dc/first_residuals.rst @@ -0,0 +1,21 @@ +.. _1dc_first_residuals: + +Inspecting the residuals +------------------------ + +.. code-block:: bash + + $ csresmap + Input event list, counts cube, or observation definition XML file [obs.xml] + Input model XML file [results.xml] + First coordinate of image center in degrees (RA or galactic l) (0-360) [0.0] + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [0.0] + Lower energy limit (TeV) [0.1] + Upper energy limit (TeV) [100.0] + Coordinate System (CEL|GAL) [GAL] + Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] + Size of the X axis in pixels [200] + Size of the Y axis in pixels [200] 100 + Pixel size (deg/pixel) [0.1] 0.05 + Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUB] + Output residual map file [resmap.fits] diff --git a/doc/source/users/tutorials/1dc/first_select_models.rst b/doc/source/users/tutorials/1dc/first_select_models.rst new file mode 100644 index 0000000..7e3dc68 --- /dev/null +++ b/doc/source/users/tutorials/1dc/first_select_models.rst @@ -0,0 +1,11 @@ +.. _1dc_select_models: + +Selecting the relevant model components +--------------------------------------- + +.. code-block:: bash + + $ csmodelselect fluxlimit=1.0e-10 + Input event list or observation definition XML file [obs.xml] + Input model definition XML file [inmodel.xml] ../models/models_gps.xml + Output model definition XML file [outmodel.xml] models.xml diff --git a/doc/source/users/tutorials/1dc/first_select_obs.rst b/doc/source/users/tutorials/1dc/first_select_obs.rst new file mode 100644 index 0000000..da22883 --- /dev/null +++ b/doc/source/users/tutorials/1dc/first_select_obs.rst @@ -0,0 +1,71 @@ +.. _1dc_first_select_obs: + +Selecting the relevant observations +----------------------------------- + +Let us in the following assume that you want to analyse the Galactic Plane +Survey data obtained with baseline arrays around the Galactic Centre. +For the purpose of this first analysis, you should create a subfolder under +the ``1dc`` folder (or any other convenient place) that will contain the +results for your first analysis. +You do this by typing: + +.. code-block:: bash + + $ cd 1dc + $ mkdir my_first_analysis + $ cd my_first_analysis + +The first step of the analysis consists in selecting the observations from the +: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: + +.. code-block:: bash + + $ csobsselect + Input event list or observation definition XML file [obs.xml] ../data/obs_gps_baseline.xml + Pointing selection region shape (CIRCLE|BOX) [CIRCLE] + Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] GAL + Galactic longitude of selection centre (deg) (0-360) [184.56] 0.0 + Galactic latitude of selection centre (deg) (-90-90) [-5.79] 0.0 + Radius of selection circle (deg) (0-180) [5.0] + Output observation definition XML file [outobs.xml] obs.xml + +You selected ``CIRCLE`` as the shape of the pointing selection region, +specified the Galactic Centre as the centre of the selection region, and +selected all observations with pointing directions within 5 degrees from +the Galactic Centre from the ``obs_gps_baseline.xml`` file. +The selected observations are written into the file ``obs.xml`` that will be +created in the ``my_first_analysis`` folder. +The content of the file will look as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + ... + + +Each ```` element corresponds to one observation that is identified +by a name attribute and a unique identifier attribute. +An ```` element contains two parameters: +the ``EventList`` parameter that specifies the name of the corresponding event +file relative to the current working directory, and +the ``Calibration`` parameter that specifies the +:ref:`Instrument Response Function ` that applies to the +event file. + diff --git a/doc/source/users/tutorials/1dc/first_skymap.png b/doc/source/users/tutorials/1dc/first_skymap.png new file mode 100644 index 0000000..2520697 --- /dev/null +++ b/doc/source/users/tutorials/1dc/first_skymap.png diff --git a/doc/source/users/tutorials/1dc/first_skymap.rst b/doc/source/users/tutorials/1dc/first_skymap.rst new file mode 100644 index 0000000..5976cad --- /dev/null +++ b/doc/source/users/tutorials/1dc/first_skymap.rst @@ -0,0 +1,40 @@ +.. _1dc_sky_map: + +Generating a sky map from the events +------------------------------------ + +Once the observations are selected, the first thing that you want to do is to +visualize the content of the observations by generating a sky map from the +events. +You do this with the :ref:`ctskymap` tool by typing: + +.. code-block:: bash + + $ ctskymap + Input event list or observation definition XML file [events.fits] obs.xml + 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|MER|MOL|STG|TAN) [CAR] + Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] GAL + Image scale (in degrees/pixel) [0.02] + Size of the X axis in pixels [200] 500 + Size of the Y axis in pixels [200] 250 + Lower energy limit (TeV) [0.1] + Upper energy limit (TeV) [100.0] + Output skymap file [skymap.fits] + +We generate here a sky map centred on the Galactic Centre in Galactic +coordinates using a cartesian projection. +The sky map is 10° wide and 5° high, with an image scale of 0.02° per pixel. +All events between 0.1 and 100 TeV have been collected in the skymap. +The :ref:`ctskymap` tool writes the result into the FITS file ``skymap.fits`` +that will be created in the ``my_first_analysis`` folder. +The FITS file can be displayed using for example ds9 (see below): + +.. figure:: first_skymap.png + :width: 600px + :align: center + + *Sky map of the events recorded during the Galactic Plane Survey around the Galactic Centre* + +Bla diff --git a/doc/source/users/tutorials/1dc/first_stacked.rst b/doc/source/users/tutorials/1dc/first_stacked.rst new file mode 100644 index 0000000..9f6c12a --- /dev/null +++ b/doc/source/users/tutorials/1dc/first_stacked.rst @@ -0,0 +1,6 @@ +.. _1dc_first_stacked: + +Performing a stacked analysis +----------------------------- + +To be written ... diff --git a/doc/source/users/tutorials/1dc/getting.rst b/doc/source/users/tutorials/1dc/getting.rst new file mode 100644 index 0000000..18163a9 --- /dev/null +++ b/doc/source/users/tutorials/1dc/getting.rst @@ -0,0 +1,15 @@ +.. _1dc_getting: + +Getting the data and analysis tools +=================================== + +Getting the data +---------------- + +To be written ... + + +Getting the analysis tools +-------------------------- + +To be written ... diff --git a/doc/source/users/tutorials/1dc/index.rst b/doc/source/users/tutorials/1dc/index.rst new file mode 100644 index 0000000..425dede --- /dev/null +++ b/doc/source/users/tutorials/1dc/index.rst @@ -0,0 +1,12 @@ +.. _1dc: + +First CTA Data Challenge +======================== + +.. toctree:: + :maxdepth: 2 + + scope + getting + first + diff --git a/doc/source/users/tutorials/1dc/scope.rst b/doc/source/users/tutorials/1dc/scope.rst new file mode 100644 index 0000000..436747d --- /dev/null +++ b/doc/source/users/tutorials/1dc/scope.rst @@ -0,0 +1,38 @@ +.. _1dc_scope: + +Scope of the First CTA Data Challenge +===================================== + +The primary goal of the +:ref:`First CTA Data Challenge ` +is to make the members of the CTA Consortium Science Working Groups familiar +with the CTA data format and tools and to stimulate the simulation and +benchmarking activities in the groups. +A secondary goal is to test CTA Science Analysis tools and to provide User +feedback to the code developers. + +The data distributed in the +:ref:`First CTA Data Challenge ` +are high-level data in form of +:ref:`event lists ` +and +:ref:`Instrument Response Functions ` +(data level 3). +The +:ref:`event lists ` +have been 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° and 40° **(TBC)** have been simulated. + +Data are provided for the Baseline arrays and the Threshold Implementation. + +Two Key Science Projects (KSPs) have been simulated using realistic pointing +patterns: + +* the Galactic Plane Scan (GPS) +* the extragalactic survey + +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. diff --git a/doc/source/users/tutorials/index.rst b/doc/source/users/tutorials/index.rst new file mode 100644 index 0000000..64977c0 --- /dev/null +++ b/doc/source/users/tutorials/index.rst @@ -0,0 +1,9 @@ +.. _tutorials: + +Tutorials +========= + +.. toctree:: + :maxdepth: 2 + + 1dc/index