climada.entity.impact_funcs package

Contents

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

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

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

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

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

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

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

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

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

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 = 1, **kwargs)[source]#

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

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

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

Reinitialize attributes.

append(func)[source]#

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

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

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

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

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

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

Check instance attributes.

Raises:

ValueError –

extend(impact_funcs)[source]#

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

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

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

This function is deprecated, use ImpactFuncSet.from_excel instead.

classmethod from_mat(file_name, var_names=None)[source]#

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

This function is deprecated, use ImpactFuncSet.from_mat instead.

write_excel(file_name, var_names=None)[source]#

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

Bases: ImpactFunc

Impact functions for tropical cyclones.

__init__()[source]#

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

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

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

This function is deprecated, use ImpfStormEurope.from_schwierz instead.

set_welker(impf_id=1)[source]#

This function is deprecated, use ImpfStormEurope.from_welker instead.

climada.entity.impact_funcs.storm_europe.IFStormEurope()[source]#

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

Bases: ImpactFunc

Impact functions for tropical cyclones.

__init__()[source]#

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

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

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

Bases: ImpactFuncSet

Impact function set (ImpfS) for tropical cyclones.

__init__()[source]#

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

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

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

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

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

Is ImpfTropCyclone now

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

Contents