Add some documentation for ExtremeFinder.

anntzer · anntzer · commit a93ddb7917d6 · 2020-03-12T11:11:06.000+01:00
Let's try to figure out how this whole thing is constructed :)  At least
that's my understanding.
diff --git a/lib/mpl_toolkits/axisartist/angle_helper.py b/lib/mpl_toolkits/axisartist/angle_helper.py
@@ -335,26 +335,49 @@ def __call__(self, direction, factor, values):  # hour
 
 
 class ExtremeFinderCycle(ExtremeFinderSimple):
-    """
-    When there is a cycle, e.g., longitude goes from 0-360.
-    """
+    # docstring inherited
+
     def __init__(self, nx, ny,
                  lon_cycle=360., lat_cycle=None,
                  lon_minmax=None, lat_minmax=(-90, 90)):
+        """
+        This subclass handles the case where one or both coordinates should be
+        taken modulo 360, or be restricted to not exceed a specific range.
+
+        Parameters
+        ----------
+        nx, ny : int
+            The number of samples in each direction.
+
+        lon_cycle, lat_cycle : 360 or None
+            If not None, values in the corresponding direction are taken modulo
+            *lon_cycle* or *lat_cycle*; in theory this can be any number but
+            the implementation actually assumes that it is 360 (if not None);
+            other values give nonsensical results.
+
+            This is done by "unwrapping" the transformed grid coordinates so
+            that jumps are less than a half-cycle; then normalizing the span to
+            no more than a full cycle.
+
+            For example, if values are in the union of the [0, 2] and
+            [358, 360] intervals (typically, angles measured modulo 360), the
+            values in the second interval are normalized to [-2, 0] instead so
+            that the values now cover [-2, 2].  If values are in a range of
+            [5, 1000], this gets normalized to normalized to [5, 365].
+
+        lon_minmax, lat_minmax : (float, float) or None
+            If not None, the computed bounding box is clipped to the given
+            range in the corresponding direction.
+        """
         self.nx, self.ny = nx, ny
         self.lon_cycle, self.lat_cycle = lon_cycle, lat_cycle
         self.lon_minmax = lon_minmax
         self.lat_minmax = lat_minmax
 
     def __call__(self, transform_xy, x1, y1, x2, y2):
-        """
-        get extreme values.
-
-        x1, y1, x2, y2 in image coordinates (0-based)
-        nx, ny : number of divisions in each axis
-        """
-        x_, y_ = np.linspace(x1, x2, self.nx), np.linspace(y1, y2, self.ny)
-        x, y = np.meshgrid(x_, y_)
+        # docstring inherited
+        x, y = np.meshgrid(
+            np.linspace(x1, x2, self.nx), np.linspace(y1, y2, self.ny))
         lon, lat = transform_xy(np.ravel(x), np.ravel(y))
 
         # iron out jumps, but algorithm should be improved.
@@ -374,13 +397,6 @@ def __call__(self, transform_xy, x1, y1, x2, y2):
         lon_min, lon_max = np.nanmin(lon), np.nanmax(lon)
         lat_min, lat_max = np.nanmin(lat), np.nanmax(lat)
 
-        lon_min, lon_max, lat_min, lat_max = \
-            self._adjust_extremes(lon_min, lon_max, lat_min, lat_max)
-
-        return lon_min, lon_max, lat_min, lat_max
-
-    def _adjust_extremes(self, lon_min, lon_max, lat_min, lat_max):
-
         lon_min, lon_max, lat_min, lat_max = \
             self._add_pad(lon_min, lon_max, lat_min, lat_max)
 
diff --git a/lib/mpl_toolkits/axisartist/floating_axes.py b/lib/mpl_toolkits/axisartist/floating_axes.py
@@ -143,16 +143,21 @@ def get_line(self, axes):
 
 
 class ExtremeFinderFixed(ExtremeFinderSimple):
-    def __init__(self, extremes):
-        self._extremes = extremes
+    # docstring inherited
 
-    def __call__(self, transform_xy, x1, y1, x2, y2):
+    def __init__(self, extremes):
         """
-        get extreme values.
+        This subclass always returns the same bounding box.
 
-        x1, y1, x2, y2 in image coordinates (0-based)
-        nx, ny : number of division in each axis
+        Parameters
+        ----------
+        extremes : (float, float, float, float)
+            The bounding box always returned by this helper.
         """
+        self._extremes = extremes
+
+    def __call__(self, transform_xy, x1, y1, x2, y2):
+        # docstring inherited
         return self._extremes
 
 
diff --git a/lib/mpl_toolkits/axisartist/grid_finder.py b/lib/mpl_toolkits/axisartist/grid_finder.py
@@ -16,39 +16,50 @@ def _deprecate_factor_none(factor):
     return factor
 
 
-# extremes finder
 class ExtremeFinderSimple:
-    def __init__(self, nx, ny):
-        self.nx, self.ny = nx, ny
+    """
+    A helper class to figure out the range of grid lines that need to be drawn.
+    """
 
-    def __call__(self, transform_xy, x1, y1, x2, y2):
+    def __init__(self, nx, ny):
         """
-        get extreme values.
-
-        x1, y1, x2, y2 in image coordinates (0-based)
-        nx, ny : number of division in each axis
+        Parameters
+        ----------
+        nx, ny : int
+            The number of samples in each direction.
         """
-        x_, y_ = np.linspace(x1, x2, self.nx), np.linspace(y1, y2, self.ny)
-        x, y = np.meshgrid(x_, y_)
-        lon, lat = transform_xy(np.ravel(x), np.ravel(y))
-
-        lon_min, lon_max = lon.min(), lon.max()
-        lat_min, lat_max = lat.min(), lat.max()
+        self.nx = nx
+        self.ny = ny
 
-        return self._add_pad(lon_min, lon_max, lat_min, lat_max)
-
-    def _add_pad(self, lon_min, lon_max, lat_min, lat_max):
+    def __call__(self, transform_xy, x1, y1, x2, y2):
         """
-        A small amount of padding is added because the current clipping
-        algorithms seems to fail when the gridline ends at the bbox boundary.
+        Compute an approximation of the bounding box obtained by applying
+        *transform_xy* to the box delimited by ``(x1, y1, x2, y2)``.
+
+        The intended use is to have ``(x1, y1, x2, y2)`` in axes coordinates,
+        and have *transform_xy* be the transform from axes coordinates to data
+        coordinates; this method then returns the range of data coordinates
+        that span the actual axes.
+
+        The computation is done by sampling ``nx * ny`` equispaced points in
+        the ``(x1, y1, x2, y2)`` box and finding the resulting points with
+        extremal coordinates; then adding some padding to take into account the
+        finite sampling.
+
+        As each sampling step covers a relative range of *1/nx* or *1/ny*,
+        the padding is computed by expanding the span covered by the extremal
+        coordinates by these fractions.
         """
-        dlon = (lon_max - lon_min) / self.nx
-        dlat = (lat_max - lat_min) / self.ny
-
-        lon_min, lon_max = lon_min - dlon, lon_max + dlon
-        lat_min, lat_max = lat_min - dlat, lat_max + dlat
-
-        return lon_min, lon_max, lat_min, lat_max
+        x, y = np.meshgrid(
+            np.linspace(x1, x2, self.nx), np.linspace(y1, y2, self.ny))
+        xt, yt = transform_xy(np.ravel(x), np.ravel(y))
+        return self._add_pad(xt.min(), xt.max(), yt.min(), yt.max())
+
+    def _add_pad(self, x_min, x_max, y_min, y_max):
+        """Perform the padding mentioned in `__call__`."""
+        dx = (x_max - x_min) / self.nx
+        dy = (y_max - y_min) / self.ny
+        return x_min - dx, x_max + dx, y_min - dy, y_max + dy
 
 
 class GridFinder:
