hatch functions (#123)

* hatch functions

* update functions and add tests

* changelog

* better names

* changelog: better wording

* add example

* add to README (docs)

Author: mathause

CHANGELOG.md

@@ -17,6 +17,14 @@
 
 ### Enhancements
 
+- Added convinience functions to draw hatches and add stippling:
+
+  1. `mpu.hatch`: for regular axes
+  2. `mpu.hatch_map`: for cartopy GeoAxes
+  3. `mpu.hatch_map_global`: as 2. but also adds a cyclic point to the array
+
+  all three functions expect a 2D boolean `xr.DataArray` and a hatch pattern. Values that are `True` are hatched.
+
 - Enable passing `AxesGrid` (from `mpl_toolkits.axes_grid1`) to `set_map_layout` ([#116](https://github.com/mathause/mplotutils/pull/116)).
 - Raise more informative error when a wrong type is passed to `set_map_layout` ([#121](https://github.com/mathause/mplotutils/pull/121)).
 - `set_map_layout` now raises an explicit error when the figure contains SubFigure ([#121](https://github.com/mathause/mplotutils/pull/121)).

README.md

@@ -2,8 +2,11 @@
 
 > *helper functions for cartopy and matplotlib*
 
+## fix layout for cartopy axes and colorbars
+
 This package solves two main problems for plots with maps created with cartopy. Because these plots have a fixed aspect ratio (1) colorbars will extend beyond the visible axes and (2) the distance between individual subplots will seemingly be random.
 
+**subplots**
 
 Without mplotutils         |  With mplotutils
 :-------------------------:|:-------------------------:
@@ -22,6 +25,13 @@ Matplotlib's [axes_grid](https://matplotlib.org/stable/users/explain/toolkits/ax
 
 The code to create the example can be found in [docs/example_axes_grid.py](docs/example_axes_grid.py).
 
+## hatching
+
+mplotutils (from version 0.6) includes helper functions to draw hatches and add stippling:
+
+<img src="docs/example_hatch.png" alt="mplotutils hatching" width="350"/>
+
+The code to create the example can be found in [docs/example_hatch.py](docs/example_hatch.py).
 
 ## Installation
 

docs/example_hatch.png

@@ -0,0 +1,48 @@
+import cartopy.crs as ccrs
+import matplotlib.pyplot as plt
+import numpy as np
+import xarray as xr
+
+import mplotutils as mpu
+
+
+def main():
+
+    # read example data
+    air = xr.tutorial.open_dataset("air_temperature").air
+    air = air.resample(time="d").mean()
+
+    mean, std = air.mean("time"), air.std("time")
+
+    anomaly = air.isel(time=3) - mean
+
+    # create plot
+    f, ax = plt.subplots(subplot_kw={"projection": ccrs.PlateCarree()})
+
+    ax.coastlines()
+
+    h = anomaly.plot(ax=ax, transform=ccrs.PlateCarree(), add_colorbar=False)
+
+    # only for illustration purposes
+    signif = np.abs(anomaly) >= std
+
+    mpu.hatch_map(signif, "///", ax=ax, color="0.2", label="significant", linewidth=0.5)
+
+    ax.legend()
+
+    # adjust the margins manually
+    f.subplots_adjust(left=0.025, right=0.85, top=0.9, bottom=0.05)
+
+    # ensure the figure has the correct size
+    mpu.set_map_layout(ax)
+
+    mpu.colorbar(h, ax)
+
+    ax.set_title("Temperature")
+
+
+if __name__ == "__main__":
+
+    main()
+
+    plt.savefig("example_hatch.png", dpi=200)

docs/example_hatch.py

@@ -4,6 +4,7 @@
 
 from . import _colorbar, cartopy_utils, colormaps
 from ._colorbar import *
+from ._hatch import hatch, hatch_map, hatch_map_global
 from ._savefig import autodraw
 from .cartopy_utils import *
 from .colormaps import *

mplotutils/__init__.py

@@ -0,0 +1,237 @@
+import warnings
+
+import cartopy.crs as ccrs
+import matplotlib as mpl
+import numpy as np
+import xarray as xr
+
+import mplotutils as mpu
+
+_HATCHES_PER_FIGURE = {}
+
+
+from mplotutils.mpl import _maybe_gca
+
+
+def hatch(da, hatch, *, ax=None, label=None, linewidth=None, color="0.1"):
+    """add hatch pattern to an axes
+
+    Parameters
+    ----------
+    da : xr.DataArray
+        DataArray with the hatch information, must be boolean 2D array. Data of value
+        `True` is hatched.
+    hatch : str
+        Hatch pattern, one of: '/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'.
+        Hatching patterns can be repeated to increase the density.
+    ax : matplotlib.axes, default: None
+        Axes to draw the hatch on. If not given, uses the current axes or creates new
+        axes.
+    label : str
+        label for a legend entry
+    linewidth : float, default: 0.25
+        Default thickness of the hatching. Note that only one linewidth per figure is
+        supported (by matplotlib).
+    color : matplotlib color, default: "0.1"
+        Color of the hatch lines.
+
+    Returns
+    -------
+    `~.contour.QuadContourSet`
+
+    Notes
+    -----
+    Don't use this function to hatch levels of a contour plot - it's better to add
+    hatches directly to `countourf`.
+    """
+
+    return _hatch(
+        da,
+        hatch,
+        ax=ax,
+        label=label,
+        linewidth=linewidth,
+        color=color,
+        cyclic=False,
+        transform=None,
+    )
+
+
+def hatch_map(
+    da, hatch, *, ax=None, label=None, linewidth=None, color="0.1", transform=None
+):
+    """add hatch pattern to a regional cartopy map
+
+    Parameters
+    ----------
+    da : xr.DataArray
+        DataArray with the hatch information, must be boolean 2D array. Data of value
+        `True` is hatched.
+    hatch : str
+        Hatch pattern, one of: '/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'.
+        Hatching patterns can be repeated to increase the density.
+    ax : matplotlib.axes, default: None
+        Axes to draw the hatch on. If not given, uses the current axes or creates new
+        axes.
+    label : str
+        label for a legend entry
+    linewidth : float, default: 0.25
+        Default thickness of the hatching. Note that only one linewidth per figure is
+        supported (by matplotlib).
+    color : matplotlib color, default: "0.1"
+        Color of the hatch lines.
+    transform : cartopy projection, optional
+        Defines the transformation of the data. If None uses 'PlateCarree'.
+
+    Returns
+    -------
+    `~.contour.QuadContourSet`
+
+    Notes
+    -----
+    Don't use this function to hatch levels of a contour plot - it's better to add
+    hatches directly to `countourf`.
+    """
+
+    if transform is None:
+        transform = ccrs.PlateCarree()
+
+    return _hatch(
+        da,
+        hatch,
+        ax=ax,
+        label=label,
+        linewidth=linewidth,
+        color=color,
+        cyclic=False,
+        transform=transform,
+    )
+
+
+def hatch_map_global(
+    da, hatch, *, ax=None, label=None, linewidth=None, color="0.1", transform=None
+):
+    """add hatch pattern to a global cartopy map - adds a cyclic data point
+
+    Parameters
+    ----------
+    da : xr.DataArray
+        DataArray with the hatch information, must be boolean 2D array. Data of value
+        `True` is hatched.
+    hatch : str
+        Hatch pattern, one of: '/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'.
+        Hatching patterns can be repeated to increase the density.
+    ax : matplotlib.axes, default: None
+        Axes to draw the hatch on. If not given, uses the current axes or creates new
+        axes.
+    label : str
+        label for a legend entry
+    linewidth : float, default: 0.25
+        Default thickness of the hatching. Note that only one linewidth per figure is
+        supported (by matplotlib).
+    color : matplotlib color, default: "0.1"
+        Color of the hatch lines.
+    transform : cartopy projection, optional
+        Defines the transformation of the data. If None uses 'PlateCarree'.
+
+    Returns
+    -------
+    `~.contour.QuadContourSet`
+
+    Notes
+    -----
+    Don't use this function to hatch levels of a contour plot - it's better to add
+    hatches directly to `countourf`.
+    """
+
+    if transform is None:
+        transform = ccrs.PlateCarree()
+
+    return _hatch(
+        da,
+        hatch,
+        ax=ax,
+        label=label,
+        linewidth=linewidth,
+        color=color,
+        cyclic=True,
+        transform=transform,
+    )
+
+
+def _hatch(
+    da,
+    hatch,
+    *,
+    ax=None,
+    label=None,
+    linewidth=None,
+    color="0.1",
+    cyclic=False,
+    transform=None,
+):
+
+    if not isinstance(da, xr.DataArray):
+        raise TypeError(f"Expected a xr.DataArray, got {type(da)}.")
+
+    if not np.issubdtype(da.dtype, bool):
+        raise TypeError(f"Expected a boolean array, got {da.dtype}")
+
+    if da.ndim != 2:
+        raise ValueError(f"Expected a 2D array, got {da.ndim=}")
+
+    if ax is None:
+        ax = _maybe_gca()
+
+    fig = ax.figure
+
+    # only one linewidth is possible per figure (actually it is just read before
+    # saving the figure, so the above is not 100 % correct)
+    if linewidth is None:
+        # only set linewidth if not yet set
+        if not _HATCHES_PER_FIGURE.get(fig):
+            mpl.rcParams["hatch.linewidth"] = 0.25
+    else:
+        if _HATCHES_PER_FIGURE.get(fig):
+            warnings.warn(
+                "Can only set one `linewidth` per figure. Overwriting previous value of"
+                f" {_HATCHES_PER_FIGURE[fig]}."
+            )
+
+        mpl.rcParams["hatch.linewidth"] = linewidth
+
+        _HATCHES_PER_FIGURE[fig] = linewidth
+
+    mpl.rcParams["hatch.color"] = color
+
+    if label is not None:
+        # add an empty patch to generate a legend entry
+        xy = np.full((0, 2), fill_value=np.nan)
+        empty_legend_patch = mpl.patches.Polygon(
+            xy,
+            facecolor="none",
+            ec="0.1",
+            hatch=hatch,
+            label=label,
+        )
+
+        # NOTE: manually overwrites the private _hatch_color property - allows to have
+        # different ec and hatch color (so the box of the legend is black)
+        empty_legend_patch._hatch_color = mpl.colors.to_rgba(
+            mpl.rcParams["hatch.color"]
+        )
+        ax.add_patch(empty_legend_patch)
+
+    if cyclic:
+        _, lon_dim = da.dims
+        da = mpu.cyclic_dataarray(da, lon_dim)
+
+    return da.plot.contourf(
+        ax=ax,
+        hatches=["", hatch],
+        levels=[0, 0.5, 1],
+        colors="none",
+        extend="neither",
+        transform=transform,
+        add_colorbar=False,
+    )

mplotutils/_hatch.py

@@ -1,10 +1,19 @@
 import contextlib
+import warnings
 
 import matplotlib
 import matplotlib.pyplot as plt
 import pytest
 
 
+@contextlib.contextmanager
+def assert_no_warnings():
+
+    with warnings.catch_warnings(record=True) as record:
+        yield
+        assert len(record) == 0, "got unexpected warning(s)"
+
+
 @contextlib.contextmanager
 def figure_context(*args, **kwargs):
     fig = plt.figure(*args, **kwargs)