[Option Appraisal Module] [Package 1: Measures] Split 1: Adds `MeasureConfig` dataclasses for serializable measure configuration. by spjuhel · Pull Request #1276 · CLIMADA-project/climada_python

spjuhel · 2026-04-07T07:50:14Z

Changes proposed in this PR:

This PR introduces a new module defining a family of dataclasses that encode adaptation measure parameters in a serializable, declarative form. This is a preparatory step for the broader Measure/MeasureSet rework.

The objective is to retain the possibility to define measures from modifiers in addition to the upcoming system that will use python functions directly, and provide a (better) user interface for this.

no existing code is changed.

New dataclasses:

MeasureConfig top-level configuration for a single measure, aggregating all modifier configs below.
ImpfsetModifierConfig parameters for modifying impact functions (intensity, MDD, PAA scaling, optional replacement)
HazardModifierConfig parameters for modifying hazard (intensity scaling, frequency cutoff, optional replacement)
ExposuresModifierConfig parameters for modifying exposures (impact function remapping, zeroing regions, optional replacement)
CostIncomeConfig serializable representation of cost/income cash flow parameters

All configs inherit from the abstract _ModifierConfig base, which provides shared to_dict/from_dict and a __repr__ that highlights non-default fields.

MeasureConfig supports full serialization to/from dict, YAML, and legacy Excel rows (from_row), which will serve as the migration path for the existing file-based I/O in MeasureSet.

PR Author Checklist

PR Reviewer Checklist

chahank · 2026-04-07T08:09:38Z

Excellent idea!

Cleans-up, Docstringfies Better to_dict, color parser, and post_inits Removes duplicate docstring

…MADA-project/climada_python into feature/option-appraisal-dataclasses

spjuhel · 2026-04-08T09:48:43Z

@chahank

Question: Should measures (defined by MeasureConfig) be specific to a hazard? (I see reasons for both yes and no)

Currently, they are specific (thus configs require you to provide haz_type).

I see how you could want modifications of impact function to be for multiple hazards
But also you should probably not be able to apply a shift in intensity for multiple hazards?

Any opinion on that?

spjuhel · 2026-04-08T14:09:04Z

This PR is officially open for review! Review is advised after #1274 is merged.

Actual changes to be reviewed are in:

climada/entity/measures/measure_config.py
climada/entity/measures/test/test_measure_config.py
doc/user-guide/climada_measure_config.ipynb (and a few other tutos where a target was added at the top)

chahank · 2026-04-09T12:21:19Z

@chahank

Question: Should measures (defined by MeasureConfig) be specific to a hazard? (I see reasons for both yes and no)

Currently, they are specific (thus configs require you to provide haz_type).

I see how you could want modifications of impact function to be for multiple hazards But also you should probably not be able to apply a shift in intensity for multiple hazards?

Any opinion on that?

Good question. I would then to keep it hazard type specific. But maybe best is to ask core users of the model :).
@ChrisFairless : any opinion?

…e/option-appraisal-dataclasses

This reverts commit 775c621.

peanutfun

I reviewed mostly on a technical level. Very nice code quality overall, nice class structure! I found a few issues. Sorry for the brevity 😬 ✌️

Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>

…e/option-appraisal-dataclasses

…raisal-dataclasses

spjuhel · 2026-05-13T12:40:47Z

@ValentinGebhart This has been reviewed on the technical aspects. Can you give a look at the guide here and tell me if its clear enough?

Note: The "measure tutorial" link at the end does not work yet and is a placeholder.

ValentinGebhart

Thanks for this very clear tutorial! I added only a few rephrasings and some comments at points where I thought it was not perfectly clear. However all are only minor things, and I find the explanations very clear about how to define the MeasureConfigs.

ValentinGebhart · 2026-05-22T06:17:08Z

+    "\n",
+    "CLIMADA uses `Measure` objects to model the effects of adaptation measures. `Measure` objects were formerly defined declaratively (via for instance, a shifting or scaling of the hazard intensity or a change of impact function), and are now defined as python functions to enable more flexibility on the possible changes (see the [tutorial on measure objects](measure-tutorial)'). \n",
+    "\n",
+    "The caveat of defining measure effects as python functions is that it cannot be serialized (written to a file), and also makes reading from a file a challenge.\n",


Is it really impossible to save python functions? That means that measures that do not correspond to MeasureConfigs cannot be saved?

ValentinGebhart · 2026-05-22T06:20:06Z

+    "\n",
+    "The caveat of defining measure effects as python functions is that it cannot be serialized (written to a file), and also makes reading from a file a challenge.\n",
+    "\n",
+    "In order to close that gap, the `measure` module now ships `MeasureConfig` objects, which handle the reading, writing and \"declarative\" defining of `Measure` objects.\n",


If I understood correctly, this sounds a bit misleading, as if MeasureConfig handle reading and writing of ALL Measure objects, while actually they can only read and write those that correspond to MeasureConfig objects, right?
Maybe rephrase to
"which can be read from and written to files, and which enable a "declarative" defining of Measure objects."

ValentinGebhart · 2026-05-22T06:23:23Z

+    "- `ExposuresModifierConfig`: Modifies exposure data (e.g., reassigning IDs or zeroing regions).\n",
+    "- `CostIncomeConfig`: Handles the financial aspects, including initial costs and recurring income.\n",
+    "\n",
+    "Note that everything can be defined and accessed directly from the `MeasureConfig` container, the underlying ones are there to keep things organized.\n",


On first reading the meaning was not super clear to me. Maybe rephrase to
"Note that all effects of a MeasureConfig object can be directly defined using the MeasureConfig container, the underlying ones are there to keep things organized.

ValentinGebhart · 2026-05-22T06:25:27Z

+    "| **Hazard** | `haz_int_mult` | `float` | Multiplier for hazard intensity (default: 1.0). |\n",
+    "| | `haz_int_add` | `float` | Additive offset for hazard intensity (default: 0.0). |\n",
+    "| | `new_hazard_path` | | Path to an HDF5 file to replace the current hazard. |\n",
+    "| | `impact_rp_cutoff` | `float` | Return period (years) threshold; events below this are ignored. |\n",


ValentinGebhart · 2026-05-22T06:28:22Z

+    "        0,\n",
+    "        25,\n",
+    "        78,\n",
+    "    ],  # Sets the value of exposure points with index 0, 25 and 78 to 0.\n",


This seems in conflict to what you wrote above. Here it sounds that you set to zero exposure points with specific index values, above it sounds that you set to zero exposure points with specific region_ids ("List of Region IDs where exposure value is set to 0."

ValentinGebhart · 2026-05-22T06:35:50Z

+    "        0,\n",
+    "        25,\n",
+    "        78,\n",
+    "    ],  # Sets the value of exposure points with index 0, 25 and 78 to 0.\n",


This seems in conflict to what you wrote above. Here it sounds that you set to zero exposure points with specific index values, above it sounds that you set to zero exposure points with specific region_ids ("List of Region IDs where exposure value is set to 0."

ValentinGebhart · 2026-05-22T06:43:57Z

+    "    cost_yearly_growth_rate=0.02,\n",
+    "    periodic_income=100_000.0,\n",
+    "    income_yearly_growth_rate=0.03,\n",
+    "    freq=\"Y\",\n",


The freq attribute is not shown in the below print, and it not entirely clear to me what it does. Above, it is written "frequecy of cash flows". That means that if one uses, e.g., freq="2Y", the growth rates etc are still yearly but the the costs and incomes occur only every two years?

ValentinGebhart · 2026-05-22T06:45:10Z

+    "custom_schedule = [\n",
+    "    {\"date\": \"2024-01-01\", \"value\": -1000000},  # Initial cost\n",
+    "    {\"date\": \"2029-01-01\", \"value\": -200000},  # Mid-term overhaul\n",
+    "    {\"date\": \"2034-01-01\", \"value\": 500000},  # Terminal value\n",


Maybe clarify what negative and positive values are, and above cost were given as positive values. I assume here negative values are one-time costs and negative values are one-time incomes?

ValentinGebhart · 2026-05-22T06:54:14Z

+    "- Applying a cutoff on frequency based on impacts: via `impact_rp_cutoff` (see the note).\n",
+    "\n",
+    "```{note}\n",
+    "Providing a value for `impact_rp_cutoff` \"removes\" (it sets their intensity to 0.) events from the hazard, for which the exceedance frequency (inverse of return period) of impacts is below the given threshold.\n",


I was actually wondering about this one: AFAIK you want to have each measure consist of three functions that modify each of the risk components. This parameter however looks like it takes into account all hazard, vulnerability and exposure, as it looks at the impacts per event, which seems a bit confusing with the three function structure. My main question is if this cutoff is applied at the start (computing the impact events to be excluded before applying all other stuff), or at the end (after all other effect were taken into account)?

Introduces measure config dataclasses

2c0dffa

chahank reviewed Apr 7, 2026

View reviewed changes

Comment thread climada/entity/measures/measure_config.py Outdated

chahank reviewed Apr 7, 2026

View reviewed changes

Comment thread climada/entity/measures/measure_config.py

spjuhel added 7 commits April 7, 2026 10:22

Cleans-up, Docstringfies

e9f4831

Better to_dict, color parser, and post_inits

bcf6811

Unit tests

2718c84

Removes duplicate docstring

c5345fb

Forgotten places

4551e3c

Cleans-up, Docstringfies Better to_dict, color parser, and post_inits Removes duplicate docstring

tests again

78c4968

Merge branch 'feature/option-appraisal-dataclasses' of github.com:CLI…

3cae5d7

…MADA-project/climada_python into feature/option-appraisal-dataclasses

spjuhel changed the title ~~[Option Appraisal Module] - Adds MeasureConfig dataclasses for serializable measure configuration.~~ [Option Appraisal Module] [Package 1: Measures] Split 1: Adds MeasureConfig dataclasses for serializable measure configuration. Apr 7, 2026

Adds freq modifiers

c96a061

spjuhel added 2 commits April 8, 2026 16:02

Improves __repr__

4e416bc

Tutorial first draft

30bdce6

spjuhel marked this pull request as ready for review April 8, 2026 14:04

spjuhel requested review from emanuel-schmid and peanutfun as code owners April 8, 2026 14:04

spjuhel added 8 commits April 9, 2026 14:55

Merge branch 'feature/option-appraisal-split-make-legacy' into featur…

5c80864

…e/option-appraisal-dataclasses

Includes guide in documentation index

cc70476

Updates changelog

44a36d4

Merge branch 'feature/option-appraisal-split-make-legacy' into featur…

5634482

…e/option-appraisal-dataclasses

Adds new class to API ref

8a09101

Fixes wrong filename

775c621

Revert "Fixes wrong filename"

3ddf2b4

This reverts commit 775c621.

Correct rename

5b11b68

peanutfun requested changes Apr 17, 2026

View reviewed changes

spjuhel and others added 5 commits April 20, 2026 11:29

Apply suggestions from code review from Lukas

891497f

Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>

Cleans up tests

48ed8ac

Applies additional comments from Lukas

d335ca0

Merge branch 'feature/option-appraisal-split-make-legacy' into featur…

0423a6f

…e/option-appraisal-dataclasses

Merge remote-tracking branch 'origin/develop' into feature/option-app…

7803112

…raisal-dataclasses

some typos and rephrasing

991562d

ValentinGebhart approved these changes May 22, 2026

View reviewed changes

ValentinGebhart reviewed May 22, 2026

View reviewed changes

	"\| \| `impact_rp_cutoff` \| `float` \| Return period (years) threshold; events below this are ignored. \|\n",
	"\| \| `impact_rp_cutoff` \| `float` \| Return period (years) threshold; events with impacts below this threshold are ignored. \|\n",

Conversation

spjuhel commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Author Checklist

PR Reviewer Checklist

Uh oh!

Uh oh!

Uh oh!

chahank commented Apr 7, 2026

Uh oh!

spjuhel commented Apr 8, 2026

Uh oh!

spjuhel commented Apr 8, 2026

Uh oh!

chahank commented Apr 9, 2026

Uh oh!

peanutfun left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spjuhel commented May 13, 2026

Uh oh!

ValentinGebhart left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ValentinGebhart May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

spjuhel commented Apr 7, 2026 •

edited

Loading

ValentinGebhart May 22, 2026 •

edited

Loading