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.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)[source]#

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.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)[source]#

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)[source]#

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.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)[source]#

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 offset alias defining the period length (e.g. "Y" for yearly, "M" for monthly). Default is "Y".

  • 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[source]#

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)[source]#

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 offset 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() → dict[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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')[source]#

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')[source]#

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’).

classmethod from_config(config: CostIncomeConfig) → CostIncome[source]#

Create a CostIncome from a CostIncomeConfig.

Parameters:

config (CostIncomeConfig)

Return type:

CostIncome

classmethod from_dict(args_dict: dict) → CostIncome[source]#

Create a CostIncome from a dictionary.

Parameters:

args_dict (dict)

Return type:

CostIncome

classmethod from_yaml(path: str) → CostIncome[source]#

Create a CostIncome from a yaml file.

Parameters:

path (str) – Path to the yaml file.

Return type:

CostIncome

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

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][source]#

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)[source]#

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[source]#

Return cash flows as a formatted DataFrame.

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

Combine multiple CostIncomes together.

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

On this page

This Page