Explain center=False, deprecate sealevel kw. (#36)

* Use center=False to plot LGM data in docs.

* Use center=False to plot LGM data in examples.

* Use vmin=0 to plot boot data in docs.

* Use vmin=0 to plot boot data in examples.

* Add a note to explain center=False in docs.

* Deprecate sealevel kwarg of bedrock_altitude.

* Use shoreline sealevel as contour not offset.

This should not change the looks of the plot.

* Document changes in whatsnew.

doc/datasets/masking.rst

@@ -25,7 +25,7 @@ the case in the demo files.
 .. plot::
 
    with hyoga.open.example('pism.alps.out.2d.nc') as ds:
-       ds.hyoga.plot.bedrock_altitude(vmin=0, vmax=4500)
+       ds.hyoga.plot.bedrock_altitude(center=False)
        for i, value in enumerate([0.1, 1, 500]):
            hyoga.config.glacier_masking_point = value
            ds.hyoga.plot.ice_margin(edgecolor=f'C{i}', linewidths=1)
@@ -48,7 +48,7 @@ per year:
        ds = ds.hyoga.assign_icemask(
            (ds.hyoga.getvar('land_ice_thickness') > 1) &
            (ds.hyoga.getvar('magnitude_of_land_ice_surface_velocity') > 10))
-       ds.hyoga.plot.bedrock_altitude(vmin=0, vmax=4500)
+       ds.hyoga.plot.bedrock_altitude(center=False)
        ds.hyoga.plot.ice_margin(facecolor='tab:blue')
 
 Note that the :meth:`~.Dataset.hyoga.assign_icemask` method edits (or add) a
@@ -113,7 +113,7 @@ with a much higher resolution.
 .. plot::
    :context:
 
-   ds.hyoga.plot.bedrock_altitude(vmin=0, vmax=4500)
+   ds.hyoga.plot.bedrock_altitude(center=False)
    ds.hyoga.plot.surface_velocity(vmin=1e1, vmax=1e3)
    ds.hyoga.plot.surface_altitude_contours()
    ds.hyoga.plot.ice_margin(edgecolor='0.25')

doc/datasets/plotting.rst

@@ -18,6 +18,15 @@ bedrock altitude and a simple ice margin contour:
        ds.hyoga.plot.bedrock_altitude(center=False)
        ds.hyoga.plot.ice_margin(facecolor='tab:blue')
 
+.. note::
+
+   Due to isostatic depression, the example bedrock altitude extends slightly
+   below zero. Here ``center=False`` instructs xarray to not center the
+   colormap around zero despite the negative values. Alternatively, use
+   ``vmin`` and ``vmax`` to pass explicit bounds. Use ``center=True`` or
+   ``center=sealevel`` in order to plot undersea and land altitudes using a
+   diverging colormap.
+
 Hyoga alters matplotlib_ defaults with its own style choices. However, these
 choices can always be overridden using matplotlib keyword arguments.
 Accessor plot methods such as :meth:`~.Dataset.hyoga.plot.bedrock_altitude` and
@@ -44,7 +53,7 @@ but the limits can be customized:
 .. plot::
 
    with hyoga.open.example('pism.alps.out.2d.nc') as ds:
-       ds.hyoga.plot.bedrock_altitude(vmin=0, vmax=4500)
+       ds.hyoga.plot.bedrock_altitude(center=False)
        ds.hyoga.plot.surface_velocity(vmin=1e1, vmax=1e3)
        ds.hyoga.plot.ice_margin(edgecolor='0.25')
 

doc/datasets/vectors.rst

@@ -28,7 +28,7 @@ coastline at the highest available scale:
 .. plot::
 
    with hyoga.open.example('pism.alps.in.boot.nc') as ds:
-      ds.hyoga.plot.bedrock_altitude(center=False)
+      ds.hyoga.plot.bedrock_altitude(vmin=0)
       ds.hyoga.plot.natural_earth()
 
 .. warning::
@@ -45,7 +45,7 @@ instance, to plot glaciated areas in blue, use:
 .. plot::
 
    with hyoga.open.example('pism.alps.in.boot.nc') as ds:
-      ds.hyoga.plot.bedrock_altitude(center=False)
+      ds.hyoga.plot.bedrock_altitude(vmin=0)
       ds.hyoga.plot.natural_earth('glaciated_areas', color='tab:blue')
 
 The method defaults to plotting themes in the ``physical`` category at the
@@ -55,7 +55,7 @@ while lower scales are available through the ``scale`` keyword argument:
 .. plot::
 
    with hyoga.open.example('pism.alps.in.boot.nc') as ds:
-      ds.hyoga.plot.bedrock_altitude(center=False)
+      ds.hyoga.plot.bedrock_altitude(vmin=0)
       ds.hyoga.plot.natural_earth(
           theme='urban_areas', category='cultural', scale='50m',
           color='tab:orange')
@@ -66,7 +66,7 @@ share the same category and scale:
 .. plot::
 
    with hyoga.open.example('pism.alps.in.boot.nc') as ds:
-      ds.hyoga.plot.bedrock_altitude(center=False)
+      ds.hyoga.plot.bedrock_altitude(vmin=0)
       ds.hyoga.plot.natural_earth(('lakes', 'lakes_europe'))
 
 Hyoga also provides two aliases ``'lakes_all'`` and ``'rivers_all'`` that
@@ -76,7 +76,7 @@ such regional subsets as ``'lakes_europe'``.
 .. plot::
 
    with hyoga.open.example('pism.alps.in.boot.nc') as ds:
-      ds.hyoga.plot.bedrock_altitude(center=False)
+      ds.hyoga.plot.bedrock_altitude(vmin=0)
       ds.hyoga.plot.natural_earth('rivers_all')
 
 Plotting and reprojection is handled by using :class:`geopandas.GeoDataFrame`
@@ -87,7 +87,7 @@ regional significance:
 .. plot::
 
    with hyoga.open.example('pism.alps.in.boot.nc') as ds:
-      ds.hyoga.plot.bedrock_altitude(center=False)
+      ds.hyoga.plot.bedrock_altitude(vmin=0)
       ds.hyoga.plot.natural_earth(
           'populated_places', category='cultural',
           column='SCALERANK', cmap='Reds_r')
@@ -106,7 +106,7 @@ system (given by a ``.proj4`` attribute, see :ref:`plotting_natural_earth`).
 .. plot::
 
    with hyoga.open.example('pism.alps.in.boot.nc') as ds:
-      ds.hyoga.plot.bedrock_altitude(center=False)
+      ds.hyoga.plot.bedrock_altitude(vmin=0)
       ds.hyoga.plot.paleoglaciers(alpha=0.75)
 
 A ``source`` keyword argument controls the source of data plotted, and

doc/whatsnew.rst

@@ -33,6 +33,13 @@ Breaking changes
   `xarray#7115 <https://github.com/pydata/xarray/issues/7115>`_,
   `NEP-29 <https://numpy.org/neps/nep-0029-deprecation_policy.html>`_)
 
+Deprecations
+~~~~~~~~~~~~
+
+- The ``sealevel`` argument in :meth:`.Dataset.hyoga.plot.bedrock_altitude` is
+  deprecated and will be removed in v0.4.0. Use ``center=sealevel`` instead
+  (:issue:`27`, :pull:`36`).
+
 New features
 ~~~~~~~~~~~~
 
@@ -51,7 +58,9 @@ Documentation
 ~~~~~~~~~~~~~
 
 - List plot method :meth:`.Dataset.hyoga.plot.bedrock_altitude_contours`
-  parameters in docstring (:issue: `33`).
+  parameters in docstring (:issue:`33`).
+- Homogenize and explain the use of ``center=False`` in documentation pages and
+  gallery examples (:issue:`27`, :pull:`36`)
 
 Internal changes
 ~~~~~~~~~~~~~~~~

examples/datasets/plot_bedrock_erosion.py

@@ -22,7 +22,7 @@
 with hyoga.open.example('pism.alps.out.2d.nc') as ds:
 
     # plot model output
-    ds.hyoga.plot.bedrock_altitude(ax=ax, vmin=0, vmax=4500)
+    ds.hyoga.plot.bedrock_altitude(ax=ax, center=False)
     ds.hyoga.plot.surface_altitude_contours(ax=ax)
     ds.hyoga.plot.bedrock_erosion(
         ax=ax, cbar_ax=cax, levels=[10**i for i in range(-9, 1)],

examples/datasets/plot_bedrock_isostasy.py

@@ -25,7 +25,7 @@
     ds = ds.hyoga.assign_isostasy(hyoga.open.example('pism.alps.in.boot.nc'))
 
     # plot model output
-    ds.hyoga.plot.bedrock_altitude(ax=ax, vmin=0, vmax=4500)
+    ds.hyoga.plot.bedrock_altitude(ax=ax, center=False)
     ds.hyoga.plot.surface_altitude_contours(ax=ax)
     ds.hyoga.plot.bedrock_isostasy(
         ax=ax, cbar_ax=cax, levels=[-150, -100, -50, 0, 0.5, 1, 1.5])

examples/datasets/plot_ice_margin.py

@@ -17,7 +17,7 @@
 with hyoga.open.example('pism.alps.out.2d.nc') as ds:
 
     # plot model output
-    ds.hyoga.plot.bedrock_altitude(cmap='Greys', vmin=0, vmax=4500)
+    ds.hyoga.plot.bedrock_altitude(cmap='Greys', center=False)
     ds.hyoga.plot.ice_margin(edgecolor='tab:blue', linewidths=1)
     ds.hyoga.plot.ice_margin(facecolor='tab:blue')
 

examples/datasets/plot_surface_contours.py

@@ -17,7 +17,7 @@
 with hyoga.open.example('pism.alps.out.2d.nc') as ds:
 
     # plot model output
-    ds.hyoga.plot.bedrock_altitude(vmin=0, vmax=3000)
+    ds.hyoga.plot.bedrock_altitude(center=False)
     ds.hyoga.plot.ice_margin(facecolor='w')
     ds.hyoga.plot.surface_altitude_contours(colors='tab:blue')
 

examples/datasets/plot_surface_streamplot.py

@@ -21,7 +21,7 @@
 with hyoga.open.example('pism.alps.out.2d.nc') as ds:
 
     # plot model output
-    ds.hyoga.plot.bedrock_altitude(ax=ax, vmin=0, vmax=4500)
+    ds.hyoga.plot.bedrock_altitude(ax=ax, center=False)
     ds.hyoga.plot.surface_altitude_contours(ax=ax)
     ds.hyoga.plot.ice_margin(ax=ax, facecolor='w')
     streams = ds.hyoga.plot.surface_velocity_streamplot(

examples/datasets/plot_surface_velocity.py

@@ -21,7 +21,7 @@
 with hyoga.open.example('pism.alps.out.2d.nc') as ds:
 
     # plot model output
-    ds.hyoga.plot.bedrock_altitude(ax=ax, vmin=0, vmax=4500)
+    ds.hyoga.plot.bedrock_altitude(ax=ax, center=False)
     ds.hyoga.plot.surface_altitude_contours(ax=ax)
     ds.hyoga.plot.surface_velocity(ax=ax, cbar_ax=cax, vmin=1e1, vmax=1e3)
     ds.hyoga.plot.ice_margin(ax=ax)

examples/shading/plot_bedrock_altitude.py

@@ -17,7 +17,7 @@
 with hyoga.open.example('pism.alps.in.boot.nc') as ds:
 
     # plot model output
-    ds.hyoga.plot.bedrock_altitude(cmap='Topographic', vmin=0, vmax=4500)
+    ds.hyoga.plot.bedrock_altitude(cmap='Topographic', vmin=0)
     ds.hyoga.plot.bedrock_hillshade()
 
     # add coastline and rivers

examples/shading/plot_bedrock_contours.py

@@ -23,7 +23,7 @@
 
     # plot model output
     ds.hyoga.plot.bedrock_altitude_contours(
-        ax=ax, cbar_ax=cax, cmap='Topographic', vmin=0, vmax=4500)
+        ax=ax, cbar_ax=cax, cmap='Topographic', vmin=0)
     ds.hyoga.plot.bedrock_hillshade(ax=ax)
 
     # add coastline and rivers

examples/vectors/plot_natural_earth.py

@@ -18,7 +18,7 @@
 
 # plot demo bedrock altitude
 with hyoga.open.example('pism.alps.out.2d.nc') as ds:
-    ds.hyoga.plot.bedrock_altitude(ax=ax, vmin=0, vmax=4500)
+    ds.hyoga.plot.bedrock_altitude(ax=ax, vmin=0)
 
     # plot canonical Natural Earth background
     ds.hyoga.plot.natural_earth(ax=ax)

examples/vectors/plot_paleoglaciers_alpine.py

@@ -17,7 +17,7 @@
 with hyoga.open.example('pism.alps.in.boot.nc') as ds:
 
     # plot model output
-    ds.hyoga.plot.bedrock_altitude(vmin=0, vmax=4500)
+    ds.hyoga.plot.bedrock_altitude(vmin=0)
     ax = ds.hyoga.plot.paleoglaciers(alpha=0.75)
 
 # set title

hyoga/plot/datasets.py

@@ -8,6 +8,7 @@
 shortcuts to oft-used plot methods with sensible defaults.
 """
 
+import warnings
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 import hyoga.plot.colormaps
@@ -85,6 +86,9 @@ def bedrock_altitude(self, sealevel=0, **kwargs):
             level, which may be useful for instance if different colors are
             used for negative and positive elevations. Note that `vmax=3000`,
             though, will always be 3000 bedrock altitude units above sea level.
+            .. deprecated:: 0.2.1
+                will be removed in version 0.4.0. To center the colormap around
+                sealevel, use the xarray keyword argument ``center=sealevel``.
         **kwargs: optional
             Keyword arguments passed to :meth:`xarray.DataArray.plot.imshow`.
             Defaults to a grey colormap, `zorder=-1` so that any other plot
@@ -98,6 +102,11 @@ def bedrock_altitude(self, sealevel=0, **kwargs):
         """
         style = dict(add_colorbar=False, cmap='Greys', zorder=-1)
         style.update(kwargs)
+        # if threshold is present, compute an ice mask
+        if sealevel != 0:
+            warnings.warn(
+                "the sealevel argument is deprecated and will be removed in "
+                "v0.4.0, use center=sealevel instead.", FutureWarning)
         var = self._hyoga.getvar('bedrock_altitude') - sealevel
         return self._imshow(var, **style)
 
@@ -258,13 +267,13 @@ def bedrock_isostasy(self, **kwargs):
         return self._contourf(var, **style)
 
     def bedrock_shoreline(self, sealevel=0, **kwargs):
-        """Plot bedrock topography and shoreline.
+        """Plot bedrock shoreline contour.
 
         Parameters
         ----------
         sealevel: float, optional
-            Substract this value to the bedrock altitude before plotting. This
-            will effectively shift the shoreline according to sea level.
+            A single contour level determining the shoreline altitude. Will be
+            overriden if ``levels`` is present in ``kwargs``.
         **kwargs: optional
             Keyword arguments passed to :meth:`xarray.DataArray.plot.contour`.
             Defaults to a dark gray thin contour.
@@ -274,9 +283,9 @@ def bedrock_shoreline(self, sealevel=0, **kwargs):
         contours : QuadContourSet
             The plotted bedrock shoreline contour set.
         """
-        style = dict(colors=['0.25'], levels=[0], linewidths=0.25, zorder=0)
+        style = dict(colors=['0.25'], levels=[sealevel], linewidths=0.25)
         style.update(**kwargs)
-        var = self._hyoga.getvar('bedrock_altitude') - sealevel
+        var = self._hyoga.getvar('bedrock_altitude')
         return self._contour(var, **style)
 
     def ice_margin(self, edgecolor='0.25', facecolor=None, **kwargs):