Improve docs (especially concerning image, cube and maps)

docs/cube/index.rst

@@ -1,3 +1,10 @@
+.. note::
+
+    A new set of map and cube classes is being developed in `gammapy.maps`
+    and long-term will replace the existing `gammapy.image.SkyImage` and
+    `gammapy.cube.SkyCube` classes. Please consider trying out `gammapy.maps`
+    and changing your scripts to use those new classes. See :ref:`maps`.
+
 .. _cube:
 
 ************************************
@@ -42,8 +49,14 @@ Use the cube methods to do computations::
     image = cube.sky_image_integral(emin=emin, emax=emax)
     image.show('ds9')
 
-TODO: also show how to work with counts and exposure cube using the example at ``test_datasets/unbundled/fermi``
-(or make a better one).
+Using `gammapy.cube`
+=====================
+
+`Gammapy tutorial notebooks`_ that show examples using ``gammapy.cube``:
+
+* :gp-extra-notebook:`data_fermi_lat`
+* :gp-extra-notebook:`cube_analysis_part1`
+* :gp-extra-notebook:`cube_analysis_part2`
 
 Reference/API
 =============

docs/image/index.rst

@@ -1,5 +1,12 @@
 .. include:: ../references.txt
 
+.. note::
+
+    A new set of map and cube classes is being developed in `gammapy.maps`
+    and long-term will replace the existing `gammapy.image.SkyImage` and
+    `gammapy.cube.SkyCube` classes. Please consider trying out `gammapy.maps`
+    and changing your scripts to use those new classes. See :ref:`maps`.
+
 .. _image:
 
 *****************************************************
@@ -41,7 +48,13 @@ in an interactive python environment or see the :doc:`sky_image` page.
 Using `gammapy.image`
 =====================
 
-If you'd like to learn more about using `gammapy.image`, read the following sub-pages:
+Many of the `Gammapy tutorial notebooks`_ show examples using ``gammapy.image``:
+
+* :gp-extra-notebook:`first_steps`
+* :gp-extra-notebook:`image_pipe`
+* :gp-extra-notebook:`image_analysis`
+
+Documentation pages with more detailed information:
 
 .. toctree::
    :maxdepth: 1

docs/maps/index.rst

@@ -399,6 +399,10 @@ diffuse model cube using the `~MapBase.reproject` method:
 Using `gammapy.maps`
 ====================
 
+`Gammapy tutorial notebooks`_ that show examples using ``gammapy.maps``:
+
+* :gp-extra-notebook:`data_fermi_lat`
+
 More detailed documentation on the WCS and HPX classes in
 `gammapy.maps` can be found in the following sub-pages:
 

docs/spectrum/index.rst

@@ -66,14 +66,17 @@ It will print the following output to the console:
     Fit Range: [  5.99484250e+08   1.00000000e+11] keV
 
 
+
+Using `gammapy.spectrum`
+========================
+
 For more advanced use cases please go to the tutorial notebooks:
 
 * :gp-extra-notebook:`spectrum_simulation` - simulate and fit 1D spectra using pre-defined or a user-defined model.
 * :gp-extra-notebook:`spectrum_analysis` - spectral analysis starting from event lists and field-of-view IRFs.
 
+The following pages describe ``gammapy.spectrum`` in more detail:
 
-Content
-=======
 .. toctree::
    :maxdepth: 1
 

gammapy/cube/core.py

@@ -1,12 +1,4 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
-"""Gamma-ray spectral cube: longitude, latitude and spectral axis.
-
-TODO: split `SkyCube` into a base class ``SkyCube`` and a few sub-classes:
-
-* ``SkyCube`` to represent functions evaluated at grid points (diffuse model format ... what is there now).
-* ``ExposureCube`` should also be supported (same semantics, but different units / methods as ``SkyCube`` (``gtexpcube`` format)
-* ``SkyCubeHistogram`` to represent model or actual counts in energy bands (``gtbin`` format)
-"""
 from __future__ import absolute_import, division, print_function, unicode_literals
 from collections import OrderedDict
 import numpy as np
@@ -34,19 +26,18 @@ class SkyCube(MapBase):
 
     .. note::
 
-        There is a very nice ``SkyCube`` implementation here:
-        http://spectral-cube.readthedocs.io/en/latest/index.html
-
-        Here is some discussion if / how it could be used:
-        https://github.com/radio-astro-tools/spectral-cube/issues/110
-
-    For now we re-implement what we need here.
+        A new set of map and cube classes is being developed in `gammapy.maps`
+        and long-term will replace the existing `gammapy.image.SkyImage` and
+        `gammapy.cube.SkyCube` classes. Please consider trying out `gammapy.maps`
+        and changing your scripts to use those new classes. See :ref:`maps`.
 
     The order of the sky cube axes is defined as following:
 
     * The ``data`` array axis order is ``(energy, lat, lon)``.
     * The ``wcs`` object is a two dimensional celestial WCS with axis order ``(lon, lat)``.
 
+    For further information, see :ref:`cube`.
+
     Parameters
     ----------
     name : str

gammapy/datasets/fermi.py

@@ -248,9 +248,10 @@ class FermiLATDataset(object):
 
     def __init__(self, filename):
         import yaml
-        filename = make_path(filename)
-        self._path = filename.parents[0].resolve()
-        self.config = yaml.load(open(str(filename), 'r'))
+        path = make_path(filename)
+        self._path = path.parents[0].resolve()
+        with path.open() as fh:
+            self.config = yaml.load(fh)
 
     @property
     def name(self):

gammapy/image/basic.py

@@ -325,11 +325,9 @@ class FermiLATBasicImageEstimator(BasicImageEstimator):
     Parameters
     ----------
     reference : `~gammapy.image.SkyImage`
-        Reference sky image.
-    emin : `~astropy.units.Quantity`
-        Lower bound of energy range.
-    emax : `~astropy.units.Quantity`
-        Upper bound of energy range.
+        Reference sky image
+    emin, emax : `~astropy.units.Quantity`
+        Energy range
     spectral_model : `~gammapy.spectrum.models.SpectralModel`
         Spectral model assumption to compute mean exposure and psf images.
 
@@ -453,6 +451,8 @@ def background(self, dataset):
         energy_band = u.Quantity([p['emin'], p['emax']])
 
         background_cube = self._total_background_cube(dataset)
+
+
         exposure_cube = dataset.exposure.reproject(background_cube)
         psf = dataset.psf
 
@@ -532,8 +532,7 @@ def _psf_image(self, dataset, nxpix=101, nypix=101, binsz=0.02):
         return psf_image
 
     def run(self, dataset, which='all'):
-        """
-        Estimate sky images.
+        """Estimate sky images.
 
         Parameters
         ----------

gammapy/image/core.py

@@ -37,6 +37,13 @@ class MapBase(object):
 
     This is just a temp solution to put code that's common
     between `SkyImage` and `SkyCube`.
+
+    .. note::
+
+        A new set of map and cube classes is being developed in `gammapy.maps`
+        and long-term will replace the existing `gammapy.image.SkyImage` and
+        `gammapy.cube.SkyCube` classes. Please consider trying out `gammapy.maps`
+        and changing your scripts to use those new classes. See :ref:`maps`.
     """
 
     @property
@@ -57,10 +64,16 @@ def _check_is_mask(self):
 
 
 class SkyImage(MapBase):
-    """
-    Sky image.
+    """Sky image.
+
+    .. note::
+
+        A new set of map and cube classes is being developed in `gammapy.maps`
+        and long-term will replace the existing `gammapy.image.SkyImage` and
+        `gammapy.cube.SkyCube` classes. Please consider trying out `gammapy.maps`
+        and changing your scripts to use those new classes. See :ref:`maps`.
 
-    For a usage example see :gp-extra-notebook:`image_analysis`
+    For further information, see :ref:`image`.
 
     Parameters
     ----------

gammapy/utils/scripts.py

@@ -184,6 +184,9 @@ def make_path(path):
     path : str, `~gammapy.extern.pathlib.Path`
         path to expand
     """
+    # TODO: raise error or warning if environment variables that don't resolve are used
+    # e.g. "spam/$DAMN/ham" where `$DAMN` is not defined
+    # Otherwise this can result in cryptic errors later on
     return Path(expandvars(str(path)))