climada.engine package

climada.engine package#

climada.engine.unsequa package

climada.engine.calibration_opt module#

climada.engine.calibration_opt.calib_instance(hazard, exposure, impact_func, df_out=Empty DataFrame Columns: [] Index: [], yearly_impact=False, return_cost='False')[source]#

calculate one impact instance for the calibration algorithm and write to given DataFrame

Parameters:

hazard (Hazard)
exposure (Exposure)
impact_func (ImpactFunc)
df_out (Dataframe, optional) – Output DataFrame with headers of columns defined and optionally with first row (index=0) defined with values. If columns “impact”, “event_id”, or “year” are not included, they are created here. Data like reported impacts or impact function parameters can be given here; values are preserved.
yearly_impact (boolean, optional) – if set True, impact is returned per year, not per event
return_cost (str, optional) – if not ‘False’ but any of ‘R2’, ‘logR2’, cost is returned instead of df_out

Returns:

df_out – DataFrame with modelled impact written to rows for each year or event.

Return type:

DataFrame

climada.engine.calibration_opt.init_impf(impf_name_or_instance, param_dict, df_out=Empty DataFrame Columns: [] Index: [0])[source]#

create an ImpactFunc based on the parameters in param_dict using the method specified in impf_parameterisation_name and document it in df_out.

Parameters:

impf_name_or_instance (str or ImpactFunc) – method of impact function parameterisation e.g. ‘emanuel’ or an instance of ImpactFunc
param_dict (dict, optional) – dict of parameter_names and values e.g. {‘v_thresh’: 25.7, ‘v_half’: 70, ‘scale’: 1} or {‘mdd_shift’: 1.05, ‘mdd_scale’: 0.8, ‘paa_shift’: 1, paa_scale’: 1}

Returns:

imp_fun (ImpactFunc) – The Impact function based on the parameterisation
df_out (DataFrame) – Output DataFrame with headers of columns defined and with first row (index=0) defined with values. The impact function parameters from param_dict are represented here.

climada.engine.calibration_opt.change_impf(impf_instance, param_dict)[source]#

apply a shifting or a scaling defined in param_dict to the impact function in impf_istance and return it as a new ImpactFunc object.

Parameters:

impf_instance (ImpactFunc) – an instance of ImpactFunc
param_dict (dict) – dict of parameter_names and values (interpreted as factors, 1 = neutral) e.g. {‘mdd_shift’: 1.05, ‘mdd_scale’: 0.8, ‘paa_shift’: 1, paa_scale’: 1}

Returns:

ImpactFunc

Return type:

The Impact function based on the parameterisation

climada.engine.calibration_opt.init_impact_data(hazard_type, region_ids, year_range, source_file, reference_year, impact_data_source='emdat', yearly_impact=True)[source]#

creates a dataframe containing the recorded impact data for one hazard type and one area (countries, country or local split)

Parameters:

hazard_type (str) – default = ‘TC’, type of hazard ‘WS’,’FL’ etc.
region_ids (str) – name the region_ids or country names
year_range (list) – list containting start and end year. e.g. [1980, 2017]
source_file (str)
reference_year (int) – impacts will be scaled to this year
impact_data_source (str, optional) – default ‘emdat’, others maybe possible
yearly_impact (bool, optional) – if set True, impact is returned per year, not per event

Returns:

df_out – Dataframe with recorded impact written to rows for each year or event.

Return type:

pd.DataFrame

climada.engine.calibration_opt.calib_cost_calc(df_out, cost_function)[source]#

calculate the cost function of the modelled impact impact_CLIMADA and: the reported impact impact_scaled in df_out

Parameters:

df_out (pd.Dataframe) – DataFrame as created in calib_instance
cost_function (str) – chooses the cost function e.g. ‘R2’ or ‘logR2’

Returns:

cost – The results of the cost function when comparing modelled and reported impact

Return type:

float

climada.engine.calibration_opt.calib_all(hazard, exposure, impf_name_or_instance, param_full_dict, impact_data_source, year_range, yearly_impact=True)[source]#

portrait the difference between modelled and reported impacts for all impact functions described in param_full_dict and impf_name_or_instance

Parameters:

hazard (list or Hazard)
exposure (list or Exposures) – list or instance of exposure of full countries
impf_name_or_instance (string or ImpactFunc) – the name of a parameterisation or an instance of class ImpactFunc e.g. ‘emanuel’
param_full_dict (dict) – a dict containing keys used for f_name_or_instance and values which are iterable (lists) e.g. {‘v_thresh’ : [25.7, 20], ‘v_half’: [70], ‘scale’: [1, 0.8]}
impact_data_source (dict or pd.Dataframe) – with name of impact data source and file location or dataframe
year_range (list)
yearly_impact (bool, optional)

Returns:

df_result – df with modelled impact written to rows for each year or event.

Return type:

pd.DataFrame

climada.engine.calibration_opt.calib_optimize(hazard, exposure, impf_name_or_instance, param_dict, impact_data_source, year_range, yearly_impact=True, cost_fucntion='R2', show_details=False)[source]#

portrait the difference between modelled and reported impacts for all impact functions described in param_full_dict and impf_name_or_instance

Parameters:

hazard (list or Hazard)
exposure (list or Exposures) – list or instance of exposure of full countries
impf_name_or_instance (string or ImpactFunc) – the name of a parameterisation or an instance of class ImpactFunc e.g. ‘emanuel’
param_dict (dict) – a dict containing keys used for impf_name_or_instance and one set of values e.g. {‘v_thresh’: 25.7, ‘v_half’: 70, ‘scale’: 1}
impact_data_source (dict or pd. dataframe) – with name of impact data source and file location or dataframe
year_range (list)
yearly_impact (bool, optional)
cost_function (str, optional) – the argument for function calib_cost_calc, default ‘R2’
show_details (bool, optional) – if True, return a tuple with the parameters AND the details of the optimization like success, status, number of iterations etc

Returns:

param_dict_result – the parameters with the best calibration results (or a tuple with (1) the parameters and (2) the optimization output)

Return type:

dict or tuple

climada.engine.cost_benefit module#

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.

Type:: dict

Key#

measure name (‘no measure’ used for case without measure),

Type:: str

Value#

Type:: np.array

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__(present_year: int = 2016, future_year: int = 2030, tot_climate_risk: float = 0.0, unit: str = 'USD', color_rgb: Dict[str, ndarray] | None = None, benefit: Dict[str, float] | None = None, cost_ben_ratio: Dict[str, float] | None = None, imp_meas_present: Dict[str, float | Tuple[float, float] | Impact | ImpactFreqCurve] | None = None, imp_meas_future: Dict[str, float | Tuple[float, float] | Impact | ImpactFreqCurve] | None = None)[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, assign_centroids=True)[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 (climada.Hazard)
entity (climada.entity)
haz_future (climada.Hazard, optional) – hazard in the future (future year provided at ent_future)
ent_future (Entity, optional) – entity in the future. Default is None
future_year (int, optional) – future year to consider if no ent_future. Default is None 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 is None.
save_imp (bool, optional) – Default: False
assign_centroids (bool, optional) – indicates whether centroids are assigned to the self.exposures object. Centroids assignment is an expensive operation; set this to False to save computation time if the exposures from ent and ent_fut have already centroids assigned for the respective hazards. Default: True
True if Impact of each measure is saved. Default is 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 is None.
risk_func (func, optional) – function describing risk measure given an Impact. Default: average annual impact (aggregated).

Return type:

climada.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.

Parameters:

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, optional) – factor to which to multiply the insurance layer to compute its cost. Default is 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 is 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)

Return type:

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)

Return type:

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 (climada.Hazard)
entity (climada.Entity)
haz_future (Hazard) – hazard in the future (future year provided at ent_future). haz_future is expected to have the same centroids as hazard.
ent_future (climada.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

Return type:

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 (climada.Hazard)
entity (climada.Entity)
ent_future (climada.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 used in combine_measures. Default: 1 (linear).
axis (matplotlib.axes._subplots.AxesSubplot, optional) – axis to use
kwargs (optional) – arguments for bar matplotlib function, e.g. alpha=0.5

Return type:

matplotlib.axes._subplots.AxesSubplot

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

Risk measurement as average annual impact aggregated.

Parameters:: impact (climada.engine.Impact) – an Impact instance
Return type:: float

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

Risk measurement as exceedance impact at 100 years return period.

Parameters:: impact (climada.engine.Impact) – an Impact instance
Return type:: float

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

Risk measurement as exceedance impact at 250 years return period.

Parameters:: impact (climada.engine.Impact) – an Impact instance
Return type:: float

climada.engine.forecast module#

class climada.engine.forecast.Forecast(hazard_dict: Dict[str, Hazard], exposure: Exposures, impact_funcs: ImpactFuncSet, haz_model: str = 'NWP', exposure_name: str | None = None)[source]#

Bases: object

Forecast definition. Compute an impact forecast with predefined hazard originating from a forecast (like numerical weather prediction models), exposure and impact. Use the calc() method to calculate a forecasted impact. Then use the plotting methods to illustrate the forecasted impacts. By default plots are saved under in a ‘/forecast/plots’ folder in the configurable save_dir in local_data (see climada.util.config) under a name summarizing the Hazard type, haz model name, initialization time of the forecast run, event date, exposure name and the plot title. As the class is relatively new, there might be future changes to the attributes, the methods, and the parameters used to call the methods. It was discovered at some point, that there might be a memory leak in matplotlib even when figures are closed (matplotlib/matplotlib#8519). Due to this reason the plotting functions in this module have the flag close_fig, to close figures within the function scope, which might mitigate that problem if a script runs this plotting functions many times.

run_datetime#

initialization time of the forecast model run used to create the Hazard

Type:: list of datetime.datetime

event_date#

Date on which the Hazard event takes place

Type:: datetime.datetime

hazard#

List of the hazard forecast with different lead times.

Type:: list of CLIMADA Hazard

haz_model#

Short string specifying the model used to create the hazard, if possible three big letters.

Type:: str

exposure#

an CLIMADA Exposures containg values at risk

Type:: Exposure

exposure_name#

string specifying the exposure (e.g. ‘EU’), which is used to name output files.

Type:: str

vulnerability#

Set of impact functions used in the impact calculation.

Type:: ImpactFuncSet

__init__(hazard_dict: Dict[str, Hazard], exposure: Exposures, impact_funcs: ImpactFuncSet, haz_model: str = 'NWP', exposure_name: str | None = None)[source]#

Initialization with hazard, exposure and vulnerability.

Parameters:

hazard_dict (dict) – Dictionary of the format {run_datetime: Hazard} with run_datetime being the initialization time of a weather forecast run and Hazard being a CLIMADA Hazard derived from that forecast for one event. A probabilistic representation of that one event is possible, as long as the attribute Hazard.date is the same for all events. Several run_datetime:Hazard combinations for the same event can be provided.
exposure (Exposures)
impact_funcs (ImpactFuncSet)
haz_model (str, optional) – Short string specifying the model used to create the hazard, if possible three big letters. Default is ‘NWP’ for numerical weather prediction.
exposure_name (str, optional) – string specifying the exposure (e.g. ‘EU’), which is used to name output files. If None, the name will be inferred from the Exposures GeoDataframe region_id column, using the corresponding name of the region with the lowest ISO 3166-1 numeric code. If that fails, it defaults to "custom".

ei_exp(run_datetime=None)[source]#

Expected impact per exposure

Parameters:: run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
Return type:: float

ai_agg(run_datetime=None)[source]#

average impact aggregated over all exposures

Parameters:: run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
Return type:: float

haz_summary_str(run_datetime=None)[source]#

provide a summary string for the hazard part of the forecast

Parameters:: run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
Returns:: summarizing the most important information about the hazard
Return type:: str

summary_str(run_datetime=None)[source]#

provide a summary string for the impact forecast

Parameters:: run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
Returns:: summarizing the most important information about the impact forecast
Return type:: str

lead_time(run_datetime=None)[source]#

provide the lead time for the impact forecast

Parameters:: run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
Returns:: the difference between the initialization time of the forecast model run and the date of the event, commenly named lead time
Return type:: datetime.timedelta

calc(force_reassign=False)[source]#

calculate the impacts for all lead times using exposure, all hazards of all run_datetime, and ImpactFunctionSet.

Parameters:: force_reassign (bool, optional) – Reassign hazard centroids to the exposure for all hazards, default is false.

plot_imp_map(run_datetime=None, explain_str=None, save_fig=True, close_fig=False, polygon_file=None, polygon_file_crs='epsg:4326', proj=<Projected CRS: +proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: unknown - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, figsize=(9, 13), adapt_fontsize=True)[source]#

plot a map of the impacts

Parameters:

run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
explain_str (str, optional) – Short str which explains type of impact, explain_str is included in the title of the figure. default is ‘mean building damage caused by wind’
save_fig (bool, optional) – Figure is saved if True, folder is within your configurable save_dir and filename is derived from the method summary_str() (for more details see class docstring). Default is True.
close_fig (bool, optional) – Figure not drawn if True. Default is False.
polygon_file (str, optional) – Points to a .shp-file with polygons do be drawn as outlines on the plot, default is None to not draw the lines. please also specify the crs in the parameter polygon_file_crs.
polygon_file_crs (str, optional) – String of pattern <provider>:<code> specifying the crs. has to be readable by pyproj.Proj. Default is ‘epsg:4326’.
proj (ccrs) – coordinate reference system used in coordinates The default is ccrs.PlateCarree()
figsize (tuple) – figure size for plt.subplots, width, height in inches The default is (9, 13)
adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default is True.

Returns:

axes

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_hist(run_datetime=None, explain_str=None, save_fig=True, close_fig=False, figsize=(9, 8))[source]#

plot histogram of the forecasted impacts all ensemble members

Parameters:

run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
explain_str (str, optional) – Short str which explains type of impact, explain_str is included in the title of the figure. default is ‘total building damage’
save_fig (bool, optional) – Figure is saved if True, folder is within your configurable save_dir and filename is derived from the method summary_str() (for more details see class docstring). Default is True.
close_fig (bool, optional) – Figure is not drawn if True. Default is False.
figsize (tuple) – figure size for plt.subplots, width, height in inches The default is (9, 8)

Returns:

axes

Return type:

matplotlib.axes.Axes

plot_exceedence_prob(threshold, explain_str=None, run_datetime=None, save_fig=True, close_fig=False, polygon_file=None, polygon_file_crs='epsg:4326', proj=<Projected CRS: +proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: unknown - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, figsize=(9, 13), adapt_fontsize=True)[source]#

plot exceedence map

Parameters:

threshold (float) – Threshold of impact unit for which exceedence probability should be plotted.
explain_str (str, optional) – Short str which explains threshold, explain_str is included in the title of the figure.
run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
save_fig (bool, optional) – Figure is saved if True, folder is within your configurable save_dir and filename is derived from the method summary_str() (for more details see class docstring). Default is True.
close_fig (bool, optional) – Figure not drawn if True. Default is False.
polygon_file (str, optional) – Points to a .shp-file with polygons do be drawn as outlines on the plot, default is None to not draw the lines. please also specify the crs in the parameter polygon_file_crs.
polygon_file_crs (str, optional) – String of pattern <provider>:<code> specifying the crs. has to be readable by pyproj.Proj. Default is ‘epsg:4326’.
proj (ccrs) – coordinate reference system used in coordinates The default is ccrs.PlateCarree()
figsize (tuple) – figure size for plt.subplots, width, height in inches The default is (9, 13)
adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise, the default matplotlib font size is used. Default is True.

Returns:

axes

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_warn_map(polygon_file=None, polygon_file_crs='epsg:4326', thresholds='default', decision_level='exposure_point', probability_aggregation=0.5, area_aggregation=0.5, title='WARNINGS', explain_text='warn level based on thresholds', run_datetime=None, proj=<Projected CRS: +proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: unknown - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, figsize=(9, 13), save_fig=True, close_fig=False, adapt_fontsize=True)[source]#

plot map colored with 5 warning colors for all regions in provided shape file.

Parameters:

polygon_file (str, optional) – path to shp-file containing warning region polygons
polygon_file_crs (str, optional) – String of pattern <provider>:<code> specifying the crs. has to be readable by pyproj.Proj. Default is ‘epsg:4326’.
thresholds (list of 4 floats, optional) – Thresholds for coloring region in second, third, forth and fifth warning color.
decision_level (str, optional) – Either ‘exposure_point’ or ‘polygon’. Default value is ‘exposure_point’.
probability_aggregation (float or str, optional) – Either a float between [0..1] spezifying a quantile or ‘mean’ or ‘sum’. Default value is 0.5.
area_aggregation (float or str.) – Either a float between [0..1] specifying a quantile or ‘mean’ or ‘sum’. Default value is 0.5.
run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
title (str, optional) – Default is ‘WARNINGS’.
explain_text (str, optional) – Defaut is ‘warn level based on thresholds’.
proj (ccrs) – coordinate reference system used in coordinates
figsize (tuple) – figure size for plt.subplots, width, height in inches The default is (9, 13)
save_fig (bool, optional) – Figure is saved if True, folder is within your configurable save_dir and filename is derived from the method summary_str() (for more details see class docstring). Default is True.
close_fig (bool, optional) – Figure is not drawn if True. The default is False.
adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise, the default matplotlib font size is used. Default is True.

Returns:

axes

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_hexbin_ei_exposure(run_datetime=None, figsize=(9, 13))[source]#

plot the expected impact

Parameters:

run_datetime (datetime.datetime, optional) – Select the used hazard by the run_datetime, default is first element of attribute run_datetime.
figsize (tuple) – figure size for plt.subplots, width, height in inches The default is (9, 13)

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

climada.engine.impact module#

class climada.engine.impact.ImpactFreqCurve(return_per: ~numpy.ndarray = <factory>, impact: ~numpy.ndarray = <factory>, unit: str = '', frequency_unit: str = '1/year', label: str = '')[source]#

Bases: object

Impact exceedence frequency curve.

return_per: ndarray#: return period

impact: ndarray#: impact exceeding frequency

__init__(return_per: ~numpy.ndarray = <factory>, impact: ~numpy.ndarray = <factory>, unit: str = '', frequency_unit: str = '1/year', label: str = '') → None#

unit: str = ''#: value unit used (given by exposures unit)

frequency_unit: str = '1/year'#: value unit used (given by exposures unit)

label: str = ''#: string describing source data

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

Plot impact frequency curve.

Parameters:

axis (matplotlib.axes.Axes, optional) – axis to use
log_frequency (boolean, optional) – plot logarithmioc exceedance frequency on x-axis
kwargs (dict, optional) – arguments for plot matplotlib function, e.g. color=’b’

Return type:

matplotlib.axes.Axes

class climada.engine.impact.Impact(event_id=None, event_name=None, date=None, frequency=None, frequency_unit='1/year', coord_exp=None, crs='EPSG:4326', eai_exp=None, at_event=None, tot_value=0.0, aai_agg=0.0, unit='', imp_mat=None, haz_type='')[source]#

Bases: object

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

event_id#

id (>0) of each hazard event

Type:: np.array

event_name#

list name of each hazard event

Type:: list

date#

date if events as integer date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1 (ordinal format of datetime library)

Type:: np.array

coord_exp#

exposures coordinates [lat, lon] (in degrees)

Type:: np.array

crs#

WKT string of the impact’s crs

Type:: str

eai_exp#

expected impact for each exposure within a period of 1/frequency_unit

Type:: np.array

at_event#

impact for each hazard event

Type:: np.array

frequency#

frequency of event

Type:: np.array

frequency_unit#

frequency unit used (given by hazard), default is ‘1/year’

Type:: str

aai_agg#

average impact within a period of 1/frequency_unit (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

haz_type#

the hazard type of the hazard

Type:: str

__init__(event_id=None, event_name=None, date=None, frequency=None, frequency_unit='1/year', coord_exp=None, crs='EPSG:4326', eai_exp=None, at_event=None, tot_value=0.0, aai_agg=0.0, unit='', imp_mat=None, haz_type='')[source]#

Init Impact object

Parameters:

event_id (np.array, optional) – id (>0) of each hazard event
event_name (list, optional) – list name of each hazard event
date (np.array, optional) – date if events as integer date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1 (ordinal format of datetime library)
frequency (np.array, optional) – frequency of event impact for each hazard event
frequency_unit (np.array, optional) – frequency unit, default: ‘1/year’
coord_exp (np.array, optional) – exposures coordinates [lat, lon] (in degrees)
crs (Any, optional) – Coordinate reference system. CRS instances from pyproj and rasterio will be transformed into WKT. Other types are not handled explicitly.
eai_exp (np.array, optional) – expected impact for each exposure within a period of 1/frequency_unit
at_event (np.array, optional) – impact for each hazard event
tot_value (float, optional) – total exposure value affected
aai_agg (float, optional) – average impact within a period of 1/frequency_unit (aggregated)
unit (str, optional) – value unit used (given by exposures unit)
imp_mat (sparse.csr_matrix, optional) – matrix num_events x num_exp with impacts.
haz_type (str, optional) – the hazard type

calc(exposures, impact_funcs, hazard, save_mat=False, assign_centroids=True)[source]#: This function is deprecated, use ImpactCalc.impact instead.

classmethod from_eih(exposures, hazard, at_event, eai_exp, aai_agg, imp_mat=None)[source]#

Set Impact attributes from precalculated impact metrics.

Changed in version 3.3: The impfset argument was removed.

Parameters:

exposures (climada.entity.Exposures) – exposure used to compute imp_mat
impfset (climada.entity.ImpactFuncSet) – impact functions set used to compute imp_mat
hazard (climada.Hazard) – hazard used to compute imp_mat
at_event (np.array) – impact for each hazard event
eai_exp (np.array) – expected impact for each exposure within a period of 1/frequency_unit
aai_agg (float) – average impact within a period of 1/frequency_unit (aggregated)
imp_mat (sparse.csr_matrix, optional) – matrix num_events x num_exp with impacts. Default is None (empty sparse csr matrix).

Returns:

impact with all risk metrics set based on the given impact matrix

Return type:

climada.engine.impact.Impact

property tot_value#: Return the total exposure value close to a hazard

Deprecated since version 3.3: Use climada.entity.exposures.base.Exposures.affected_total_value() instead.

transfer_risk(attachment, cover)[source]#

Compute the risk transfer for the full portfolio. This is the risk of the full portfolio summed over all events. For each event, the transfered risk amounts to the impact minus the attachment (but maximally equal to the cover) multiplied with the probability of the event.

Parameters:

attachment (float) – attachment per event for entire portfolio.
cover (float) – cover per event for entire portfolio.

Returns:

transfer_at_event (np.array) – risk transfered per event
transfer_aai_agg (float) – average risk within a period of 1/frequency_unit, transfered

residual_risk(attachment, cover)[source]#

Compute the residual risk after application of insurance attachment and cover to entire portfolio. This is the residual risk of the full portfolio summed over all events. For each event, the residual risk is obtained by subtracting the transfered risk from the trom the total risk per event. of the event.

Parameters:

attachment (float) – attachment per event for entire portfolio.
cover (float) – cover per event for entire portfolio.

Returns:

residual_at_event (np.array) – residual risk per event
residual_aai_agg (float) – average residual risk within a period of 1/frequency_unit

See also

transfer_risk: compute the transfer risk per portfolio.

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) – (deductible)
cover (float)

Return type:

climada.engine.impact.Impact

impact_per_year(all_years=True, year_range=None)[source]#

Calculate yearly impact from impact data.

Note: the impact in a given year is summed over all events. Thus, the impact in a given year can be larger than the total affected exposure value.

Parameters:

all_years (boolean, optional) – return values for all years between first and last year with event, including years without any events. Default: True
year_range (tuple or list with integers, optional) – start and end year

Returns:

year_set – Key=year, value=Summed impact per year.

Return type:

dict

impact_at_reg(agg_regions=None)[source]#

Aggregate impact on given aggregation regions. This method works only if Impact.imp_mat was stored during the impact calculation.

Parameters:: agg_regions (np.array, list (optional)) – The length of the array must equal the number of centroids in exposures. It reports what macro-regions these centroids belong to. For example, asuming there are three centroids and agg_regions = [‘A’, ‘A’, ‘B’] then impact of the first and second centroids will be assigned to region A, whereas impact from the third centroid will be assigned to area B. If no aggregation regions are passed, the method aggregates impact at the country (admin_0) level. Default is None.
Returns:: Contains the aggregated data per event. Rows: Hazard events. Columns: Aggregation regions.
Return type:: pd.DataFrame

calc_impact_year_set(all_years=True, year_range=None)[source]#: This function is deprecated, use Impact.impact_per_year instead.

local_exceedance_impact(return_periods=(25, 50, 100, 250), method='interpolate', min_impact=0, log_frequency=True, log_impact=True)[source]#

Compute local exceedance impact for given return periods. The default method is fitting the ordered impacts per centroid to the corresponding cummulated frequency with linear interpolation on log-log scale.

Parameters:

return_periods (array_like) – User-specified return periods for which the exceedance intensity should be calculated locally (at each centroid). Defaults to (25, 50, 100, 250).
method (str) – Method to interpolate to new return periods. Currently available are “interpolate”, “extrapolate”, “extrapolate_constant” and “stepfunction”. If set to “interpolate”, return periods outside the range of the Impact object’s observed local return periods will be assigned NaN. If set to “extrapolate_constant” or “stepfunction”, return periods larger than the Impact object’s observed local return periods will be assigned the largest local impact, and return periods smaller than the Impact object’s observed local return periods will be assigned 0. If set to “extrapolate”, local exceedance impacts will be extrapolated (and interpolated). Defauls to “interpolate”.
min_impact (float, optional) – Minimum threshold to filter the impact. Defaults to 0.
log_frequency (bool, optional) – This parameter is only used if method is set to “extrapolate” or “interpolate”. If set to True, (cummulative) frequency values are converted to log scale before inter- and extrapolation. Defaults to True.
log_impact (bool, optional) – This parameter is only used if method is set to “extrapolate” or “interpolate”. If set to True, impact values are converted to log scale before inter- and extrapolation. Defaults to True.

Returns:

gdf (gpd.GeoDataFrame) – GeoDataFrame containing exeedance impacts for given return periods. Each column corresponds to a return period, each row corresponds to a centroid. Values in the gdf correspond to the exceedance impact for the given centroid and return period
label (str) – GeoDataFrame label, for reporting and plotting
column_label (function) – Column-label-generating function, for reporting and plotting

local_exceedance_imp(return_periods=(25, 50, 100, 250))[source]#: This function is deprecated, use Impact.local_exceedance_impact instead.

Deprecated since version The: use of Impact.local_exceedance_imp is deprecated. Use Impact.local_exceedance_impact instead. Some errors in the previous calculation in Impact.local_exceedance_imp have been corrected. To reproduce data with the previous calculation, use CLIMADA v5.0.0 or less.

local_return_period(threshold_impact=(1000.0, 10000.0), method='interpolate', min_impact=0, log_frequency=True, log_impact=True)[source]#

Compute local return periods for given threshold impacts. The default method is fitting the ordered impacts per centroid to the corresponding cummulated frequency with linear interpolation on log-log scale.

Parameters:

threshold_impact (array_like) – User-specified impact values for which the return period should be calculated locally (at each centroid). Defaults to (1000, 10000)
method (str) – Method to interpolate to new threshold impacts. Currently available are “interpolate”, “extrapolate”, “extrapolate_constant” and “stepfunction”. If set to “interpolate”, threshold impacts outside the range of the Impact object’s local impacts will be assigned NaN. If set to “extrapolate_constant” or “stepfunction”, threshold impacts larger than the Impacts object’s local impacts will be assigned NaN, and threshold impacts smaller than the Impact object’s local impacts will be assigned the smallest observed local return period. If set to “extrapolate”, local return periods will be extrapolated (and interpolated). Defaults to “interpolate”.
min_impacts (float, optional) – Minimum threshold to filter the impact. Defaults to 0.
log_frequency (bool, optional) – This parameter is only used if method is set to “interpolate”. If set to True, (cummulative) frequency values are converted to log scale before inter- and extrapolation. Defaults to True.
log_impact (bool, optional) – This parameter is only used if method is set to “interpolate”. If set to True, impact values are converted to log scale before inter- and extrapolation. Defaults to True.

Returns:

gdf (gpd.GeoDataFrame) – GeoDataFrame containing return periods for given threshold impacts. Each column corresponds to a threshold_impact value, each row corresponds to a centroid. Values in the gdf correspond to the return period for the given centroid and threshold_impact value
label (str) – GeoDataFrame label, for reporting and plotting
column_label (function) – Column-label-generating function, for reporting and plotting

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
Return type:: ImpactFreqCurve

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

Plot scatter expected impact within a period of 1/frequency_unit 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.Axes, optional) – axis to use
adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default is True.
kwargs (dict, optional) – arguments for hexbin matplotlib function

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

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

Plot hexbin expected impact within a period of 1/frequency_unit 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.Axes, optional) – axis to use
adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default: True
kwargs (dict, optional) – arguments for hexbin matplotlib function

Return type:

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

Plot raster expected impact within a period of 1/frequency_unit 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.Axes, optional) – axis to use
adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default is True.
kwargs (dict, optional) – arguments for imshow matplotlib function

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_basemap_eai_exposure(mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', zoom=10, url={'attribution': '(C) OpenStreetMap contributors (C) CARTO', 'html_attribution': '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors © <a href="https://carto.com/attributions">CARTO</a>', 'max_zoom': 20, 'name': 'CartoDB.Positron', 'subdomains': 'abcd', 'url': 'https://{s}.basemaps.cartocdn.com/{variant}/{z}/{x}/{y}{r}.png', 'variant': 'light_all'}, axis=None, **kwargs)[source]#

Plot basemap expected impact of each exposure within a period of 1/frequency_unit.

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, default: ctx.providers.CartoDB.Positron
axis (matplotlib.axes.Axes, optional) – axis to use
kwargs (dict, optional) – arguments for scatter matplotlib function, e.g. cmap=’Greys’. Default: ‘Wistia’

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_hexbin_impact_exposure(event_id=1, mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', axis=None, adapt_fontsize=True, **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’ ]
axis (matplotlib.axes.Axes) – optional axis to use
adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default is True.
kwargs (dict, optional) – arguments for hexbin matplotlib function

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_basemap_impact_exposure(event_id=1, mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', zoom=10, url={'attribution': '(C) OpenStreetMap contributors (C) CARTO', 'html_attribution': '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors © <a href="https://carto.com/attributions">CARTO</a>', 'max_zoom': 20, 'name': 'CartoDB.Positron', 'subdomains': 'abcd', 'url': 'https://{s}.basemaps.cartocdn.com/{variant}/{z}/{x}/{y}{r}.png', 'variant': 'light_all'}, 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, default: ctx.providers.CartoDB.Positron
axis (matplotlib.axes.Axes, optional) – axis to use
kwargs (dict, optional) – arguments for scatter matplotlib function, e.g. cmap=’Greys’. Default: ‘Wistia’

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

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

This function is deprecated, use Impact.local_exceedance_impact and util.plot.plot_from_gdf instead.

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

Parameters:

return_periods (tuple of int, optional) – return periods to consider. Default: (25, 50, 100, 250)
log10_scale (boolean, optional) – plot impact as log10(impact). Default: True
smooth (bool, optional) – smooth plot to plot.RESOLUTIONxplot.RESOLUTION. Default: True
kwargs (dict, optional) – arguments for pcolormesh matplotlib function used in event plots

Returns:

axis (matplotlib.axes.Axes)
imp_stats (np.array) – return_periods.size x num_centroids

Deprecated since version The: use of Impact.plot_rp_imp is deprecated.Use Impact.local_exceedance_impact and util.plot.plot_from_gdf instead.

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_hdf5(file_path: str | Path, dense_imp_mat: bool = False)[source]#

Write the data stored in this object into an H5 file.

Try to write all attributes of this class into H5 datasets or attributes. By default, any iterable will be stored in a dataset and any string or scalar will be stored in an attribute. Dictionaries will be stored as groups, with the previous rules being applied recursively to their values.

The impact matrix can be stored in a sparse or dense format.

Parameters:

file_path (str or Path) – File path to write data into. The enclosing directory must exist.
dense_imp_mat (bool) – If True, write the impact matrix as dense matrix that can be more easily interpreted by common H5 file readers but takes up (vastly) more space. Defaults to False.

Raises:

TypeError – If event_name does not contain strings exclusively.

write_sparse_csr(file_name)[source]#: Write imp_mat matrix in numpy’s npz format.

static read_sparse_csr(file_name)[source]#

Read imp_mat matrix from numpy’s npz format.

Parameters:: file_name (str)
Return type:: sparse.csr_matrix

classmethod from_csv(file_name)[source]#

Read csv file containing impact data generated by write_csv.

Parameters:: file_name (str) – absolute path of the file
Returns:: imp – Impact from csv file
Return type:: climada.engine.impact.Impact

read_csv(*args, **kwargs)[source]#: This function is deprecated, use Impact.from_csv instead.

classmethod from_excel(file_name)[source]#

Read excel file containing impact data generated by write_excel.

Parameters:: file_name (str) – absolute path of the file
Returns:: imp – Impact from excel file
Return type:: climada.engine.impact.Impact

read_excel(*args, **kwargs)[source]#: This function is deprecated, use Impact.from_excel instead.

classmethod from_hdf5(file_path: str | Path)[source]#

Create an impact object from an H5 file.

This assumes a specific layout of the file. If values are not found in the expected places, they will be set to the default values for an Impact object.

The following H5 file structure is assumed (H5 groups are terminated with /, attributes are denoted by .attrs/):

file.h5
├─ at_event
├─ coord_exp
├─ eai_exp
├─ event_id
├─ event_name
├─ frequency
├─ imp_mat
├─ .attrs/
│  ├─ aai_agg
│  ├─ crs
│  ├─ frequency_unit
│  ├─ haz_type
│  ├─ tot_value
│  ├─ unit

As per the climada.engine.impact.Impact.__init__(), any of these entries is optional. If it is not found, the default value will be used when constructing the Impact.

The impact matrix imp_mat can either be an H5 dataset, in which case it is interpreted as dense representation of the matrix, or an H5 group, in which case the group is expected to contain the following data for instantiating a scipy.sparse.csr_matrix:

imp_mat/
├─ data
├─ indices
├─ indptr
├─ .attrs/
│  ├─ shape

Parameters:: file_path (str or Path) – The file path of the file to read.
Returns:: imp – Impact with data from the given file
Return type:: Impact

static video_direct_impact(exp, impf_set, haz_list, file_name='', writer=<matplotlib.animation.PillowWriter object>, imp_thresh=0, args_exp=None, args_imp=None, ignore_zero=False, pop_name=False)[source]#

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

Parameters:

exp (climada.entity.Exposures) – exposures instance, constant during all video
impf_set (climada.entity.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, optional) – represent damages greater than threshold. Default: 0
args_exp (dict, optional) – arguments for scatter (points) or hexbin (raster) matplotlib function used in exposures
args_imp (dict, optional) – arguments for scatter (points) or hexbin (raster) matplotlib function used in impact
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 The default is False.

Return type:

list of Impact

select(event_ids=None, event_names=None, dates=None, coord_exp=None, reset_frequency=False)[source]#

Select a subset of events and/or exposure points from the impact. If multiple input variables are not None, it returns all the impacts matching at least one of the conditions.

Notes

the frequencies are NOT adjusted. Method to adjust frequencies

and obtain correct eai_exp:: 1- Select subset of impact according to your choice imp = impact.select(…) 2- Adjust manually the frequency of the subset of impact imp.frequency = […] 3- Use select without arguments to select all events and recompute the eai_exp with the updated frequencies. imp = imp.select()

Parameters:

event_ids (list of int, optional) – Selection of events by their id. The default is None.
event_names (list of str, optional) – Selection of events by their name. The default is None.
dates (tuple, optional) – (start-date, end-date), events are selected if they are >= than start-date and <= than end-date. Dates in same format as impact.date (ordinal format of datetime library) The default is None.
coord_exp (np.array, optional) – Selection of exposures coordinates [lat, lon] (in degrees) The default is None.
reset_frequency (bool, optional) – Change frequency of events proportional to difference between first and last year (old and new). Assumes annual frequency values. Default: False.

Raises:

ValueError – If the impact matrix is missing, the eai_exp and aai_agg cannot be updated for a selection of events and/or exposures.

Returns:

imp – A new impact object with a selection of events and/or exposures

Return type:

climada.engine.impact.Impact

classmethod concat(imp_list: Iterable, reset_event_ids: bool = False)[source]#

Concatenate impact objects with the same exposure

This function is useful if, e.g. different impact functions have to be applied for different seasons (e.g. for agricultural impacts).

It checks if the exposures of the passed impact objects are identical and then

concatenates the attributes event_id, event_name, date, frequency, imp_mat, at_event,
sums up the values of attributes eai_exp, aai_exp
and takes the following attributes from the first impact object in the passed impact list: coord_exp, crs, unit, tot_value, frequency_unit, haz_type

If event ids are not unique among the passed impact objects an error is raised. In this case, the user can set reset_event_ids=True to create unique event ids for the concatenated impact.

If all impact matrices of the impacts in imp_list are empty, the impact matrix of the concatenated impact is also empty.

Parameters:

imp_list (Iterable of climada.engine.impact.Impact) – Iterable of Impact objects to concatenate
reset_event_ids (boolean, optional) – Reset event ids of the concatenated impact object

Returns:

impact – New impact object which is a concatenation of all impacts

Return type:

climada.engine.impact.Impact

Notes

Concatenation of impacts with different exposure (e.g. different countries) could also be implemented here in the future.

match_centroids(hazard, distance='euclidean', threshold=100)[source]#

Finds the closest hazard centroid for each impact coordinate. Creates a temporary GeoDataFrame and uses u_coord.match_centroids(). See there for details and parameters

Parameters:

hazard (Hazard) – Hazard to match (with raster or vector centroids).
distance (str, optional) – Distance to use in case of vector centroids. Possible values are “euclidean”, “haversine” and “approx”. Default: “euclidean”
threshold (float) – If the distance (in km) to the nearest neighbor exceeds threshold, the index -1 is assigned. Set threshold to 0, to disable nearest neighbor matching. Default: 100 (km)

Returns:

array of closest Hazard centroids, aligned with the Impact’s coord_exp array

Return type:

np.array

climada.engine.impact_calc module#

class climada.engine.impact_calc.ImpactCalc(exposures, impfset, hazard)[source]#

Bases: object

Class to compute impacts from exposures, impact function set and hazard

__init__(exposures, impfset, hazard)[source]#

ImpactCalc constructor

The dimension of the imp_mat variable must be compatible with the exposures and hazard objects.

This will call climada.hazard.base.Hazard.check_matrices().

Parameters:

exposures (climada.entity.Exposures) – exposures used to compute impacts
impf_set (climada.entity.ImpactFuncSet) – impact functions set used to compute impacts
hazard (climada.Hazard) – hazard used to compute impacts

property n_exp_pnt#: Number of exposure points (rows in gdf)

property n_events#: Number of hazard events (size of event_id array)

impact(save_mat=True, assign_centroids=True, ignore_cover=False, ignore_deductible=False)[source]#

Compute the impact of a hazard on exposures.

Parameters:

save_mat (bool, optional) – if true, save the total impact matrix (events x exposures) Default: True
assign_centroids (bool, optional) – indicates whether centroids are assigned to the self.exposures object. Centroids assignment is an expensive operation; set this to False to save computation time if the hazards’ centroids are already assigned to the exposures object. Default: True
ignore_cover (bool, optional) – if set to True, the column ‘cover’ of the exposures GeoDataFrame, if present, is ignored and the impact it not capped by the values in this column. Default: False
ignore_deductible (bool, opotional) – if set to True, the column ‘deductible’ of the exposures GeoDataFrame, if present, is ignored and the impact it not reduced through values in this column. Default: False

Examples

>>> haz = Hazard.from_hdf5(HAZ_DEMO_H5)  # Set hazard
>>> impfset = ImpactFuncSet.from_excel(ENT_TEMPLATE_XLS)
>>> exp = Exposures(pd.read_excel(ENT_TEMPLATE_XLS))
>>> impcalc = ImpactCal(exp, impfset, haz)
>>> imp = impcalc.impact(insured=True)
>>> imp.aai_agg

climada.engine.impact_data module#

climada.engine.impact_data.assign_hazard_to_emdat(certainty_level, intensity_path_haz, names_path_haz, reg_id_path_haz, date_path_haz, emdat_data, start_time, end_time, keep_checks=False)[source]#

assign_hazard_to_emdat: link EMdat event to hazard

Parameters:

certainty_level (str) – ‘high’ or ‘low’
intensity_path_haz (sparse matrix) – with hazards as rows and grid points as cols, values only at location with impacts
names_path_haz (str) – identifier for each hazard (i.e. IBtracID) (rows of the matrix)
reg_id_path_haz (str) – ISO country ID of each grid point (cols of the matrix)
date_path_haz (str) – start date of each hazard (rows of the matrix)
emdat_data (pd.DataFrame) – dataframe with EMdat data
start_time (str) – start date of events to be assigned ‘yyyy-mm-dd’
end_time (str) – end date of events to be assigned ‘yyyy-mm-dd’
keep_checks (bool, optional)

Return type:

pd.dataframe with EMdat entries linked to a hazard

climada.engine.impact_data.hit_country_per_hazard(intensity_path, names_path, reg_id_path, date_path)[source]#

hit_country_per_hazard: create list of hit countries from hazard set

Parameters:

intensity_path (str) – Path to file containing sparse matrix with hazards as rows and grid points as cols, values only at location with impacts
names_path (str) – Path to file with identifier for each hazard (i.e. IBtracID) (rows of the matrix)
reg_id_path (str) – Path to file with ISO country ID of each grid point (cols of the matrix)
date_path (str) – Path to file with start date of each hazard (rows of the matrix)

Return type:

pd.DataFrame with all hit countries per hazard

climada.engine.impact_data.create_lookup(emdat_data, start, end, disaster_subtype='Tropical cyclone')[source]#

create_lookup: prepare a lookup table of EMdat events to which hazards can be assigned

Parameters:

emdat_data (pd.DataFrame) – with EMdat data
start (str) – start date of events to be assigned ‘yyyy-mm-dd’
end (str) – end date of events to be assigned ‘yyyy-mm-dd’
disaster_subtype (str) – EMdat disaster subtype

Return type:

pd.DataFrame

climada.engine.impact_data.emdat_possible_hit(lookup, hit_countries, delta_t)[source]#

relate EM disaster to hazard using hit countries and time

Parameters:

lookup (pd.DataFrame) – to relate EMdatID to hazard
delta_t – max time difference of start of EMdat event and hazard
hit_countries

Return type:

list with possible hits

climada.engine.impact_data.match_em_id(lookup, poss_hit)[source]#

function to check if EM_ID has been assigned already and combine possible hits

Parameters:

lookup (pd.dataframe) – to relate EMdatID to hazard
poss_hit (list) – with possible hits

Returns:

with all possible hits per EMdat ID

Return type:

list

climada.engine.impact_data.assign_track_to_em(lookup, possible_tracks_1, possible_tracks_2, level)[source]#

function to assign a hazard to an EMdat event to get some confidene into the procedure, hazards get only assigned if there is no other hazard occuring at a bigger time interval in that country Thus a track of possible_tracks_1 gets only assigned if there are no other tracks in possible_tracks_2. The confidence can be expressed with a certainty level

Parameters:

lookup (pd.DataFrame) – to relate EMdatID to hazard
possible_tracks_1 (list) – list of possible hits with smaller time horizon
possible_tracks_2 (list) – list of possible hits with larger time horizon
level (int) – level of confidence

Returns:

lookup with assigend tracks and possible hits

Return type:

pd.DataFrame

climada.engine.impact_data.check_assigned_track(lookup, checkset)[source]#

compare lookup with assigned tracks to a set with checked sets

Parameters:

lookup (pd.DataFrame) – dataframe to relate EMdatID to hazard
checkset (pd.DataFrame) – dataframe with already checked hazards

Return type:

error scores

climada.engine.impact_data.clean_emdat_df(emdat_file, countries=None, hazard=None, year_range=None, target_version=None)[source]#

Get a clean and standardized DataFrame from EM-DAT-CSV-file (1) load EM-DAT data from CSV to DataFrame and remove header/footer, (2) handle version, clean up, and add columns, and (3) filter by country, hazard type and year range (if any given)

Parameters:

emdat_file (str, Path, or DataFrame) – Either string with full path to CSV-file or pandas.DataFrame loaded from EM-DAT CSV
countries (list of str) – country ISO3-codes or names, e.g. [‘JAM’, ‘CUB’]. countries=None for all countries (default)
hazard (list or str) – List of Disaster (sub-)type accordung EMDAT terminology, i.e.: Animal accident, Drought, Earthquake, Epidemic, Extreme temperature, Flood, Fog, Impact, Insect infestation, Landslide, Mass movement (dry), Storm, Volcanic activity, Wildfire; Coastal Flooding, Convective Storm, Riverine Flood, Tropical cyclone, Tsunami, etc.; OR CLIMADA hazard type abbreviations, e.g. TC, BF, etc.
year_range (list or tuple) – Year range to be extracted, e.g. (2000, 2015); (only min and max are considered)
target_version (int) – required EM-DAT data format version (i.e. year of download), changes naming of columns/variables, default: newest available version in VARNAMES_EMDAT that matches the given emdat_file

Returns:

df_data – DataFrame containing cleaned and filtered EM-DAT impact data

Return type:

pd.DataFrame

climada.engine.impact_data.emdat_countries_by_hazard(emdat_file_csv, hazard=None, year_range=None)[source]#

return list of all countries exposed to a chosen hazard type from EMDAT data as CSV.

Parameters:

emdat_file (str, Path, or DataFrame) – Either string with full path to CSV-file or pandas.DataFrame loaded from EM-DAT CSV
hazard (list or str) – List of Disaster (sub-)type accordung EMDAT terminology, i.e.: Animal accident, Drought, Earthquake, Epidemic, Extreme temperature, Flood, Fog, Impact, Insect infestation, Landslide, Mass movement (dry), Storm, Volcanic activity, Wildfire; Coastal Flooding, Convective Storm, Riverine Flood, Tropical cyclone, Tsunami, etc.; OR CLIMADA hazard type abbreviations, e.g. TC, BF, etc.
year_range (list or tuple) – Year range to be extracted, e.g. (2000, 2015); (only min and max are considered)

Returns:

countries_iso3a (list) – List of ISO3-codes of countries impacted by the disaster (sub-)types
countries_names (list) – List of names of countries impacted by the disaster (sub-)types

climada.engine.impact_data.scale_impact2refyear(impact_values, year_values, iso3a_values, reference_year=None)[source]#

Scale give impact values proportional to GDP to the according value in a reference year (for normalization of monetary values)

Parameters:

impact_values (list or array) – Impact values to be scaled.
year_values (list or array) – Year of each impact (same length as impact_values)
iso3a_values (list or array) – ISO3alpha code of country for each impact (same length as impact_values)
reference_year (int, optional) – Impact is scaled proportional to GDP to the value of the reference year. No scaling for reference_year=None (default)

climada.engine.impact_data.emdat_impact_yearlysum(emdat_file_csv, countries=None, hazard=None, year_range=None, reference_year=None, imp_str="Total Damages ('000 US$)", version=None)[source]#

function to load EM-DAT data and sum impact per year

Parameters:: emdat_file_csv (str or DataFrame) – Either string with full path to CSV-file or pandas.DataFrame loaded from EM-DAT CSV

countrieslist of str: country ISO3-codes or names, e.g. [‘JAM’, ‘CUB’]. countries=None for all countries (default)
hazardlist or str: List of Disaster (sub-)type accordung EMDAT terminology, i.e.: Animal accident, Drought, Earthquake, Epidemic, Extreme temperature, Flood, Fog, Impact, Insect infestation, Landslide, Mass movement (dry), Storm, Volcanic activity, Wildfire; Coastal Flooding, Convective Storm, Riverine Flood, Tropical cyclone, Tsunami, etc.; OR CLIMADA hazard type abbreviations, e.g. TC, BF, etc.
year_rangelist or tuple: Year range to be extracted, e.g. (2000, 2015); (only min and max are considered)
versionint, optional: required EM-DAT data format version (i.e. year of download), changes naming of columns/variables, default: newest available version in VARNAMES_EMDAT

Returns:: out – DataFrame with summed impact and scaled impact per year and country.
Return type:: pd.DataFrame

climada.engine.impact_data.emdat_impact_event(emdat_file_csv, countries=None, hazard=None, year_range=None, reference_year=None, imp_str="Total Damages ('000 US$)", version=None)[source]#

function to load EM-DAT data return impact per event

Parameters:: emdat_file_csv (str or DataFrame) – Either string with full path to CSV-file or pandas.DataFrame loaded from EM-DAT CSV

countrieslist of str: country ISO3-codes or names, e.g. [‘JAM’, ‘CUB’]. default: countries=None for all countries
hazardlist or str: List of Disaster (sub-)type accordung EMDAT terminology, i.e.: Animal accident, Drought, Earthquake, Epidemic, Extreme temperature, Flood, Fog, Impact, Insect infestation, Landslide, Mass movement (dry), Storm, Volcanic activity, Wildfire; Coastal Flooding, Convective Storm, Riverine Flood, Tropical cyclone, Tsunami, etc.; OR CLIMADA hazard type abbreviations, e.g. TC, BF, etc.
year_rangelist or tuple: Year range to be extracted, e.g. (2000, 2015); (only min and max are considered)
reference_yearint reference year of exposures. Impact is scaled: proportional to GDP to the value of the reference year. Default: No scaling for 0
imp_strstr: Column name of impact metric in EMDAT CSV, default = “Total Damages (‘000 US$)”
versionint, optional: EM-DAT version to take variable/column names from, default: newest available version in VARNAMES_EMDAT

Returns:: out – EMDAT DataFrame with new columns “year”, “region_id”, and “impact” and +impact_scaled” total impact per event with same unit as chosen impact, but multiplied by 1000 if impact is given as 1000 US$ (e.g. imp_str=”Total Damages (‘000 US$) scaled”).
Return type:: pd.DataFrame

climada.engine.impact_data.emdat_to_impact(emdat_file_csv, hazard_type_climada, year_range=None, countries=None, hazard_type_emdat=None, reference_year=None, imp_str='Total Damages')[source]#

function to load EM-DAT data return impact per event

Parameters:

emdat_file_csv (str or pd.DataFrame) – Either string with full path to CSV-file or pandas.DataFrame loaded from EM-DAT CSV
countries (list of str) – country ISO3-codes or names, e.g. [‘JAM’, ‘CUB’]. default: countries=None for all countries
hazard_type_climada (str) – CLIMADA hazard type abbreviations, e.g. TC, BF, etc.
hazard_type_emdat (list or str) – List of Disaster (sub-)type accordung EMDAT terminology, i.e.: Animal accident, Drought, Earthquake, Epidemic, Extreme temperature, Flood, Fog, Impact, Insect infestation, Landslide, Mass movement (dry), Storm, Volcanic activity, Wildfire; Coastal Flooding, Convective Storm, Riverine Flood, Tropical cyclone, Tsunami, etc.
year_range (list or tuple) – Year range to be extracted, e.g. (2000, 2015); (only min and max are considered)
reference_year (int reference year of exposures. Impact is scaled) – proportional to GDP to the value of the reference year. Default: No scaling for 0
imp_str (str) – Column name of impact metric in EMDAT CSV, default = “Total Damages (‘000 US$)”

Returns:

impact_instance (climada.engine.Impact) – impact object of same format as output from CLIMADA impact computation. Values scaled with GDP to reference_year if reference_year is given. i.e. current US$ for imp_str=”Total Damages (‘000 US$) scaled” (factor 1000 is applied) impact_instance.eai_exp holds expected impact for each country (within 1/frequency_unit). impact_instance.coord_exp holds rough central coordinates for each country.
countries (list of str) – ISO3-codes of countries in same order as in impact_instance.eai_exp

climada.engine package

Contents

climada.engine package#

climada.engine.calibration_opt module#

climada.engine.cost_benefit module#

climada.engine.forecast module#

climada.engine.impact module#

climada.engine.impact_calc module#

climada.engine.impact_data module#