return an ImpactFreqCurve object when inter- extrapolating

ValentinGebhart · ValentinGebhart · commit 36d4cc8b4505 · 2026-04-01T16:53:46.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,7 +13,7 @@ Code freeze date: YYYY-MM-DD
 ### Added
 
 - Better type hints and overloads signatures for ImpactFuncSet [#1250](https://github.com/CLIMADA-project/climada_python/pull/1250)
-- Add inter- and extrapolation options to `ImpactFreqCurve` with methods `extrapolate` and `plot_extrapolate` [#1252](https://github.com/CLIMADA-project/climada_python/pull/1252)
+- Add inter- and extrapolation options to `ImpactFreqCurve` with method `interpolate` [#1252](https://github.com/CLIMADA-project/climada_python/pull/1252)
 
 ### Changed
 - Updated Impact Calculation Tutorial (`doc.climada_engine_Impact.ipynb`) [#1095](https://github.com/CLIMADA-project/climada_python/pull/1095).
@@ -23,7 +23,7 @@ Code freeze date: YYYY-MM-DD
 - Fixed asset count in impact logging message [#1195](https://github.com/CLIMADA-project/climada_python/pull/1195).
 
 ### Deprecated
-- `Impact.calc_freq_curve()` should not be given the parameter `return_per`. Use the parameter `return_periods` in `Impact.calc_freq_curve().extrapolate()` instead.
+- `Impact.calc_freq_curve()` should not be given the parameter `return_per`. Use the parameter `return_periods` in `Impact.calc_freq_curve().interpolate()` instead.
 
 ### Removed
 - `climada.util.earth_engine.py` Google Earth Engine methods did not facilitate direct use of GEE data in CLIMADA. Code was relocated to [climada-snippets](https://github.com/CLIMADA-project/climada-snippets). [#1109](https://github.com/CLIMADA-project/climada_python/pull/1109)
diff --git a/climada/engine/impact.py b/climada/engine/impact.py
@@ -788,7 +788,7 @@ def calc_freq_curve(self, return_per=None):
         if return_per is not None:
             warnings.warn(
                 "Calculating the frequency curve on user-specified return periods is deprecated. "
-                "Use ImpactFreqCurve.extrapolate() instead.",
+                "Use ImpactFreqCurve.calc_freq_curve().interpolate() instead.",
                 DeprecationWarning,
                 stacklevel=2,
             )
@@ -2287,19 +2287,28 @@ def plot(self, axis=None, log_frequency=False, **kwargs):
         -------
         matplotlib.axes.Axes
         """
-
-        return self._plot(
-            self.return_per,
-            self.impact,
-            axis,
-            log_frequency,
-            self.frequency_unit,
-            self.unit,
-            self.label,
-            **kwargs,
+        # check frequency unit
+        return_period_unit = u_dt.convert_frequency_unit_to_time_unit(
+            self.frequency_unit
         )
 
-    def extrapolate(
+        if not axis:
+            _, axis = plt.subplots(1, 1)
+        axis.set_title(self.label)
+        axis.set_ylabel("Impact (" + self.unit + ")")
+
+        if log_frequency:
+            axis.set_xlabel(f"Exceedance frequency ({self.frequency_unit})")
+            axis.set_xscale("log")
+            axis.plot(self.return_per**-1, self.impact, **kwargs)
+
+        else:
+            axis.set_xlabel(f"Return period ({return_period_unit})")
+            axis.plot(self.return_per, self.impact, **kwargs)
+
+        return axis
+
+    def interpolate(
         self,
         return_periods,
         *,
@@ -2310,7 +2319,7 @@ def extrapolate(
         bin_decimals=None,
         y_asymptotic=0.0,
     ):
-        """Extrapolate impact frequency curve with different interpolation and extrapolation options.
+        """Interpolate and extrapolate impact frequency curve using different methods.
 
         Parameters
         ----------
@@ -2348,8 +2357,8 @@ def extrapolate(
 
         Returns
         -------
-        np.array
-            array of exceeded impacts at given return periods
+        ImpactFreqCurve
+            impact frequency curve with inter- and extrapolated values
 
         See Also
         --------
@@ -2363,7 +2372,7 @@ def extrapolate(
         impacts = np.squeeze(np.array(self.impact)[sorted_idxs])
         rps = np.asarray(self.return_per)[sorted_idxs]
         frequency = np.diff(1 / np.array(rps)[::-1], prepend=0)[::-1]
-        return u_interp.preprocess_and_interpolate_ev(
+        impact_interpolated = u_interp.preprocess_and_interpolate_ev(
             exceedance_frequency,
             None,
             frequency,
@@ -2376,154 +2385,10 @@ def extrapolate(
             bin_decimals=bin_decimals,
         )
 
-    def plot_extrapolate(
-        self,
-        *,
-        return_periods=None,
-        axis=None,
-        log_frequency=False,
-        kwargs_interp=None,
-        **kwargs,
-    ):
-        """Plot impact frequency curve with interpolation and extrapolation options.
-
-        Parameters
-        ----------
-        return_periods : Iterable[float], optional
-            Return period values to plot, e.g. np.linspace(5, 500, 1000) to plot between 5 and
-            500 years. If None, the plot range defined between 0.5*min(data_return_periods) and
-            1.2*max(data_return_periods), where data_return_periods are the return period values
-            extracted from the impact object's data. Defaults to None.
-        axis : matplotlib.axes.Axes, optional
-            axis to use
-        log_frequency : boolean, optional
-            plot logarithmioc exceedance frequency on x-axis
-        kwargs_interp : dict, optional
-            dict with (key, value) pairs to handle inter- and extrapolation behaviour, e.g.
-            {"method": "extrapolate"}. Default is {"method": "interpolate", "log_frequency": True,
-            "log_impact": True, "min_impact": 0, "bin_decimals": None}. Available options are
-            method : str, optional
-                Method to interpolate to new return periods. Currently available are
-                "interpolate", "extrapolate", "extrapolate_constant" and "stepfunction". If set
-                to "interpolate", return periods outside the range of the Impact object's observed
-                return periods will be assigned NaN. If set to "extrapolate_constant" or
-                "stepfunction", return periods larger than the Impact object's observed return
-                periods will be assigned the largest impact, and return periods smaller than the
-                Impact object's observed return periods will be assigned 0. If set to
-                "extrapolate", exceedance impacts will be extrapolated (and interpolated). The
-                extrapolation to large return periods uses the two highest impacts of the centroid
-                and their return periods and extends the interpolation between these points to the
-                given return period (similar for small return periods). Defauls to "interpolate".
-            min_impact : float, optional
-                Minimum threshold to filter the impact. Defaults to 0.
-            log_frequency : bool, optional
-                If set to True, (cummulative) frequency values are converted to log scale before
-                inter- and extrapolation. Defaults to True.
-            log_impact : bool, optional
-                If set to True, impact values are converted to log scale before
-                inter- and extrapolation. Defaults to True.
-            bin_decimals : int, optional
-                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.
-            y_asymptotic : float, optional
-                Has no effect if method is "interpolate". Else, if data size < 2 or if method
-                is set to "extrapolate_constant" or "stepfunction", it provides return value for
-                exceeded impact for return periods smaller than the data range. Defaults to 0.
-        kwargs : dict, optional
-            arguments for plot matplotlib function, e.g. color='b'
-
-        Returns
-        -------
-        matplotlib.axes.Axes
-
-        See Also
-        --------
-        climada.engine.impact.ImpactFreqCurve.extrapolate:
-            extrapolation method used in the plotting function
-        util.interpolation.preprocess_and_interpolate_ev :
-            inter- and extrapolation method
-        """
-        if kwargs_interp is None:
-            kwargs_interp = {}
-        kwargs_interp = {
-            "method": "interpolate",
-            "log_frequency": True,
-            "log_impact": True,
-            "min_impact": 0.0,
-            "bin_decimals": None,
-            "y_asymptotic": 0.0,
-        } | kwargs_interp
-
-        if return_periods is None:
-            return_periods = np.linspace(
-                0.5 * min(self.return_per), 1.2 * max(self.return_per), 500
-            )
-
-        impacts = self.extrapolate(return_periods, **kwargs_interp)
-
-        # check frequency unit
-        return_period_unit = u_dt.convert_frequency_unit_to_time_unit(
-            self.frequency_unit
+        return ImpactFreqCurve(
+            return_per=return_periods,
+            impact=impact_interpolated,
+            unit=self.unit,
+            frequency_unit=self.frequency_unit,
+            label=self.label,
         )
-
-        if not axis:
-            _, axis = plt.subplots(1, 1)
-        axis.set_title(self.label)
-        axis.set_ylabel("Impact (" + self.unit + ")")
-        if log_frequency:
-            axis.set_xlabel(f"Exceedance frequency ({self.frequency_unit})")
-            axis.set_xscale("log")
-            x_vals = return_periods**-1
-        else:
-            axis.set_xlabel(f"Return period ({return_period_unit})")
-            x_vals = return_periods
-
-        # plot extrapolated data as dashed line
-        if kwargs_interp["method"] == "interpolate":
-            axis.plot(x_vals, impacts, linestyle="-", **kwargs)
-        else:
-            kwargs_copy = kwargs.copy()
-            color = kwargs_copy.pop("color", None)
-            min_rp = min(self.return_per)
-            max_rp = max(self.return_per)
-            mask = (return_periods >= min_rp) & (return_periods <= max_rp)
-
-            line_data = axis.plot(
-                x_vals[mask], impacts[mask], linestyle="-", color=color, **kwargs_copy
-            )[0]
-            color = line_data.get_color()
-            axis.plot(x_vals, impacts, linestyle="--", color=color, **kwargs_copy)
-
-        return axis
-
-    @staticmethod
-    def _plot(
-        return_per,
-        impact,
-        axis,
-        log_frequency,
-        frequency_unit,
-        unit,
-        title,
-        **kwargs,
-    ):
-        """
-        private function to plot an impact's exceedance frequency curve
-        """
-        # check frequency unit
-        return_period_unit = u_dt.convert_frequency_unit_to_time_unit(frequency_unit)
-
-        if not axis:
-            _, axis = plt.subplots(1, 1)
-        axis.set_title(title)
-        axis.set_ylabel("Impact (" + unit + ")")
-        if log_frequency:
-            axis.set_xlabel(f"Exceedance frequency ({frequency_unit})")
-            axis.set_xscale("log")
-            axis.plot(return_per**-1, impact, **kwargs)
-        else:
-            axis.set_xlabel(f"Return period ({return_period_unit})")
-            axis.plot(return_per, impact, **kwargs)
-        return axis
diff --git a/climada/engine/test/test_impact.py b/climada/engine/test/test_impact.py
@@ -321,8 +321,8 @@ def test_ref_value_rp_pass(self):
         self.assertEqual("USD", ifc.unit)
         self.assertEqual("1/week", ifc.frequency_unit)
 
-    def test_extrapolate_freq_curve(self):
-        """Test extrapolate method of freq curve"""
+    def test_interpolate_freq_curve(self):
+        """Test inter- and extrapolate method of freq curve"""
         imp = Impact()
         imp.frequency = np.array([0.2, 0.1, 0.1, 0.1])
         imp.at_event = np.array([0.0, 100.0, 50.0, 110.0])
@@ -337,23 +337,27 @@ def test_extrapolate_freq_curve(self):
 
         # stepfunction assigns zero return periods below data and max(impact) for those above
         npt.assert_array_almost_equal(
-            ifc.extrapolate([1, 5, 20], method="stepfunction"), [0.0, 100.0, 110.0]
+            ifc.interpolate([1, 5, 20], method="stepfunction").impact,
+            [0.0, 100.0, 110.0],
         )
 
         # interpolate assigns nan to return periods outside of data
         npt.assert_array_almost_equal(
-            ifc.extrapolate([1, 5, 20], method="interpolate"), [np.nan, 100.0, np.nan]
+            ifc.interpolate([1, 5, 20], method="interpolate").impact,
+            [np.nan, 100.0, np.nan],
         )
 
         # extrapolate_constant assigns zero return periods below data and max(impact) for those above
         npt.assert_array_almost_equal(
-            ifc.extrapolate([1, 5, 20], method="extrapolate_constant"),
+            ifc.interpolate([1, 5, 20], method="extrapolate_constant").impact,
             [0.0, 100.0, 110.0],
         )
 
         # by binning the last two digits, 100 and 110 are rounded to 100
         npt.assert_array_almost_equal(
-            ifc.extrapolate([1, 5, 20], method="extrapolate_constant", bin_decimals=-2),
+            ifc.interpolate(
+                [1, 5, 20], method="extrapolate_constant", bin_decimals=-2
+            ).impact,
             [0.0, 100.0, 100.0],
         )
 
@@ -363,12 +367,12 @@ def test_extrapolate_freq_curve(self):
         # rp=4: extrapolate impacts [50, 100] and ex_freqs [.3, .2] to ex_freq=0.25 --> 75
         # rp=1: extrapolate impacts [100, 110] and ex_freqs [.2, .1] to ex_freq=0.05 --> 115
         npt.assert_array_almost_equal(
-            ifc.extrapolate(
+            ifc.interpolate(
                 [1.0, 2.5, 4, 20],
                 method="extrapolate",
                 log_frequency=False,
                 log_impact=False,
-            ),
+            ).impact,
             [-300.0, 0.0, 75.0, 115.0],
         )
 
