docs improvements

README.rst

@@ -16,12 +16,11 @@ Salem
     :target: https://zenodo.org/badge/latestdoi/42607422
 
 
-Salem is a `cat`_. Salem is also a small library to do geoscientific data
+Salem is a small library to do geoscientific data
 processing and plotting. It extends `xarray`_ to add geolocalised
 subsetting, masking, and plotting operations to xarray's `DataArray`_ and
 `DataSet`_ structures.
 
-.. _cat: https://drive.google.com/file/d/0B-0AsTwFw61uSE0zaktOOVN5X1E/view?usp=sharing
 .. _xarray: http://xarray.pydata.org/en/stable/
 .. _DataArray: http://xarray.pydata.org/en/stable/data-structures.html#dataarray
 .. _DataSet: http://xarray.pydata.org/en/stable/data-structures.html#dataset

docs/examples.rst

@@ -1,3 +1,4 @@
+.. _examples:
 
 Examples
 ========

docs/faq.rst

@@ -6,46 +6,65 @@ Frequently Asked Questions
 Is your library mature for production code?
 -------------------------------------------
 
-No. The API is not always as clever as I wish it would, and it will probably
-change in the future. It is quite well tested though, at least for the cases
-I encounter in my daily work.
+Not really. The API is not always as clever as I wish it would, and it will
+probably change in the future. Salem is well tested though, at least for the
+cases I encounter in my daily work.
 
 
 .. _faqtools:
 
 What others tools should I know about?
 --------------------------------------
 
-If you want to plot on maps, `cartopy`_ is probably one of the best tools you
-could pick. For reprojection workflows on large or numerous gridded files you
-probably want to use `rasterio`_.
+The python atmospheric sciences community is a bit spread between `iris`_ and
+`xarray`_ for N-Dimensional data handling. I find that xarray is very intuitive
+to learn thanks to its strong interaction with `pandas`_.
 
-The python atmopsheric sciences community is a bit spread between `iris`_ and
-`xarray`_ for N-Dimensional data handling (I picked the later for it's
-strong interaction with `pandas`_). Several great libraries are available to
-meteorologists and climatologists, for example `MetPy`_,
-`windspharm`_, `xgcm`_, and all the ones I forgot to mention.
+Here are some tools that share functionalities with Salem:
+
+- `cartopy`_ is the reference tool for plotting on maps. Salem provides a way
+  to plot with cartopy in addition to Salem's homegrowm graphics.
+  (see :ref:`plotting`)
+- Salem provides useful reprojection tools (see :ref:`gis`). The transformation
+  routines are quite fast (we use pyproj for the map transformations and
+  scipy for the interpolation) but they are all done on memory (i.e. not
+  adapted for large datasets). For large reprojection workflows you might want
+  to have a look at `cartopy`_ and `pyresample`_.
+- `regionmask`_ provides similar tools as salem's region-of-interest
+  functionalities if you are woking with shapefiles. regionmask seems a bit
+  more general than Salem, but I'm not sure if it works with any map
+  projection as Salem does.
+- In the future, I hope that `pangeo-data`_ will overtake most of the
+  functionalities I need. But this is not going to happen tomorrow...
+
+
+Several libraries are available to meteorologists and climatologists, but I
+don't think they share much functionality with Salem: for example `MetPy`_,
+`windspharm`_, `xgcm`_, `aospy`_, and all the ones I forgot to mention.
 
 .. _cartopy: http://scitools.org.uk/cartopy/docs/latest/index.html
+.. _pyresample: https://github.com/pytroll/pyresample
 .. _rasterio: https://github.com/mapbox/rasterio
 .. _iris: http://scitools.org.uk/iris/
 .. _xarray: http://xarray.pydata.org/en/stable/
 .. _pandas: http://pandas.pydata.org/
 .. _windspharm: http://ajdawson.github.io/windspharm/
 .. _xgcm: https://github.com/xgcm/xgcm
 .. _MetPy: http://metpy.readthedocs.io/en/stable/
+.. _aospy: https://github.com/spencerahill/aospy
+.. _regionmask: https://github.com/mathause/regionmask
+.. _pangeo-data: https://pangeo-data.github.io/
 
 
-But then, why developing Salem?
--------------------------------
+Why developing Salem?
+---------------------
 
 As an atmospheric scientist, I hate to have to take care about projections and
 maps. Salem was created to hide all these concerns. By the time I started, it
 seemed a good idea to provide map transformation tools without depending on
 GDAL (thanks to `conda-forge`_  GDAL is now much easier to install).
 It is still possible to do reprojection work in Salem using scipy and
-pyproj alone. It is al done in python and on memory,
-so don't expect miracles on that side.
+pyproj alone.
 
 Furthermore, I use the atmospheric model WRF quite often in my work.
 Its output files are absolutely not compliant with the CF conventions.

docs/index.rst

@@ -2,27 +2,22 @@
 Salem
 =====
 
-Salem is a `cat`_. Salem is also a small library to do geoscientific data
+Salem is a small library to do geoscientific data
 processing and plotting. It extends `xarray`_ to add geolocalised
 subsetting, masking, and plotting operations to xarray's `DataArray`_ and
 `DataSet`_ structures.
 
-.. _cat: https://drive.google.com/file/d/0B-0AsTwFw61uSE0zaktOOVN5X1E/view?usp=sharing
 .. _xarray: http://xarray.pydata.org/en/stable/
 .. _DataArray: http://xarray.pydata.org/en/stable/data-structures.html#dataarray
 .. _DataSet: http://xarray.pydata.org/en/stable/data-structures.html#dataset
 
 
 .. warning::
 
-    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
-    want the wheel to be. Some might still find it useful: as an addition to
-    xarray, or if you use the `WRF model`_ for example.
-
-.. _WRF Model: http://www2.mmm.ucar.edu/wrf/users/
+    Salem is at an early development stage, and its API
+    might change in the future. See :ref:`examples` for a quick overview
+    of Salem's functionalities, and see also the :ref:`faq` for more
+    information and a list of related tools.
 
 
 Documentation

salem/graphics.py

@@ -319,7 +319,7 @@ def plot(self, ax):
 
         More useful for child classes.
 
-        Returns: imshow primitive
+        Returns an imshow primitive
         """
         data = np.atleast_2d(self.data)
         toplot = self.cmap(self.norm(data))
@@ -958,7 +958,7 @@ def plot(self, ax):
         It first plots the image and then adds all the cartographic
         information on top of it.
 
-        Returns: imshow primitive
+        Returns an imshow primitive
         """
 
         # Image is the easiest

salem/sio.py

@@ -885,9 +885,9 @@ def open_xr_dataset(file):
     to be understood alone, and datasets tend to loose their attrs with
     operations...
 
-    Returns:
-    --------
-    xr.Dataset
+    Returns
+    -------
+    an xarray Dataset
     """
 
     # if geotiff, use Salem
@@ -944,9 +944,9 @@ def open_wrf_dataset(file, **kwargs):
     **kwargs : optional
         Additional arguments passed on to ``xarray.open_dataset``.
 
-    Returns:
-    --------
-    xr.Dataset
+    Returns
+    -------
+    an xarray Dataset
     """
 
     nc = netCDF4.Dataset(file)

salem/tests/test_gis.py

@@ -2,6 +2,7 @@
 
 import unittest
 import warnings
+import os
 
 import time
 import pyproj
@@ -64,6 +65,7 @@ def test_constructor(self):
             self.assertEqual(g, rg)
             g.to_json('test.json')
             rg = Grid.from_json('test.json')
+            os.remove('test.json')
             self.assertEqual(g, rg)
 
             oargs = dict(nxny=(3, 3), dxdy=(1, 1), x0y0=(0, 0), proj=proj)
@@ -204,9 +206,11 @@ def test_comparisons(self):
         self.assertTrue(g1.almost_equal(rg))
         g1.to_json('test.json')
         rg = Grid.from_json('test.json')
+        os.remove('test.json')
         self.assertEqual(g1, rg)
         g2.to_json('test.json')
         rg = Grid.from_json('test.json')
+        os.remove('test.json')
         self.assertEqual(g2, rg)
         self.assertNotEqual(g1, rg)
         self.assertTrue(g1.almost_equal(rg))
@@ -228,6 +232,7 @@ def test_comparisons(self):
         self.assertTrue(g1.almost_equal(rg))
         g1.to_json('test.json')
         rg = Grid.from_json('test.json')
+        os.remove('test.json')
         self.assertEqual(g1, rg)
         self.assertTrue(g1.almost_equal(rg))