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

[chahank]

Just as a reminder for later:

• I would group all the adaptation option appraisal stuff in a separate entry in the documentation toc (instead of it being under impact).
• The trajectories and other tutorial should ideally have a quick and dirty example at the very top (and not after a lenghty wall of text and introduction to all the components). This makes it much easier to enter in the topic.

[spjuhel]

@chahank

• The adaptation option appraisal stuff will be in a different set of PR, indeed, they'll have their own section.
• I've updated the tuto with a quickstart, (it is minimalistic though)

[chahank]

It still indicates many files as new or as modified which I think were addressed in the pull request 1-4. Can you please check why (it makes it very hard to review the relevant changes made in this PR alone)? Maybe another develop merge is needed?

[spjuhel]

I think these relate to #1254 (I thought I would have merged by then)

[spjuhel]

You can review these files:

• climada/trajectories/interpolated_trajectory.py
• climada/trajectories/calc_risk_metrics.py
• doc/user-guide/climada_trajectories.ipynb
• climada/trajectories/test/*

[chahank]

You can review these files:

* climada/trajectories/interpolated_trajectory.py

* climada/trajectories/calc_risk_metrics.py

* doc/user-guide/climada_trajectories.ipynb

* climada/trajectories/test/*

Excellent, thanks for the guidance!

[chahank]

I have so far looked at the tutorial. Great job, it is very comprehensive, and the quick intro at the beginning is very useful. I would suggest the following small improvements.

Quick example:

• (minor point) Could one replace the

exp_future = Exposures.from_hdf5(EXP_DEMO_H5)
exp_future.gdf["value"] *= 1.1

with a direct future exposure file? I recall a few discussion with users that seem to believe that scaling the value is the only way to get future exposures, and I think this is because of such examples in our documentation.

• Can you add the interpolated_risk_traj.plot_waterfall(), otherwise it is a bit confusing to see only relative impact changes.

Others:

• Can you explain when one would use StaticRiskTrajectory and when the InterpolatedRiskTrajectory? Now it is said what the technical difference is, but not what the use-case difference is.
• Overall, it is a bit verbose a points for my taste. Sentences like As always users should carefully consider if the tool fits the purpose and if the limitations remain acceptable, even more so when used to design Disaster Risk Reduction or Climate Change Adaptation measures. I think do not add much to a tutorial, but make it longer and thus decrease the probability of users reading it all.
• I like the distinction between simple and advanced uses. Could you make a TOC at the beginning to make navigating and finding the write information easier?

[spjuhel]

Is this not enough?

I'm very reluctant to add custom-made ToC...

[chahank]

Is this not enough?

I'm very reluctant to add custom-made ToC...

I agree that adding a custom made TOC is not ideal. Can you adjust the current headings such that the subsections in the advance usage are shown? I think these need to be easily accessible without having to scroll through the whole thing.