Update docs and links in tutorial

Author: peanutfun

climada/util/calibrate/base.py

@@ -49,7 +49,7 @@ class Input:
         Exposures object to compute impacts from
     data : pandas.Dataframe
         The data to compare computed impacts to. Index: Event IDs matching the IDs of
-        ``hazard``. Columns: Arbitrary columns. NaN values in the data frame have
+        :py:attr:`hazard`. Columns: Arbitrary columns. NaN values in the data frame have
         special meaning: Corresponding impact values computed by the model are ignored
         in the calibration.
     impact_func_creator : Callable

climada/util/calibrate/ensemble.py

@@ -205,7 +205,9 @@ def to_csv(self, filepath: Path | str):
         )
         self.data.to_csv(filepath, index=None)
 
-    def _to_impf_sets(self, impact_func_creator) -> list[ImpactFuncSet]:
+    def _to_impf_sets(
+        self, impact_func_creator: Callable[..., ImpactFuncSet]
+    ) -> list[ImpactFuncSet]:
         """Return a list of impact functions created from the stored parameters"""
         return [
             impact_func_creator(**row["Parameters"]) for _, row in self.data.iterrows()
@@ -453,18 +455,32 @@ def plot_category(
 
 @dataclass
 class EnsembleOptimizer(ABC):
-    """Abstract base class for defining an ensemble optimizer
+    """Abstract base class for defining an ensemble optimizer.
+
+    An ensemble optimizer uses a user-defined optimizer type to run multiple calibration
+    tasks. The tasks are defined by the :py:attr:`samples` attribute: For each entry in
+    :py:attr:`samples`, a new :py:class:`~climada.util.calibrate.base.Input` is created
+    and passed to an instance of :py:attr:`optimizer_type`. Derived classes need to set
+    the :py:attr:`samples` during initialization and define the
+    :py:meth:`input_from_sample` method.
+
+    The calibration tasks can be conducted in parallel by executing :py:meth:`run` with
+    ``processes`` set to a value larger than 1.
 
     Attributes
     ----------
     input : Input
-        The input for the optimization
+        The generic input for the optimization
     optimizer_type : type[Optimizer]
         The type of the optimizer to use for each calibration task
     optimizer_init_kwargs
-        Keyword argument for initializing the calibration optimizer
+        Keyword argument for initializing an instance of the chosen
+        :py:attr:`optimizer_type`.
     samples : list of list of tuple(int, int)
-        The samples for each calibration task
+        The samples for each calibration task. Each entry is a list of tuples that
+        encode row and column indices of the ``Input``
+        :py:attr:`~climada.util.calibrate.base.Input.data` that are selected for the
+        particular calibration task. See :py:func:`sample_data`.
     """
 
     input: Input
@@ -551,18 +567,23 @@ def _update_init_kwargs(
 
 @dataclass
 class AverageEnsembleOptimizer(EnsembleOptimizer):
-    """An optimizer for the average ensemble
+    """An optimizer for the "average ensemble".
+
+    This optimizer samples a fraction of the original events in
+    :py:attr:`~climada.util.calibrate.ensemble.EnsembleOptimizer.input`.
+    :py:attr:`~climada.util.calibrate.base.Input.data`.
 
     Attributes
     ----------
     sample_fraction : float
-        The fraction of data points to use for each calibration
+        The fraction of data points to use for each calibration. For values > 1,
+        :py:attr:`replace` must be ``True``.
     ensemble_size : int
-        The number of calibration tasks to perform
+        The number of calibration tasks to perform (and hence size of the ensemble).
     random_state : int
         The seed for the random number generator selecting the samples
     replace : bool
-        If samples of the impact data should be drawn with replacement
+        If samples of the input data should be drawn with replacement
     """
 
     sample_fraction: InitVar[float] = 0.8
@@ -600,13 +621,18 @@ def input_from_sample(self, sample: list[tuple[int, int]]):
 
 @dataclass
 class TragedyEnsembleOptimizer(EnsembleOptimizer):
-    """An optimizer for the ensemble of tragedies
+    """An optimizer for the "ensemble of tragedies".
+
+    Each sample (and thus calibration task) of this optimizer only contains a single
+    event from :py:attr:`~climada.util.calibrate.ensemble.EnsembleOptimizer.input`.
+    :py:attr:`~climada.util.calibrate.base.Input.data`.
 
     Attributes
     ----------
     ensemble_size : int, optional
         The number of calibration tasks to perform. Defaults to ``None``, which means
         one for each data point. Must be smaller or equal to the number of data points.
+        If smaller, random events will be left out from the ensemble calibration.
     random_state : int
         The seed for the random number generator selecting the samples
     """

doc/api/climada/climada.util.calibrate.rst

@@ -1,3 +1,5 @@
+.. _calibration-module:
+
 ==================================
 Impact Function Calibration Module
 ==================================
@@ -34,7 +36,14 @@ Calibration based on the ``scipy.optimize`` module.
 Ensemble Optimizers
 -------------------
 
-Calibration creating ensembles of impact functions.
+Ensemble optimizers calibrate an ensemble of optimized parameter sets from subsets of the original input by employing multiple instances of the above "default" optimizers.
+This gives a better sense of uncertainty in the calibration results:
+By only selecting a subset of events to calibrate on, and by repeating this process for several times, one receives a varying set of impact functions that may spread considerably, as some events might dominate the calibration.
+We distinguish two cases:
+The :py:class:`~climada.util.calibrate.ensemble.AverageEnsembleOptimizer` samples a subset of all events with or without replacement.
+The resulting "average ensemble" contains uncertainty information on the average impact function for all events.
+The :py:class:`~climada.util.calibrate.ensemble.TragedyEnsembleOptimizer` calibrates one impact function for each single event.
+The resulting "ensemble of tragedies" encodes the inter-event uncertainty.
 
 .. automodule:: climada.util.calibrate.ensemble
    :members:

doc/user-guide/climada_util_calibrate.ipynb

@@ -7,17 +7,17 @@
    "source": [
     "# Impact Function Calibration\n",
     "\n",
-    "CLIMADA provides the [`climada.util.calibrate`](../climada/climada.util.calibrate) module for calibrating impact functions based on impact data.\n",
+    "CLIMADA provides the [`climada.util.calibrate`](calibration-module) module for calibrating impact functions based on impact data.\n",
     "This tutorial will guide through the usage of this module by calibrating an impact function for tropical cyclones (TCs).\n",
     "\n",
-    "For further information on the classes available from the module, see its [documentation](../climada/climada.util.calibrate).\n",
+    "For further information on the classes available from the module, see its [documentation](calibration-module).\n",
     "\n",
     "## Overview\n",
     "\n",
     "The basic idea of the calibration is to find a set of parameters for an impact function that minimizes the deviation between the calculated impact and some impact data.\n",
     "For setting up a calibration task, users have to supply the following information:\n",
     "\n",
-    "* Hazard and Exposure (as usual, see [the tutorial](../tutorial/1_main_climada.ipynb#tutorial-an-example-risk-assessment))\n",
+    "* Hazard and Exposure (as usual, see [the tutorial](1_main_climada.ipynb#tutorial-an-example-risk-assessment))\n",
     "* The impact data to calibrate the model to\n",
     "* An impact function definition depending on the calibrated parameters\n",
     "* Bounds and constraints of the calibrated parameters (depending on the calibration algorithm)\n",