doc(risk transfer): Improves clarity of risk transfer mechanism

Author: spjuhel

climada/trajectories/impact_calc_strat.py

@@ -89,17 +89,14 @@ def _apply_risk_transfer(
             )
 
     def calculate_residual_or_risk_transfer_impact_matrix(
-        self, imp_mat, risk_transf_attach, risk_transf_cover, calc_residual
+        self, imp_mat, attachement, cover, calc_residual
     ):
-        """
-        Calculate either the residual or the risk transfer impact matrix.
+        """Calculate either the residual or the risk transfer impact matrix from a global risk transfer mechanism.
+
+        To compute the transfered risk, the function first computes for each event, the (positive) difference between their total impact and `attachment`. The transfered risk for each event is then defined as the minimum between this value and `cover`. The residual impact is the total impact minus the transfered risk.
+        The impact matrix is then adjusted by multiply impact per centroids by the ratio between residual risk and total impact for each event. As such, the risk transfer is shared among all impacted exposure points and equaly distributed.
 
-        The impact matrix is adjusted based on the total impact for each event.
-        When calculating the residual impact, the result is the total impact minus
-        the risk layer. The risk layer is defined as the minimum of the cover and
-        the maximum of the difference between the total impact and the attachment.
-        If `calc_residual` is False, the function returns the risk layer matrix
-        instead of the residual.
+        If `calc_residual` is False, the function returns the transfered risk at each points instead of the residual risk by using the ratio between transfered risk and total impact instead.
 
         Parameters
         ----------
@@ -118,13 +115,18 @@ def calculate_residual_or_risk_transfer_impact_matrix(
         scipy.sparse.csr_matrix
             The adjusted impact matrix, either residual or risk transfer.
 
+        Warnings
+        --------
+
+        This transfer capability is different and not exclusive with the one implemented in ImpactCalc, which is defined at the centroid level. The mechanism here corresponds to a global cover applied to the whole region studied.
+
         """
         imp_mat = copy.deepcopy(imp_mat)
         # Calculate the total impact per event
         total_at_event = imp_mat.sum(axis=1).A1
         # Risk layer at event
         transfer_at_event = np.minimum(
-            np.maximum(total_at_event - risk_transf_attach, 0), risk_transf_cover
+            np.maximum(total_at_event - attachement, 0), cover
         )
         residual_at_event = np.maximum(total_at_event - transfer_at_event, 0)
 

climada/trajectories/riskperiod.py

@@ -90,12 +90,13 @@ class CalcRiskPeriod:
         The method used to calculate the impact from the (Haz,Exp,Vul) of the two snapshots.
         Defaults to ImpactCalc
     risk_transf_attach: float, optional
-        The attachement of risk transfer to apply. Defaults to None.
+        A global attachement of risk transfer to apply. Note that this is different (and not exclusive) from the attachement
+        that can be defined in the `Exposures` object. Defaults to None.
     risk_transf_cover: float, optional
-        The cover of risk transfer to apply. Defaults to None.
+        A global cover of risk transfer to apply. See `risk_transf_attach` above. Defaults to None.
     calc_residual: bool, optional
-        A boolean stating whether the residual (True) or transfered risk (False) is retained when doing
-        the risk transfer. Defaults to False.
+        A boolean stating whether the residual (True) or transfered risk (False) is
+        retained when applying a global risk transfer. Defaults to False.
     measure: Measure, optional
         The measure to apply to both snapshots. Defaults to None.