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]

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.

[chahank]

Thanks for the updates already! Are you @spjuhel already satisfied with the changes in the tutorial or is it planned to implement more of the suggestions above?

And a little note, for the quick example, can one also replace the future hazard by a file instead of the multiplication of the frequency?

I will come to the content afterwards.

[spjuhel]

Not entirely,

The ToC thing I want to have a look, I am pretty sure making deeper title visible will be messy (wrt the rest of documentation), but I think I can adjust that by just removing the "Using the trajectory module title".

For the Hazard, the thing is we don't have a future hazard demo file (Or I haven't found it).

I think I addressed everything else?

[chahank]

Not entirely,

The ToC thing I want to have a look, I am pretty sure making deeper title visible will be messy (wrt the rest of documentation), but I think I can adjust that by just removing the "Using the trajectory module title".

Yes, I think this is a good solution (the title is anyway a bit redundant for a tutorial). I would also remove the

For the Hazard, the thing is we don't have a future hazard demo file (Or I haven't found it).

Then we need to make one ;).

I think I addressed everything else?

Yes thanks! Just maybe I missed it, but I do not see "when one would use StaticRiskTrajectory and when the InterpolatedRiskTrajectory?".

[spjuhel]

Yes thanks! Just maybe I missed it, but I do not see "when one would use StaticRiskTrajectory and when the InterpolatedRiskTrajectory?".

https://climada-python--1201.org.readthedocs.build/en/1201/user-guide/climada_trajectories.html#when-to-use-static-vs-interpolated-trajectories

Will work ASAP on your other comments.

[chahank]

Some modest changes and I think otherwise the code is already very nice. Maybe check merge conflicts should be checked though ;).

[spjuhel]

Ok, I'm merging as soon as the tests are green :)

[spjuhel]

OK the failures are related to #1292, nothing to worry.

@emanuel-schmid the integration tests ran fine locally, please tell me if anything is wrong on jenkins (no reason a priori)

[chahank]

Fantastic, great job @spjuhel