climada.engine.unsequa package

climada.engine.unsequa.calc_base module

class climada.engine.unsequa.calc_base.Calc

Bases: object

Base class for uncertainty quantification

Contains the generic sampling and sensitivity methods. For computing the uncertainty distribution for specific CLIMADA outputs see the subclass CalcImpact and CalcCostBenefit.

__init__()

Empty constructor to be overwritten by subclasses

check_distr()

Log warning if input parameters repeated among input variables

Return type

True.

property input_vars

Uncertainty variables

Returns

All uncertainty variables associated with the calculation

Return type

tuple(UncVar)

property distr_dict

Dictionary of the input variable distribution

Probabilitiy density distribution of all the parameters of all the uncertainty variables listed in self.InputVars

Returns

distr_dict – Dictionary of all probability density distributions.

Return type

dict( sp.stats objects )

est_comp_time(n_samples, time_one_run, pool=None)

Estimate the computation time

Parameters

• n_samples (int/float) – The total number of samples

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

Return type

Estimated computation time in secs.

make_sample(N, sampling_method='saltelli', sampling_kwargs=None)

Make samples of the input variables

For all input parameters, sample from their respective distributions using the chosen sampling_method from SALib. https://salib.readthedocs.io/en/latest/api.html

This sets the attributes unc_output.samples_df, unc_output.sampling_method, unc_output.sampling_kwargs.

Parameters

• N (int) – Number of samples as used in the sampling method from SALib

• sampling_method (str, optional) – 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 (kwargs, optional) – Optional keyword arguments passed on to the SALib sampling_method. The default is None.

Returns

unc_output – Uncertainty data object with the samples

Return type

climada.engine.uncertainty.unc_output.UncOutput()

See also

SALib.sample

sampling methods from SALib SALib.sample

https

//salib.readthedocs.io/en/latest/api.html

sensitivity(unc_output, sensitivity_method='sobol', sensitivity_kwargs=None)

Compute the sensitivity indices using SALib.

Prior to doing the sensitivity analysis, one must compute the uncertainty (distribution) of the output values (with self.uncertainty()) for all the 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.

This sets the attributes: sens_output.sensistivity_method sens_output.sensitivity_kwargs sens_output.xxx_sens_df for each metric unc_output.xxx_unc_df

Parameters

• unc_output (climada.engine.uncertainty.unc_output.UncOutput()) – Uncertainty data object in which to store the sensitivity indices

• sensitivity_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

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

Returns

sens_output – Uncertainty data object with all the sensitivity indices, and all the uncertainty data copied over from unc_output.

Return type

climada.engine.uncertainty.unc_output.UncOutput()

climada.engine.unsequa.calc_cost_benefit module

class climada.engine.unsequa.calc_cost_benefit.CalcCostBenefit(haz_input_var, ent_input_var, haz_fut_input_var=None, ent_fut_input_var=None)

Bases: climada.engine.unsequa.calc_base.Calc

Cost Benefit uncertainty analysis class

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

metric_names

Names of the cost benefit output metris (‘tot_climate_risk’, ‘benefit’, ‘cost_ben_ratio’,

‘imp_meas_present’, ‘imp_meas_future’)

Type

tuple(str)

value_unit

Unit of the exposures value

Type

str

input_var_names

Names of the required uncertainty variables (‘haz_input_var’, ‘ent_input_var’, ‘haz_fut_input_var’, ‘ent_fut_input_var’)

Type

tuple(str)

haz_input_var

Present Hazard uncertainty variable

Type

climada.engine.uncertainty.input_var.InputVar

ent_input_var

Present Entity uncertainty variable

Type

climada.engine.uncertainty.input_var.InputVar

haz_unc_fut_Var

Future Hazard uncertainty variable

Type

climada.engine.uncertainty.input_var.InputVar

ent_fut_input_var

Future Entity uncertainty variable

Type

climada.engine.uncertainty.input_var.InputVar

__init__(haz_input_var, ent_input_var, haz_fut_input_var=None, ent_fut_input_var=None)

Initialize UncCalcCostBenefit

Sets the uncertainty input variables, the cost benefit metric_names, and the units.

Parameters

• haz_input_var (climada.engine.uncertainty.input_var.InputVar) – or climada.hazard.Hazard Hazard uncertainty variable or Hazard for the present Hazard in climada.engine.CostBenefit.calc

• ent_input_var (climada.engine.uncertainty.input_var.InputVar) – or climada.entity.Entity Entity uncertainty variable or Entity for the present Entity in climada.engine.CostBenefit.calc

• haz_fut_input_var (climada.engine.uncertainty.input_var.InputVar) – or climada.hazard.Hazard, optional Hazard uncertainty variable or Hazard for the future Hazard The Default is None.

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

uncertainty(unc_data, pool=None, **cost_benefit_kwargs)

Computes the cost benefit for each sample in unc_output.sample_df.

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

This sets the attributes: unc_output.imp_meas_present_unc_df, unc_output.imp_meas_future_unc_df unc_output.tot_climate_risk_unc_df unc_output.benefit_unc_df unc_output.cost_ben_ratio_unc_df unc_output.unit unc_output.cost_benefit_kwargs

Parameters

• unc_data (climada.engine.uncertainty.unc_output.UncOutput) – Uncertainty data object with the input parameters samples

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

• cost_benefit_kwargs (keyword arguments) – Keyword arguments passed on to climada.engine.CostBenefit.calc()

Returns

unc_output – Uncertainty data object in with the cost benefit outputs for each sample and all the sample data copied over from unc_sample.

Return type

climada.engine.uncertainty.unc_output.UncCostBenefitOutput

Raises

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

See also

climada.engine.cost_benefit

Compute risk and adptation option cost benefits.

climada.engine.unsequa.calc_impact module

class climada.engine.unsequa.calc_impact.CalcImpact(exp_input_var, impf_input_var, haz_input_var)

Bases: climada.engine.unsequa.calc_base.Calc

Impact uncertainty caclulation class.

This is the 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

metric_names

Names of the impact output metris (‘aai_agg’, ‘freq_curve’, ‘at_event’, ‘eai_exp’, ‘tot_value’)

Type

tuple(str)

value_unit

Unit of the exposures value

Type

str

input_var_names

Names of the required uncertainty input variables (‘exp_input_var’, ‘impf_input_var’, ‘haz_input_var’)

Type

tuple(str)

exp_input_var

Exposure uncertainty variable

Type

climada.engine.uncertainty.input_var.InputVar

impf_input_var

Impact function set uncertainty variable

Type

climada.engine.uncertainty.input_var.InputVar

haz_input_var

Hazard uncertainty variable

Type

climada.engine.uncertainty.input_var.InputVar

__init__(exp_input_var, impf_input_var, haz_input_var)

Initialize UncCalcImpact

Sets the uncertainty input variables, the impact metric_names, and the units.

Parameters

• exp_input_var (climada.engine.uncertainty.input_var.InputVar or climada.entity.Exposure) – Exposure uncertainty variable or Exposure

• impf_input_var (climada.engine.uncertainty.input_var.InputVar or climada.entity.ImpactFuncSet) – Impact function set uncertainty variable or Impact function set

• haz_input_var (climada.engine.uncertainty.input_var.InputVar or climada.hazard.Hazard) – Hazard uncertainty variable or Hazard

uncertainty(unc_sample, rp=None, calc_eai_exp=False, calc_at_event=False, pool=None)

Computes the impact for each sample in unc_data.sample_df.

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 the number of samples and/or the number of centroids and/or exposures points is large).

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

This sets the attributes: unc_output.aai_agg_unc_df, unc_output.freq_curve_unc_df unc_output.eai_exp_unc_df unc_output.at_event_unc_df unc_output.tot_value_unc_df unc_output.unit

Parameters

• unc_sample (climada.engine.uncertainty.unc_output.UncOutput) – Uncertainty data object with the input parameters samples

• 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. The default is None.

Returns

unc_output – Uncertainty data object with the impact outputs for each sample and all the sample data copied over from unc_sample.

Return type

climada.engine.uncertainty.unc_output.UncImpactOutput

Raises

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

See also

climada.engine.impact

Compute risk.

climada.engine.unsequa.input_var module

class climada.engine.unsequa.input_var.InputVar(func, distr_dict)

Bases: object

Input variable for the uncertainty analysis

An uncertainty input variable requires a single or multi-parameter function. The parameters must follow a given distribution. The uncertainty input variables are the input parameters of the model.

distr_dict

Distribution of the uncertainty parameters. Keys are uncertainty parameters names and Values are probability density distribution from the 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

func

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

Type

function

Notes

A few default Variables are defined for Hazards, Exposures, Impact Fucntions, Measures and Entities.

Examples

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

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

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

distr_dict = {

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

iv_cat = InputVar(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) }

iv_cont = InputVar(func=imp_fun_tc, distr_dict=distr_dict)

__init__(func, distr_dict)

Initialize InputVar

Parameters

• 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 func function. The distribution must be of type scipy.stats https://docs.scipy.org/doc/scipy/reference/stats.html

evaluate(**params)

Return the value of uncertainty input variable.

By default, the value of the average is returned.

Parameters

**params (optional) – Input parameters will be passed to self.InputVar_func.

Returns

unc_func(**params) – Output of the uncertainty variable.

Return type

climada object

plot(figsize=None)

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_inputvar(var)

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

Parameters

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

Returns

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

Return type

InputVar

static haz(haz, n_ev=None, bounds_int=None, bounds_freq=None)

Helper wrapper for basic hazard uncertainty input variable

The following types of uncertainties can be added: HE: sub-sampling events from the total event set

For each sub-sample, n_ev events are sampled with replacement. HE is the value of the seed for the uniform random number generator.

HI: scale the intensity of all events (homogeneously)

The instensity of all events is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_int

HF: scale the frequency of all events (homogeneously)

The frequency of all events is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_freq

If a bounds is None, this parameter is assumed to have no uncertainty.

Parameters

• haz (climada.hazard.Hazard) – The base hazard

• n_ev (int, optional) – Number of events to be subsampled per sample. Can be equal or larger than haz.size. The default is None.

• bounds_int ((float, float), optional) – Bounds of the uniform distribution for the homogeneous intensity scaling. The default is None.

• bounds_freq ((float, float), optional) – Bounds of the uniform distribution for the homogeneous frequency scaling. The default is None.

Returns

Uncertainty input variable for a hazard object.

Return type

climada.engine.unsequa.input_var.InputVar

static exp(exp_list, bounds_totval=None, bounds_noise=None)

Helper wrapper for basic exposure uncertainty input variable

The following types of uncertainties can be added: ET: scale the total value (homogeneously)

The value at each exposure point is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_totvalue

EN: mutliplicative noise (inhomogeneous)

The value of each exposure point is independently multiplied by a random number sampled uniformly from a distribution with (min, max) = bounds_noise. EN is the value of the seed for the uniform random number generator.

EL: sample uniformly from exposure list

From the provided list of exposure is elements are uniformly sampled. For example, LitPop instances with different exponents.

If a bounds is None, this parameter is assumed to have no uncertainty.

Parameters

• exp_list (list of climada.entity.exposures.Exposures) – The list of base exposure. Can be one or many to uniformly sample from.

• bounds_totval ((float, float), optional) – Bounds of the uniform distribution for the homogeneous total value scaling.. The default is None.

• bounds_noise ((float, float), optional) – Bounds of the uniform distribution to scale each exposure point independently. The default is None.

Returns

Uncertainty input variable for an exposure object.

Return type

climada.engine.unsequa.input_var.InputVar

static impfset(impf_set, haz_id_dict=None, bounds_mdd=None, bounds_paa=None, bounds_impfi=None)

Helper wrapper for basic impact function set uncertainty input variable.

One impact function (chosen with haz_type and fun_id) is characterized.

The following types of uncertainties can be added: MDD: scale the mdd (homogeneously)

The value of mdd at each intensity is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_mdd

PAA: scale the paa (homogeneously)

The value of paa at each intensity is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_paa

IFi: shift the intensity (homogeneously)

The value intensity are all summed with a random number sampled uniformly from a distribution with (min, max) = bounds_int

If a bounds is None, this parameter is assumed to have no uncertainty.

Parameters

• impf_set (climada.entity.impact_funcs.impact_func_set.ImpactFuncSet) – The base impact function set.

• bounds_mdd ((float, float), optional) – Bounds of the uniform distribution for the homogeneous mdd scaling. The default is None.

• bounds_paa ((float, float), optional) – Bounds of the uniform distribution for the homogeneous paa scaling. The default is None.

• bounds_impfi ((float, float), optional) – Bounds of the uniform distribution for the homogeneous shift of intensity. The default is None.

• haz_id_dict (dict(), optional) – Dictionary of the impact functions affected by uncertainty. Keys are hazard types (str), values are a list of impact function id (int). Default is impsf_set.get_ids() i.e. all impact functions in the set

Returns

Uncertainty input variable for an impact function set object.

Return type

climada.engine.unsequa.input_var.InputVar

static ent(impf_set, disc_rate, exp_list, meas_set, haz_id_dict, bounds_disc=None, bounds_cost=None, bounds_totval=None, bounds_noise=None, bounds_mdd=None, bounds_paa=None, bounds_impfi=None)

Helper wrapper for basic entity set uncertainty input variable.

Important: only the impact function defined by haz_type and fun_id will be affected by bounds_impfi, bounds_mdd, bounds_paa.

The following types of uncertainties can be added: DR: value of constant discount rate (homogeneously)

The value of the discounts in each year is sampled uniformly from a distribution with (min, max) = bounds_disc

CO: scale the cost (homogeneously)

The cost of all measures is multiplied by the same number sampled uniformly from a distribution with (min, max) = bounds_cost

ET: scale the total value (homogeneously)

The value at each exposure point is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_totval

EN: mutliplicative noise (inhomogeneous)

The value of each exposure point is independently multiplied by a random number sampled uniformly from a distribution with (min, max) = bounds_noise. EN is the value of the seed for the uniform random number generator.

EL: sample uniformly from exposure list

From the provided list of exposure is elements are uniformly sampled. For example, LitPop instances with different exponents.

MDD: scale the mdd (homogeneously)

The value of mdd at each intensity is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_mdd

PAA: scale the paa (homogeneously)

The value of paa at each intensity is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_paa

IFi: shift the intensity (homogeneously)

The value intensity are all summed with a random number sampled uniformly from a distribution with (min, max) = bounds_int

If a bounds is None, this parameter is assumed to have no uncertainty.

Parameters

• bounds_disk ((float, float), optional) – Bounds of the uniform distribution for the homogeneous discount rate scaling. The default is None.

• bounds_cost ((float, float), optional) – Bounds of the uniform distribution for the homogeneous cost of all measures scaling. The default is None.

• bounds_totval ((float, float), optional) – Bounds of the uniform distribution for the homogeneous total exposure value scaling. The default is None.

• bounds_noise ((float, float), optional) – Bounds of the uniform distribution to scale each exposure point independently. The default is None.

• bounds_mdd ((float, float), optional) – Bounds of the uniform distribution for the homogeneous mdd scaling. The default is None.

• bounds_paa ((float, float), optional) – Bounds of the uniform distribution for the homogeneous paa scaling. The default is None.

• bounds_impfi ((float, float), optional) – Bounds of the uniform distribution for the homogeneous shift of intensity. The default is None.

• impf_set (climada.engine.impact_funcs.impact_func_set.ImpactFuncSet) – The base impact function set.

• disc_rate (climada.entity.disc_rates.base.DiscRates) – The base discount rates.

• exp_list ([climada.entity.exposures.base.Exposure]) – The list of base exposure. Can be one or many to uniformly sample from.

• meas_set (climada.entity.measures.measure_set.MeasureSet) – The base measures.

• haz_id_dict (dict) – Dictionary of the impact functions affected by uncertainty. Keys are hazard types (str), values are a list of impact function id (int).

Returns

Entity uncertainty input variable

Return type

climada.engine.unsequa.input_var.InputVar

static entfut(impf_set, exp_list, meas_set, haz_id_dict, bounds_cost=None, bounds_eg=None, bounds_noise=None, bounds_impfi=None, bounds_mdd=None, bounds_paa=None)

Helper wrapper for basic future entity set uncertainty input variable.

Important: only the impact function defined by haz_type and fun_id will be affected by bounds_impfi, bounds_mdd, bounds_paa.

The following types of uncertainties can be added: CO: scale the cost (homogeneously)

The cost of all measures is multiplied by the same number sampled uniformly from a distribution with (min, max) = bounds_cost

EG: scale the exposures growth (homogeneously)

The value at each exposure point is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_eg

EN: mutliplicative noise (inhomogeneous)

The value of each exposure point is independently multiplied by a random number sampled uniformly from a distribution with (min, max) = bounds_noise. EN is the value of the seed for the uniform random number generator.

EL: sample uniformly from exposure list

From the provided list of exposure is elements are uniformly sampled. For example, LitPop instances with different exponents.

MDD: scale the mdd (homogeneously)

The value of mdd at each intensity is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_mdd

PAA: scale the paa (homogeneously)

The value of paa at each intensity is multiplied by a number sampled uniformly from a distribution with (min, max) = bounds_paa

IFi: shift the impact function intensity (homogeneously)

The value intensity are all summed with a random number sampled uniformly from a distribution with (min, max) = bounds_impfi

If a bounds is None, this parameter is assumed to have no uncertainty.

Parameters

• bounds_cost ((float, float), optional) – Bounds of the uniform distribution for the homogeneous cost of all measures scaling. The default is None.

• bounds_eg ((float, float), optional) – Bounds of the uniform distribution for the homogeneous total exposure growth scaling. The default is None.

• bounds_noise ((float, float), optional) – Bounds of the uniform distribution to scale each exposure point independently. The default is None.

• bounds_mdd ((float, float), optional) – Bounds of the uniform distribution for the homogeneous mdd scaling. The default is None.

• bounds_paa ((float, float), optional) – Bounds of the uniform distribution for the homogeneous paa scaling. The default is None.

• bounds_impfi ((float, float), optional) – Bounds of the uniform distribution for the homogeneous shift of intensity. The default is None.

• impf_set (climada.engine.impact_funcs.impact_func_set.ImpactFuncSet) – The base impact function set.

• exp_list ([climada.entity.exposures.base.Exposure]) – The list of base exposure. Can be one or many to uniformly sample from.

• meas_set (climada.entity.measures.measure_set.MeasureSet) – The base measures.

• haz_id_dict (dict) – Dictionary of the impact functions affected by uncertainty. Keys are hazard types (str), values are a list of impact function id (int).

Returns

Entity uncertainty input variable

Return type

climada.engine.unsequa.input_var.InputVar

climada.engine.unsequa.unc_output module

class climada.engine.unsequa.unc_output.UncOutput(samples_df, unit=None)

Bases: object

Class to store and plot uncertainty and sensitivity analysis output data

This is the base class to store uncertainty and sensitivity outputs of an analysis done on climada.engine.impact.Impact() or climada.engine.costbenefit.CostBenefit() object.

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_dict of all input variables. 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

__init__(samples_df, unit=None)

Initialize Uncertainty Data object.

Parameters

• samples_df (pandas.DataFrame) – input parameters samples

• unit (str, optional) – value unit

get_samples_df()

get_unc_df(metric_name)

set_unc_df(metric_name, unc_df)

get_sens_df(metric_name)

set_sens_df(metric_name, sens_df)

check_salib(sensitivity_method)

Checks whether the chosen sensitivity method and the sampling method used to generated self.samples_df respect the pairing recommendation by the SALib package.

https://salib.readthedocs.io/en/latest/api.html

Parameters

sensitivity_method (str) – Name of the sensitivity analysis method.

Returns

True if sampling and sensitivity methods respect the recommended pairing.

Return type

bool

property sampling_method

Returns the sampling method used to generate self.samples_df

Returns

Sampling method name

Return type

str

property sampling_kwargs

Returns the kwargs of the sampling method that generate self.samples_df

Returns

Dictionary of arguments for SALib sampling method

Return type

dict

property n_samples

The effective number of samples

Returns

effective number of samples

Return type

int

property param_labels

Labels of all uncertainty input parameters.

Returns

Labels of all uncertainty input parameters.

Return type

list of str

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

Salib problem dictionary.

Return type

dict

property uncertainty_metrics

Retrieve all uncertainty output metrics names

Returns

unc_metric_list – List of names of attributes containing metrics uncertainty values, without the trailing ‘_unc_df’

Return type

[str]

property sensitivity_metrics

Retrieve all sensitivity output metrics names

Returns

sens_metric_list – List of names of attributes containing metrics sensitivity values, without the trailing ‘_sens_df’

Return type

[str]

get_uncertainty(metric_list=None)

Returns uncertainty dataframe with values for each sample

Parameters

metric_list ([str], optional) – List of uncertainty metrics to consider. The default returns all uncertainty metrics at once.

Returns

Joint dataframe of all uncertainty values for all metrics in the metric_list.

Return type

pandas.DataFrame

See also

uncertainty_metrics

list of all available uncertainty metrics

get_sensitivity(salib_si, metric_list=None)

Returns sensitivity index

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 (str) – Sensitivity index

• metric_list ([str], optional) – List of sensitivity metrics to consider. The default returns all sensitivity indices at once.

Returns

Joint dataframe of the sensitvity indices for all metrics in the metric_list

Return type

pandas.DataFrame

See also

sensitvity_metrics

list of all available sensitivity metrics

get_largest_si(salib_si, metric_list=None, threshold=0.01)

Get largest si per metric

Parameters

• salib_si (str) – The name of the sensitivity index to plot.

• metric_list (list of strings, optional) – List of metrics to plot the sensitivity. Default is None.

• threshold (float) – The minimum value a sensitivity index must have to be considered as the largest. The default is 0.01.

Returns

max_si_df – Dataframe with the largest si and its value per metric

Return type

pandas.dataframe

plot_sample(figsize=None)

Plot the sample distributions of the uncertainty input parameters

For each uncertainty input variable, the sample distributions is shown in a separate axes.

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_uncertainty(metric_list=None, orig_list=None, figsize=None, log=False, axes=None)

Plot the uncertainty distribution

For each risk metric, a separate axes is used to plot the uncertainty distribution of the output values obtained over the sampled input parameters.

Parameters

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

• orig_list (list[float], optional) – List of the original (without uncertainty) values for each sub-metric of the mtrics in metric_list. The ordering is identical. 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)

• log (boolean, optional) – Use log10 scale for x axis. Default is False.

• axes (matplotlib.pyplot.axes, optional) – Axes handles to use for the plot. The default is None.

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

See also

uncertainty_metrics

list of all available uncertainty metrics

plot_rp_uncertainty(orig_list=None, figsize=(16, 6), axes=None)

Plot the distribution of return period uncertainty

Parameters

• orig_list (list[float], optional) – List of the original (without uncertainty) values for each sub-metric of the mtrics in metric_list. The ordering is identical. The default is None.

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

• axes (matplotlib.pyplot.axes, optional) – Axes handles to use for the plot. The default is None.

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(salib_si='S1', salib_si_conf='S1_conf', metric_list=None, figsize=None, axes=None, **kwargs)

Bar plot of a first order sensitivity index

For each metric, the sensitivity indices are plotted in a separate axes.

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’].

Note that not all sensitivity indices have a confidence interval.

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. The default is S1.

• salib_si_conf (string, optional) – The confidence value for the first order sensitivity index to plot. The default is S1_conf.

• metric_list (list of strings, optional) – List of metrics to plot the sensitivity. If a metric is not found it is ignored.

• 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)

• axes (matplotlib.pyplot.axes, optional) – Axes handles to use for the plot. The default is None.

• kwargs – Keyword arguments passed on to pandas.DataFrame.plot(kind=’bar’)

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

See also

sensitvity_metrics

list of all available sensitivity metrics

plot_sensitivity_second_order(salib_si='S2', salib_si_conf='S2_conf', metric_list=None, figsize=None, axes=None, **kwargs)

Plot second order sensitivity indices as matrix.

For each metric, the sensitivity indices are plotted in a separate axes.

E.g. For the sensitivity analysis method ‘sobol’, the choices are [‘S2’, ‘S2_conf’].

Note that not all sensitivity indices have a confidence interval.

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

Parameters

• salib_si (string, optional) – The second order sensitivity indexto plot. The default is S2.

• salib_si_conf (string, optional) – The confidence value for thesensitivity index salib_si to plot. The default is S2_conf.

• metric_list (list of strings, optional) – List of metrics to plot the sensitivity. If a metric is not found it is ignored. Default is all 1D metrics.

• 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 * 5, nrows * 5)

• axes (matplotlib.pyplot.axes, optional) – Axes handles to use for the plot. The default is None.

• kwargs – Keyword arguments passed on to matplotlib.pyplot.imshow()

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

See also

sensitvity_metrics

list of all available sensitivity metrics

plot_sensitivity_map(salib_si='S1', **kwargs)

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

Requires the uncertainty distribution for eai_exp.

Parameters

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

• kwargs – Keyword arguments passed on to climada.util.plot.geo_scatter_categorical

Raises

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

Returns

ax – The axis handle of the plot.

Return type

matplotlib.pyplot.axes

See also

climada.util.plot.geo_scatter_categorical

geographical plot for categorical variable

to_hdf5(filename=None)

Save output to .hdf5

Parameters

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

Returns

save_path – Path to the saved file

Return type

pathlib.Path

static from_hdf5(filename)

Load a uncertainty and uncertainty output data from .hdf5 file

Parameters

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

Returns

unc_output – Uncertainty and sensitivity data loaded from .hdf5 file.

Return type

climada.engine.uncertainty.unc_output.UncOutput

class climada.engine.unsequa.unc_output.UncCostBenefitOutput(samples_df, unit, imp_meas_present_unc_df, imp_meas_future_unc_df, tot_climate_risk_unc_df, benefit_unc_df, cost_ben_ratio_unc_df, cost_benefit_kwargs)

Bases: climada.engine.unsequa.unc_output.UncOutput

Extension of UncOutput specific for CalcCostBenefit, returned by the uncertainty() method.

__init__(samples_df, unit, imp_meas_present_unc_df, imp_meas_future_unc_df, tot_climate_risk_unc_df, benefit_unc_df, cost_ben_ratio_unc_df, cost_benefit_kwargs)

Constructor

Uncertainty output values from cost_benefit.calc for each sample

Parameters

• samples_df (pandas.DataFrame) – input parameters samples

• unit (str) – value unit

• imp_meas_present_unc_df (pandas.DataFrame) – Each row contains the values of imp_meas_present for one sample (row of samples_df)

• imp_meas_future_unc_df (pandas.DataFrame) – Each row contains the values of imp_meas_future for one sample (row of samples_df)

• tot_climate_risk_unc_df (pandas.DataFrame) – Each row contains the values of tot_cliamte_risk for one sample (row of samples_df)

• benefit_unc_df (pandas.DataFrame) – Each row contains the values of benefit for one sample (row of samples_df)

• cost_ben_ratio_unc_df (pandas.DataFrame) – Each row contains the values of cost_ben_ratio for one sample (row of samples_df)

• cost_benefit_kwargs (pandas.DataFrame) – Each row contains the value of cost_benefit for one sample (row of samples_df)

class climada.engine.unsequa.unc_output.UncImpactOutput(samples_df, unit, aai_agg_unc_df, freq_curve_unc_df, eai_exp_unc_df, at_event_unc_df, tot_value_unc_df, coord_df)

Bases: climada.engine.unsequa.unc_output.UncOutput

Extension of UncOutput specific for CalcImpact, returned by the uncertainty() method.

__init__(samples_df, unit, aai_agg_unc_df, freq_curve_unc_df, eai_exp_unc_df, at_event_unc_df, tot_value_unc_df, coord_df)

Constructor

Uncertainty output values from impact.calc for each sample

Parameters

• samples_df (pandas.DataFrame) – input parameters samples

• unit (str) – value unit

• aai_agg_unc_df (pandas.DataFrame) – Each row contains the value of aai_aag for one sample (row of samples_df)

• freq_curve_unc_df (pandas.DataFrame) – Each row contains the values of the impact exceedence frequency curve for one sample (row of samples_df)

• eai_exp_unc_df (pandas.DataFrame) – Each row contains the values of eai_exp for one sample (row of samples_df)

• at_event_unc_df (pandas.DataFrame) – Each row contains the values of at_event for one sample (row of samples_df)

• tot_value_unc_df (pandas.DataFrame) – Each row contains the value of tot_value for one sample (row of samples_df)

• coord_df (pandas.DataFrame) – Coordinates of the exposure