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 = 1, **kwargs)

Step function type impact function.

By default, everything is destroyed above the step. Useful for high resolution modelling.

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

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, 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 = 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+exp^{-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.

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)

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

Parameters:

func (ImpactFunc) – ImpactFunc instance

Raises:

ValueError –

remove_func(haz_type=None, fun_id=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, fun_id=None)

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=None)

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)

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=None, fun_id=None)

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)

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=None, fun_id=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=None)

Returns dictionaries with numerical and alphabetical ISO3 codes of all countries associated to a calibration region. 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

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

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

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