climada.engine package

climada.engine.impact module

class climada.engine.impact.Impact[source]

Bases: object

Impact definition. Compute from an entity (exposures and impact functions) and hazard.

tag

dictionary of tags of exposures, impact functions set and hazard: {‘exp’: Tag(), ‘if_set’: Tag(), ‘haz’: TagHazard()}

Type

dict

event_id

id (>0) of each hazard event

Type

np.array

event_name

name of each hazard event

Type

list

date

date of events

Type

np.array

coord_exp

exposures coordinates [lat, lon] (in degrees)

Type

np.ndarray

eai_exp

expected annual impact for each exposure

Type

np.array

at_event

impact for each hazard event

Type

np.array

frequency

annual frequency of event

Type

np.arrray

tot_value

total exposure value affected

Type

float

aai_agg

average annual impact (aggregated)

Type

float

unit

value unit used (given by exposures unit)

Type

str

imp_mat

matrix num_events x num_exp with impacts. only filled if save_mat is True in calc()

Type

sparse.csr_matrix

__init__()[source]

Empty initialization.

calc_freq_curve(return_per=None)[source]

Compute impact exceedance frequency curve.

Parameters

return_per (np.array, optional) – return periods where to compute the exceedance impact. Use impact’s frequencies if not provided

Returns

ImpactFreqCurve

calc(exposures, impact_funcs, hazard, save_mat=False)[source]

Compute impact of an hazard to exposures.

Parameters

  • exposures (Exposures) – exposures

  • impact_funcs (ImpactFuncSet) – impact functions

  • hazard (Hazard) – hazard

  • self_mat (bool) – self impact matrix: events x exposures

Examples

Use Entity class:

>>> haz = Hazard('TC') # Set hazard
>>> haz.read_mat(HAZ_DEMO_MAT)
>>> haz.check()
>>> ent = Entity() # Load entity with default values
>>> ent.read_excel(ENT_TEMPLATE_XLS) # Set exposures
>>> ent.check()
>>> imp = Impact()
>>> imp.calc(ent.exposures, ent.impact_funcs, haz)
>>> imp.calc_freq_curve().plot()

Specify only exposures and impact functions:

>>> haz = Hazard('TC') # Set hazard
>>> haz.read_mat(HAZ_DEMO_MAT)
>>> haz.check()
>>> funcs = ImpactFuncSet()
>>> funcs.read_excel(ENT_TEMPLATE_XLS) # Set impact functions
>>> funcs.check()
>>> exp = Exposures(pd.read_excel(ENT_TEMPLATE_XLS)) # Set exposures
>>> exp.check()
>>> imp = Impact()
>>> imp.calc(exp, funcs, haz)
>>> imp.aai_agg
calc_risk_transfer(attachment, cover)[source]

Compute traaditional risk transfer over impact. Returns new impact with risk transfer applied and the insurance layer resulting Impact metrics.

Parameters

  • attachment (float) – attachment (deductible)

  • cover (float) – cover

Returns

Impact, Impact

plot_hexbin_eai_exposure(mask=None, ignore_zero=True, pop_name=True, buffer=0.0, extend='neither', axis=None, **kwargs)[source]

Plot hexbin expected annual impact of each exposure.

Parameters

  • mask (np.array, optional) – mask to apply to eai_exp plotted.

  • ignore_zero (bool, optional) – flag to indicate if zero and negative values are ignored in plot. Default: False

  • pop_name (bool, optional) – add names of the populated places

  • buffer (float, optional) – border to add to coordinates. Default: 1.0.

  • extend (str, optional) – extend border colorbar with arrows. [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ]

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

  • kwargs (optional) – arguments for hexbin matplotlib function

Returns

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_scatter_eai_exposure(mask=None, ignore_zero=True, pop_name=True, buffer=0.0, extend='neither', axis=None, **kwargs)[source]

Plot scatter expected annual impact of each exposure.

Parameters

  • mask (np.array, optional) – mask to apply to eai_exp plotted.

  • ignore_zero (bool, optional) – flag to indicate if zero and negative values are ignored in plot. Default: False

  • pop_name (bool, optional) – add names of the populated places

  • buffer (float, optional) – border to add to coordinates. Default: 1.0.

  • extend (str, optional) – extend border colorbar with arrows. [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ]

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

  • kwargs (optional) – arguments for hexbin matplotlib function

Returns

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_raster_eai_exposure(res=None, raster_res=None, save_tiff=None, raster_f=<function Impact.<lambda>>, label='value (log10)', axis=None, **kwargs)[source]

Plot raster expected annual impact of each exposure.

Parameters

  • res (float, optional) – resolution of current data in units of latitude and longitude, approximated if not provided.

  • raster_res (float, optional) – desired resolution of the raster

  • save_tiff (str, optional) – file name to save the raster in tiff format, if provided

  • raster_f (lambda function) – transformation to use to data. Default: log10 adding 1.

  • label (str) – colorbar label

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

  • kwargs (optional) – arguments for imshow matplotlib function

Returns

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_basemap_eai_exposure(mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', zoom=10, url='http://tile.stamen.com/terrain/tileZ/tileX/tileY.png', axis=None, **kwargs)[source]

Plot basemap expected annual impact of each exposure.

Parameters

  • mask (np.array, optional) – mask to apply to eai_exp plotted.

  • ignore_zero (bool, optional) – flag to indicate if zero and negative values are ignored in plot. Default: False

  • pop_name (bool, optional) – add names of the populated places

  • buffer (float, optional) – border to add to coordinates. Default: 0.0.

  • extend (str, optional) – extend border colorbar with arrows. [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ]

  • zoom (int, optional) – zoom coefficient used in the satellite image

  • url (str, optional) – image source, e.g. ctx.sources.OSM_C

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

  • kwargs (optional) – arguments for scatter matplotlib function, e.g. cmap=’Greys’. Default: ‘Wistia’

Returns

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_hexbin_impact_exposure(event_id=1, mask=None, ignore_zero=True, pop_name=True, buffer=0.0, extend='neither', axis=None, **kwargs)[source]

Plot hexbin impact of an event at each exposure. Requires attribute imp_mat.

Parameters

  • event_id (int, optional) – id of the event for which to plot the impact. Default: 1.

  • mask (np.array, optional) – mask to apply to impact plotted.

  • ignore_zero (bool, optional) – flag to indicate if zero and negative values are ignored in plot. Default: False

  • pop_name (bool, optional) – add names of the populated places

  • buffer (float, optional) – border to add to coordinates. Default: 1.0.

  • extend (str, optional) – extend border colorbar with arrows. [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ]

  • kwargs (optional) – arguments for hexbin matplotlib function

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

Returns

matplotlib.figure.Figure, cartopy.mpl.geoaxes.GeoAxesSubplot

plot_basemap_impact_exposure(event_id=1, mask=None, ignore_zero=True, pop_name=True, buffer=0.0, extend='neither', zoom=10, url='http://tile.stamen.com/terrain/tileZ/tileX/tileY.png', axis=None, **kwargs)[source]

Plot basemap impact of an event at each exposure. Requires attribute imp_mat.

Parameters

  • event_id (int, optional) – id of the event for which to plot the impact. Default: 1.

  • mask (np.array, optional) – mask to apply to impact plotted.

  • ignore_zero (bool, optional) – flag to indicate if zero and negative values are ignored in plot. Default: False

  • pop_name (bool, optional) – add names of the populated places

  • buffer (float, optional) – border to add to coordinates. Default: 0.0.

  • extend (str, optional) – extend border colorbar with arrows. [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ]

  • zoom (int, optional) – zoom coefficient used in the satellite image

  • url (str, optional) – image source, e.g. ctx.sources.OSM_C

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

  • kwargs (optional) – arguments for scatter matplotlib function, e.g. cmap=’Greys’. Default: ‘Wistia’

Returns

cartopy.mpl.geoaxes.GeoAxesSubplot

write_csv(file_name)[source]

Write data into csv file. imp_mat is not saved.

Parameters

file_name (str) – absolute path of the file

write_excel(file_name)[source]

Write data into Excel file. imp_mat is not saved.

Parameters

file_name (str) – absolute path of the file

write_sparse_csr(file_name)[source]

Write imp_mat matrix in numpy’s npz format.

calc_impact_year_set(all_years=True, year_range=[])[source]

Calculate yearly impact from impact data.

Parameters

  • all_years (boolean) – return values for all years between first and

  • last year with event, including years without any events.

  • year_range (tuple or list with integers) – start and end year

Returns

Impact year set of type numpy.ndarray with summed impact per year.

local_exceedance_imp(return_periods=25, 50, 100, 250)[source]

Compute exceedance impact map for given return periods. Requires attribute imp_mat.

Parameters

return_periods (np.array) – return periods to consider

Returns

np.array

plot_rp_imp(return_periods=25, 50, 100, 250, log10_scale=True, smooth=True, axis=None, **kwargs)[source]

Compute and plot exceedance impact maps for different return periods. Calls local_exceedance_imp.

Parameters

  • return_periods (tuple(int), optional) – return periods to consider

  • log10_scale (boolean, optional) – plot impact as log10(impact)

  • smooth (bool, optional) – smooth plot to plot.RESOLUTIONxplot.RESOLUTION

  • kwargs (optional) – arguments for pcolormesh matplotlib function used in event plots

Returns

matplotlib.axes._subplots.AxesSubplot, np.ndarray (return_periods.size x num_centroids)

static read_sparse_csr(file_name)[source]

Read imp_mat matrix from numpy’s npz format.

Parameters

file_name (str) – file name

Returns

sparse.csr_matrix

read_csv(file_name)[source]

Read csv file containing impact data generated by write_csv.

Parameters

file_name (str) – absolute path of the file

read_excel(file_name)[source]

Read excel file containing impact data generated by write_excel.

Parameters

file_name (str) – absolute path of the file

static video_direct_impact(exp, if_set, haz_list, file_name='', writer=<matplotlib.animation.PillowWriter object>, imp_thresh=0, args_exp={}, args_imp={})[source]

Computes and generates video of accumulated impact per input events over exposure.

Parameters

  • exp (Exposures) – exposures instance, constant during all video

  • if_set (ImpactFuncSet) – impact functions

  • haz_list (list(Hazard)) – every Hazard contains an event; all hazards use the same centroids

  • file_name (str, optional) – file name to save video, if provided

  • writer = (matplotlib.animation., optional*) – video writer. Default: pillow with bitrate=500

  • imp_thresh (float) – represent damages greater than threshold

  • args_exp (optional) – arguments for scatter (points) or hexbin (raster) matplotlib function used in exposures

  • args_imp (optional) – arguments for scatter (points) or hexbin (raster) matplotlib function used in impact

Returns

list(Impact)

class climada.engine.impact.ImpactFreqCurve[source]

Bases: object

Impact exceedence frequency curve.

tag

dictionary of tags of exposures, impact functions set and hazard: {‘exp’: Tag(), ‘if_set’: Tag(), ‘haz’: TagHazard()}

Type

dict

return_per

return period

Type

np.array

impact

impact exceeding frequency

Type

np.array

unit

value unit used (given by exposures unit)

Type

str

label

string describing source data

Type

str

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

plot(axis=None, log_frequency=False, **kwargs)[source]

Plot impact frequency curve.

Parameters

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

  • log_frequency (boolean) – plot logarithmioc exceedance frequency on x-axis

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

Returns

matplotlib.axes._subplots.AxesSubplot

climada.engine.cost_benefit module

climada.engine.cost_benefit.risk_aai_agg(impact)[source]

Risk measurement as average annual impact aggregated.

Parameters

impact (Impact) – an Impact instance

Returns

float

climada.engine.cost_benefit.risk_rp_100(impact)[source]

Risk measurement as exceedance impact at 100 years return period.

Parameters

impact (Impact) – an Impact instance

Returns

float

climada.engine.cost_benefit.risk_rp_250(impact)[source]

Risk measurement as exceedance impact at 250 years return period.

Parameters

impact (Impact) – an Impact instance

Returns

float

class climada.engine.cost_benefit.CostBenefit[source]

Bases: object

Impact definition. Compute from an entity (exposures and impact functions) and hazard.

present_year

present reference year

Type

int

future_year

future year

Type

int

tot_climate_risk

total climate risk without measures

Type

float

unit

unit used for impact

Type

str

color_rgb

color code RGB for each measure. Key: measure name (‘no measure’ used for case without measure), Value: np.array

Type

dict

benefit

benefit of each measure. Key: measure name, Value: float benefit

Type

dict

cost_ben_ratio

cost benefit ratio of each measure. Key: measure name, Value: float cost benefit ratio

Type

dict

imp_meas_future

impact of each measure at future or default. Key: measure name (‘no measure’ used for case without measure), Value: dict with:

‘cost’ (tuple): (cost measure, cost factor insurance), ‘risk’ (float): risk measurement, ‘risk_transf’ (float): annual expected risk transfer, ‘efc’ (ImpactFreqCurve): impact exceedance freq

(optional) ‘impact’ (Impact): impact instance

Type

dict

imp_meas_present

impact of each measure at present. Key: measure name (‘no measure’ used for case without measure), Value: dict with:

‘cost’ (tuple): (cost measure, cost factor insurance), ‘risk’ (float): risk measurement, ‘risk_transf’ (float): annual expected risk transfer, ‘efc’ (ImpactFreqCurve): impact exceedance freq

(optional) ‘impact’ (Impact): impact instance

Type

dict

__init__()[source]

Initilization

calc(hazard, entity, haz_future=None, ent_future=None, future_year=None, risk_func=<function risk_aai_agg>, imp_time_depen=None, save_imp=False)[source]

Compute cost-benefit ratio for every measure provided current and, optionally, future conditions. Present and future measures need to have the same name. The measures costs need to be discounted by the user. If future entity provided, only the costs of the measures of the future and the discount rates of the present will be used.

Parameters

  • hazard (Hazard) – hazard

  • entity (Entity) – entity

  • haz_future (Hazard, optional) – hazard in the future (future year provided at ent_future)

  • ent_future (Entity, optional) – entity in the future

  • future_year (int, optional) – future year to consider if no ent_future provided. The benefits are added from the entity.exposures.ref_year until ent_future.exposures.ref_year, or until future_year if no ent_future given. Default: entity.exposures.ref_year+1

  • risk_func (func, optional) – function describing risk measure to use to compute the annual benefit from the Impact. Default: average annual impact (aggregated).

  • imp_time_depen (float, optional) – parameter which represents time evolution of impact (super- or sublinear). If None: all years count the same when there is no future hazard nor entity and 1 (linear annual change) when there is future hazard or entity. Default: None.

  • save_imp (bool, optional) – True if Impact of each measure is saved. Default: False.

combine_measures(in_meas_names, new_name, new_color, disc_rates, imp_time_depen=None, risk_func=<function risk_aai_agg>)[source]

Compute cost-benefit of the combination of measures previously computed by calc with save_imp=True. The benefits of the measures per event are added. To combine with risk transfer options use apply_risk_transfer.

Parameters

  • in_meas_names (list(str)) – list with names of measures to combine

  • new_name (str) – name to give to the new resulting measure

  • new_color (np.array) – color code RGB for new measure, e.g. np.array([0.1, 0.1, 0.1])

  • disc_rates (DiscRates) – discount rates instance

  • imp_time_depen (float, optional) – parameter which represents time evolution of impact (super- or sublinear). If None: all years count the same when there is no future hazard nor entity and 1 (linear annual change) when there is future hazard or entity. Default: None.

  • risk_func (func, optional) – function describing risk measure given an Impact. Default: average annual impact (aggregated).

Returns

CostBenefit

apply_risk_transfer(meas_name, attachment, cover, disc_rates, cost_fix=0, cost_factor=1, imp_time_depen=None, risk_func=<function risk_aai_agg>)[source]

Applies risk transfer to given measure computed before with saved impact and compares it to when no measure is applied. Appended to dictionaries of measures.

Paramters:

meas_name (str): name of measure where to apply risk transfer attachment (float): risk transfer values attachment (deductible) cover (float): risk transfer cover cost_fix (float): fixed cost of implemented innsurance, e.g.

transaction costs

cost_factor (float): factor to which to multiply the insurance layer

to compute its cost. Default: 1

imp_time_depen (float, optional): parameter which represents time

evolution of impact (super- or sublinear). If None: all years count the same when there is no future hazard nor entity and 1 (linear annual change) when there is future hazard or entity. Default: None.

risk_func (func, optional): function describing risk measure given

an Impact. Default: average annual impact (aggregated).

remove_measure(meas_name)[source]

Remove computed values of given measure

Parameters

meas_name (str) – name of measure to remove

plot_cost_benefit(cb_list=None, axis=None, **kwargs)[source]

Plot cost-benefit graph. Call after calc().

Parameters

  • cb_list (list(CostBenefit), optional) – if other CostBenefit provided, overlay them all. Used for uncertainty visualization.

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

  • kwargs (optional) – arguments for Rectangle matplotlib, e.g. alpha=0.5 (color is set by measures color attribute)

Returns

matplotlib.axes._subplots.AxesSubplot

plot_event_view(return_per=10, 25, 100, axis=None, **kwargs)[source]

Plot averted damages for return periods. Call after calc().

Parameters

  • return_per (list, optional) – years to visualize. Default 10, 25, 100

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

  • kwargs (optional) – arguments for bar matplotlib function, e.g. alpha=0.5 (color is set by measures color attribute)

Returns

matplotlib.axes._subplots.AxesSubplot

static plot_waterfall(hazard, entity, haz_future, ent_future, risk_func=<function risk_aai_agg>, axis=None, **kwargs)[source]

Plot waterfall graph at future with given risk metric. Can be called before and after calc().

Parameters

  • hazard (Hazard) – hazard

  • entity (Entity) – entity

  • haz_future (Hazard) – hazard in the future (future year provided at ent_future)

  • ent_future (Entity) – entity in the future

  • risk_func (func, optional) – function describing risk measure given an Impact. Default: average annual impact (aggregated).

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

  • kwargs (optional) – arguments for bar matplotlib function, e.g. alpha=0.5

Returns

matplotlib.axes._subplots.AxesSubplot

plot_arrow_averted(axis, in_meas_names=None, accumulate=False, combine=False, risk_func=<function risk_aai_agg>, disc_rates=None, imp_time_depen=1, **kwargs)[source]

Plot waterfall graph with accumulated values from present to future year. Call after calc() with save_imp=True.

Parameters

  • axis (matplotlib.axes._subplots.AxesSubplot) – axis from plot_waterfall or plot_waterfall_accumulated where arrow will be added to last bar

  • in_meas_names (list(str), optional) – list with names of measures to represented total averted damage. Default: all measures

  • accumulate (bool, optional) – accumulated averted damage (True) or averted damage in future (False). Default: False

  • combine (bool, optional) – use combine_measures to compute total averted damage (True) or just add benefits (False). Default: False

  • risk_func (func, optional) – function describing risk measure given an Impact used in combine_measures. Default: average annual impact (aggregated).

  • disc_rates (DiscRates, optional) – discount rates used in combine_measures

  • imp_time_depen (float, optional) – parameter which represent time evolution of impact used in combine_measures. Default: 1 (linear).

  • kwargs (optional) – arguments for bar matplotlib function, e.g. alpha=0.5

plot_waterfall_accumulated(hazard, entity, ent_future, risk_func=<function risk_aai_agg>, imp_time_depen=1, axis=None, **kwargs)[source]

Plot waterfall graph with accumulated values from present to future year. Call after calc() with save_imp=True. Provide same inputs as in calc.

Parameters

  • hazard (Hazard) – hazard

  • entity (Entity) – entity

  • ent_future (Entity) – entity in the future

  • risk_func (func, optional) – function describing risk measure given an Impact. Default: average annual impact (aggregated).

  • imp_time_depen (float, optional) – parameter which represent time evolution of impact. Default: 1 (linear).

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

  • kwargs (optional) – arguments for bar matplotlib function, e.g. alpha=0.5

Returns

matplotlib.axes._subplots.AxesSubplot