Risk Trajectory Split 5: Interpolated Risk Trajectories

[spjuhel]

As the Risk trajectory PR is too substantial, this is the fifth (and final) split.

This PR builds on all previous splits (#1197 #1198 #1199 #1200).

It implements the high level InterpolatedRiskTrajectory class and the low level computing class CalcRiskMetricsPeriod, similarly as Split 4, but with interpolation in between pairs of consecutive Snapshot. The additional complexity and the differences with Split 4 are summarized below.

It also ships the tutorial for the trajectory module.

Core differences

Instead of having one CalcRiskMetricsPoints for all snapshot, the high level class holds a list of CalcRiskMetricsPeriod objects (one for each pair of consecutive snapshots), each having the role of computing the metrics for the period defined by the two snapshots.

CalcRiskMetricsPeriod thus takes a starting (0) and ending (1) Snapshot instead of a list of them.
It also takes an InterpolationStrategy in addition to the ImpactComputationStrategy, and a "time resolution", which defines the number of time points to have for the metrics (including start and end).

Interpolation conceptual flow (in calc_risk_metrics)

Instead of "simply" computing the impacts for each snapshot, it computes all corners of the so-called Risk Cube™ (all 2³ convolutions of (exp,haz,vul) Impact triplet), and the interpolated risk metrics based on these.

The eight corners are @lazy_property, and labelled EiHjVk (where i,j,k are 0 or 1), such that for instance E0H0V0 is the impact object corresponding to Exposure, Hazard and Vulnerability of Snapshot 0.

From then, arrays of impact matrices are interpolated between corners for as many points as needed by the given time resolution. (i.e. if start date is 2020, end date is 2025 and resolution is yearly, arrays of 5 impact matrices will be computed).

As it is not feasible (in general) to interpolate between corners with a different hazard (shapes of impact matrices may differ), this interpolation of impact matrices is only done "along the exposure dimension", that is for the four edges of the Risk Cube™ where hazard and vulnerability remain constant along the edge. (side note here, it should actually also be possible to do that for vulnerability, will see for future updates)

These four arrays of matrices are labelled imp_mats_HiVj, to be read as "Evolution of impacts matrices with hazard constant to snapshot i, vulnerability constant to snapshot j, and exposure changing from snapshot 0 to 1".

From then on, interpolation is made on the metrics themselves and not the matrices.
We compute both the EAIs for each of the four arrays (per_date_eai_HiVj), from which the corresponding AAIs can be computed (per_date_aai_HiVj), and the "return period impacts".

Then we can compute the "fully interpolated metrics basis", per_date_eai, per_date_aai (return periods have a special treatment given they rely on an argument), and cache them using @lazy_property. Computation is done by interpolating first along the hazard dimension and then along the vulnerability one.

Finally, we can have the calc_<risk_metric> methods which take care of tidying the data in nice dataframes.

Differences in interface class

InterpolatedRiskTrajectory handle the additional "time resolution" attribute, ships per_period_<risk_metric> methods in addition to the per_date ones, where average values of the metric for each period (consecutive pairs of snapshots) are computed.

PR Author Checklist

• Read the Contribution Guide
• Correct target branch selected (if unsure, select develop)
• Descriptive pull request title added
• Source branch up-to-date with target branch
• Documentation updated
• Tests updated
• Tests passing
• No new linter issues
• Changelog updated

PR Reviewer Checklist

• Read the Contribution Guide
• CLIMADA Reviewer Checklist passed
• Tests passing
• No new linter issues