climada.engine.uncertainty package

climada.engine.uncertainty.base module

class climada.engine.uncertainty.base.UncVar(uncvar_func, distr_dict)[source]

Bases: object

Uncertainty variable

An uncertainty variable requires a single or multi-parameter function. The parameters must follow a given distribution.

distr_dict

Distribution of the uncertainty parameters. Keys are uncertainty parameters names and Values are probability density distribution from scipy.stats package https://docs.scipy.org/doc/scipy/reference/stats.html

Type

dict

labels

Names of the uncertainty parameters (keys of distr_dict)

Type

list

uncvar_func

User defined python fucntion with the uncertainty parameters as kwargs and which returns a climada object.

Type

function

Examples

Categorical variable function: LitPop exposures with m,n exponents in [0,5]

import scipy as sp def litpop_cat(m, n):

exp = Litpop() exp.set_country(‘CHE’, exponent=[m, n]) return exp

distr_dict = {

‘m’: sp.stats.randint(low=0, high=5), ‘n’: sp.stats.randint(low=0, high=5) }

unc_var_cat = UncVar(uncvar_func=litpop_cat, distr_dict=distr_dict)

Continuous variable function: Impact function for TC

import scipy as sp def imp_fun_tc(G, v_half, vmin, k, _id=1):

imp_fun = ImpactFunc() imp_fun.haz_type = ‘TC’ imp_fun.id = _id imp_fun.intensity_unit = ‘m/s’ imp_fun.intensity = np.linspace(0, 150, num=100) imp_fun.mdd = np.repeat(1, len(imp_fun.intensity)) imp_fun.paa = np.array([sigmoid_function(v, G, v_half, vmin, k)

for v in imp_fun.intensity])

imp_fun.check() impf_set = ImpactFuncSet() impf_set.append(imp_fun) return impf_set

distr_dict = {“G”: sp.stats.uniform(0.8, 1),

“v_half”: sp.stats.uniform(50, 100), “vmin”: sp.stats.norm(loc=15, scale=30), “k”: sp.stats.randint(low=1, high=9) }

unc_var_cont = UncVar(uncvar_func=imp_fun_tc, distr_dict=distr_dict)

__init__(uncvar_func, distr_dict)[source]

Initialize UncVar

Parameters

  • uncvar_func (function) – Variable defined as a function of the uncertainty parameters

  • distr_dict (dict) – Dictionary of the probability density distributions of the uncertainty parameters, with keys matching the keyword arguments (i.e. uncertainty parameters) of the uncvar_func function. The distribution must be of type scipy.stats https://docs.scipy.org/doc/scipy/reference/stats.html

Returns

Return type

None.

plot(figsize=None)[source]

Plot the distributions of the parameters of the uncertainty variable.

Parameters

figsize (tuple(int or float, int or float), optional) – The figsize argument of matplotlib.pyplot.subplots() The default is derived from the total number of plots (nplots) as:

nrows, ncols = int(np.ceil(nplots / 3)), min(nplots, 3) figsize = (ncols * FIG_W, nrows * FIG_H)

Returns

axes – The figure and axes handle of the plot.

Return type

matplotlib.pyplot.figure, matplotlib.pyplot.axes

static var_to_uncvar(var)[source]

Returns an uncertainty variable with no distribution if var is not an UncVar. Else, returns var.

Parameters

var (climada.uncertainty.UncVar or any other CLIMADA object)

Returns

var if var is UncVar, else UncVar with var and no distribution.

Return type

UncVar

class climada.engine.uncertainty.base.Uncertainty(unc_vars, samples=None, metrics=None, sensitivity=None)[source]

Bases: object

Uncertainty analysis class

This is the base class to perform uncertainty analysis on the outputs of a climada.engine.impact.Impact() or climada.engine.costbenefit.CostBenefit() object.

unc_vars

Dictonnary of the required uncertainty variables.

Type

dict(UncVar)

samples_df

Values of the sampled uncertainty parameters. It has n_samples rows and one column per uncertainty parameter.

Type

pandas.DataFrame

sampling_method

Name of the sampling method from SAlib. https://salib.readthedocs.io/en/latest/api.html#

Type

str

n_samples

Effective number of samples (number of rows of samples_df)

Type

int

param_labels

Name of all the uncertainty parameters

Type

list

distr_dict

Comon flattened dictionary of all the distr_dic list in unc_vars. It represents the distribution of all the uncertainty parameters.

Type

dict

problem_sa

The description of the uncertainty variables and their distribution as used in SALib. https://salib.readthedocs.io/en/latest/basics.html.

Type

dict

metrics

Dictionary of the value of the CLIMADA metrics for each sample (of the uncertainty parameters) defined in samples_df. Keys are metrics names, e.g. ‘aai_agg’’, ‘freq_curve’, ‘eai_exp’, ‘at_event’ for impact.calc and ‘tot_climate_risk’, ‘benefit’, ‘cost_ben_ratio’, ‘imp_meas_present’, ‘imp_meas_future’ for cost_benefit.calc. Values are pd.DataFrame of dict(pd.DataFrame), with one row for one sample.

Type

dict

sensitivity

Sensitivity indices for each metric. Keys are metrics names, e.g. ‘aai_agg’’, ‘freq_curve’, ‘eai_exp’, ‘at_event’ for impact.calc and ‘tot_climate_risk’, ‘benefit’, ‘cost_ben_ratio’, ‘imp_meas_present’, ‘imp_meas_future’ for cost_benefit.calc. Values are the sensitivity indices dictionary as returned by SALib.

Type

dict

__init__(unc_vars, samples=None, metrics=None, sensitivity=None)[source]

Initialize Uncertainty

Parameters

  • unc_vars (dict) – keys are names and values are climade.engine.uncertainty.UncVar

  • samples (pd.DataFrame, optional) – DataFrame of sampled parameter values. Column names must be parameter names (all labels) from all unc_vars. The default is pd.DataFrame().

  • metrics (dict(), optional) – dictionary of the CLIMADA metrics (outputs from Impact.calc() or CostBenefits.calcl()) for which the uncertainty distribution (and optionally the sensitivity) will be computed. For each sample (row of samples), each metric must have a definite value. Metrics are named directly after their defining attributes:

    Impact: [‘aai_agg’, ‘freq_curve’, ‘eai_exp’, ‘at_event’] CostBenefits: [‘tot_climate_risk’, ‘benefit’, ‘cost_ben_ratio’,

    ‘imp_meas_present’, ‘imp_meas_future’]

    Keys are metric names and values are pd.DataFrame with values for each parameter sample (one row per sample). The default is {}.

  • sensitivity (dict(), optional) – dictionary of the sensitivity analysis for each uncertainty parameter. The default is {}.

check()[source]

Check if the data variables are consistent

Returns

check – True if data is consistent.

Return type

boolean

property n_samples

The effective number of samples

Returns

n_samples – effective number of samples

Return type

int

property param_labels

Labels of all uncertainty parameters.

Returns

param_labels – Labels of all uncertainty parameters.

Return type

list of strings

property distr_dict

Dictionary of the distribution of all the parameters of all variables listed in self.unc_vars

Returns

distr_dict – Dictionary of all distributions.

Return type

dict( sp.stats objects )

property problem_sa

The description of the uncertainty variables and their distribution as used in SALib. https://salib.readthedocs.io/en/latest/basics.html

Returns

problem_sa – Salib problem dictionary.

Return type

dict

make_sample(N, sampling_method='saltelli', sampling_kwargs=None)[source]

Make a sample for all parameters with their respective distributions using the chosen sampling_method from SALib. https://salib.readthedocs.io/en/latest/api.html

This sets the attributes self.sampling method and self.samples_df.

Parameters

  • N (int) – Number of samples as defined in SALib.sample.saltelli.sample().

  • sampling_method (string) – The sampling method as defined in SALib. Possible choices: ‘saltelli’, ‘fast_sampler’, ‘latin’, ‘morris’, ‘dgsm’, ‘ff’ https://salib.readthedocs.io/en/latest/api.html The default is ‘saltelli’

  • sampling_kwargs (dict()) – Optional keyword arguments of the chosen SALib sampling method.

Returns

df_samples – Dataframe of the generated samples (one row = one sample, columns = uncertainty parameters)

Return type

pd.DataFrame()

est_comp_time(time_one_run, pool=None)[source]

Estimate the computation time

Parameters

  • time_one_run (int/float) – Estimated computation time for one parameter set in seconds

  • pool (pathos.pool, optional) – pool that would be used for parallel computation. The default is None.

Returns

Return type

Estimated computation time in secs.

calc_sensitivity(salib_method='sobol', method_kwargs=None)[source]

Compute the sensitivity indices using SALib. Prior to doing this sensitivity analysis, one must compute the distribution of the output metrics values (i.e. self.metrics is defined) for all the parameter samples (rows of self.samples_df).

According to Wikipedia, sensitivity analysis is “the study of how the uncertainty in the output of a mathematical model or system (numerical or otherwise) can be apportioned to different sources of uncertainty in its inputs.” The sensitivity of each input is often represented by a numeric value, called the sensitivity index. Sensitivity indices come in several forms:

First-order indices: measures the contribution to the output variance by a single model input alone. Second-order indices: measures the contribution to the output variance caused by the interaction of two model inputs. Total-order index: measures the contribution to the output variance caused by a model input, including both its first-order effects (the input varying alone) and all higher-order interactions.

This sets the attribute self.sensitivity.

Parameters

  • salib_method (str) – sensitivity analysis method from SALib.analyse Possible choices:

    ‘fast’, ‘rbd_fact’, ‘morris’, ‘sobol’, ‘delta’, ‘ff’

    The default is ‘sobol’. Note that in Salib, sampling methods and sensitivity analysis methods should be used in specific pairs. https://salib.readthedocs.io/en/latest/api.html

  • method_kwargs (dict(), optional) – Keyword arguments of the chosen SALib analyse method. The default is to use SALib’s default arguments.

Returns

sensitivity_dict – dictionary of the sensitivity indices. Keys are the metrics names, values the sensitivity indices dictionary as returned by SALib.

Return type

dict

plot_distribution(metric_list=None, figsize=None)[source]

Plot the distribution of values.

Parameters

  • metric_list (list, optional) – List of metrics to plot the distribution. The default is None.

  • figsize (tuple(int or float, int or float), optional) – The figsize argument of matplotlib.pyplot.subplots() The default is derived from the total number of plots (nplots) as:

    nrows, ncols = int(np.ceil(nplots / 3)), min(nplots, 3) figsize = (ncols * FIG_W, nrows * FIG_H)

Raises

ValueError – If no metric distribution was computed the plot cannot be made.

Returns

axes – The axes handle of the plot.

Return type

matplotlib.pyplot.axes

plot_sample(figsize=None)[source]

Plot the sample distributions of the uncertainty parameters.

Parameters

figsize (tuple(int or float, int or float), optional) – The figsize argument of matplotlib.pyplot.subplots() The default is derived from the total number of plots (nplots) as:

nrows, ncols = int(np.ceil(nplots / 3)), min(nplots, 3) figsize = (ncols * FIG_W, nrows * FIG_H)

Raises

ValueError – If no sample was computed the plot cannot be made.

Returns

axes – The axis handle of the plot.

Return type

matplotlib.pyplot.axes

plot_sensitivity(salib_si='S1', metric_list=None, figsize=None)[source]

Plot one of the first order sensitivity indices of the chosen metric(s). This requires that a senstivity analysis was already performed.

E.g. For the sensitivity analysis method ‘sobol’, the choices are [‘S1’, ‘ST’], for ‘delta’ the choices are [‘delta’, ‘S1’].

For more information see the SAlib documentation: https://salib.readthedocs.io/en/latest/basics.html

Parameters

  • salib_si (string, optional) – The first order (one value per metric output) sensitivity index to plot. This must be a key of the sensitivity dictionaries in self.sensitivity[metric] for each metric in metric_list. The default is S1.

  • metric_list (list of strings, optional) – List of metrics to plot the sensitivity. If a metric is not found in self.sensitivity, it is ignored. The default is all metrics from Impact.calc or CostBenefit.calc: [‘aai_agg’, ‘freq_curve’, ‘tot_climate_risk’, ‘benefit’,

    ‘cost_ben_ratio’, ‘imp_meas_present’, ‘imp_meas_future’, ‘tot_value’]

  • figsize (tuple(int or float, int or float), optional) – The figsize argument of matplotlib.pyplot.subplots() The default is derived from the total number of plots (nplots) as:

    nrows, ncols = int(np.ceil(nplots / 3)), min(nplots, 3) figsize = (ncols * FIG_W, nrows * FIG_H)

Raises

ValueError – If no sensitivity is available the plot cannot be made.

Returns

axes – The axes handle of the plot.

Return type

matplotlib.pyplot.axes

save_samples_df(filename=None)[source]

Save the samples_df dataframe to .csv

Parameters

filename (str or pathlib.Path, optional) – The filename with absolute or relative path. The default name is “samples_df + datetime.now() + .csv” and the default path is taken from climada.config

Returns

save_path – Path to the saved file

Return type

pathlib.Path

load_samples_df(filename)[source]

Load a samples_df from .csv file

Parameters

filename (str or pathlib.Path) – The filename with absolute or relative path.

Returns

samples_df – The loaded samples_df

Return type

pandas.DataFrame

save_metrics(filename=None)[source]

Save the metrics dictionary to .json

Parameters filename : str or pathlib.Path, optional

The filename with absolute or relative path. The default name is “metrics + datetime.now() + .json” and the default path is taken from climada.config

Returns

save_path – Path to the saved file

Return type

pathlib.Path

load_metrics(filename, directory=None)[source]

Load a metrics from .json file

Parameters

  • filename (str or pathlib.Path) – The filename.

  • directory (str or pathlib.Path, optional) – The directory path. The default is taken from climada.config

Returns

metrics – The loaded metrics dictionary

Return type

dict

save_sensitivity(filename=None)[source]

Save the sensitivity dictionary to .json

Parameters filename : str or pathlib.Path, optional

The filename with absolute or relative path. The default name is “sensitivity + datetime.now() + .json” and the default path is taken from climada.config

Returns

save_path – Path to the saved file

Return type

pathlib.Path

load_sensitivity(filename)[source]

Load a sensitivity from .json file

Parameters

  • filename (str or pathlib.Path) – The filename

  • directory (str or pathlib.Path, optional) – The directory path. The default is taken from climada.config

Returns

sensitivity – The loaded sensitivity dictionary

Return type

dict

climada.engine.uncertainty.unc_cost_benefit module

class climada.engine.uncertainty.unc_cost_benefit.UncCostBenefit(haz_unc, ent_unc, haz_fut_unc=None, ent_fut_unc=None)[source]

Bases: climada.engine.uncertainty.base.Uncertainty

Cost Benefit Uncertainty analysis class

This is the base class to perform uncertainty analysis on the outputs of a climada.engine.costbenefit.CostBenefit().

unc_vars

Dictonnary of the required uncertainty variables. Keys are [‘ent’, ‘haz’, ‘ent_fut’, ‘haz_fut’], and values are the corresponding UnvVar.

Type

dict(UncVar)

samples_df

Values of the sampled uncertainty parameters. It has n_samples rows and one column per uncertainty parameter.

Type

pandas.DataFrame

sampling_method

Name of the sampling method from SAlib. https://salib.readthedocs.io/en/latest/api.html#

Type

str

n_samples

Effective number of samples (number of rows of samples_df)

Type

int

param_labels

Name of all the uncertainty parameters

Type

list

distr_dict

Comon flattened dictionary of all the distr_dic list in unc_vars. It represents the distribution of all the uncertainty parameters.

Type

dict

problem_sa

The description of the uncertainty variables and their distribution as used in SALib. https://salib.readthedocs.io/en/latest/basics.html

Type

dict

metrics

Dictionnary of the value of the CLIMADA metrics for each sample (of the uncertainty parameters) defined in samples_df. Keys are metrics names [‘tot_climate_risk’, ‘benefit’, ‘cost_ben_ratio’, ‘imp_meas_present’, ‘imp_meas_future’] and values are pd.DataFrame of dict(pd.DataFrame) with one row for one sample.

Type

dict

sensitivity

Sensitivity indices for each metric. Keys are metrics names [‘tot_climate_risk’, ‘benefit’, ‘cost_ben_ratio’, ‘imp_meas_present’, ‘imp_meas_future’] and values are the sensitivity indices dictionary as returned by SALib.

Type

dict

__init__(haz_unc, ent_unc, haz_fut_unc=None, ent_fut_unc=None)[source]

Initialize UncCostBenefit

Parameters

  • haz_unc (climada.engine.uncertainty.UncVar) – or climada.hazard.Hazard Hazard uncertainty variable or Hazard for the present Hazard in climada.engine.CostBenefit.calc

  • ent_unc (climada.engine.uncertainty.UncVar) – or climada.entity.Entity Entity uncertainty variable or Entity for the future Entity in climada.engine.CostBenefit.calc

  • haz_unc_fut (climada.engine.uncertainty.UncVar) – or climada.hazard.Hazard, optional Hazard uncertainty variable or Hazard for the future Hazard in climada.engine.CostBenefit.calc The Default is None.

  • ent_fut_unc (climada.engine.uncertainty.UncVar) – or climada.entity.Entity, optional Entity uncertainty variable or Entity for the future Entity in climada.engine.CostBenefit.calc

calc_distribution(pool=None, **kwargs)[source]

Computes the cost benefit for each of the parameters set defined in uncertainty.samples.

By default, imp_meas_present, imp_meas_future, tot_climate_risk, benefit, cost_ben_ratio are computed.

This sets the attribute self.metrics.

Parameters

  • pool (pathos.pools.ProcessPool, optional) – Pool of CPUs for parralel computations. Default is None. The default is None.

  • **kwargs (keyword arguments) – Any keyword arguments of climada.engine.CostBenefit.calc() EXCEPT: haz, ent, haz_fut, ent_fut

climada.engine.uncertainty.unc_impact module

class climada.engine.uncertainty.unc_impact.UncImpact(exp_unc, impf_unc, haz_unc)[source]

Bases: climada.engine.uncertainty.base.Uncertainty

Impact uncertainty analysis class

This is the base class to perform uncertainty analysis on the outputs of a climada.engine.impact.Impact() object.

rp

List of the chosen return periods.

Type

list(int)

calc_eai_exp

Compute eai_exp or not

Type

bool

calc_at_event

Compute eai_exp or not

Type

bool

unc_vars

Dictonnary of the required uncertainty variables [‘exp’, ‘impf’, ‘haz’] and values are the corresponding UncVar.

Type

dict(UncVar)

samples_df

Values of the sampled uncertainty parameters. It has n_samples rows and one column per uncertainty parameter.

Type

pandas.DataFrame

sampling_method

Name of the sampling method from SAlib. https://salib.readthedocs.io/en/latest/api.html#

Type

str

n_samples

Effective number of samples (number of rows of samples_df)

Type

int

param_labels

Name of all the uncertainty parameters

Type

list

distr_dict

Comon flattened dictionary of all the distr_dic list in unc_vars. It represents the distribution of all the uncertainty parameters.

Type

dict

problem_sa

The description of the uncertainty variables and their distribution as used in SALib. https://salib.readthedocs.io/en/latest/basics.html

Type

dict

metrics

Dictionnary of the value of the CLIMADA metrics for each sample (of the uncertainty parameters) defined in samples_df. Keys are metrics names [‘aai_agg’’, ‘freq_curve’, ‘eai_exp’, ‘at_event’] and falues are pd.DataFrame of dict(pd.DataFrame), with one row for one sample.

Type

dict

sensitivity

Sensitivity indices for each metric. Keys are metrics names [‘aai_agg’’, ‘freq_curve’, ‘eai_exp’, ‘at_event’] and values are the sensitivity indices dictionary as returned by SALib.

Type

dict

__init__(exp_unc, impf_unc, haz_unc)[source]

Initialize UncImpact

Parameters

  • exp_unc (climada.engine.uncertainty.UncVar or climada.entity.Exposure) – Exposure uncertainty variable or Exposure

  • impf_unc (climada.engine.uncertainty.UncVar or climada.entity.ImpactFuncSet) – Impactfunction uncertainty variable or Impact function

  • haz_unc (climada.engine.uncertainty.UncVar or climada.hazard.Hazard) – Hazard uncertainty variable or Hazard

calc_distribution(rp=None, calc_eai_exp=False, calc_at_event=False, pool=None)[source]

Computes the impact for each of the parameters set defined in uncertainty.samples.

By default, the aggregated average annual impact (impact.aai_agg) and the excees impact at return periods rp (imppact.calc_freq_curve(self.rp).impact) is computed. Optionally, eai_exp and at_event is computed (this may require a larger amount of memory if n_samples and/or the number of centroids is large).

This sets the attributes self.rp, self.calc_eai_exp, self.calc_at_event, self.metrics.

Parameters

  • rp (list(int), optional) – Return periods in years to be computed. The default is [5, 10, 20, 50, 100, 250].

  • calc_eai_exp (boolean, optional) – Toggle computation of the impact at each centroid location. The default is False.

  • calc_at_event (boolean, optional) – Toggle computation of the impact for each event. The default is False.

  • pool (pathos.pools.ProcessPool, optional) – Pool of CPUs for parralel computations. Default is None. The default is None.

Raises

ValueError: – If no sampling parameters defined, the distribution cannot be computed.

plot_rp_distribution(figsize=(8, 6))[source]

Plot the distribution of return period values.

Parameters

figsize (tuple(int or float, int or float), optional) – The figsize argument of matplotlib.pyplot.subplots() The default is (8, 6)

Raises

ValueError – If no metric distribution was computed the plot cannot be made.

Returns

ax – The axis handle of the plot.

Return type

matplotlib.pyplot.axes

plot_sensitivity_map(exp, salib_si='S1', figsize=(8, 6))[source]

Plot a map of the largest sensitivity index in each exposure point

Parameters

  • exp (climada.exposure) – The exposure from which to take the coordinates

  • salib_si (str, optional) – The name of the sensitivity index to plot. The default is ‘S1’.

  • figsize (tuple(int or float, int or float), optional) – The figsize argument of matplotlib.pyplot.subplots() The default is (8, 6)

Raises

ValueError – If no sensitivity data is found, raise error.

Returns

ax – The axis handle of the plot.

Return type

matplotlib.pyplot.axes

climada.engine.uncertainty.unc_robustness module

class climada.engine.uncertainty.unc_robustness.UncRobustness[source]

Bases: object

Compute variance from multiplicative Gaussian noise

__init__()[source]

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