climada.engine package
Contents
climada.engine 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#
- class climada.engine.cost_benefit.CostBenefit(present_year: int = 2016, future_year: int = 2030, tot_climate_risk: float = 0.0, unit: str = 'USD', color_rgb: Optional[Dict[str, numpy.ndarray]] = None, benefit: Optional[Dict[str, float]] = None, cost_ben_ratio: Optional[Dict[str, float]] = None, imp_meas_present: Optional[Dict[str, Union[float, Tuple[float, float], climada.engine.impact.Impact, climada.engine.impact.ImpactFreqCurve]]] = None, imp_meas_future: Optional[Dict[str, Union[float, Tuple[float, float], climada.engine.impact.Impact, climada.engine.impact.ImpactFreqCurve]]] = None)[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.
- 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: Optional[Dict[str, numpy.ndarray]] = None, benefit: Optional[Dict[str, float]] = None, cost_ben_ratio: Optional[Dict[str, float]] = None, imp_meas_present: Optional[Dict[str, Union[float, Tuple[float, float], climada.engine.impact.Impact, climada.engine.impact.ImpactFreqCurve]]] = None, imp_meas_future: Optional[Dict[str, Union[float, Tuple[float, float], climada.engine.impact.Impact, climada.engine.impact.ImpactFreqCurve]]] = 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 froment
andent_fut
have already centroids assigned for the respective hazards. Default: TrueTrue 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 ashazard
.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.forecast module#
- class climada.engine.forecast.Forecast(hazard_dict: Dict[str, climada.hazard.base.Hazard], exposure: climada.entity.exposures.base.Exposures, impact_funcs: climada.entity.impact_funcs.impact_func_set.ImpactFuncSet, haz_model: str = 'NWP', exposure_name: Optional[str] = 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 (https://github.com/matplotlib/matplotlib/issues/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
- __init__(hazard_dict: Dict[str, climada.hazard.base.Hazard], exposure: climada.entity.exposures.base.Exposures, impact_funcs: climada.entity.impact_funcs.impact_func_set.ImpactFuncSet, haz_model: str = 'NWP', exposure_name: Optional[str] = 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 GeoDataframeregion_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=<Derived 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=<Derived 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=<Derived 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: numpy.ndarray#
return period
- impact: numpy.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, aai_agg=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, aai_agg=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
andrasterio
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
- 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
- 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_imp(return_periods=(25, 50, 100, 250))[source]#
Compute exceedance impact map for given return periods. Requires attribute imp_mat.
- Parameters
return_periods (Any, optional) – return periods to consider Dafault is (25, 50, 100, 250)
- Return type
np.array
- 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
- 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': 'Map tiles by Stamen Design, CC BY 3.0 -- Map data (C) OpenStreetMap contributors', 'ext': 'png', 'html_attribution': 'Map tiles by <a href="http://stamen.com">Stamen Design</a>, <a href="http://creativecommons.org/licenses/by/3.0">CC BY 3.0</a> — Map data © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors', 'max_zoom': 18, 'min_zoom': 0, 'name': 'Stamen.Terrain', 'subdomains': 'abcd', 'url': 'https://stamen-tiles-{s}.a.ssl.fastly.net/{variant}/{z}/{x}/{y}{r}.{ext}', 'variant': 'terrain'}, 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, e.g. ctx.providers.OpenStreetMap.Mapnik
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': 'Map tiles by Stamen Design, CC BY 3.0 -- Map data (C) OpenStreetMap contributors', 'ext': 'png', 'html_attribution': 'Map tiles by <a href="http://stamen.com">Stamen Design</a>, <a href="http://creativecommons.org/licenses/by/3.0">CC BY 3.0</a> — Map data © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors', 'max_zoom': 18, 'min_zoom': 0, 'name': 'Stamen.Terrain', 'subdomains': 'abcd', 'url': 'https://stamen-tiles-{s}.a.ssl.fastly.net/{variant}/{z}/{x}/{y}{r}.{ext}', 'variant': 'terrain'}, 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.providers.OpenStreetMap.Mapnik
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]#
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
- 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: Union[str, pathlib.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.
Notes
This writer does not support attributes with variable types. Please make sure that
event_name
is a list of equally-typed values, e.g., allstr
.- 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 toFalse
.
- 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
- 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
- classmethod from_hdf5(file_path: Union[str, pathlib.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
- 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)[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.
- 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
- 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
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.
- 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: Trueignore_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_mat(HAZ_DEMO_MAT) # 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
See also
apply_deductible_to_mat
apply deductible to impact matrix
apply_cover_to_mat
apply cover to impact matrix
- minimal_exp_gdf(impf_col, assign_centroids, ignore_cover, ignore_deductible)[source]#
Get minimal exposures geodataframe for impact computation
- Parameters
exposures (climada.entity.Exposures)
hazard (climada.Hazard)
impf_col (str) – Name of the impact function column in exposures.gdf
assign_centroids (bool) – Indicates whether centroids are re-assigned to the self.exposures object or kept from previous impact calculation with a hazard of the same hazard type. Centroids assignment is an expensive operation; set this to
False
to save computation time if the centroids have not changed since the last impact calculation.include_cover (bool) – if set to True, the column ‘cover’ of the exposures GeoDataFrame is excluded from the returned GeoDataFrame, otherwise it is included if present.
include_deductible (bool) – if set to True, the column ‘deductible’ of the exposures GeoDataFrame is excluded from the returned GeoDataFrame, otherwise it is included if present.
- imp_mat_gen(exp_gdf, impf_col)[source]#
Generator of impact sub-matrices and correspoding exposures indices
The exposures gdf is decomposed into chunks that fit into the max defined memory size. For each chunk, the impact matrix is computed and returned, together with the corresponding exposures points index.
- Parameters
exp_gdf (GeoDataFrame) – Geodataframe of the exposures with columns required for impact computation.
impf_col (str) – name of the desired impact column in the exposures.
- Raises
ValueError – if the hazard is larger than the memory limit
- Yields
scipy.sparse.crs_matrix, np.ndarray – impact matrix and corresponding exposures indices for each chunk.
- insured_mat_gen(imp_mat_gen, exp_gdf, impf_col)[source]#
Generator of insured impact sub-matrices (with applied cover and deductible) and corresponding exposures indices
This generator takes a ‘regular’ impact matrix generator and applies cover and deductible onto the impacts. It yields the same sub-matrices as the original generator.
Deductible and cover are taken from the dataframe stored in exposures.gdf.
- Parameters
imp_mat_gen (generator of tuples (sparse.csr_matrix, np.array)) – The generator for creating the impact matrix. It returns a part of the full matrix and the associated exposure indices.
exp_gdf (GeoDataFrame) – Geodataframe of the exposures with columns required for impact computation.
impf_col (str) – Name of the column in ‘exp_gdf’ indicating the impact function (id)
- Yields
mat (scipy.sparse.csr_matrix) – Impact sub-matrix (with applied cover and deductible) with size (n_events, len(exp_idx))
exp_idx (np.array) – Exposure indices for impacts in mat
- impact_matrix(exp_values, cent_idx, impf)[source]#
Compute the impact matrix for given exposure values, assigned centroids, a hazard, and one impact function.
- Parameters
exp_values (np.array) – Exposure values
cent_idx (np.array) – Hazard centroids assigned to each exposure location
hazard (climada.Hazard) – Hazard object
impf (climada.entity.ImpactFunc) – one impactfunction comon to all exposure elements in exp_gdf
- Returns
Impact per event (rows) per exposure point (columns)
- Return type
scipy.sparse.csr_matrix
- stitch_impact_matrix(imp_mat_gen)[source]#
Make an impact matrix from an impact sub-matrix generator
- stitch_risk_metrics(imp_mat_gen)[source]#
Compute the impact metrics from an impact sub-matrix generator
This method is used to compute the risk metrics if the user decided not to store the full impact matrix.
- Parameters
imp_mat_gen (generator of tuples (sparse.csr_matrix, np.array)) – The generator for creating the impact matrix. It returns a part of the full matrix and the associated exposure indices.
- Returns
at_event (np.array) – Accumulated damage for each event
eai_exp (np.array) – Expected impact within a period of 1/frequency_unit for each exposure point
aai_agg (float) – Average impact within a period of 1/frequency_unit aggregated
- static apply_deductible_to_mat(mat, deductible, hazard, cent_idx, impf)[source]#
Apply a deductible per exposure point to an impact matrix at given centroid points for given impact function.
All exposure points must have the same impact function. For different impact functions apply use this method repeatedly on the same impact matrix.
- Parameters
imp_mat (scipy.sparse.csr_matrix) – impact matrix (events x exposure points)
deductible (np.array()) – deductible for each exposure point
hazard (climada.Hazard) – hazard used to compute the imp_mat
cent_idx (np.array()) – index of centroids associated with each exposure point
impf (climada.entity.ImpactFunc) – impact function associated with the exposure points
- Returns
imp_mat – impact matrix with applied deductible
- Return type
scipy.sparse.csr_matrix
- static apply_cover_to_mat(mat, cover)[source]#
Apply cover to impact matrix.
The impact data is clipped to the range [0, cover]. The cover is defined per exposure point.
- Parameters
imp_mat (scipy.sparse.csr_matrix) – impact matrix
cover (np.array()) – cover per exposures point (columns of imp_mat)
- Returns
imp_mat – impact matrix with applied cover
- Return type
scipy.sparse.csr_matrix
- static eai_exp_from_mat(mat, freq)[source]#
Compute impact for each exposures from the total impact matrix
- Parameters
imp_mat (sparse.csr_matrix) – matrix num_events x num_exp with impacts.
frequency (np.array) – frequency of events within a period of 1/frequency_unit
- Returns
eai_exp – expected impact within a period of 1/frequency_unit for each exposure
- Return type
np.array
- static at_event_from_mat(mat)[source]#
Compute impact for each hazard event from the total impact matrix :Parameters: imp_mat (sparse.csr_matrix) – matrix num_events x num_exp with impacts.
- Returns
at_event – impact for each hazard event
- Return type
np.array
- static aai_agg_from_eai_exp(eai_exp)[source]#
Aggregate impact.eai_exp
- Parameters
eai_exp (np.array) – expected impact within a period of 1/frequency_unit for each exposure point
- Returns
average aggregated impact within a period of 1/frequency_unit
- Return type
float
- classmethod risk_metrics(mat, freq)[source]#
Compute risk metricss eai_exp, at_event, aai_agg for an impact matrix and a frequency vector.
- Parameters
mat (sparse.csr_matrix) – matrix num_events x num_exp with impacts.
freq (np.array) – array with the frequency per event
- Returns
eai_exp (np.array) – expected impact within a period of 1/frequency_unit at each exposure point
at_event (np.array()) – total impact for each event
aai_agg (float) – average impact within a period of 1/frequency_unit aggregated over all exposure points
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