Docs improvements and minor bug fixes (#22)

.travis.yml

@@ -37,6 +37,7 @@ before_install:
   - hash -r
   - conda config --set always_yes yes --set changeps1 no
   - conda update -q conda
+  - pip install pyyaml
 
 install:
   - conda env create --file ci/requirements-$CONDA_ENV.yml --quiet

README.rst

@@ -4,14 +4,16 @@
 Salem
 =====
 
+.. image:: https://badge.fury.io/py/salem.svg
+    :target: https://badge.fury.io/py/salem
 .. image:: https://travis-ci.org/fmaussion/salem.svg?branch=master
     :target: https://travis-ci.org/fmaussion/salem
 .. image:: https://coveralls.io/repos/fmaussion/salem/badge.svg?branch=master&service=github
-  :target: https://coveralls.io/github/fmaussion/salem?branch=master
+    :target: https://coveralls.io/github/fmaussion/salem?branch=master
 .. image:: https://readthedocs.org/projects/salem/badge/?version=stable
-  :target: http://salem.readthedocs.io/en/stable/?badge=stable
+    :target: http://salem.readthedocs.io/en/stable/?badge=stable
 .. image:: https://zenodo.org/badge/42607422.svg
-   :target: https://zenodo.org/badge/latestdoi/42607422
+    :target: https://zenodo.org/badge/latestdoi/42607422
 
 
 Salem is a `cat`_. Salem is also a small library to do some geoscientific data

docs/conf.py

@@ -46,12 +46,21 @@
     'sphinx.ext.viewcode',
     'IPython.sphinxext.ipython_directive',
     'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx_gallery.gen_gallery',
 ]
 
 extlinks = {'issue': ('https://github.com/fmaussion/salem/issues/%s', 'GH'),
             'pull': ('https://github.com/fmaussion/salem/pull/%s', 'PR'),
             }
 
+sphinx_gallery_conf = {
+    # path to your examples scripts
+    'examples_dirs': 'examples',
+    # path where to save gallery generated examples
+    'gallery_dirs': 'auto_examples'
+}
+
+
 autosummary_generate = True
 
 numpydoc_class_members_toctree = True

docs/environment.yml

@@ -19,6 +19,7 @@ dependencies:
   - descartes
   - numpydoc
   - ipython=4.0.1
-  - sphinx=1.2.3  # pin to avoid https://github.com/sphinx-doc/sphinx/issues/1822
+  - sphinx
   - pip:
     - git+https://github.com/fmaussion/motionless.git
+    - sphinx-gallery

docs/examples/README.txt

@@ -0,0 +1,9 @@
+.. _recipes:
+
+Recipes
+=======
+
+Plotting
+--------
+
+How to make nice looking plots.

docs/examples/plot_googlestatic.py

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""
+===========================
+Plot on a google static map
+===========================
+
+In this script, we use `motionless <https://github.com/ryancox/motionless>`_
+to download an image from the `google static map API <http://code.google.com/apis/maps/documentation/staticmaps/>`_
+and plot it on a :py:class:`~salem.Map`. We then add information to the map
+such as a glacier outline (from the `RGI <http://www.glims.org/RGI/>`_),
+and ground penetrating radar measurements (GPR, from the
+`GlaThiDa <http://www.gtn-g.ch/data_catalogue_glathida/>`_ database).
+
+
+The GPR measurements were realized in 1997, the glacier outlines are from
+2003, and the map background is from 2016. This illustrates the retreat of
+the Kesselwandferner glacier.
+
+"""
+
+import numpy as np
+import pandas as pd
+import salem
+from salem import get_demo_file, DataLevels, GoogleVisibleMap, Map
+import matplotlib.pyplot as plt
+
+# prepare the figure
+f, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
+
+# read the shapefile and use its extent to define a ideally sized map
+shp = salem.read_shapefile(get_demo_file('rgi_kesselwand.shp'))
+g = GoogleVisibleMap(x=[shp.min_x, shp.max_x], y=[shp.min_y, shp.max_y],
+                     maptype='satellite')  # try out: 'terrain'
+
+# the google static image is a standard rgb image
+ggl_img = g.get_vardata()
+ax1.imshow(ggl_img)
+ax1.set_title('Google static map')
+
+# make a map of the same size as the image
+sm = Map(g.grid, factor=1)
+sm.set_shapefile(shp)  # add the glacier outlines
+sm.set_rgb(ggl_img)  # add the background rgb image
+sm.visualize(ax=ax2)  # plot it
+ax2.set_title('GPR measurements')
+
+# read the point GPR data and add them to the plot
+df = pd.read_csv(get_demo_file('gtd_ttt_kesselwand.csv'))
+dl = DataLevels(df.THICKNESS, levels=np.arange(10, 201, 10), extend='both')
+x, y = sm.grid.transform(df.POINT_LON.values, df.POINT_LAT.values)
+ax2.scatter(x, y, color=dl.to_rgb(), s=50, edgecolors='k', linewidths=1)
+dl.append_colorbar(ax2, label='Ice thickness (m)')
+
+# make it nice
+plt.tight_layout()
+plt.show()

docs/examples/plot_topo_shading.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""
+===================
+Topographic shading
+===================
+
+How to add topographic shading to a plot.
+
+"""
+
+from salem import mercator_grid, Map, get_demo_file
+import matplotlib.pyplot as plt
+
+# prepare the figure
+
+f, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(8, 7))
+
+# map extent
+grid = mercator_grid(center_ll=(10.76, 46.79), extent=(18000, 14000))
+sm = Map(grid, countries=False)
+sm.set_lonlat_contours(interval=0)
+
+# add topography
+fpath = get_demo_file('hef_srtm.tif')
+sm.set_topography(fpath)
+sm.visualize(ax=ax1, addcbar=False, title='relief_factor=0.7 (default)')
+
+# stronger shading
+sm.set_topography(fpath, relief_factor=1.4)
+sm.visualize(ax=ax2, addcbar=False, title='relief_factor=1.4')
+
+# add color shading
+z = sm.set_topography(fpath)
+sm.set_data(z)
+sm.set_cmap('topo')
+sm.visualize(ax=ax3, title='Color with shading', addcbar=False)
+
+# color without topo shading
+sm.set_topography()
+sm.visualize(ax=ax4, title='Color without shading', addcbar=False)
+
+# make it nice
+plt.tight_layout()
+plt.show()

docs/index.rst

@@ -35,11 +35,14 @@ Documentation
     faq
     whats-new
     installing
+    xarray
     gis
     plotting
     wrf
+    auto_examples/index
     api
 
+
 Get in touch
 ------------
 

docs/installing.rst

@@ -11,7 +11,7 @@ Required dependencies
 - Python 2.7 or 3+ (Py3 `recommended <https://python3statement.github.io/>`__)
 - `numpy <http://www.numpy.org/>`__ (of course)
 - `scipy <http://scipy.org/>`__: for its interpolation tools, among other things
-- `pyproj <https://jswhit.github.io/pyproj/>`__: for map projections
+- `pyproj <https://jswhit.github.io/pyproj/>`__: for map projections transformations
 - `netCDF4 <https://github.com/Unidata/netcdf4-python>`__: to read most geoscientific files
 - `joblib <https://pythonhosted.org/joblib/>`__: for it's `Memory`_ class
 - `six <https://pythonhosted.org/six//>`__: for Py2 compatibility
@@ -25,17 +25,17 @@ Because not using them is a bad idea
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - `pandas <http://pandas.pydata.org/>`__: working with labeled data
-- `xarray <https://jswhit.github.io/pyproj/>`__: pandas in N-dimensions
+- `xarray <https://jswhit.github.io/pyproj/>`__ (0.8 or later): pandas in N-dimensions
 
 For vector and raster operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-(rasterio and geopandas require GDAL)
-
-- `rasterio <https://mapbox.github.io/rasterio//>`__: for geotiff files
+- `rasterio <https://mapbox.github.io/rasterio/>`__: for geotiff files
 - `shapely <https://pypi.python.org/pypi/Shapely>`__: geometric objects
 - `geopandas <http://geopandas.org/>`__: geospatial data with pandas
 
+(rasterio and geopandas both require GDAL)
+
 For plotting
 ~~~~~~~~~~~~
 

docs/whats-new.rst

@@ -5,9 +5,18 @@ What's New
 v0.1.1 (Unreleased)
 -------------------
 
+Enhancements
+~~~~~~~~~~~~
+
+- General doc improvements
+- New ``ds`` keyword to the accessors ``subset()`` and ``roi()`` methods
+
 Bug fixes
 ~~~~~~~~~
 
+- Natural Earth file `lr` (low-res) now shipped with sample-data, `mr` and `hr`
+  can still be downloaded if needed
+- Remove use to deprecated ``rasterio.drivers()``
 - GeoNetCDF files without time variable should now open without error
 
 

docs/xarray.rst

@@ -0,0 +1,89 @@
+.. _xarray:
+
+xarray accessors
+================
+
+One of the main purposes of Salem is to add georeferencing tools to
+`xarray`_ 's data structures. These tools can be accessed via a `special`_
+``.salem`` attribute, available for both `xarray.DataArray`_ and
+`xarray.Dataset`_ objects after a simple ``import salem`` in your code.
+
+.. _xarray: http://xarray.pydata.org/
+.. _special: http://xarray.pydata.org/en/stable/internals.html#extending-xarray
+.. _xarray.DataArray: http://xarray.pydata.org/en/stable/data-structures.html#dataarray
+.. _xarray.Dataset: http://xarray.pydata.org/en/stable/data-structures.html#dataset
+
+
+Initializing the accessor
+-------------------------
+
+Automated projection parsing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Salem will try to understand in which projection the Dataset or DataArray is
+defined. For example, with a platte carree (or lon/lat) projection, Salem will
+know what to do based on the coordinates' names:
+
+.. ipython:: python
+
+    import numpy as np
+    import xarray as xr
+    import salem
+
+    da = xr.DataArray(np.arange(20).reshape(4, 5), dims=['lat', 'lon'],
+                      coords={'lat':np.linspace(0, 30, 4), 'lon':np.linspace(-20, 20, 5)})
+
+    da.salem
+
+    @savefig plot_xarray_simple.png width=80%
+    da.salem.quick_map();
+
+While the above should work with many (most?) climate datasets (such as
+atmospheric reanalyses or GCM output), certain NetCDF files will have a less
+standard map projection requiring special parsing. There are `conventions`_ to
+formalise these things in the NetCDF model, but Salem doesn't understand them
+yet. Currently, Salem can parse:
+- platte carree (or lon/lat) projections
+- WRF projections (see :ref:`wrf`)
+- virually any projection explicitly provided by the user
+- for geotiff files only: any projection that `rasterio`_ can understand
+
+.. _conventions: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/ch05s06.html
+.. _rasterio: https://mapbox.github.io/rasterio/
+
+
+From geotiffs
+~~~~~~~~~~~~~
+
+Salem uses `rasterio`_ to open and parse geotiff files:
+
+.. ipython:: python
+
+    fpath = salem.get_demo_file('himalaya.tif')
+    ds = salem.open_xr_dataset(fpath)
+    hmap = ds.salem.get_map(cmap='topo')
+    hmap.set_data(ds['data'])
+
+    @savefig plot_xarray_geotiff.png width=80%
+    hmap.visualize();
+
+
+Custom projections
+~~~~~~~~~~~~~~~~~~
+
+Alternatively, Salem will understand any projection supported by  `pyproj`_.
+The proj info has to be provided as attribute:
+
+.. _pyproj: https://jswhit.github.io/pyproj/
+
+.. ipython:: python
+
+    dutm = xr.DataArray(np.arange(20).reshape(4, 5), dims=['y', 'x'],
+                        coords={'y': np.arange(3, 7)*2e5,
+                                'x': np.arange(1, 6)*2e5})
+    psrs = 'epsg:32630'  # http://spatialreference.org/ref/epsg/wgs-84-utm-zone-30n/
+    dutm.attrs['pyproj_srs'] = psrs
+
+
+    @savefig plot_xarray_utm.png width=80%
+    dutm.salem.quick_map(interp='linear');