make binning possible for all methods

ValentinGebhart · ValentinGebhart · commit 3fa13805e080 · 2025-03-13T14:36:38.000+01:00
diff --git a/climada/engine/impact.py b/climada/engine/impact.py
@@ -530,10 +530,9 @@ def local_exceedance_impact(
             If set to True, impact values are converted to log scale before
             inter- and extrapolation. Defaults to True.
         bin_decimals : int, optional
-            This parameter is only used if method is set to "extrapolate". Number of decimals
-            for the binning of the impact values, see Notes. If None,
-            impact values are not binned. Defaults to None.
-
+            Number of decimals to group and bin impact values. Binning results in smoother (and
+            coarser) interpolation and more stable extrapolation. For more details and sensible
+            values for bin_decimals, see Notes. If None, values are not binned. Defaults to None.
         Returns
         -------
         gdf : gpd.GeoDataFrame
@@ -553,11 +552,15 @@ def local_exceedance_impact(
 
         Notes
         -------
-        If method = "extrapolate" and an integer bin_decimals is provided, impacts are binned
-        according to their bin_decimals decimal places. This results in a smoother (and coarser)
-        interpolation, and a more stable extrapolation. The default bin_decimals=None results in
-        not binning the values. For more information about the binning, see
-        climada.util.interpolation.preprocess_and_interpolate_ev().
+        If an integer bin_decimals is given, the impact values are binned according to their
+        bin_decimals decimals, and their corresponding frequencies are summed. This binning leads
+        to a smoother (and coarser) interpolation, and a more stable extrapolation. For instance,
+        if bin_decimals=1, the two values 12.01 and 11.97 with corresponding frequencies 0.1 and
+        0.2 are combined to a value 12.0 with frequency 0.3. The default bin_decimals=None results
+        in not binning the values.
+        E.g., if your impact range from 1 to 100, you could use bin_decimals=1, if your
+        impact range from 1e6 to 1e9, you could use bin_decimals=-5, if your impact
+        range from 0.0001 to .01, you could use bin_decimals=5.
         """
         LOGGER.info(
             "Computing exceedance impact map for return periods: %s", return_periods
@@ -683,9 +686,9 @@ def local_return_period(
             If set to True, impact values are converted to log scale before
             inter- and extrapolation. Defaults to True.
         bin_decimals : int, optional
-            This parameter is only used if method is set to "extrapolate". Number of decimals
-            for the binning of the impact values, see Notes. If None,
-            impact values are not binned. Defaults to None.
+            Number of decimals to group and bin impact values. Binning results in smoother (and
+            coarser) interpolation and more stable extrapolation. For more details and sensible
+            values for bin_decimals, see Notes. If None, values are not binned. Defaults to None.
 
         Returns
         -------
@@ -706,11 +709,15 @@ def local_return_period(
 
         Notes
         -------
-        If method = "extrapolate" and an integer bin_decimals is provided, impacts are binned
-        according to their bin_decimals decimal places. This results in a smoother (and coarser)
-        interpolation, and a more stable extrapolation. The default bin_decimals=None results in
-        not binning the values. For more information about the binning, see
-        climada.util.interpolation.preprocess_and_interpolate_ev().
+        If an integer bin_decimals is given, the impact values are binned according to their
+        bin_decimals decimals, and their corresponding frequencies are summed. This binning leads
+        to a smoother (and coarser) interpolation, and a more stable extrapolation. For instance,
+        if bin_decimals=1, the two values 12.01 and 11.97 with corresponding frequencies 0.1 and
+        0.2 are combined to a value 12.0 with frequency 0.3. The default bin_decimals=None results
+        in not binning the values.
+        E.g., if your impact range from 1 to 100, you could use bin_decimals=1, if your
+        impact range from 1e6 to 1e9, you could use bin_decimals=-5, if your impact
+        range from 0.0001 to .01, you could use bin_decimals=5.
         """
 
         LOGGER.info("Computing return period map for impacts: %s", threshold_impact)
diff --git a/climada/hazard/base.py b/climada/hazard/base.py
@@ -521,9 +521,9 @@ def local_exceedance_intensity(
             If set to True, intensity values are converted to log scale before
             inter- and extrapolation. Defaults to True.
         bin_decimals : int, optional
-            This parameter is only used if method is set to "extrapolate". Number of decimals
-            for the binning of the intensity values, see Notes. If None,
-            intensity values are not binned. Defaults to None.
+            Number of decimals to group and bin intensity values. Binning results in smoother (and
+            coarser) interpolation and more stable extrapolation. For more details and sensible
+            values for bin_decimals, see Notes. If None, values are not binned. Defaults to None.
 
         Returns
         -------
@@ -544,11 +544,15 @@ def local_exceedance_intensity(
 
         Notes
         -------
-        If method = "extrapolate" and an integer bin_decimals is provided, intensites are binned
-        according to their bin_decimals decimal places. This results in a smoother (and coarser)
-        interpolation, and a more stable extrapolation. The default bin_decimals=None results in
-        not binning the values. For more information about the binning, see
-        climada.util.interpolation.preprocess_and_interpolate_ev().
+        If an integer bin_decimals is given, the intensity values are binned according to their
+        bin_decimals decimals, and their corresponding frequencies are summed. This binning leads
+        to a smoother (and coarser) interpolation, and a more stable extrapolation. For instance,
+        if bin_decimals=1, the two values 12.01 and 11.97 with corresponding frequencies 0.1 and
+        0.2 are combined to a value 12.0 with frequency 0.3. The default bin_decimals=None results
+        in not binning the values.
+        E.g., if your intensities range from 1 to 100, you could use bin_decimals=1, if your
+        intensities range from 1e6 to 1e9, you could use bin_decimals=-5, if your intensities
+        range from 0.0001 to .01, you could use bin_decimals=5.
         """
         if not min_intensity and min_intensity != 0:
             min_intensity = self.intensity_thres
@@ -672,9 +676,9 @@ def local_return_period(
             If set to True, intensity values are converted to log scale before
             inter- and extrapolation. Defaults to True.
         bin_decimals : int, optional
-            This parameter is only used if method is set to "extrapolate". Number of decimals
-            for the binning of the intensity values, see Notes. If None,
-            intensity values are not binned. Defaults to None.
+            Number of decimals to group and bin intensity values. Binning results in smoother (and
+            coarser) interpolation and more stable extrapolation. For more details and sensible
+            values for bin_decimals, see Notes. If None, values are not binned. Defaults to None.
 
 
         Returns
@@ -696,11 +700,15 @@ def local_return_period(
 
         Notes
         -------
-        If method = "extrapolate" and an integer bin_decimals is provided, intensites are binned
-        according to their bin_decimals decimal places. This results in a smoother (and coarser)
-        interpolation, and a more stable extrapolation. The default bin_decimals=None results in
-        not binning the values. For more information about the binning, see
-        climada.util.interpolation.preprocess_and_interpolate_ev().
+        If an integer bin_decimals is given, the intensity values are binned according to their
+        bin_decimals decimals, and their corresponding frequencies are summed. This binning leads
+        to a smoother (and coarser) interpolation, and a more stable extrapolation. For instance,
+        if bin_decimals=1, the two values 12.01 and 11.97 with corresponding frequencies 0.1 and
+        0.2 are combined to a value 12.0 with frequency 0.3. The default bin_decimals=None results
+        in not binning the values.
+        E.g., if your intensities range from 1 to 100, you could use bin_decimals=1, if your
+        intensities range from 1e6 to 1e9, you could use bin_decimals=-5, if your intensities
+        range from 0.0001 to .01, you could use bin_decimals=5.
         """
         if not min_intensity and min_intensity != 0:
             min_intensity = self.intensity_thres
diff --git a/climada/util/interpolation.py b/climada/util/interpolation.py
@@ -77,9 +77,10 @@ def preprocess_and_interpolate_ev(
         Has no effect if method is "interpolate". Else, provides return value and if
         for test x values larger than given x values, if size < 2 or if method is set
         to "extrapolate_constant" or "stepfunction". Defaults to np.nan.
-    bin_decimals : int or None, optional
-        Number of decimals to group and bin the values, see Notes. If None, values are not binned.
-        Defaults to None.
+    bin_decimals : int, optional
+        Number of decimals to group and bin the values. Binning results in smoother (and coarser)
+        interpolation and more stable extrapolation. For more details and sensible values for
+        bin_decimals, see Notes. If None, values are not binned. Defaults to None.
 
     Returns
     -------
@@ -94,12 +95,15 @@ def preprocess_and_interpolate_ev(
 
     Notes
     -----
-    Before extrapolation, if an integer bin_decimals is given, the values are binned according to
-    their bin_decimals decimals, and their corresponding frequencies are summed. For instance, if
+    If an integer bin_decimals is given, the values are binned according to their
+    bin_decimals decimals, and their corresponding frequencies are summed. This binning leads to
+    a smoother (and coarser) interpolation, and a more stable extrapolation. For instance, if
     bin_decimals=1, the two values 12.01 and 11.97 with corresponding frequencies 0.1 and 0.2 are
-    combined to a value 12.0 with frequency 0.3. This binning leads to a smoother (and coarser)
-    interpolation, and a more stable extrapolation. The default bin_decimals=None results in not
+    combined to a value 12.0 with frequency 0.3. The default bin_decimals=None results in not
     binning the values.
+    E.g., if your values range from 1 to 100, you could use bin_decimals=1, if your values range
+    from 1e6 to 1e9, you could use bin_decimals=-5, if your values range from 0.0001 to .01, you
+    could use bin_decimals=5.
     """
 
     # check that only test frequencies or only test values are given
@@ -117,7 +121,7 @@ def preprocess_and_interpolate_ev(
     frequency = frequency[sorted_idxs]
 
     # group similar values together
-    if method == "extrapolate" and isinstance(bin_decimals, int):
+    if isinstance(bin_decimals, int):
         frequency, values = _group_frequency(frequency, values, bin_decimals)
 
     # transform frequencies to cummulative frequencies
