climada.entity.impact_funcs package

climada.entity.impact_funcs.base module

class climada.entity.impact_funcs.base.ImpactFunc(haz_type: str = '', id: str | int = '', intensity: ndarray | None = None, mdd: ndarray | None = None, paa: ndarray | None = None, intensity_unit: str = '', name: str = '')

Bases: object

Contains the definition of one impact function.

haz_type

hazard type acronym (e.g. ‘TC’)

Type:

str

id

id of the impact function. Exposures of the same type will refer to the same impact function id

Type:

int or str

name

name of the ImpactFunc

Type:

str

intensity_unit

unit of the intensity

Type:

str

intensity

intensity values

Type:

np.array

mdd

mean damage (impact) degree for each intensity (numbers in [0,1])

Type:

np.array

paa

percentage of affected assets (exposures) for each intensity (numbers in [0,1])

Type:

np.array

__init__(haz_type: str = '', id: str | int = '', intensity: ndarray | None = None, mdd: ndarray | None = None, paa: ndarray | None = None, intensity_unit: str = '', name: str = '')

Initialization.

Parameters:

• haz_type (str, optional) – Hazard type acronym (e.g. ‘TC’).

• id (int or str, optional) – id of the impact function. Exposures of the same type will refer to the same impact function id.

• intensity (np.array, optional) – Intensity values. Defaults to empty array.

• mdd (np.array, optional) – Mean damage (impact) degree for each intensity (numbers in [0,1]). Defaults to empty array.

• paa (np.array, optional) – Percentage of affected assets (exposures) for each intensity (numbers in [0,1]). Defaults to empty array.

• intensity_unit (str, optional) – Unit of the intensity.

• name (str, optional) – Name of the ImpactFunc.

calc_mdr(inten: float | ndarray) → ndarray

Interpolate impact function to a given intensity.

Parameters:

inten (float or np.array) – intensity, the x-coordinate of the interpolated values.

Return type:

np.array

plot(axis=None, **kwargs)

Plot the impact functions MDD, MDR and PAA in one graph, where MDR = PAA * MDD.

Parameters:

• axis (matplotlib.axes._subplots.AxesSubplot, optional) – axis to use

• kwargs (optional) – arguments for plot matplotlib function, e.g. marker=’x’

Return type:

matplotlib.axes._subplots.AxesSubplot

check()

Check consistent instance data.

Raises:

ValueError –

classmethod from_step_impf(intensity: tuple[float, float, float], haz_type: str, mdd: tuple[float, float] = (0, 1), paa: tuple[float, float] = (1, 1), impf_id: int | str = 1, **kwargs)

Step function type impact function.

By default, the impact is 100% above the step. Useful for high resolution modelling.

Parameters:

• intensity (tuple(float, float, float)) – tuple of 3-intensity numbers: (minimum, threshold, maximum)

• haz_type (str) – the reference string for the hazard (e.g., ‘TC’, ‘RF’, ‘WS’, …)

• mdd (tuple(float, float)) – (min, max) mdd values. The default is (0, 1)

• paa (tuple(float, float)) – (min, max) paa values. The default is (1, 1)

• impf_id (int|str, optional, default=1) – impact function id

• kwargs – keyword arguments passed to ImpactFunc()

Returns:

impf – Step impact function

Return type:

climada.entity.impact_funcs.ImpactFunc

set_step_impf(*args, **kwargs)

This function is deprecated, use ImpactFunc.from_step_impf instead.

classmethod from_sigmoid_impf(intensity: tuple[float, float, float], L: float, k: float, x0: float, haz_type: str, impf_id: int | str = 1, **kwargs)

Sigmoid type impact function hinging on three parameter.

This type of impact function is very flexible for any sort of study, hazard and resolution. The sigmoid is defined as:

\[f(x) = \frac{L}{1+e^{-k(x-x0)}}\]

For more information: https://en.wikipedia.org/wiki/Logistic_function

This method modifies self (climada.entity.impact_funcs instance) by assining an id, intensity, mdd and paa to the impact function.

Parameters:

• intensity (tuple(float, float, float)) – tuple of 3 intensity numbers along np.arange(min, max, step)

• L (float) – “top” of sigmoid

• k (float) – “slope” of sigmoid

• x0 (float) – intensity value where f(x)==L/2

• haz_type (str) – the reference string for the hazard (e.g., ‘TC’, ‘RF’, ‘WS’, …)

• impf_id (int, optional, default=1) – impact function id

• kwargs – keyword arguments passed to ImpactFunc()

Returns:

impf – Sigmoid impact function

Return type:

climada.entity.impact_funcs.ImpactFunc

set_sigmoid_impf(*args, **kwargs)

This function is deprecated, use LitPop.from_countries instead.

classmethod from_poly_s_shape(intensity: tuple[float, float, int], threshold: float, half_point: float, scale: float, exponent: float, haz_type: str, impf_id: int | str = 1, **kwargs)

S-shape polynomial impact function hinging on four parameter.

\[\begin{split}f(I) = \frac{\textrm{luk}(I)^{\textrm{exponent}}}{ 1 + \textrm{luk}(I)^{\textrm{exponent}} } \cdot \textrm{scale} \\ \textrm{luk}(I) = \frac{\max[I - \textrm{threshold}, 0]}{ \textrm{half_point} - \textrm{threshold} }\end{split}\]

This function is inspired by Emanuel et al. (2011) https://doi.org/10.1175/WCAS-D-11-00007.1

This method only specifies mdd, and paa = 1 for all intensities.

Parameters:

• intensity (tuple(float, float, float)) – tuple of 3 intensity numbers along np.linsapce(min, max, num)

• threshold (float) – Intensity threshold below which there is no impact. In general choose threshold > 0 for computational efficiency of impacts.

• half_point (float) – Intensity at which 50% of maximum impact is expected. If half_point <= threshold, mdd = 0 (and f(I)=0) for all intensities.

• scale (float) – Multiplicative factor for the whole function. Typically, this sets the maximum value at large intensities.

• exponent (float) – Exponent of the polynomial. Value must be exponent >= 0. Emanuel et al. (2011) uses the value 3.

• haz_type (str) – Reference string for the hazard (e.g., ‘TC’, ‘RF’, ‘WS’, …)

• impf_id (int, optional, default=1) – Impact function id

• kwargs – keyword arguments passed to ImpactFunc()

:raises ValueError : if exponent <= 0:

Returns:

impf – s-shaped polynomial impact function

Return type:

climada.entity.impact_funcs.ImpactFunc

climada.entity.impact_funcs.impact_func_set module

class climada.entity.impact_funcs.impact_func_set.ImpactFuncSet(impact_funcs: Iterable[ImpactFunc] | None = None)

Bases: object

Contains impact functions of type ImpactFunc. Loads from files with format defined in FILE_EXT.

_data

contains ImpactFunc classes. It’s not suppossed to be directly accessed. Use the class methods instead.

Type:

dict

__init__(impact_funcs: Iterable[ImpactFunc] | None = None)

Initialization.

Build an impact function set from an iterable of ImpactFunc.

Parameters:

impact_funcs (iterable of ImpactFunc, optional) – An iterable (list, set, array, …) of ImpactFunc.

Examples

Fill impact functions with values and check consistency data:

>>> intensity = np.array([0, 20])
>>> paa = np.array([0, 1])
>>> mdd = np.array([0, 0.5])
>>> fun_1 = ImpactFunc("TC", 3, intensity, mdd, paa)
>>> imp_fun = ImpactFuncSet([fun_1])
>>> imp_fun.check()

Read impact functions from file and check data consistency.

>>> imp_fun = ImpactFuncSet.from_excel(ENT_TEMPLATE_XLS)

clear()

Reinitialize attributes.

append(func: ImpactFunc)

Append a ImpactFunc. Overwrite existing if same id and haz_type.

Parameters:

func (ImpactFunc) – ImpactFunc instance

Raises:

ValueError –

remove_func(haz_type: str | None = None, fun_id: str | int | None = None)

Remove impact function(s) with provided hazard type and/or id. If no input provided, all impact functions are removed.

Parameters:

• haz_type (str, optional) – all impact functions with this hazard

• fun_id (int, optional) – all impact functions with this id

get_func(haz_type: None = None, fun_id: None = None) → dict[str, dict[int | str, ImpactFunc]]

get_func(haz_type: None = None, fun_id: int | str = None) → list[ImpactFunc]

get_func(haz_type: str = None, fun_id: None = None) → list[ImpactFunc]

get_func(haz_type: str = None, fun_id: int | str = None) → ImpactFunc

Get ImpactFunc(s) of input hazard type and/or id. If no input provided, all impact functions are returned.

Parameters:

• haz_type (str, optional) – hazard type

• fun_id (int, optional) – ImpactFunc id

Returns:

• ImpactFunc (if haz_type and fun_id),

• list(ImpactFunc) (if haz_type or fun_id),

• {ImpactFunc.haz_type ({ImpactFunc.id : ImpactFunc}} (if None))

get_hazard_types(fun_id: str | int | None = None) → list[str]

Get impact functions hazard types contained for the id provided. Return all hazard types if no input id.

Parameters:

fun_id (int, optional) – id of an impact function

Return type:

list(str)

get_ids(haz_type: None = None) → dict[str, list[str | int]]

get_ids(haz_type: str) → list[int | str]

Get impact functions ids contained for the hazard type provided. Return all ids for each hazard type if no input hazard type.

Parameters:

haz_type (str, optional) – hazard type from which to obtain the ids

Returns:

• list(ImpactFunc.id) (if haz_type provided),

• {ImpactFunc.haz_type (list(ImpactFunc.id)} (if no haz_type))

size(haz_type: str | None = None, fun_id: str | int | None = None) → int

Get number of impact functions contained with input hazard type and /or id. If no input provided, get total number of impact functions.

Parameters:

• haz_type (str, optional) – hazard type

• fun_id (int, optional) – ImpactFunc id

Return type:

int

check()

Check instance attributes.

Raises:

ValueError –

extend(impact_funcs: ImpactFuncSet)

Append impact functions of input ImpactFuncSet to current ImpactFuncSet. Overwrite ImpactFunc if same id and haz_type.

Parameters:

impact_funcs (ImpactFuncSet) – ImpactFuncSet instance to extend

Raises:

ValueError –

plot(haz_type: str | None = None, fun_id: str | int | None = None, axis=None, **kwargs)

Plot impact functions of selected hazard (all if not provided) and selected function id (all if not provided).

Parameters:

• haz_type (str, optional) – hazard type

• fun_id (int, optional) – id of the function

Return type:

matplotlib.axes._subplots.AxesSubplot

classmethod from_excel(file_name, var_names=None)

Read excel file following template and store variables.

Parameters:

• file_name (str) – absolute file name

• description (str, optional) – description of the data

• var_names (dict, optional) – name of the variables in the file

Return type:

ImpactFuncSet

read_excel(*args, **kwargs)

This function is deprecated, use ImpactFuncSet.from_excel instead.

classmethod from_mat(file_name, var_names=None)

Read MATLAB file generated with previous MATLAB CLIMADA version.

Parameters:

• file_name (str) – absolute file name

• description (str, optional) – description of the data

• var_names (dict, optional) – name of the variables in the file

Returns:

impf_set – Impact func set as defined in matlab file.

Return type:

climada.entity.impact_func_set.ImpactFuncSet

read_mat(*args, **kwargs)

This function is deprecated, use ImpactFuncSet.from_mat instead.

write_excel(file_name, var_names=None)

Write excel file following template.

Parameters:

• file_name (str) – absolute file name to write

• var_names (dict, optional) – name of the variables in the file

climada.entity.impact_funcs.storm_europe module

class climada.entity.impact_funcs.storm_europe.ImpfStormEurope

Bases: ImpactFunc

Impact functions for tropical cyclones.

__init__()

Initialization.

Parameters:

• haz_type (str, optional) – Hazard type acronym (e.g. ‘TC’).

• id (int or str, optional) – id of the impact function. Exposures of the same type will refer to the same impact function id.

• intensity (np.array, optional) – Intensity values. Defaults to empty array.

• mdd (np.array, optional) – Mean damage (impact) degree for each intensity (numbers in [0,1]). Defaults to empty array.

• paa (np.array, optional) – Percentage of affected assets (exposures) for each intensity (numbers in [0,1]). Defaults to empty array.

• intensity_unit (str, optional) – Unit of the intensity.

• name (str, optional) – Name of the ImpactFunc.

classmethod from_schwierz(impf_id=1)

Generate the impact function of Schwierz et al. 2010, doi:10.1007/s10584-009-9712-1

Returns:

impf – impact function for asset damages due to storm defined in Schwierz et al. 2010

Return type:

climada.entity.impact_funcs.storm_europe.ImpfStormEurope:

classmethod from_welker(impf_id=1)

Return the impact function of Welker et al. 2021, doi:10.5194/nhess-21-279-2021 It is the Schwierz function, calibrated with a simple multiplicative factor to minimize RMSE between modelled damages and reported damages.

Returns:

impf – impact function for asset damages due to storm defined in Welker et al. 2021

Return type:

climada.entity.impact_funcs.storm_europe.ImpfStormEurope:

set_schwierz(impf_id=1)

This function is deprecated, use ImpfStormEurope.from_schwierz instead.

set_welker(impf_id=1)

This function is deprecated, use ImpfStormEurope.from_welker instead.

climada.entity.impact_funcs.storm_europe.IFStormEurope()

Is ImpfStormEurope now

Deprecated since version The: class name IFStormEurope is deprecated and won’t be supported in a future version. Use ImpfStormEurope instead

climada.entity.impact_funcs.trop_cyclone module

class climada.entity.impact_funcs.trop_cyclone.ImpfTropCyclone

Bases: ImpactFunc

Impact functions for tropical cyclones.

__init__()

Initialization.

Parameters:

• haz_type (str, optional) – Hazard type acronym (e.g. ‘TC’).

• id (int or str, optional) – id of the impact function. Exposures of the same type will refer to the same impact function id.

• intensity (np.array, optional) – Intensity values. Defaults to empty array.

• mdd (np.array, optional) – Mean damage (impact) degree for each intensity (numbers in [0,1]). Defaults to empty array.

• paa (np.array, optional) – Percentage of affected assets (exposures) for each intensity (numbers in [0,1]). Defaults to empty array.

• intensity_unit (str, optional) – Unit of the intensity.

• name (str, optional) – Name of the ImpactFunc.

set_emanuel_usa(*args, **kwargs)

This function is deprecated, use from_emanuel_usa() instead.

classmethod from_emanuel_usa(impf_id=1, intensity=array([0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95, 100, 105, 110, 115, 120]), v_thresh=25.7, v_half=74.7, scale=1.0)

Init TC impact function using the formula of Kerry Emanuel, 2011: ‘Global Warming Effects on U.S. Hurricane Damage’, https://doi.org/10.1175/WCAS-D-11-00007.1

Parameters:

• impf_id (int, optional) – impact function id. Default: 1

• intensity (np.array, optional) – intensity array in m/s. Default: 5 m/s step array from 0 to 120m/s

• v_thresh (float, optional) – first shape parameter, wind speed in m/s below which there is no damage. Default: 25.7(Emanuel 2011)

• v_half (float, optional) – second shape parameter, wind speed in m/s at which 50% of max. damage is expected. Default: v_threshold + 49 m/s (mean value of Sealy & Strobl 2017)

• scale (float, optional) – scale parameter, linear scaling of MDD. 0<=scale<=1. Default: 1.0

Raises:

ValueError –

Returns:

impf – TC impact function instance based on formula by Emanuel (2011)

Return type:

ImpfTropCyclone

class climada.entity.impact_funcs.trop_cyclone.ImpfSetTropCyclone

Bases: ImpactFuncSet

Impact function set (ImpfS) for tropical cyclones.

__init__()

Initialization.

Build an impact function set from an iterable of ImpactFunc.

Parameters:

impact_funcs (iterable of ImpactFunc, optional) – An iterable (list, set, array, …) of ImpactFunc.

Examples

Fill impact functions with values and check consistency data:

>>> intensity = np.array([0, 20])
>>> paa = np.array([0, 1])
>>> mdd = np.array([0, 0.5])
>>> fun_1 = ImpactFunc("TC", 3, intensity, mdd, paa)
>>> imp_fun = ImpactFuncSet([fun_1])
>>> imp_fun.check()

Read impact functions from file and check data consistency.

>>> imp_fun = ImpactFuncSet.from_excel(ENT_TEMPLATE_XLS)

set_calibrated_regional_ImpfSet(*args, **kwargs)

This function is deprecated, use from_calibrated_regional_ImpfSet() instead.

classmethod from_calibrated_regional_ImpfSet(calibration_approach='TDR', q=0.5, input_file_path=None, version=1)

Calibrated regional TC wind impact functions

Based on Eberenz et al. 2021: https://doi.org/10.5194/nhess-21-393-2021

Parameters:

• calibration_approach (str, optional) – The following values are supported:

  ‘TDR’ (default)

  Total damage ratio (TDR) optimization with TDR=1.0 (simulated damage = reported damage from EM-DAT)

  ‘TDR1.5’

  Total damage ratio (TDR) optimization with TDR=1.5 (simulated damage = 1.5*reported damage from EM-DAT)

  ‘RMSF’

  Root-mean-squared fraction (RMSF) optimization

  ‘EDR’

  quantile from individually fitted v_half per event, i.e. v_half fitted to get EDR=1.0 for each event

• q (float, optional) – Quantile between 0 and 1.0 to select (EDR only). Default: 0.5, i.e. median v_half

• input_file_path (str or DataFrame, optional) – full path to calibration result file to be used instead of default file in repository (expert users only)

Returns:

impf_set – TC Impact Function Set based on Eberenz et al, 2021.

Return type:

ImpfSetTropCyclone

static calibrated_regional_vhalf(calibration_approach='TDR', q=0.5, input_file_path=None, version=1)

Calibrated TC wind impact function slope parameter v_half per region

Based on Eberenz et al., 2021: https://doi.org/10.5194/nhess-21-393-2021

Parameters:

• calibration_approach (str, optional) – The following values are supported:

  ‘TDR’ (default)

  Total damage ratio (TDR) optimization with TDR=1.0 (simulated damage = reported damage from EM-DAT)

  ‘TDR1.5’

  Total damage ratio (TDR) optimization with TDR=1.5 (simulated damage = 1.5*reported damage from EM-DAT)

  ‘RMSF’

  Root-mean-squared fraction (RMSF) optimization

  ‘EDR’

  quantile from individually fitted v_half per event, i.e. v_half fitted to get EDR=1.0 for each event

• q (float, optional) – Quantile between 0 and 1.0 to select (EDR only). Default: 0.5, i.e. median v_half

• input_file_path (str or DataFrame, optional) – full path to calibration result file to be used instead of default file in repository (expert users only)

Raises:

ValueError –

Returns:

v_half – TC impact function slope parameter v_half per region

Return type:

dict

static get_countries_per_region(region: Literal['all'] = 'all') → tuple[dict[str, str], dict[str, int], dict[str, list[int]], dict[str, list[str]]]

static get_countries_per_region(region: None) → tuple[dict[str, str], dict[str, int], dict[str, list[int]], dict[str, list[str]]]

static get_countries_per_region(region: str) → tuple[str, int, list[int], list[str]]

Returns countries within a TC calibration region and associated impact functions.

This method returns a tuple with numerical (numeric) and alphabetical (alpha3) ISO3 codes of all countries associated to a calibration region.

If no region or “all” is provided as argument, the method return a tuple of dictionaries with short name of the tropical cyclone calibration regions as keys and the values for each of those.

Notes

Only contains countries that were affected by tropical cyclones between 1980 and 2017 according to EM-DAT.

Parameters:

region (str) – regional abbreviation (default=’all’), either ‘NA1’, ‘NA2’, ‘NI’, ‘OC’, ‘SI’, ‘WP1’, ‘WP2’, ‘WP3’, ‘WP4’, or ‘all’.

Returns:

• region_name (dict or str) – long name per region

• impf_id (dict or int) – impact function ID per region

• numeric (dict or list) – numerical ISO3codes (=region_id) per region

• alpha3 (dict or list) – numerical ISO3codes (=region_id) per region

static get_impf_id_regions_per_countries(countries: list = None) → tuple

Return the impact function id and the region corresponding to some countries

Parameters:

countrieslist

List containing the ISO codes of the country, which should be either in string format if the code is “ISO 3166-1 alpha-3” abbreviated as “alpha3”, or an integer if the code is in “ISO 3166-1 numeric” abbreviated as “numeric”, which is a three-digit country code, the numeric version of “ISO 3166-1 alpha-3”. For example, the “alpha3” code of Switzerland is “CHE” and the “numeric” is 756.

Returns:

impf_idslist

List of impact function ids matching the countries.

regions_idslist

List of the region ids. Regions are a container of countries as defined in: https://nhess.copernicus.org/articles/21/393/2021/nhess-21-393-2021.pdf, and implemented in the CountryCode Enum Class. Example: “NA1”, “NA2”, …

regions_nameslist

List of the regions names. Example: “Caribbean and Mexico”, “USA and Canada”, …

climada.entity.impact_funcs.trop_cyclone.IFTropCyclone()

Is ImpfTropCyclone now

Deprecated since version The: class name IFTropCyclone is deprecated and won’t be supported in a future version. Use ImpfTropCyclone instead