change keyword name and improve docstring descriptions

Author: ValentinGebhart

climada/engine/impact.py

@@ -1178,7 +1178,7 @@ def plot_rp_imp(
         return_periods=(25, 50, 100, 250),
         log10_scale=True,
         axis=None,
-        mask_relative_distance=None,
+        mask_distance=None,
         kwargs_local_exceedance_impact=None,
         **kwargs,
     ):
@@ -1195,10 +1195,10 @@ def plot_rp_imp(
             plot impact as log10(impact). Default: True
         smooth : bool, optional
             smooth plot to plot.RESOLUTIONxplot.RESOLUTION. Default: True
-        mask_relative_distance: float, optional
-            Relative distance (with respect to maximal map extent in longitude or latitude) to data
-            points above which plot should not display values. For instance, to only plot values
-            at the centroids, use mask_relative_distance=0.01. If None, the plot is not masked.
+        mask_distance: float, optional
+            Only regions are plotted that are closer to any of the data points than this distance,
+            relative to overall plot size. For instance, to only plot values
+            at the centroids, use mask_distance=0.01. If None, the plot is not masked.
             Default is None.
         kwargs_local_exceedance_impact: dict
             Dictionary of keyword arguments for the method impact.local_exceedance_impact.
@@ -1252,7 +1252,7 @@ def plot_rp_imp(
             title,
             column_labels,
             axis=axis,
-            mask_relative_distance=mask_relative_distance,
+            mask_distance=mask_distance,
             **kwargs,
         )
         return axis, impacts_stats_vals

climada/hazard/plot.py

@@ -40,7 +40,7 @@ def plot_rp_intensity(
         self,
         return_periods=(25, 50, 100, 250),
         axis=None,
-        mask_relative_distance=None,
+        mask_distance=None,
         kwargs_local_exceedance_intensity=None,
         **kwargs,
     ):
@@ -57,10 +57,10 @@ def plot_rp_intensity(
             axis to use
         kwargs_local_exceedance_intensity: dict
             Dictionary of keyword arguments for the method hazard.local_exceedance_intensity.
-        mask_relative_distance: float, optional
-            Relative distance (with respect to maximal map extent in longitude or latitude) to data
-            points above which plot should not display values. For instance, to only plot values
-            at the centroids, use mask_relative_distance=0.01. If None, the plot is not masked.
+        mask_distance: float, optional
+            Only regions are plotted that are closer to any of the data points than this distance,
+            relative to overall plot size. For instance, to only plot values
+            at the centroids, use mask_distance=0.01. If None, the plot is not masked.
             Default is None.
         kwargs: optional
             arguments for pcolormesh matplotlib function used in event plots
@@ -99,7 +99,7 @@ def plot_rp_intensity(
             title,
             column_labels,
             axis=axis,
-            mask_relative_distance=mask_relative_distance,
+            mask_distance=mask_distance,
             **kwargs,
         )
         return axis, inten_stats.values[:, 1:].T.astype(float)
@@ -111,7 +111,7 @@ def plot_intensity(
         smooth=True,
         axis=None,
         adapt_fontsize=True,
-        mask_relative_distance=None,
+        mask_distance=None,
         **kwargs,
     ):
         """Plot intensity values for a selected event or centroid.
@@ -135,10 +135,10 @@ def plot_intensity(
             in module `climada.util.plot`)
         axis: matplotlib.axes._subplots.AxesSubplot, optional
             axis to use
-        mask_relative_distance: float, optional
-            Relative distance (with respect to maximal map extent in longitude or latitude) to data
-            points above which plot should not display values. For instance, to only plot values
-            at the centroids, use mask_relative_distance=0.01. If None, the plot is not masked.
+        mask_distance: float, optional
+            Only regions are plotted that are closer to any of the data points than this distance,
+            relative to overall plot size. For instance, to only plot values
+            at the centroids, use mask_distance=0.01. If None, the plot is not masked.
             Default is None.
         kwargs: optional
             arguments for pcolormesh matplotlib function
@@ -165,7 +165,7 @@ def plot_intensity(
                 crs_epsg,
                 axis,
                 adapt_fontsize=adapt_fontsize,
-                mask_relative_distance=mask_relative_distance,
+                mask_distance=mask_distance,
                 **kwargs,
             )
         if centr is not None:
@@ -181,7 +181,7 @@ def plot_fraction(
         centr=None,
         smooth=True,
         axis=None,
-        mask_relative_distance=None,
+        mask_distance=None,
         **kwargs,
     ):
         """Plot fraction values for a selected event or centroid.
@@ -205,10 +205,10 @@ def plot_fraction(
             in module `climada.util.plot`)
         axis: matplotlib.axes._subplots.AxesSubplot, optional
             axis to use
-        mask_relative_distance: float, optional
+        mask_distance: float, optional
             Relative distance (with respect to maximal map extent in longitude or latitude) to data
             points above which plot should not display values. For instance, to only plot values
-            at the centroids, use mask_relative_distance=0.01. If None, the plot is not masked.
+            at the centroids, use mask_distance=0.01. If None, the plot is not masked.
             Default is None.
         kwargs: optional
             arguments for pcolormesh matplotlib function
@@ -232,7 +232,7 @@ def plot_fraction(
                 col_label,
                 smooth,
                 axis,
-                mask_relative_distance=mask_relative_distance,
+                mask_distance=mask_distance,
                 **kwargs,
             )
         if centr is not None:
@@ -252,7 +252,7 @@ def _event_plot(
         axis=None,
         figsize=(9, 13),
         adapt_fontsize=True,
-        mask_relative_distance=None,
+        mask_distance=None,
         **kwargs,
     ):
         """Plot an event of the input matrix.
@@ -274,10 +274,10 @@ def _event_plot(
             axis to use
         figsize: tuple, optional
             figure size for plt.subplots
-        mask_relative_distance: float, optional
-            Relative distance (with respect to maximal map extent in longitude or latitude) to data
-            points above which plot should not display values. For instance, to only plot values
-            at the centroids, use mask_relative_distance=0.01. If None, the plot is not masked.
+        mask_distance: float, optional
+            Only regions are plotted that are closer to any of the data points than this distance,
+            relative to overall plot size. For instance, to only plot values
+            at the centroids, use mask_distance=0.01. If None, the plot is not masked.
             Default is None.
         kwargs: optional
             arguments for pcolormesh matplotlib function
@@ -326,7 +326,7 @@ def _event_plot(
             figsize=figsize,
             proj=crs_espg,
             adapt_fontsize=adapt_fontsize,
-            mask_relative_distance=mask_relative_distance,
+            mask_distance=mask_distance,
             **kwargs,
         )
 

climada/util/plot.py

@@ -338,7 +338,7 @@ def geo_im_from_array(
     axes=None,
     figsize=(9, 13),
     adapt_fontsize=True,
-    mask_relative_distance=None,
+    mask_distance=None,
     **kwargs,
 ):
     """Image(s) plot defined in array(s) over input coordinates.
@@ -370,10 +370,10 @@ def geo_im_from_array(
     adapt_fontsize : bool, optional
         If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise
         the default matplotlib font size is used. Default is True.
-    mask_relative_distance: float, optional
-        Relative distance (with respect to maximal map extent in longitude or latitude) to data
-        points above which plot should not display values. For instance, to only plot values
-        at the centroids, use mask_relative_distance=0.01. If None, the plot is not masked.
+    mask_distance: float, optional
+        Only regions are plotted that are closer to any of the data points than this distance,
+        relative to overall plot size. For instance, to only plot values
+        at the centroids, use mask_distance=0.01. If None, the plot is not masked.
         Default is None.
     **kwargs
         arbitrary keyword arguments for pcolormesh matplotlib function
@@ -456,15 +456,14 @@ def geo_im_from_array(
                 fill_value=min_value,
             )
             # Compute distance of each grid point to the nearest known point
-            if mask_relative_distance is not None:
+            if mask_distance is not None:
                 tree = cKDTree(np.array((coord[:, 1], coord[:, 0])).T)
                 distances, _ = tree.query(
                     np.c_[grid_x.ravel(), grid_y.ravel()],
                     p=2,  # for plotting squares and not sphere around centroids use p=np.inf
                 )
                 threshold = (
-                    max(extent[1] - extent[0], extent[3] - extent[2])
-                    * mask_relative_distance
+                    max(extent[1] - extent[0], extent[3] - extent[2]) * mask_distance
                 )
                 grid_im[(distances.reshape(grid_im.shape) > threshold)] = min_value
         else:
@@ -1105,7 +1104,7 @@ def plot_from_gdf(
     axis=None,
     figsize=(9, 13),
     adapt_fontsize=True,
-    mask_relative_distance=None,
+    mask_distance=None,
     **kwargs,
 ):
     """Plot several subplots from different columns of a GeoDataFrame, e.g., for
@@ -1128,10 +1127,10 @@ def plot_from_gdf(
     adapt_fontsize: bool, optional
         If set to true, the size of the fonts will be adapted to the size of the figure.
         Otherwise the default matplotlib font size is used. Default is True.
-    mask_relative_distance: float, optional
+    mask_distance: float, optional
         Relative distance (with respect to maximal map extent in longitude or latitude) to data
         points above which plot should not display values. For instance, to only plot values
-        at the centroids, use mask_relative_distance=0.01. If None, the plot is not masked.
+        at the centroids, use mask_distance=0.01. If None, the plot is not masked.
         Default is None.
     kwargs: optional
         Arguments for pcolormesh matplotlib function used in event plots.
@@ -1193,7 +1192,7 @@ def plot_from_gdf(
         axes=axis,
         figsize=figsize,
         adapt_fontsize=adapt_fontsize,
-        mask_relative_distance=mask_relative_distance,
+        mask_distance=mask_distance,
         **kwargs,
     )