Update docs

Author: peanutfun

climada/util/calibrate/base.py

@@ -66,7 +66,9 @@ class Input:
         "cost" between them. The optimization algorithm will try to minimize this
         number. The first argument is the true/correct values (:py:attr:`data`), the
         second argument is the estimated/predicted values, and the third argument is the
-        :py:attr:`data_weights`.
+        :py:attr:`data_weights`. The cost function is intended to operate on
+        ``numpy.ndarray`` objects.
+        Dataframes are transformed using :py:attr:`df_to_numpy`.
     bounds : Mapping (str, {Bounds, tuple(float, float)}), optional
         The bounds for the parameters. Keys: parameter names. Values:
         ``scipy.minimize.Bounds`` instance or tuple of minimum and maximum value.
@@ -86,15 +88,15 @@ class Input:
         :py:attr:`data`, insert this value. Defaults to NaN, in which case the impact
         from the model is ignored. Set this to zero to explicitly calibrate to zero
         impacts in these cases.
-    df_to_numpy : Callable
+    df_to_numpy : Callable, optional
         A function that transforms a pandas.DataFrame into a numpy.ndarray to be
         inserted into the :py:attr:`cost_func`. By default, this will flatten the data
         frame.
     data_weights : pandas.DataFrame, optional
         Weights for each entry in :py:attr:`data`. Must have the exact same index and
         columns. If ``None``, the weights will be ignored (equivalent to the same weight
         for each event).
-    missing_data_value : float, optional
+    missing_weights_value : float, optional
         Same as :py:attr:`missing_data_value`, but for :py:attr:`data_weights`.
     assign_centroids : bool, optional
         If ``True`` (default), assign the hazard centroids to the exposure when this
@@ -450,13 +452,13 @@ def _target_func(
 
         Parameters
         ----------
-        data : pandas.DataFrame
+        data : nd.ndarray
             The reference data used for calibration. By default, this is
             :py:attr:`Input.data`.
-        predicted : pandas.DataFrame
+        predicted : nd.ndarray
             The impact predicted by the data calibration after it has been transformed
             into a dataframe by :py:attr:`Input.impact_to_dataframe`.
-        weights : pandas.DataFrame
+        weights : nd.ndarray
             The relative weight for each data/entry pair.
 
         Returns

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

@@ -4,6 +4,23 @@
 Impact Function Calibration Module
 ==================================
 
+What's New?
+-----------
+
+Since CLIMADA v6.0.1, some functionality of this module has been changed.
+When upgrading to a newer version of CLIMADA, please mind the following changes:
+
+* :py:class:`~climada.util.calibrate.base.Input` received additional attributes.
+  We now support optional weights that are passed to the cost function.
+  Therefore, the cost function must support an additional, optional argument.
+* :py:attr:`~climada.util.calibrate.base.Input.cost_func` now receives numpy arrays.
+  An additional attribute :py:attr:`~climada.util.calibrate.base.Input.df_to_numpy` was
+  added to transform ``pandas.DataFrame`` objects to ``np.ndarray``.
+  By default, it returns a flattened array.
+* This module now exports cost functions that support optional weights, see
+  :py:mod:`climada.util.calibrate.cost_func`.
+* :ref:`Ensemble optimizers <ensemble-optimizers>` have been addded.
+
 Base Classes
 ------------
 
@@ -13,6 +30,10 @@ Generic classes for defining the data structures of this module.
    :members:
    :private-members:
 
+.. automodule:: climada.util.calibrate.cost_func
+   :members:
+   :private-members:
+
 Bayesian Optimizer
 ------------------
 
@@ -33,6 +54,8 @@ Calibration based on the ``scipy.optimize`` module.
    :show-inheritance:
    :inherited-members:  abc.ABC
 
+.. _ensemble-optimizers:
+
 Ensemble Optimizers
 -------------------