Doc improvements (#31)

docs/api.rst

@@ -107,7 +107,7 @@ Input/output
     read_shapefile_to_grid
 
 
-Xarray
+xarray
 ======
 
 .. autosummary::
@@ -116,29 +116,47 @@ Xarray
 
     open_xr_dataset
     open_wrf_dataset
-    DataArrayAccessor
-    DatasetAccessor
 
 
-Xarray accessors
+xarray accessors
 ----------------
 
 Salem adds `accessors`_ to xarray objects. They can be accessed via the
-``.salem`` attribute and add the following methods (DataArray and Dataset
-methods are almost equivalent):
+``.salem`` attribute and add the following methods:
 
 .. _accessors: http://xarray.pydata.org/en/stable/internals.html#extending-xarray
 
+
+DataArray
+^^^^^^^^^
+
 .. autosummary::
     :toctree: generated/
     :nosignatures:
 
+    DataArrayAccessor.subset
+    DataArrayAccessor.roi
+    DataArrayAccessor.transform
+    DataArrayAccessor.cartopy
+    DataArrayAccessor.get_map
+    DataArrayAccessor.quick_map
+    DataArrayAccessor.interpz
+
+
+Dataset
+^^^^^^^
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    DatasetAccessor.subset
+    DatasetAccessor.roi
+    DatasetAccessor.transform
+    DatasetAccessor.transform_and_add
     DatasetAccessor.cartopy
     DatasetAccessor.get_map
     DatasetAccessor.quick_map
-    DatasetAccessor.roi
-    DatasetAccessor.subset
-    DatasetAccessor.transform
     DatasetAccessor.wrf_zlevel
     DatasetAccessor.wrf_plevel
 

docs/examples/plot_topo_shading.py

@@ -12,7 +12,6 @@
 import matplotlib.pyplot as plt
 
 # prepare the figure
-
 f, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(8, 7))
 
 # map extent

docs/gis.rst

@@ -70,11 +70,12 @@ the two conventions are identical:
 
 .. ipython:: python
 
-    grid_c = salem.Grid(nxny=(3, 2), dxdy=(1, 1), ll_corner=(0, 0), proj=wgs84, pixel_ref='corner')
+    grid_c = salem.Grid(nxny=(3, 2), dxdy=(1, 1), ll_corner=(0, 0),
+                        proj=wgs84, pixel_ref='corner')
     assert grid_c == grid
 
 While it's good to know how grids work, most of the time grids should be
-inferred directly from the data files (if not, we have to implement it!):
+inferred directly from the data files:
 
 .. ipython:: python
 

docs/index.rst

@@ -15,7 +15,7 @@ subsetting, masking, and plotting operations to xarray's `DataArray`_ and
 
 .. warning::
 
-    Salem is at a very early development stage and is more a proof of
+    Salem is at an early development stage and is more a proof of
     feasibility than a library for "everything you'll ever have to do with
     geoscientific data". There are plenty of more mature tools out there (see
     :ref:`faqtools`). Salem basically reinvents the wheel, but in the way I
@@ -36,9 +36,9 @@ Documentation
     whats-new
     installing
     xarray_acc
-    gis
     plotting
     wrf
+    gis
     auto_examples/index
     api
 

docs/plotting.rst

@@ -49,19 +49,19 @@ You can also use the salem accessor to initialise the plot's map projection:
 Plotting with salem
 -------------------
 
-Salem comes with a homegrown plotting tool which is less flexible than
-cartopy's. It was created to overcome some of cartopy's limitations (e.g.
-the impossibility to add tick labels to Lambert Conformal maps), and to make
-regional maps which are more precise:
+Salem comes with a homegrown plotting tool. It is less flexible than
+cartopy, but it was created to overcome some of cartopy's limitations (e.g.
+the impossibility to add tick labels to lambert conformal maps), and to make
+nice looking regional maps:
 
 .. ipython:: python
 
     @savefig salem_quickmap.png width=80%
     ds.T2C.isel(time=1).salem.quick_map()
 
-Salem maps are different from cartopy's in that they don't change the axes'
-projections. The map background is always going to be a call to ``imshow()``,
-with an image of size decided at instanciation:
+Salem maps are different from cartopy's in that they don't change the
+matplotlib axes' projection. The map background is always going to be a
+call to `imshow()`_, with an image size decided at instanciation:
 
 .. ipython:: python
    :suppress:
@@ -93,3 +93,4 @@ the data that has to be plotted on it:
 
 Refer to :ref:`recipes` for more examples on how to use salem's maps.
 
+.. _imshow(): http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.imshow

docs/whats-new.rst

@@ -12,7 +12,6 @@ Enhancements
 
 - New :py:func:`~DatasetAccessor.wrf_zlevel` and
   :py:func:`~DatasetAccessor.wrf_plevel` functions for vertical interpolation
-  (still quite slow, though)
 - Salem can now plot on cartopy's maps thanks to a new
   :py:func:`~salem.proj_to_cartopy` function.
 - Doc improvements

docs/xarray_acc.rst

@@ -57,6 +57,12 @@ From geotiffs
 
 Salem uses `rasterio`_ to open and parse geotiff files:
 
+.. ipython:: python
+   :suppress:
+
+    plt.rcParams['figure.figsize'] = (7, 3)
+    f = plt.figure(figsize=(7, 3))
+
 .. ipython:: python
 
     fpath = salem.get_demo_file('himalaya.tif')
@@ -86,4 +92,86 @@ The proj info has to be provided as attribute:
 
 
     @savefig plot_xarray_utm.png width=80%
-    dutm.salem.quick_map(interp='linear');
+    dutm.salem.quick_map(interp='linear');
+
+
+Using the accessor
+------------------
+
+The accessor's methods are available trough the ``.salem`` attribute.
+
+Keeping track of attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some datasets carry their georeferencing information in global attributes (WRF
+model output files for example). This makes it possible for Salem to
+determine the data's map projection. From the variables alone,
+however, this is not possible. This is the reason why it is recommended to
+use the :py:func:`~salem.open_xr_dataset` and
+:py:func:`~salem.open_wrf_dataset` function, which add
+an attribute to the variables automatically:
+
+.. ipython:: python
+
+    dsw = salem.open_xr_dataset(salem.get_demo_file('wrfout_d01.nc'))
+    dsw.T2.pyproj_srs
+
+Unfortunately, the DataArray attributes are lost when doing operations on them.
+It is the task of the user to keep track of this attribute:
+
+.. ipython:: python
+
+    dsw.T2.mean(dim='Time', keep_attrs=True).salem  # triggers an error without keep_attrs
+
+
+Reprojecting data
+~~~~~~~~~~~~~~~~~
+
+.. ipython:: python
+   :suppress:
+
+    plt.rcParams['figure.figsize'] = (7, 3)
+    f = plt.figure(figsize=(7, 3))
+
+You can reproject a Dataset onto another one with the
+:py:func:`~salem.DatasetAccessor.transform` function:
+
+.. ipython:: python
+
+    dse = salem.open_xr_dataset(salem.get_demo_file('era_interim_tibet.nc'))
+    dsr = ds.salem.transform(dse)
+    dsr
+    @savefig plot_xarray_transfo.png width=80%
+    dsr.t2m.mean(dim='time').salem.quick_map();
+
+Currently, salem implements, the neirest neighbor (default), linear, and spline
+interpolation methods:
+
+.. ipython:: python
+
+    dsr = ds.salem.transform(dse, interp='spline')
+    @savefig plot_xarray_transfo_spline.png width=80%
+    dsr.t2m.mean(dim='time').salem.quick_map();
+
+
+Subsetting data
+~~~~~~~~~~~~~~~
+
+.. ipython:: python
+
+    shdf = salem.read_shapefile(salem.get_demo_file('world_borders.shp'))
+    shdf = shdf.loc[shdf['CNTRY_NAME'] == 'Nepal']
+    dsr = dsr.salem.subset(shape=shdf, margin=10)
+    @savefig plot_xarray_subset_out.png width=80%
+    dsr.t2m.mean(dim='time').salem.quick_map();
+
+
+Regions of interest
+~~~~~~~~~~~~~~~~~~~
+
+.. ipython:: python
+
+    dsr = dsr.salem.roi(shape=shdf)
+    @savefig plot_xarray_roi_out.png width=80%
+    dsr.t2m.mean(dim='time').salem.quick_map();
+

salem/__init__.py

@@ -63,4 +63,3 @@ def _lazy_property(self):
 from salem.utils import get_demo_file
 from salem.graphics import get_cmap, DataLevels, Map
 from salem.wrftools import geogrid_simulator
-

salem/sio.py

@@ -525,15 +525,12 @@ def cartopy(self):
     def transform(self, other, grid=None, interp='nearest', ks=3):
         """Reprojects an other Dataset or DataArray onto this grid.
 
-        If the data provided is 3D or 4D, Salem is going to try to understand
-        as much as possible what to do with it.
-
         Parameters
         ----------
         other: Dataset, DataArray or ndarray
             the data to project onto self
         grid: salem.Grid
-            in case the data provided does not carry enough georef info
+            in case the input dataset does not carry georef info
         interp : str
             'nearest' (default), 'linear', or 'spline'
         ks : int
@@ -606,6 +603,8 @@ def transform(self, other, grid=None, interp='nearest', ks=3):
 
         if was_dataarray:
             out = out[v]
+        else:
+            out.attrs['pyproj_srs'] = self.grid.proj.srs
         return out
 
 
@@ -667,15 +666,12 @@ def transform_and_add(self, other, grid=None, interp='nearest', ks=3,
                           name=None):
         """Reprojects an other Dataset and adds it's content to the current one.
 
-        If the data provided is 3D or 4D, Salem is going to try to understand
-        as much as possible what to do with it.
-
         Parameters
         ----------
         other: Dataset, DataArray or ndarray
             the data to project onto self
         grid: salem.Grid
-            in case the data provided does not carry enough georef info
+            in case the input dataset does not carry georef info
         interp : str
             'nearest' (default), 'linear', or 'spline'
         ks : int