climada.engine.unsequa package

Contents

climada.engine.unsequa package#

climada.engine.unsequa.calc_base module#

class climada.engine.unsequa.calc_base.Calc[source]#

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.

_input_var_names#

Names of the required uncertainty variables.

Type:

tuple(str)

_metric_names#

Names of the output metrics.

Type:

tuple(str)

Notes

Parallelization logics: for computation of the uncertainty users may specify a number N of processes on which to perform the computations in parallel. Since the computation for each individual sample of the input parameters is independent of one another, we implemented a simple distribution on the processes.

  1. The samples are divided in N equal sub-sample chunks

  2. Each chunk of samples is sent as one to a node for processing

Hence, this is equivalent to the user running the computation N times, once for each sub-sample. Note that for each process, all the input variables must be copied once, and hence each parallel process requires roughly the same amount of memory as if a single process would be used.

This approach differs from the usual parallelization strategy (where individual samples are distributed), because each sample requires the entire input data. With this method, copying data between processes is reduced to a minimum.

Parallelization is currently not available for the sensitivity computation, as this requires all samples simoultenaously in the current implementation of the SaLib library.

__init__()[source]#

Empty constructor to be overwritten by subclasses

check_distr()[source]#

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, processes=None)[source]#

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)[source]#

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’, ‘latin’, ‘morris’, ‘dgsm’, ‘fast_sampler’, ‘ff’, ‘finite_diff’,

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

Notes

The ‘ff’ sampling method does not require a value for the N parameter. The inputed N value is hence ignored in the sampling process in the case of this method. The ‘ff’ sampling method requires a number of uncerainty parameters to be a power of 2. The users can generate dummy variables to achieve this requirement. Please refer to https://salib.readthedocs.io/en/latest/api.html for more details.

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)[source]#

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.unsequa.UncOutput) – Uncertainty data object in which to store the sensitivity indices

  • sensitivity_method (str, optional) – Sensitivity analysis method from SALib.analyse. Possible choices: ‘sobol’, ‘fast’, ‘rbd_fast’, ‘morris’, ‘dgsm’, ‘ff’, ‘pawn’, ‘rhdm’, ‘rsa’, ‘discrepancy’, ‘hdmr’. 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.

Notes

The variables ‘Em’,’Term’,’X’,’Y’ are removed from the output of the ‘hdmr’ method to ensure compatibility with unsequa. The ‘Delta’ method is currently not supported.

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.unsequa.UncOutput

climada.engine.unsequa.calc_cost_benefit module#

class climada.engine.unsequa.calc_cost_benefit.CalcCostBenefit(haz_input_var: InputVar | Hazard, ent_input_var: InputVar | Entity, haz_fut_input_var: InputVar | Hazard | None = None, ent_fut_input_var: InputVar | Entity | None = None)[source]#

Bases: Calc

Cost Benefit uncertainty analysis class

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

value_unit#

Unit of the exposures value

Type:

str

haz_input_var#

Present Hazard uncertainty variable

Type:

InputVar or Hazard

ent_input_var#

Present Entity uncertainty variable

Type:

InputVar or Entity

haz_unc_fut_Var#

Future Hazard uncertainty variable

Type:

InputVar or Hazard

ent_fut_input_var#

Future Entity uncertainty variable

Type:

InputVar or Entity

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

_metric_names#

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

‘imp_meas_present’, ‘imp_meas_future’)

Type:

tuple(str)

__init__(haz_input_var: InputVar | Hazard, ent_input_var: InputVar | Entity, haz_fut_input_var: InputVar | Hazard | None = None, ent_fut_input_var: InputVar | Entity | None = None)[source]#

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_sample, processes=1, chunksize=None, **cost_benefit_kwargs)[source]#

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_sample (climada.engine.uncertainty.unc_output.UncOutput) – Uncertainty data object with the input parameters samples

  • processes (int, optional) – Number of CPUs to use for parralel computations. The default is 1 (not parallel)

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

  • chunksize (int, optional) – Size of the sample chunks for parallel processing. Default is equal to the number of samples divided by the number of processes.

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.

Notes

Parallelization logic is described in the base class here Calc

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: InputVar | Exposures, impf_input_var: InputVar | ImpactFuncSet, haz_input_var: InputVar | Hazard)[source]#

Bases: 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

value_unit#

Unit of the exposures value

Type:

str

exp_input_var#

Exposure uncertainty variable

Type:

InputVar or Exposures

impf_input_var#

Impact function set uncertainty variable

Type:

InputVar if ImpactFuncSet

haz_input_var#

Hazard uncertainty variable

Type:

InputVar or Hazard

_input_var_names#

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

Type:

tuple(str)

_metric_names#

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

Type:

tuple(str)

__init__(exp_input_var: InputVar | Exposures, impf_input_var: InputVar | ImpactFuncSet, haz_input_var: InputVar | Hazard)[source]#

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, processes=1, chunksize=None)[source]#

Computes the impact for each sample in unc_data.sample_df.

By default, the aggregated average impact within a period of 1/frequency_unit (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.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.

  • processes (int, optional) – Number of CPUs to use for parralel computations. The default is 1 (not parallel)

  • chunksize (int, optional) – Size of the sample chunks for parallel processing. Default is equal to the number of samples divided by the number of processes.

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.

Notes

Parallelization logic is described in the base class here Calc

See also

climada.engine.impact

compute impact and risk.

climada.engine.unsequa.input_var module#

class climada.engine.unsequa.input_var.InputVar(func: callable, distr_dict: Dict)[source]#

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):
...     intensity = np.linspace(0, 150, num=100)
...     mdd = np.repeat(1, len(intensity))
...     paa = np.array([sigmoid_function(v, G, v_half, vmin, k)
...                     for v in intensity])
...     imp_fun = ImpactFunc(haz_type='TC',
...                          id=_id,
...                          intensity_unit='m/s',
...                          intensity=intensity,
...                          mdd=mdd,
...                          paa=paa)
...     imp_fun.check()
...     impf_set = ImpactFuncSet([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: callable, distr_dict: Dict)[source]#

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)[source]#

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

Returns:

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

Return type:

climada object

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_inputvar(var)[source]#

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_list, n_ev=None, bounds_int=None, bounds_frac=None, bounds_freq=None)[source]#

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

HA: scale the fraction of all events (homogeneously)

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

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

HL: sample uniformly from hazard list

From the provided list of hazard is elements are uniformly sampled. For example, Hazards outputs from dynamical models for different input factors.

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

Parameters:

  • haz (List of climada.hazard.Hazard) – The list of base hazard. Can be one or many to uniformly sample from.

  • 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_frac ((float, float), optional) – Bounds of the uniform distribution for the homogeneous fraction 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)[source]#

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_list, haz_id_dict=None, bounds_mdd=None, bounds_paa=None, bounds_impfi=None)[source]#

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

IL: sample uniformly from impact function set list

From the provided list of impact function sets elements are uniformly sampled. For example, impact functions obtained from different calibration methods.

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

Parameters:

  • impf_set_list (list of ImpactFuncSet) – The list of base impact function set. Can be one or many to uniformly sample from. The impact function ids must identical for all impact function sets.

  • 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_list, 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)[source]#

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

IL: sample uniformly from impact function set list

From the provided list of impact function sets elements are uniformly sampled. For example, impact functions obtained from different calibration methods.

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_list (list of ImpactFuncSet) – The list of base impact function set. Can be one or many to uniformly sample from. The impact function ids must identical for all impact function sets.

  • 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_list, 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)[source]#

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

IL: sample uniformly from impact function set list

From the provided list of impact function sets elements are uniformly sampled. For example, impact functions obtained from different calibration methods.

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_list (list of ImpactFuncSet) – The list of base impact function set. Can be one or many to uniformly sample from. The impact function ids must identical for all impact function sets.

  • 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)[source]#

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)[source]#

Initialize Uncertainty Data object.

Parameters:

  • samples_df (pandas.DataFrame) – input parameters samples

  • unit (str, optional) – value unit

order_samples(by_parameters)[source]#

Function to sort the samples dataframe.

Note: the unc_output.samples_df is ordered inplace.

Parameters:

by_parameters (list[string]) – List of the uncertainty parameters to sort by (ordering in list is kept)

Return type:

None.

get_samples_df()[source]#
get_unc_df(metric_name)[source]#
set_unc_df(metric_name, unc_df)[source]#
get_sens_df(metric_name)[source]#
set_sens_df(metric_name, sens_df)[source]#
check_salib(sensitivity_method)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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, calc_delta=False)[source]#

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.

  • calc_delta (boolean, optional) – Adapt x axis label for CalcDeltaImpact unc_output. Default is False.

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, calc_delta=False)[source]#

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 metrics 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 (16, 6)

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

  • calc_delta (boolean, optional) – Adapt axis labels for CalcDeltaImpact unc_output. Default is False.

Raises:

ValueError – If no metric distribution 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', salib_si_conf='S1_conf', metric_list=None, figsize=None, axes=None, **kwargs)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

Bases: 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)[source]#

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, coord_df)[source]#

Bases: 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, coord_df)[source]#

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)

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

class climada.engine.unsequa.unc_output.UncDeltaImpactOutput(samples_df, unit, aai_agg_unc_df, freq_curve_unc_df, eai_exp_unc_df, at_event_initial_unc_df, at_event_final_unc_df, coord_df)[source]#

Bases: UncOutput

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

__init__(samples_df, unit, aai_agg_unc_df, freq_curve_unc_df, eai_exp_unc_df, at_event_initial_unc_df, at_event_final_unc_df, coord_df)[source]#

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_initial_unc_df (pandas.DataFrame) – Each row contains the values of at_event for one sample (row of samples_df)

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

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

climada.engine.unsequa.calc_delta_climate module#

class climada.engine.unsequa.calc_delta_climate.CalcDeltaImpact(exp_initial_input_var: InputVar | Exposures, impf_initial_input_var: InputVar | ImpactFuncSet, haz_initial_input_var: InputVar | Hazard, exp_final_input_var: InputVar | Exposures, impf_final_input_var: InputVar | ImpactFuncSet, haz_final_input_var: InputVar | Hazard)[source]#

Bases: Calc

Delta Impact uncertainty caclulation class.

This is the class to perform uncertainty analysis on the outputs of a relative change in impact from a (final impact - initial impact) / initial impact. Impact objects are regular climada.engine.impact.Impact() objects. The resulting Delta Impact is a relative change (fraction of the inital impact). The relative change is intuitive to understand in contrast to absolute changes which are hard to understand without knowledge of the absolute initial (baseline) state.

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

value_unit#

Unit of the exposures value

Type:

str

exp_input_var#

Exposure uncertainty variable

Type:

InputVar or Exposures

impf_input_var#

Impact function set uncertainty variable

Type:

InputVar if ImpactFuncSet

haz_input_var#

Hazard uncertainty variable

Type:

InputVar or Hazard

_input_var_names#

Names of the required uncertainty input variables (‘exp_initial_input_var’, ‘impf_initial_input_var’, ‘haz_initial_input_var’,

‘exp_final_input_var’, ‘impf_final_input_var’, ‘haz_final_input_var’’)

Type:

tuple(str)

_metric_names#

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

Type:

tuple(str)

__init__(exp_initial_input_var: InputVar | Exposures, impf_initial_input_var: InputVar | ImpactFuncSet, haz_initial_input_var: InputVar | Hazard, exp_final_input_var: InputVar | Exposures, impf_final_input_var: InputVar | ImpactFuncSet, haz_final_input_var: InputVar | Hazard)[source]#

Initialize UncCalcImpact

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

Parameters:

  • exp_initial_input_var (climada.engine.uncertainty.input_var.InputVar) – or climada.entity.Exposure Exposure uncertainty variable or Exposure of initial state

  • impf_initital_input_var (climada.engine.uncertainty.input_var.InputVar) – or climada.entity.ImpactFuncSet Impact function set uncertainty variable or Impact function set of initial state

  • haz_initial_input_var (climada.engine.uncertainty.input_var.InputVar) – or climada.hazard.Hazard Hazard uncertainty variable or Hazard of initial state

  • exp_final_input_var (climada.engine.uncertainty.input_var.InputVar or) – climada.entity.Exposure Exposure uncertainty variable or Exposure of final state

  • impf_final_input_var (climada.engine.uncertainty.input_var.InputVar or) – climada.entity.ImpactFuncSet Impact function set uncertainty variable or Impact function set of final state

  • haz_final_input_var (climada.engine.uncertainty.input_var.InputVar or) – climada.hazard.Hazard Hazard uncertainty variable or Hazard of final state

uncertainty(unc_sample, rp=None, calc_eai_exp=False, calc_at_event=False, relative_delta=True, processes=1, chunksize=None)[source]#

Computes the differential impact between the reference (initial) and future (final) for each sample in unc_data.sample_df.

By default, the aggregated average impact within a period of 1/frequency_unit (impact.aai_agg) and the excess 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). For all metrics, the impacts are caculated first and the the difference thereof is computed. For example: (impact_final.aai_agg - impact_inital.aai_agg / impact_inital.aai_agg)

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

  • relative_delta (bool, optional) – Normalize delta impacts by past impacts or not. The default is True.

  • processes (int, optional) – Number of CPUs to use for parralel computations. The default is 1 (not parallel)

  • chunksize (int, optional) – Size of the sample chunks for parallel processing. Default is equal to the number of samples divided by the number of processes.

Returns:

unc_output – Uncertainty data object with the delta 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.

Notes

Parallelization logic is described in the base class here Calc

See also

climada.engine.impact

compute impact and risk.

Contents