climada.entity.measures package

Note

This package implements the new way of defining measures. For the previous way, see climada.entity._legacy_measures

climada.entity.measures.measure_config module

class climada.entity.measures.measure_config.HazardModifierConfig(haz_type: str, haz_int_mult: float | None = 1.0, haz_int_add: float | None = 0.0, haz_freq_mult: float | None = 1.0, haz_freq_add: float | None = 0.0, new_hazard_path: str | None = None, impact_rp_cutoff: float | None = None)

Bases: ModifierConfig

Configuration for modifications to a hazard.

Supports scaling or shifting hazard intensity, applying a return-period frequency cutoff, and replacement of the hazard, loaded from a file path. If both a new file path and modifier values are provided, modifiers are applied after the replacement.

Parameters:

• haz_type (str) – Hazard type identifier (e.g. "TC") that this modifier targets.

• haz_int_mult (float, optional) – Multiplicative factor applied to hazard intensity. Default is 1.0 (no change).

• haz_int_add (float, optional) – Additive offset applied to hazard intensity after multiplication. Default is 0.0.

• new_hazard_path (str, optional) – Path to an HDF5 file containing a replacement hazard. If provided alongside modifier values, a warning is issued and modifiers are applied after loading the new hazard.

• impact_rp_cutoff (float, optional) – Return period (in years) below which hazard events are discarded. If None, no cutoff is applied.

Warns:

UserWarning – If new_hazard_path is set alongside any non-default modifier values or a non-None impact_rp_cutoff.

haz_type: str

haz_int_mult: float | None = 1.0

haz_int_add: float | None = 0.0

haz_freq_mult: float | None = 1.0

haz_freq_add: float | None = 0.0

new_hazard_path: str | None = None

impact_rp_cutoff: float | None = None

__init__(haz_type: str, haz_int_mult: float | None = 1.0, haz_int_add: float | None = 0.0, haz_freq_mult: float | None = 1.0, haz_freq_add: float | None = 0.0, new_hazard_path: str | None = None, impact_rp_cutoff: float | None = None) → None

class climada.entity.measures.measure_config.ExposuresModifierConfig(reassign_impf_id: Dict[str, Dict[int | str, int | str]] | None = None, set_to_zero: list[int] | None = None, new_exposures_path: str | None = None)

Bases: ModifierConfig

Configuration for modifications to an exposures object.

Supports remapping impact function IDs, zeroing out selected regions, and replacement of the exposures from a new file. If both a new file path and modifier values are provided, modifiers are applied after the replacement.

Parameters:

• reassign_impf_id (dict of {str: dict of {int or str: int or str}}, optional) – Nested mapping {haz_type: {old_id: new_id}} used to reassign impact function IDs in the exposures. If None, no remapping is performed.

• set_to_zero (list of int, optional) – Region IDs for which exposure values are set to zero. If None, no zeroing is applied.

• new_exposures_path (str, optional) – Path to an HDF5 file containing replacement exposures. If provided alongside modifier values, a warning is issued and modifiers are applied after loading the new exposures.

Warns:

UserWarning – If new_exposures_path is set alongside any non-None modifier values.

reassign_impf_id: Dict[str, Dict[int | str, int | str]] | None = None

set_to_zero: list[int] | None = None

new_exposures_path: str | None = None

__init__(reassign_impf_id: Dict[str, Dict[int | str, int | str]] | None = None, set_to_zero: list[int] | None = None, new_exposures_path: str | None = None) → None

class climada.entity.measures.measure_config.ImpfsetModifierConfig(haz_type: str, impf_ids: int | str | list[int | str] | None = None, impf_mdd_mult: float = 1.0, impf_mdd_add: float = 0.0, impf_paa_mult: float = 1.0, impf_paa_add: float = 0.0, impf_int_mult: float = 1.0, impf_int_add: float = 0.0, new_impfset_path: str | None = None)

Bases: ModifierConfig

Configuration for modifications to an impact function set.

Supports scaling or shifting MDD, PAA, and intensity curves, as well as replacement of the impact function set, loaded from a file path. If both a new file path and modifier values are provided, modifiers are applied after the replacement (and a warning is issued).

Parameters:

• haz_type (str) – Hazard type identifier (e.g. "TC") that this modifier targets.

• impf_ids (int or str or list of int or str, optional) – Impact function ID(s) to which modifications are applied. If None, all impact functions are affected.

• impf_mdd_mult (float, optional) – Multiplicative factor applied to the mean damage degree (MDD) curve. Default is 1.0 (no change).

• impf_mdd_add (float, optional) – Additive offset applied to the MDD curve after multiplication. Default is 0.0.

• impf_paa_mult (float, optional) – Multiplicative factor applied to the percentage of affected assets (PAA) curve. Default is 1.0.

• impf_paa_add (float, optional) – Additive offset applied to the PAA curve after multiplication. Default is 0.0.

• impf_int_mult (float, optional) – Multiplicative factor applied to the intensity axis. Default is 1.0.

• impf_int_add (float, optional) – Additive offset applied to the intensity axis after multiplication. Default is 0.0.

• new_impfset_path (str, optional) – Path to an Excel file containing a replacement impact function set. If provided alongside modifier values, a warning is issued and modifiers are applied after loading the new set.

Warns:

UserWarning – If new_impfset_path is set alongside any non-default modifier values.

haz_type: str

impf_ids: int | str | list[int | str] | None = None

impf_mdd_mult: float = 1.0

impf_mdd_add: float = 0.0

impf_paa_mult: float = 1.0

impf_paa_add: float = 0.0

impf_int_mult: float = 1.0

impf_int_add: float = 0.0

new_impfset_path: str | None = None

__init__(haz_type: str, impf_ids: int | str | list[int | str] | None = None, impf_mdd_mult: float = 1.0, impf_mdd_add: float = 0.0, impf_paa_mult: float = 1.0, impf_paa_add: float = 0.0, impf_int_mult: float = 1.0, impf_int_add: float = 0.0, new_impfset_path: str | None = None) → None

class climada.entity.measures.measure_config.CostIncomeConfig(mkt_price_year: int | None = <factory>, init_cost: float = 0.0, periodic_cost: float = 0.0, periodic_income: float = 0.0, cost_yearly_growth_rate: float = 0.0, income_yearly_growth_rate: float = 0.0, freq: str = 'Y', custom_cash_flows: list[dict] | None = None)

Bases: ModifierConfig

Serializable configuration for a CostIncome object.

Encodes all parameters required to construct a CostIncome instance, including optional custom cash flow schedules.

Parameters:

• mkt_price_year (int, optional) – Reference year for market prices. Defaults to the current year.

• init_cost (float, optional) – One-time initial investment cost (positive value). Default is 0.0.

• periodic_cost (float, optional) – Recurring cost per period (positive value). Default is 0.0.

• periodic_income (float, optional) – Recurring income per period. Default is 0.0.

• cost_yearly_growth_rate (float, optional) – Annual growth rate applied to periodic costs. Default is 0.0.

• income_yearly_growth_rate (float, optional) – Annual growth rate applied to periodic income. Default is 0.0.

• freq (str, optional) – Pandas period alias defining the period length (e.g. "Y" for yearly, "M" for monthly). Default is "Y". See [pandas documentation](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#period-aliases).

• custom_cash_flows (list of dict, optional) – Explicit cash flow schedule as a list of records with at minimum a "date" key (ISO 8601 string) and a value key. If provided, overrides the periodic cost/income logic.

mkt_price_year: int | None

init_cost: float = 0.0

periodic_cost: float = 0.0

periodic_income: float = 0.0

cost_yearly_growth_rate: float = 0.0

income_yearly_growth_rate: float = 0.0

freq: str = 'Y'

custom_cash_flows: list[dict] | None = None

classmethod from_cost_income(cost_income: CostIncome) → CostIncomeConfig

Construct a CostIncomeConfig from a live CostIncome object.

Parameters:

cost_income (CostIncome) – The live CostIncome instance to serialise.

Returns:

The config instance equivalent to the CostIncome.

Return type:

CostIncomeConfig

__init__(mkt_price_year: int | None = <factory>, init_cost: float = 0.0, periodic_cost: float = 0.0, periodic_income: float = 0.0, cost_yearly_growth_rate: float = 0.0, income_yearly_growth_rate: float = 0.0, freq: str = 'Y', custom_cash_flows: list[dict] | None = None) → None

class climada.entity.measures.measure_config.MeasureConfig(name: str, haz_type: str, impfset_modifier: ImpfsetModifierConfig, hazard_modifier: HazardModifierConfig, exposures_modifier: ExposuresModifierConfig, cost_income: CostIncomeConfig, implementation_duration: str | None = None, color_rgb: Tuple[float, float, float] | None = None)

Bases: ModifierConfig

Top-level serializable configuration for a single adaptation measure.

Aggregates all modifier sub-configs (hazard, impact functions, exposures, cost/income) into a single object that can be round-tripped through dict, YAML, or a legacy Excel row.

This class is the primary entry point for defining measures in a declarative, file-based workflow and serves as the serialization counterpart to Measure.

Parameters:

• name (str) – Unique name identifying this measure.

• haz_type (str) – Hazard type identifier (e.g. "TC") this measure is designed for.

• impfset_modifier (ImpfsetModifierConfig) – Configuration describing modifications to the impact function set.

• hazard_modifier (HazardModifierConfig) – Configuration describing modifications to the hazard.

• exposures_modifier (ExposuresModifierConfig) – Configuration describing modifications to the exposures.

• cost_income (CostIncomeConfig) – Financial parameters associated with implementing this measure.

• implementation_duration (str, optional) – Pandas period alias (e.g. "2Y") representing the time before the measure is fully operational. If None, the measure takes effect immediately.

• color_rgb (tuple of float, optional) – RGB colour triple in the range [0, 1] used for visualisation. If None, defaults to black (0, 0, 0).

name: str

haz_type: str

impfset_modifier: ImpfsetModifierConfig

hazard_modifier: HazardModifierConfig

exposures_modifier: ExposuresModifierConfig

cost_income: CostIncomeConfig

implementation_duration: str | None = None

color_rgb: Tuple[float, float, float] | None = None

to_dict(omit_default: bool = True) → dict

Serialize the measure configuration to a flat dictionary.

Sub-config dictionaries are merged into the top-level dict (i.e. their keys are inlined, not nested). haz_type is always included at the top level. Fields with None values are preserved.

Returns:

Flat dictionary representation suitable for YAML or Excel serialization.

Return type:

dict

classmethod from_dict(kwargs_dict: dict) → MeasureConfig

Instantiate a MeasureConfig from a flat dictionary.

Delegates sub-config construction to the respective from_dict classmethods. Unknown keys are silently discarded by each sub-config parser.

Parameters:

kwargs_dict (dict) – Flat dictionary, as produced by to_dict() or read from a legacy Excel row. Must contain at minimum "name" and "haz_type".

Returns:

A fully populated configuration instance.

Return type:

MeasureConfig

to_yaml(path: str) → None

Write this configuration to a YAML file.

The file is structured as {"measures": [<this config as dict>]}, matching the expected format for from_yaml().

Parameters:

path (str) – Destination file path. Will be created or overwritten.

classmethod from_yaml(path: str) → MeasureConfig

Load a MeasureConfig from a YAML file.

Expects the file to contain a top-level "measures" list; reads only the first entry.

Parameters:

path (str) – Path to the YAML file to read.

Returns:

The configuration parsed from the first entry in measures.

Return type:

MeasureConfig

classmethod from_row(row: Series) → MeasureConfig

Construct a MeasureConfig from a legacy Excel row.

Converts the row to a dictionary and delegates to from_dict(). This is the primary migration path for measures currently stored in the legacy Excel-based MeasureSet format.

Parameters:

row (pd.Series) – A single row from a legacy measures Excel sheet, with column names matching the flat dictionary keys expected by from_dict().

Returns:

A configuration instance populated from the row data.

Return type:

MeasureConfig

__init__(name: str, haz_type: str, impfset_modifier: ImpfsetModifierConfig, hazard_modifier: HazardModifierConfig, exposures_modifier: ExposuresModifierConfig, cost_income: CostIncomeConfig, implementation_duration: str | None = None, color_rgb: Tuple[float, float, float] | None = None) → None

climada.entity.measures.cost_income module

class climada.entity.measures.cost_income.CostIncome(*, mkt_price_year: int | None = None, init_cost: float = 0.0, periodic_cost: float = 0.0, periodic_income: float = 0.0, cost_yearly_growth_rate: float = 0.0, income_yearly_growth_rate: float = 0.0, custom_cash_flows: DataFrame | None = None, freq: str = 'Y')

Bases: object

Manages costs and incomes related to a measure over time.

Income are stored a positive numbers and costs as negative ones.

mkt_price_year

The reference year for market prices.

Type:

datetime, default to today’s year.

init_cost

Initial implementation cost (stored as negative).

Type:

float

periodic_cost

Recurring cost per period (stored as negative).

Type:

float

periodic_income

Recurring income per period.

Type:

float

cost_yearly_growth_rate

Yearly growth rate of costs.

Type:

float

income_yearly_growth_rate

Yearly growth rate of income.

Type:

float

custom_cash_flows

User-defined cash flows indexed by date.

Type:

pd.DataFrame, optional

freq

Frequency of the cash flows (e.g., ‘Y’, ‘3M’, ‘7D’).

Type:

str

__init__(*, mkt_price_year: int | None = None, init_cost: float = 0.0, periodic_cost: float = 0.0, periodic_income: float = 0.0, cost_yearly_growth_rate: float = 0.0, income_yearly_growth_rate: float = 0.0, custom_cash_flows: DataFrame | None = None, freq: str = 'Y')

Initialize CostIncome with parameters.

Parameters:

• mkt_price_year (datetime, default to today’s year.) – The reference year for market prices.

• init_cost (float) – Initial implementation cost (stored as negative).

• periodic_cost (float) – Recurring cost per period (stored as negative).

• periodic_income (float) – Recurring income per period.

• cost_yearly_growth_rate (float) – Yearly growth rate of costs.

• income_yearly_growth_rate (float) – Yearly growth rate of income.

• custom_cash_flows (pd.DataFrame, optional) – User-defined cash flows indexed by date.

• freq (str) – Frequency of the cash flows (e.g., ‘Y’, ‘3M’, ‘7D’).

property custom_cash_flows: DataFrame | None

Get or set the optional user-defined cash flows.

Input cash flow have to contain a “date” column as well as at least one of “cost” and “income”. The custom cash flow is coerced to the internal period frequency.

Type:

pd.DataFrame

classmethod from_config(config: CostIncomeConfig) → CostIncome

Create a CostIncome from a CostIncomeConfig.

Parameters:

config (CostIncomeConfig)

Return type:

CostIncome

classmethod from_dict(args_dict: dict) → CostIncome

Create a CostIncome from a dictionary.

Parameters:

args_dict (dict)

Return type:

CostIncome

classmethod from_yaml(path: str) → CostIncome

Create a CostIncome from a yaml file.

Parameters:

path (str) – Path to the yaml file.

Return type:

CostIncome

calc_at_date(impl_date: Timestamp, curr_date: Timestamp) → Tuple[float, float, float]

Calculate cash flows for a single timestamp.

Computes the total cash flow, total cost, and total income for a given evaluation date, accounting for growth rates applied to base costs and incomes, as well as the custom cash flow if provided.

The calculation applies compound growth to both costs and incomes based on the number of years elapsed since the market price reference date (self.mkt_price_year).

Parameters:

• impl_date (pd.Timestamp) – The implementation date that determines which cost/income regime applies. Dates before this use have no cost or income; “at the date” uses the implementation cost, and dates after use the initialized or periodic amounts respectively.

• curr_date (pd.Timestamp) – The evaluation date for which cash flows are being calculated. This is compared against impl_date to determine the applicable base amounts and is also used to index into custom_cash_flows if present.

Returns:

A tuple containing:

• total_cash_flowfloat

  Net cash flow for the period, calculated as total_income + total_cost. Note: Costs are typically negative values in financial contexts, so this represents the net position.

• total_costfloat

  Total cost amount for the period, including both standard and custom cost components.

• total_incomefloat

  Total income amount for the period, including both standard and custom income components.

Return type:

Tuple[float, float, float]

Notes

Growth calculations use compound interest formula:

\[factor = (1 + rate)^{years\_passed}\]

where years_passed is computed as (curr_date - mkt_price_year).days / 365.0.

Cost and income regimes:

• Before impl_date: Both base cost and income are zero

• At impl_date: Uses init_cost for cost

• After impl_date: Uses periodic_cost for cost and periodic_income for income

Custom cash flows (if self.custom_cash_flows is not None) are added on top of the calculated standard amounts. Missing dates in the custom cash flow DataFrame will raise a KeyError.

calc_cash_flows(impl_date, start_date, end_date) → Tuple[ndarray, ndarray, ndarray]

Calculate net cash flows, costs, and incomes over a period.

Computes cash flow metrics across a specified date range by iterating through each period.

The method creates a period range based on the configured frequency (self.freq) and evaluates cash flows at the start time of each period. Results are returned as NumPy arrays for efficient downstream processing.

Parameters:

• impl_date – The implementation date that determines which cost/income regime applies.

• start_date – The beginning of the calculation period.

• end_date – The end of the calculation period.

Returns:

A tuple containing three NumPy arrays of equal length:

• netnp.ndarray

  Net cash flow for each period (income + cost).

• costsnp.ndarray

  Total costs for each period.

• incomesnp.ndarray

  Total incomes for each period.

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

calc_total(impl_date, start_date, end_date) → Tuple[float, float, float]

Calculate the total value of the cash flows over a given period.

Parameters:

impl_date:

The date the measure is implemented.

start_year:

The start date of the period.

end_year: int

The end year of the period.

Returns:

Tuple[float, float, float]

the total net, cost, and income values over the given period.

plot_cash_flows(impl_date: Any, start_date: Any, end_date: Any, figsize: Tuple[int, int] = (12, 7), title: str | None = None)

Plot periodic and cumulative cash flows over a given period.

Displays a two-panel figure: - Top panel: stacked bar chart of costs and incomes per period,

with a net cash flow line overlay.

• Bottom panel: cumulative net cash flow over time.

Parameters:

• impl_date – The date the measure is implemented.

• start_date – Start of the evaluation period.

• end_date – End of the evaluation period.

• figsize (tuple, optional) – Figure size as (width, height). Default is (12, 7).

• title (str, optional) – Overall figure title. Defaults to ‘Cash Flow Analysis’.

Return type:

plt.Figure

to_dataframe(impl_date, start_date, end_date) → DataFrame

Return cash flows as a formatted DataFrame.

static comb_cost_income(cost_incomes: list[CostIncome]) → CostIncome

Combine multiple CostIncomes together.

Combination sums the costs and incomes from all provided CostIncome objects.