Cleanup of PR gammapy#319: re-structure high-level docs, change a_la_…

…michi option for method.

docs/background/make_models.rst

@@ -1,4 +1,4 @@
-.. _background_make_models:
+.. _background_make_background_models:
 
 Make background models
 ======================
@@ -67,55 +67,16 @@ The output files are created in the output directory:
   visualization using eg. ``DS9``. The table files contain also a
   counts (events) and a livetime correction data cubes.
 
-.. _background_make_models_datasets_for_testing:
+In order to compare 2 sets of background cube models, the following
+script in the `examples` directory can be used:
+:download:`plot_bg_cube_model_comparison.py
+<../../examples/plot_bg_cube_model_comparison.py>`
 
 Datasets for testing
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
-In order to test the background generation tools, either real data
-from an existing experiment such as H.E.S.S. can be used. Since the
-data of current experiments is not public. Rudimentary tools to
+In order to test the background model generation tools, real
+data from existing experiments such as H.E.S.S. can be used. Since
+the data of current experiments is not public, rudimentary tools to
 prepare a dummy dataset have been placed in Gammapy:
-
-* `~gammapy.datasets.make_test_dataset`: function to produce a dummy
-  observation list and its corresponding dataset
-  consisting on event lists and effective area tables and store
-  everything on disk.
-
-* `~gammapy.datasets.make_test_eventlist`: function called
-  recursivelly by `~gammapy.datasets.make_test_dataset` to produce
-  the data (event lists and effective area table)corresponding to
-  one observation.
-
-They are very easy to use. A H.E.S.S.-like test dataset can be
-produced with a few lines of python code:
-
-.. code-block:: python
-
-    fits_path = '/path/to/fits/event_lists/base/dir'
-    observatory_name = 'HESS'
-    n_obs = 2
-    random_state = np.random.RandomState(seed=0)
-
-    make_test_dataset(fits_path=fits_path,
-                      observatory_name=observatory_name,
-                      n_obs=n_obs,
-                      random_state=random_state)
-
-Then the data can be read back using the `~gammapy.obs.DataStore`
-class, and eg. print the observation table and the names of the filescreated with a few extra lines of python code:
-
-.. code-block:: python
-
-    scheme = 'HESS'
-    data_store = DataStore(dir=fits_path, scheme=scheme)
-    observation_table = data_store.make_observation_table()
-    print(observation_table)
-    event_list_files = data_store.make_table_of_files(observation_table,
-                                                      filetypes=['events'])
-    aeff_table_files = data_store.make_table_of_files(observation_table,
-                                                      filetypes=['effective area'])
-    for i_ev_file, i_aeff_file in zip(event_list_files['filename'],
-                                      aeff_table_files['filename']):
-        print(' ev infile: {}'.format(i_ev_file))
-        print(' aeff infile: {}'.format(i_aeff_file))
+:ref:`datasets_make_datasets_for_testing`.

docs/background/models.rst

@@ -1,13 +1,13 @@
 .. _bg_models:
 
-Background Models
+Background models
 =================
 
 The naming of the models in this section follows the convention from
 :ref:`dataformats_overview`.
 
 The documentation on how to produce background models in Gammapy is
-available at :ref:`background_make_models`.
+available at :ref:`background_make_background_models`.
 
 .. _background_3D:
 
@@ -20,16 +20,44 @@ given in detector coordinates **(DETX, DETY)**, a.k.a.
 **nominal system**. This is a tangential system to the instrument
 during observations.
 
-The `~gammapy.background.CubeBackgroundModel` is used as container class for this model.
-It has methods to read, write and operate the 3D cubes.
+Two classes are used as container for this model:
 
-For the moment, only I/O and visualization methods are implemented.
-A test file is located in the `~gammapy-extra` repository
-(`bg_cube_model_test.fits <https://github.com/gammapy/gammapy-extra/blob/master/test_datasets/background/bg_cube_model_test.fits>`_).
-The file has been produced with `~gammapy.datasets.make_test_bg_cube_model`.
+* The `~gammapy.background.Cube` class is used as base container for
+  cubes. It has generic methods to I/O (read/write) and operate the
+  3D cubes. It also has visualization methods to plot slices/bins of
+  the cubes.
 
-An example script of how to read/write the files and perform some
-simple plots is given in the `examples` directory:
+* The `~gammapy.background.CubeBackgroundModel` class is used to
+  contain and handle cube bacground models.
+  It contais 3 cubes of type `~gammapy.background.Cube`:
+
+    * `~gammapy.background.CubeBackgroundModel.counts_cube`:
+      contains the counts (a.k.a. events) used to fill the model.
+    * `~gammapy.background.CubeBackgroundModel.livetime_cube`:
+      contains the livetime correction used for the model.
+    * `~gammapy.background.CubeBackgroundModel.background_cube`:
+      contains the background model (background rate).
+
+  The class also defines usefull methods to produce the models, such
+  as define binning, fill (histogram) the model or smooth.
+
+Two test files are located in the `~gammapy-extra` repository as
+examples and test benches of these classes:
+
+* `bg_cube_model_test1.fits
+  <https://github.com/gammapy/gammapy-extra/blob/master/test_datasets/background/bg_cube_model_test1.fits>`_
+  is a `~gammapy.background.Cube` produced with
+  `~gammapy.datasets.make_test_bg_cube_model`, using a simplified
+  background model.
+
+* `bg_cube_model_test2.fits.gz
+  <https://github.com/gammapy/gammapy-extra/blob/master/test_datasets/background/bg_cube_model_test2.fits.gz>`_
+  is a `~gammapy.background.CubeBackgroundModel` produced with
+  `~gammapy.background.make_bg_cube_model`, using dummy data produced
+  with `~gammapy.datasets.make_test_dataset`.
+
+An example script of how to read/write the cubes from file and
+perform some simple plots is given in the `examples` directory:
 :download:`plot_bg_cube_model.py <../../examples/plot_bg_cube_model.py>`
 
 .. literalinclude:: ../../examples/plot_bg_cube_model.py
@@ -46,12 +74,3 @@ More complex plots can be easily produced with a few lines of code:
 
 .. plot:: background/plot_bgcube.py
    :include-source:
-
-There is also a method in the `~gammapy.datasets` module called
-`~gammapy.datasets.make_test_bg_cube_model` for creating test
-`~gammapy.background.CubeBackgroundModel` objects.
-
-In order to compare 2 sets of background cube models, the following
-script in the `examples` directory can be used:
-:download:`plot_bg_cube_model_comparison.py
-<../../examples/plot_bg_cube_model_comparison.py>`

docs/background/plot_bgcube.py

@@ -5,7 +5,7 @@
 from gammapy.background import Cube
 from gammapy import datasets
 
-filename = datasets.get_path('../test_datasets/background/bg_cube_model_test.fits',
+filename = datasets.get_path('../test_datasets/background/bg_cube_model_test1.fits',
                              location='remote')
 bg_cube_model = Cube.read(filename, format='table', scheme='bg_cube')
 

docs/datasets/index.rst

@@ -56,3 +56,11 @@ Reference/API
 
 .. automodapi:: gammapy.datasets
     :no-inheritance-diagram:
+
+Sub-pages
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   make_datasets

docs/datasets/make_datasets.rst

@@ -0,0 +1,60 @@
+.. _datasets_make_datasets_for_testing:
+
+Make datasets for testing
+=========================
+
+In order to test some of the tools from Gammapy, such as the
+background generation tools
+(:ref:`background_make_background_models`), real data
+from existing experiments such as H.E.S.S. can be used. Since the
+data of current experiments is not public, rudimentary tools to
+prepare a dummy dataset have been placed in Gammapy:
+
+* `~gammapy.datasets.make_test_dataset`: function to produce a dummy
+  observation list and its corresponding dataset
+  consisting on event lists and effective area tables and store
+  everything on disk.
+
+* `~gammapy.datasets.make_test_eventlist`: function called
+  recursivelly by `~gammapy.datasets.make_test_dataset` to produce
+  the data (event lists and effective area table) corresponding to
+  one observation.
+
+Currently only background events are simulated (no signal),
+following a very simple model, and only a few
+columns of the `~gammapy.data.EventList` class are filled. In
+addition, the effective area files produced, are empty except fot
+the low energy threshold header entry.
+
+The tools are very easy to use. A H.E.S.S.-like test dataset can be
+produced with a few lines of python code:
+
+.. code-block:: python
+
+    fits_path = '/path/to/fits/event_lists/base/dir'
+    observatory_name = 'HESS'
+    n_obs = 2
+    random_state = np.random.RandomState(seed=0)
+
+    make_test_dataset(fits_path=fits_path,
+                      observatory_name=observatory_name,
+                      n_obs=n_obs,
+                      random_state=random_state)
+
+Then the data can be read back using the `~gammapy.obs.DataStore`
+class, and eg. print the observation table and the names of the filescreated with a few extra lines of python code:
+
+.. code-block:: python
+
+    scheme = 'HESS'
+    data_store = DataStore(dir=fits_path, scheme=scheme)
+    observation_table = data_store.make_observation_table()
+    print(observation_table)
+    event_list_files = data_store.make_table_of_files(observation_table,
+                                                      filetypes=['events'])
+    aeff_table_files = data_store.make_table_of_files(observation_table,
+                                                      filetypes=['effective area'])
+    for i_ev_file, i_aeff_file in zip(event_list_files['filename'],
+                                      aeff_table_files['filename']):
+        print(' ev infile: {}'.format(i_ev_file))
+        print(' aeff infile: {}'.format(i_aeff_file))