easyvvuq.analysis package

Submodules

easyvvuq.analysis.base module

Provides a base class for all analysis elements.

class easyvvuq.analysis.base.BaseAnalysisElement

Bases: BaseElement

Base class for all EasyVVUQ analysis elements.

analyse(data_frame=None)

Perform analysis on input data_frame.

Parameters:

data_frame (pandas DataFrame) – Input data for analysis.

Return type:

AnalysisResults instance

element_category()

Element type for logging and verification.

Returns:

Element category.

Return type:

str

element_name()

Name for this element for logging purposes.

Returns:

Element name.

Return type:

str

element_version()

Version of this element for logging purposes.

Returns:

Element version.

Return type:

str

easyvvuq.analysis.basic_stats module

Provides analysis element for basic statistical analysis.

The analysis is based on pandas.DataFrame.describe() function.

class easyvvuq.analysis.basic_stats.BasicStats(groupby=None, qoi_cols=None)

Bases: BaseAnalysisElement

analyse(data_frame=None)

Perform the basis stats analysis on the input data_frame.

Analysis is based on pandas.Dataframe.describe and results in values for: count, mean, std, min, max and 25%, 50% & 75% percentiles for each value in the analysis.

The data_frame is grouped according to self.groupby if specified and analysis is performed on the columns selected in self.qoi_cols if set.

Parameters:

data_frame (pandas.DataFrame) – Summary data produced through collation of simulation output.

Returns:

Basic statistic for selected columns and groupings of data.

Return type:

pandas.DataFrame

element_name()

Name for this element for logging purposes

element_version()

Version of this element for logging purposes

easyvvuq.analysis.ensemble_boot module

Provides analysis element for ensemble bootstrapping analysis.

class easyvvuq.analysis.ensemble_boot.EnsembleBoot(groupby=[], qoi_cols=[], stat_func=<function mean>, alpha=0.05, sample_size=None, n_boot_samples=1000, pivotal=False, stat_name='boot')

Bases: BaseAnalysisElement

analyse(data_frame=None)

Perform bootstrapping analysis on the input data_frame.

The data_frame is grouped according to self.groupby if specified and analysis is performed on the columns selected in self.qoi_cols if set.

Parameters:

data_frame (pandas.DataFrame) – Summary data produced through collation of simulation output.

Returns:

Basic statistic for selected columns and groupings of data.

Return type:

pandas.DataFrame

element_name()

Name for this element for logging purposes

element_version()

Version of this element for logging purposes

class easyvvuq.analysis.ensemble_boot.EnsembleBootMultiple(groupby=[], qoi_cols=[], stat_func=[<function mean>], alpha=0.05, sample_size=None, n_boot_samples=1000, pivotal=False, stat_name=None)

Bases: BaseAnalysisElement

analyse(data_frame=None)

Perform bootstrapping analysis on the input data_frame.

The data_frame is grouped according to self.groupby if specified and analysis is performed on the columns selected in self.qoi_cols if set.

Parameters:

data_frame (pandas.DataFrame) – Summary data produced through collation of simulation output.

Returns:

Basic statistic for selected columns and groupings of data.

Return type:

pandas.DataFrame

element_name()

Name for this element for logging purposes

element_version()

Version of this element for logging purposes

easyvvuq.analysis.ensemble_boot.bootstrap(data, stat_func, alpha=0.05, sample_size=None, n_samples=1000, pivotal=False)

Parameters:

• data (pandas.DataFrame) – Input data to be analysed.

• stat_func (function) – Statistical function to be applied to data for bootstrapping.

• alpha (float) – Produce estimate of 100.0*(1-alpha) confidence interval.

• sample_size (int) – Size of the sample to be drawn from the input data.

• n_samples (int) – Number of times samples are to be drawn from the input data.

• pivotal (bool) – Use the pivotal method? Default to percentile method.

Returns:

• float – Value of the bootstrap statistic

• float – Highest value of the confidence interval

• float – Lowest value of the confidence interval

easyvvuq.analysis.ensemble_boot.confidence_interval(dist, value, alpha, pivotal=False)

Get the bootstrap confidence interval for a given distribution.

Parameters:

• dist – Array containing distribution of bootstrap results.

• value – Value of statistic for which we are calculating error bars.

• alpha – The alpha value for the confidence intervals.

• pivotal – Use the pivotal method? Default to percentile method.

Returns:

• float – Value of the bootstrap statistic

• float – Highest value of the confidence interval

• float – Lowest value of the confidence interval

easyvvuq.analysis.ensemble_boot.ensemble_bootstrap(data, groupby=[], qoi_cols=[], stat_func=<function mean>, alpha=0.05, sample_size=None, n_samples=1000, pivotal=False, stat_name='boot')

Perform bootstrapping analysis on input data.

Parameters:

• data (pandas.DataFrame) – DataFrame to be analysed.

• groupby (list or None) – Columns to use to group the data in analyse method before calculating stats.

• qoi_cols (list or None) – Columns of quantities of interest (for which stats will be calculated).

• stat_func (function) – Statistical function to be applied to data for bootstrapping.

• alpha (float, default=0.05) – Produce estimate of 100.0*(1-alpha) confidence interval.

• sample_size (int) – Size of the sample to be drawn from the input data.

• n_samples (int, default=1000) – Number of times samples are to be drawn from the input data.

• pivotal (bool, default=False) – Use the pivotal method? Default to percentile method.

• stat_name (str, default=’boot’) – Name to use to describe columns containing output statistic (for example ‘mean’).

Returns:

Description of input data using bootstrap statistic and high/low confidence intervals.

Return type:

pandas.DataFrame

easyvvuq.analysis.fd_analysis module

Analysis element for polynomial chaos expansion (PCE). We use ChaosPy under the hood for this functionality.

class easyvvuq.analysis.fd_analysis.FDAnalysis(sampler=None, qoi_cols=None)

Bases: BaseAnalysisElement

analyse(data_frame=None)

Perform PCE analysis on input data_frame.

Parameters:

data_frame (pandas DataFrame) – Input data for analysis.

Returns:

Use it to get the sobol indices and other information.

Return type:

PCEAnalysisResults

element_name()

Name for this element for logging purposes.

Returns:

“FD_Analysis”

Return type:

str

element_version()

Version of this element for logging purposes.

Returns:

Element version.

Return type:

str

class easyvvuq.analysis.fd_analysis.PCEAnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)

Bases: QMCAnalysisResults

Analysis results for the FDAnalysis class.

get_distribution(qoi)

Returns a distribution for the given qoi.

Parameters:

qoi (str) – QoI name

Return type:

A ChaosPy PDF

supported_stats()

Types of statistics supported by the describe method.

Return type:

list of str

surrogate()

Return a PCE surrogate model.

Returns:

• A function that takes a dictionary of parameter - value pairs and returns

• a dictionary with the results (same output as decoder).

easyvvuq.analysis.gp_analyse module

Will create a Gaussian Process surrogate of your model. For the sampler you can use the random sampler or the quasi-random sampler. Don’t forget to set the analysis class to GaussianProcessSurrogate as is shown in the example below.

This uses the Gaussian Process model from sklearn.

Examples

>>> campaign = uq.Campaign(name='surrogate')
>>> sampler = uq.sampling.RandomSampler(
    vary = {"Pe": cp.Uniform(100.0, 200.0), "f": cp.Uniform(0.95, 1.05)}
    max_num=100, analysis_class=uq.analysis.GaussianProcessSurrogate)
>>> campaign.add_app(name="sc", params=params, actions=actions)
>>> campaign.set_sampler(sampler)
>>> campaign.execute().collate()
>>> results = campaign.analyse(qoi_cols=output_columns)
>>> surrogate = results.surrogate()
>>> surrogate({'Pe' : 110.0, 'f': 1.0})

class easyvvuq.analysis.gp_analyse.GaussianProcessSurrogate(sampler, qoi_cols, **kwargs)

Bases: BaseAnalysisElement

analyse(data_frame=None)

Construct a Gaussian Process surrogate based on data in data_frame.

Parameters:

• data_frame (pandas.DataFrame) – Data which you want to use to fit the Gaussian Process to.

• kwargs (keyword arguments) – These arguments will be passed to sklearn’s GaussianProcessRegressor. For details on what this could be, please see

Returns:

GaussianProcessSurrogateResults instance. Used to interact with the surrogate model and to possibly access other functionality provided by the fitted model.

Return type:

easyvvuq.analysis.gp.GaussianProcessSurrogateResults

class easyvvuq.analysis.gp_analyse.GaussianProcessSurrogateResults(gp, parameters, qoi)

Bases: AnalysisResults

Gaussian process surrogate results class. You would never create this manually in normal use. It is meant to be returned as the result of GaussianProcessSurrogate analyse method.

Parameters:

• gps (list) – This will be one GP model for each coordinate of a vector QoI.

• parameters (list) – A list of input parameter names.

• qoi (str) – Output variable name.

get_params()

surrogate()

Returns the GP surrogate model as a Python function.

Returns:

Returns a function that takes a dictionary and returns a dictionary. These dictionaries use the same format as Encoder and Decoder used to construct the surrogate.

Return type:

function

easyvvuq.analysis.mcmc module

Analysis element for the Markov Chain Monte Carlo (MCMC) method. For more details on the method see the easyvvuq.sampling.MonteCarloSampler class. The analysis part of Markov Chain Monte Carlo consists of approximating the distribution from the results obtained by evaluating the samples.

class easyvvuq.analysis.mcmc.MCMCAnalysis(sampler)

Bases: BaseAnalysisElement

The analysis part of the MCMC method in EasyVVUQ

Parameters:

sampler (MCMCSampler) – An instance of MCMCSampler used to generate MCMC samples.

analyse(df)

Performs some pre-processing on the chains in order to be able to construct the histograms or other methods of distribution estimation.

Parameters:

df (DataFrame) – DataFrame with the results obtained by evaluating the samples generated by the MCMC sampler.

class easyvvuq.analysis.mcmc.MCMCAnalysisResults(chains)

Bases: AnalysisResults

The analysis results class for MCMC. You will not need to instantiate this class manually.

Parameters:

chains (dict) – A dictionary with pandas DataFrame that correspond to an MCMC chain each. A chain consists of points that MCMC has visited. From this a distribution of the input variables can be constructed by means of a simple histogram.

plot_chains(input_parameter, chain=None)

Will plot the chains with the input parameter value in the y axis.

Parameters:

• input_parameter (str) – Input parameter name.

• chain (int, optional) – The chain number of the chain to plot.

plot_hist(input_parameter, chain=None, skip=0, merge=True)

Will plot a histogram for a given input parameter.

Parameters:

• input_parameter (str) – An input parameter name to draw the histogram for.

• chain (int, optional) – Index of a chain to be plotted.

• skip (int) – How many steps to skip (for getting rid of burn-in).

• merge (bool) – If set to True will use all chains to construct the histogram.

easyvvuq.analysis.pce_analysis module

Analysis element for polynomial chaos expansion (PCE). We use ChaosPy under the hood for this functionality.

class easyvvuq.analysis.pce_analysis.PCEAnalysis(sampler=None, qoi_cols=None, sampling=False, CorrelationMatrices=True, OutputDistributions=True)

Bases: BaseAnalysisElement

analyse(data_frame=None)

Perform PCE analysis on input data_frame.

Parameters:

data_frame (pandas DataFrame) – Input data for analysis.

Returns:

Use it to get the sobol indices and other information.

Return type:

PCEAnalysisResults

element_name()

Name for this element for logging purposes.

Returns:

“PCE_Analysis”

Return type:

str

element_version()

Version of this element for logging purposes.

Returns:

Element version.

Return type:

str

class easyvvuq.analysis.pce_analysis.PCEAnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)

Bases: QMCAnalysisResults

Analysis results for the PCEAnalysis class.

get_distribution(qoi)

Returns a distribution for the given qoi.

Parameters:

qoi (str) – QoI name

Return type:

A ChaosPy PDF

supported_stats()

Types of statistics supported by the describe method.

Return type:

list of str

surrogate()

Return a PCE surrogate model.

Returns:

• A function that takes a dictionary of parameter - value pairs and returns

• a dictionary with the results (same output as decoder).

easyvvuq.analysis.qmc_analysis module

Analysis element for Quasi-Monte Carlo (QMC) sensitivity analysis.

Please refer to the article below for the basic approach used here. https://en.wikipedia.org/wiki/Variance-based_sensitivity_analysis

class easyvvuq.analysis.qmc_analysis.QMCAnalysis(sampler, qoi_cols=None)

Bases: BaseAnalysisElement

analyse(data_frame)

Perform QMC analysis on a given pandas DataFrame.

Parameters:

data_frame (pandas DataFrame) – Input data for analysis.

Returns:

AnalysisResults object for QMC.

Return type:

easyvvuq.analysis.qmc.QMCAnalysisResults

contains_nan(values)

Checks if None or numpy.nan exists in values. Returns True if any there are at least one occurrence of None or numpy.nan. :Parameters: values (array_like, list, number) – values where to check for occurrences of None or np.nan.

Can be irregular and have any number of nested elements.

Returns:

True if values has at least one occurrence of None or numpy.nan.

Return type:

bool

create_mask(samples)

Mask samples that do not give results (anything but np.nan or None). :Parameters: samples (array_like) – Evaluations for the model.

Returns:

• masked_samples (list) – The evaluations that have results (not numpy.nan or None).

• mask (boolean array) – The mask itself, used to create the masked arrays.

element_name()

Name for this element.

Returns:

“QMC_Analysis”

Return type:

str

element_version()

Version of this element.

Returns:

Element version.

Return type:

str

get_samples(data_frame)

Converts the Pandas dataframe into a dictionary.

Parameters:

data_frame (pandas DataFrame) – the EasyVVUQ Pandas dataframe from collation.

Returns:

A dictionary with the QoI names as keys. Each element is a list of code evaluations.

Return type:

dict

sobol_bootstrap(samples, alpha=0.05, n_bootstrap=1000)

Computes the first order and total order Sobol indices using Saltelli’s method. To assess the sampling inaccuracy, bootstrap confidence intervals are also computed.

Reference: A. Saltelli, Making best use of model evaluations to compute sensitivity indices, Computer Physics Communications, 2002.

Parameters:

• samples (list) – The samples for a given QoI.

• alpha (float) – The (1 - alpha) * 100 confidence interval parameter. The default is 0.05.

• n_samples (int) – The number of bootstrap samples. The default is 1000.

Returns:

• sobols_first_dict, conf_first_dict, sobols_total_dict, conf_total_dict

• dictionaries containing the first- and total-order Sobol indices for all

• parameters, and (1-alpha)*100 lower and upper confidence bounds.

sobol_bootstrap_(samples, alpha=0.05, n_samples=1000)

Computes the first order and total order Sobol indices using Saltelli’s method. To assess the sampling inaccuracy, bootstrap confidence intervals are also computed.

Reference: A. Saltelli, Making best use of model evaluations to compute sensitivity indices, Computer Physics Communications, 2002.

Parameters:

• samples (list) – The samples for a given QoI.

• alpha (float) – The (1 - alpha) * 100 confidence interval parameter. The default is 0.05.

• n_samples (int) – The number of bootstrap samples. The default is 1000.

Returns:

• sobols_first_dict, conf_first_dict, sobols_total_dict, conf_total_dict

• dictionaries containing the first- and total-order Sobol indices for all

• parameters, and (1-alpha)*100 lower and upper confidence bounds.

class easyvvuq.analysis.qmc_analysis.QMCAnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)

Bases: AnalysisResults

Analysis results for the QMCAnalysis Method. Refer to the AnalysisResults base class documentation for details on using it.

supported_stats()

Types of statistics supported by the describe method.

Return type:

list of str

easyvvuq.analysis.results module

Represents the results obtained during the analysis stage. All the analysis classes should implement this in a way that makes most sense. Provides a more unified interface for accessing the results in a variety of formats (e.g. NumPy arrays or pandas DataFrames). This module also provides a variety of ways to display results as well as a way to access surrogate functionality.

class easyvvuq.analysis.results.AnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)

Bases: object

Contains the analysis results.

Parameters:

• raw_data (obj) – An arbitrary object that contains raw analysis data.

• samples (pandas DataFrame) – Collated samples.

• qois (list of str) – List of qoi names used during the analysis.

• inputs (list of str) – List of input names used during the analysis.

derivatives_first(qoi=None, input_=None)

Return first order derivative-based sensitivity indices.

Parameters:

• qoi (str or tuple) – The name of the quantity of interest or None. Use a tuple of the form (qoi, index) where index is integer that means the coordinate index of a vector qoi.

• input_ (str) – The name of the input parameter or None.

Examples

>>> results.derivatives_first()
{'f': {'x1': array([0.610242]), 'x2': array([0.26096511])}}
>>> results.derivatives_first('f')
{'x1': array([0.610242]), 'x2': array([0.26096511])}
>>> results.derivatives_first('f', 'x1')
array([0.610242])
>>> results_vectors.derivatives_first(('g', 2))
{'x1': array([0.5]), 'x2': array([0.5])}

Returns:

If both qoi and input_ are specified will return a dictionary, otherwise will return an array.

Return type:

dict or array

describe(qoi=None, statistic=None)

Returns descriptive statistics.

Examples

>>> results.describe()
             g                             h
             0         1         2         0         1
mean  0.500000  0.500000  1.000000  0.250000  0.693787
var   0.083333  0.083333  0.166667  0.048611  0.068236
std   0.288675  0.288675  0.408248  0.220479  0.261220
10%   0.100897  0.099462  0.441589  0.019049  0.276504
90%   0.896960  0.899417  1.544624  0.584600  0.974707
min   0.000041  0.000005  0.016687  0.000016 -0.008642
max   0.999998  0.999873  1.993517  0.985350  1.024599

>>> result.describe('h')
             h
             0         1
mean  0.250000  0.693787
var   0.048611  0.068236
std   0.220479  0.261220
10%   0.019049  0.276504
90%   0.584600  0.974707
min   0.000016 -0.008642
max   0.985350  1.024599

>>> results.describe('h', 'var')
array([0.04861111, 0.06823568])

Parameters:

• qoi (str or None) – if not None it is the name of the quantity of interest

• statistic (str or None) – if not None it is the name of the statistic, currently supported ones are: [‘mean’, ‘var’, ‘std’, ‘10%’, ‘90%’, ‘min’, ‘max’, ‘median’]

Returns:

If both quantity of interest and the statistic are specified will return an array with the values for that statistic. Otherwise will return a DataFrame with more data.

Return type:

DataFrame or array

get_distribution(qoi)

Returns a distribution for the given qoi.

Parameters:

qoi (str) – QoI name

Return type:

A ChaosPy distribution

plot_moments(qoi, ylabel=None, xlabel=None, xvalues=None, alpha=0.2, filename=None, dpi=None, ax=None)

Plot statistical moments for this analysis.

Parameters:

• qoi (str) – a vector quantity of interest for which sobol indices will be plotted

• ylabel (str or None) – if None will use “Values”

• xlabel (str or None) – if None will use the name of the qoi

• xvalues (array or None) – x-axis coordiante if None will use range(len(qoi_values)))

• alpha (float) – transparency amount

• filename (str or None) – if None will try to open a plotting window on-screen, otherwise will write the plot to this file, with the type determined by the extension specified

• dpi (int) – dots per inch, quality of the image if a raster format was chosen

• ax (matplotlib axes object, default None) – if None, plots to a new axes, otherwise plot to existing axes ax

Returns:

the actual axes plotted to

Return type:

matplotlib axes object

plot_sobols_first(qoi, inputs=None, withdots=False, ylabel=None, xlabel=None, xvalues=None, filename=None, dpi=None, ax=None)

Plot first order sobol indices.

Parameters:

• qoi (str) – a vector quantity of interest for which sobol indices will be plotted

• inputs (list of str or None) – list of inputs to plot if None will use all input variables

• withdots (bool) – if True will add shapes on top of the lines in the plot for visual clarity

• ylabel (str or None) – if None will use “First Order Sobol Index”

• xlabel (str or None) – if None will use the name of the qoi

• xvalues (array or None) – x-axis coordiante if None will use range(len(qoi_values))

• filename (str or None) – if None will try to open a plotting window on-screen, otherwise will write the plot to this file, with the type determined by the extension specified

• dpi (int) – dots per inch, quality of the image if a raster format was chosen

• ax (matplotlib axes object, default None) – if None, plots to a new axes, otherwise plot to existing axes ax

Returns:

the actual axes plotted to

Return type:

matplotlib axes object

plot_sobols_treemap(qoi, figsize=(10, 10), ax=None, filename=None, dpi=None)

Plot sobols first and second order indices in a hierarchical treemap format.

Parameters:

• qoi (str) – Name of the quantity of interest.

• figsize (tuple) – A tuple with two integers representing figure size in inches.

• ax (matplotlib) – Matplotlib axis to plot on.

• filename (str) – Filename to write the plot to. If left None will display to screen.

• dpi (int) – Dots per inches. Only used when writing to file.

sobols_first(qoi=None, input_=None)

Return first order sensitivity indices.

Parameters:

• qoi (str or tuple) – The name of the quantity of interest or None. Use a tuple of the form (qoi, index) where index is integer that means the coordinate index of a vector qoi.

• input_ (str) – The name of the input parameter or None.

Examples

>>> results.sobols_first()
{'f': {'x1': array([0.610242]), 'x2': array([0.26096511])}}
>>> results.sobols_first('f')
{'x1': array([0.610242]), 'x2': array([0.26096511])}
>>> results.sobols_first('f', 'x1')
array([0.610242])
>>> results_vectors.sobols_first(('g', 2))
{'x1': array([0.5]), 'x2': array([0.5])}

Returns:

If both qoi and input_ are specified will return a dictionary, otherwise will return an array.

Return type:

dict or array

sobols_second(qoi=None, input_=None)

Return second order sensitivity indices.

Parameters:

• qoi (str or tuple) – The name of the quantity of interest or None. Use a tuple of the form (qoi, index) where index is integer that means the coordinate index of a vector qoi.

• input_ (str) – The name of the input parameter or None.

Examples

>>> results.sobols_second('a')
{'F': {'L': array([0.000121]),
'a': array([0.00695338]),
'D': array([0.00141272])},
'L': {'F': array([0.000121]),
'a': array([0.00012737]),
'D': array([0.00012716])},
'a': {'F': array([0.00695338]),
'L': array([0.00012737]),
'D': array([0.00730415])},
'D': {'F': array([0.00141272]),
'L': array([0.00012716]),
'a': array([0.00730415])}}
>>> results.sobols_second('g1', 'L')
{'F': array([0.000121]), 'a': array([0.00012737]), 'D': array([0.00012716])}

Returns:

Will always return a dictionary unlike first order sobol indices. Because the index is specified by a pair of inputs. The dictionary will include all inputs but input_.

Return type:

dict

sobols_total(qoi=None, input_=None)

Returns total order sensitivity indices.

Parameters:

• qoi (str or tuple) – The name of the quantity of interest or None. Use a tuple of the form (qoi, index) where index is integer that means the coordinate index of a vector qoi.

• input_ (str) – The name of the input parameter or None.

Examples

>>> results.sobols_total('g1')
{'F': array([0.14299044]),
'L': array([0.01247877]),
'a': array([0.7105291]),
'D': array([0.15018883])}
>>> results.sobols_total('g1', 'F')
array([0.14299044])

Returns:

If both qoi and input_ are specified will return a dictionary, otherwise will return an array.

Return type:

dict or array

supported_stats()

Returns a list of descriptive statistics that the method reports.

Examples

>>> results.supported_stats()
['min', 'max', '10%', '90%', '1%', '99%', 'median', 'mean', 'var', 'std']

Returns:

A list of statistics that can then be passed to the describe method.

Return type:

list of str

surrogate()

Returns the surrogate model as a function from parameter dictionary to output dictionary. This only needs to be implemented if the analysis method in question provides surrogate models.

Returns:

Returns a function that takes a dictionary and returns a dictionary. These dictionaries use the same format as Encoder and Decoder used to construct the surrogate.

Return type:

function

easyvvuq.analysis.sc_analysis module

ANALYSIS CLASS FOR THE SC SAMPLER

class easyvvuq.analysis.sc_analysis.SCAnalysis(sampler=None, qoi_cols=None)

Bases: BaseAnalysisElement

SC2PCE(samples, qoi, verbose=True, **kwargs)

Computes the Polynomials Chaos Expansion coefficients from the SC expansion via a transformation of basis (Lagrange polynomials basis –> orthonomial basis).

Parameters:

• samples (array) – SC code samples from which to compute the PCE coefficients

• qoi (string) – Name of the QoI.

Returns:

pce_coefs – PCE coefficients per multi index l

Return type:

dict

adapt_dimension(qoi, data_frame, store_stats_history=True, method='surplus', **kwargs)

Compute the adaptation metric and decide which of the admissible level indices to include in next iteration of the sparse grid. The adaptation metric is based on the hierarchical surplus, defined as the difference between the new code values of the admissible level indices, and the SC surrogate of the previous iteration. Alternatively, it can be based on the difference between the output mean of the current level, and the mean computed with one extra admissible index.

This subroutine must be called AFTER the code is evaluated at the new points, but BEFORE the analysis is performed.

Parameters:

• qoi (string) – the name of the quantity of interest which is used to base the adaptation metric on.

• data_frame (pandas.DataFrame)

• store_stats_history (bool) – store the mean and variance at each refinement in self.mean_history and self.std_history. Used for checking convergence in the statistics over the refinement iterations

• method (string) – name of the refinement error, default is ‘surplus’. In this case the error is based on the hierarchical surplus, which is an interpolation based error. Another possibility is ‘var’, in which case the error is based on the difference in the variance between the current estimate and the estimate obtained when a particular candidate direction is added.

adaptation_histogram()

Plots a bar chart of the maximum order of the quadrature rule that is used in each dimension. Use in case of the dimension adaptive sampler to get an idea of which parameters were more refined than others. This gives only a first-order idea, as it only plots the max quad order independently per input parameter, so higher-order refinements that were made do not show up in the bar chart.

adaptation_table(**kwargs)

Plots a color-coded table of the quadrature-order refinement. Shows in what order the parameters were refined, and unlike adaptation_histogram, this also shows higher-order refinements.

Parameters:

• **kwargs (can contain kwarg ‘order’ to specify the order in which)

• the variables on the x axis are plotted (e.g. in order of decreasing

• 1st order Sobol index).

Return type:

None.

analyse(data_frame=None, compute_moments=True, compute_Sobols=True)

Perform SC analysis on input data_frame.

Parameters:

data_frame (pandas.DataFrame) – Input data for analysis.

Returns:

Results dictionary with sub-dicts with keys: [‘statistical_moments’, ‘sobol_indices’]. Each dict has an entry for each item in qoi_cols.

Return type:

dict

combination_technique(qoi, samples=None, **kwargs)

Efficient quadrature formulation for (sparse) grids. See:

Gerstner, Griebel, “Numerical integration using sparse grids” Uses the general combination technique (page 12).

Parameters:

• qoi (str) – name of the qoi

• samples (array) – compute the mean by setting samples = self.samples. To compute the variance, set samples = (self.samples - mean)**2

compute_comb_coef(**kwargs)

Compute general combination coefficients. These are the coefficients multiplying the tensor products associated to each multi index l, see page 12 Gerstner & Griebel, numerical integration using sparse grids

compute_marginal(qoi, u, u_prime, diff)

Computes a marginal integral of the qoi(x) over the dimension defined by u_prime, for every x value in dimensions u

Parameters:

• - qoi (str) (name of the quantity of interest)

• - u (array of int) (dimensions which are not integrated)

• - u_prime (array of int) (dimensions which are integrated)

• - diff (array of int) (levels)

• Returns

• - Values of the marginal integral

• ——-

static compute_tensor_prod_u(xi, wi, u, u_prime)

Calculate tensor products of weights and collocation points with dimension of u and u’

Parameters:

• xi (array of floats) (1D colloction points)

• wi (array of floats) (1D quadrature weights)

• u (array of int) (dimensions)

• u_prime (array of int) (remaining dimensions (u union u’ = range(N)))

• Returns

• dict of tensor products of weight and points for dimensions u and u’

• ——-

element_name()

Name for this element for logging purposes

element_version()

Version of this element for logging purposes

generalized_pce_coefs(l_norm, pce_coefs, comb_coef)

Computes the generalized PCE coefficients, defined as the linear combibation of PCE coefficients which make it possible to write the dimension-adaptive PCE expansion in standard form. See DOI: 10.13140/RG.2.2.18085.58083/1

Parameters:

• l_norm (array) – array of quadrature order multi indices

• pce_coefs (tuple) – tuple of PCE coefficients computed by SC2PCE subroutine

• comb_coef (tuple) – tuple of combination coefficients computed by compute_comb_coef

Returns:

gen_pce_coefs – The generalized PCE coefficients, indexed per multi index.

Return type:

tuple

get_adaptation_errors()

Returns self.adaptation_errors

get_moments(qoi)

Parameters:

qoi (str) – name of the qoi

Return type:

mean and variance of qoi (float (N_qoi,))

get_pce_sobol_indices(qoi, typ='first_order', **kwargs)

Computes Sobol indices using Polynomials Chaos coefficients. These coefficients are computed from the SC expansion via a transformation of basis (SC2PCE subroutine). This works better than computing the Sobol indices directly from the SC expansion in the case of the dimension-adaptive sampler. See DOI: 10.13140/RG.2.2.18085.58083/1

Method: J.D. Jakeman et al, “Adaptive multi-index collocation for uncertainty quantification and sensitivity analysis”, 2019. (Page 18)

Parameters:

• qoi (str) – name of the Quantity of Interest for which to compute the indices

• typ (str) – Default = ‘first_order’. ‘all’ is also possible

• **kwargs (dict) – if this contains ‘samples’, use these instead of the SC samples ] in the database

Returns:

Mean: PCE mean Var: PCE variance S_u: PCE Sobol indices, either the first order indices or all indices

Return type:

Tuple

get_pce_stats(l_norm, pce_coefs, comb_coef)

Compute the mean and the variance based on the generalized PCE coefficients See DOI: 10.13140/RG.2.2.18085.58083/1

Parameters:

• l_norm (array) – array of quadrature order multi indices

• pce_coefs (tuple) – tuple of PCE coefficients computed by SC2PCE subroutine

• comb_coef (tuple) – tuple of combination coefficients computed by compute_comb_coef

Return type:

mean, variance and generalized pce coefficients

get_sample_array(qoi)

Parameters:

qoi (str) – name of quantity of interest

Return type:

array of all samples of qoi

get_sobol_indices(qoi, typ='first_order')

Computes Sobol indices using Stochastic Collocation. Method: Tang (2009), GLOBAL SENSITIVITY ANALYSIS FOR STOCHASTIC COLLOCATION EXPANSION.

Parameters:

• qoi (str) (name of the Quantity of Interest for which to compute the indices)

• typ (str) (Default = ‘first_order’. ‘all’ is also possible)

Return type:

Either the first order or all Sobol indices of qoi

get_uncertainty_amplification(qoi)

Computes a measure that signifies the ratio of output to input uncertainty. It is computed as the (mean) Coefficient of Variation (V) of the output divided by the (mean) CV of the input.

Parameters:

qoi (string) (name of the Quantity of Interest)

Returns:

blowup (float)

Return type:

the ratio output CV / input CV

load_state(filename)

Loads the complete state of the analysis object from a pickle file, stored using save_state.

Parameters:

filename (string) – name of the file to load

merge_accepted_and_admissible(level=0, **kwargs)

In the case of the dimension-adaptive sampler, there are 2 sets of quadrature multi indices. There are the accepted indices that are actually used in the analysis, and the admissible indices, of which some might move to the accepted set in subsequent iterations. This subroutine merges the two sets of multi indices by moving all admissible to the set of accepted indices. Do this at the end, when no more refinements will be executed. The samples related to the admissble indices are already computed, although not used in the analysis. By executing this subroutine at very end, all computed samples are used during the final postprocessing stage. Execute campaign.apply_analysis to let the new set of indices take effect. If further refinements are executed after all via sampler.look_ahead, the number of new admissible samples to be computed can be very high, especially in high dimensions. It is possible to undo the merge via analysis.undo_merge before new refinements are made. Execute campaign.apply_analysis again to let the old set of indices take effect.

plot_grid()

Plots the collocation points for 2 and 3 dimensional problems

plot_stat_convergence()

Plots the convergence of the statistical mean and std dev over the different refinements in a dimension-adaptive setting. Specifically the inf norm of the difference between the stats of iteration i and iteration i-1 is plotted.

quadrature(qoi, samples=None)

Computes a (Smolyak) quadrature

Parameters:

• qoi (str) – name of the qoi

• samples (array) – compute the mean by setting samples = self.samples. To compute the variance, set samples = (self.samples - mean)**2

Return type:

the quadrature of qoi

save_state(filename)

Saves the complete state of the analysis object to a pickle file, except the sampler object (self.samples).

Parameters:

filename (string) – name to the file to write the state to

sc_expansion(samples, x)

Non recursive implementation of the SC expansion. Performs interpolation of code output samples for both full and sparse grids.

Parameters:

• samples (list) – list of code output samples.

• x (array) – One or more locations in stochastic space at which to evaluate the surrogate.

Returns:

surr – The interpolated values of the code output at input locations specified by x.

Return type:

array

surrogate(qoi, x, L=None)

Use sc_expansion UQP as a surrogate

Parameters:

• qoi (str) – name of the qoi

• x (array) – location at which to evaluate the surrogate

• L (int) – level of the (sparse) grid, default = self.L

Return type:

the interpolated value of qoi at x (float, (N_qoi,))

undo_merge()

This reverses the effect of the merge_accepted_and_admissble subroutine. Execute if further refinement are required after all.

class easyvvuq.analysis.sc_analysis.SCAnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)

Bases: AnalysisResults

supported_stats()

Types of statistics supported by the describe method.

Return type:

list of str

surrogate()

Return an SC surrogate model.

Returns:

• A function that takes a dictionary of parameter - value pairs and returns

• a dictionary with the results (same output as decoder).

easyvvuq.analysis.sc_analysis.lagrange_poly(x, x_i, j)

Lagrange polynomials used for interpolation

l_j(x) = product(x - x_m / x_j - x_m) with 0 <= m <= k

and m !=j

Parameters:

• x (float) – location at which to compute the polynomial

• x_i (list or array of float) – nodes of the Lagrange polynomials

• j (int) – index of node at which l_j(x_j) = 1

Returns:

l_j(x) calculated as shown above.

Return type:

float

easyvvuq.analysis.sc_analysis.powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

Taken from: https://docs.python.org/3/library/itertools.html#recipes

Parameters:

iterable (iterable) – Input sequence

easyvvuq.analysis.sc_analysis.setdiff2d(X, Y)

Computes the difference of two 2D arrays X and Y

Parameters:

• X (2D numpy array)

• Y (2D numpy array)

Return type:

The difference X Y as a 2D array

easyvvuq.analysis.ssc_analysis module

ANALYSIS CLASS FOR THE SSC SAMPLER

class easyvvuq.analysis.ssc_analysis.SSCAnalysis(sampler=None, qoi_cols=None)

Bases: BaseAnalysisElement

SSc analysis class.

adapt_locally(n_new_samples=1)

Locally refine the sampling plan based on the SSC geometric refinement measure.

Parameters:

n_new_samples (int, optional) – The number of new code evaulations to perform. The default is 1.

Returns:

• None. Updates the Delaunay triangulation of the SSC sampler with

• the new points. A new ensemble must be executed next.

analyse(data_frame=None, compute_moments=True, n_mc=20000)

Perform SSC analysis on input data_frame.

Parameters:

• data_frame (pandas.DataFrame) – Input data for analysis.

• compute_moments (bool, optional.) – Compute the first 2 moments. Default is True.

Returns:

results – A dictionary containing the statistical moments.

Return type:

dict

element_name()

Name for this element for logging purposes

element_version()

Version of this element for logging purposes

get_moments(qoi, n_mc)

Compute the mean and variance through Monte Carlo sampling of the SSC surrogate. Independent random inputs samples are drawn though the SSC sampler object.

Parameters:

• qoi (string) – The name of the QoI.

• n_mc (int) – The number of Monte Carlo samples.

Returns:

• mean (array) – The mean of qoi.

• var (array) – The variance of qoi.

get_sample_array(qoi)

Parameters:

qoi (str) – name of quantity of interest

Return type:

array of all samples of qoi

load_samples(data_frame)

Extract output values for each quantity of interest from Dataframe.

Parameters:

data_frame (EasyVVUQ (pandas) data frame) – The code samples from the EasyVVUQ data frame.

Return type:

None.

load_state(filename)

Loads the complete state of the analysis object from a pickle file, stored using save_state.

Parameters:

filename (string) – name of the file to load

plot_grid()

Plot the 1D or 2D sampling plan and color code the simplices according to their polynomial order.

Return type:

None.

save_state(filename)

Saves the complete state of the analysis object to a pickle file, except the sampler object (self.sampler).

Parameters:

filename (string) – name to the file to write the state to

surrogate(qoi, xi)

Evaluate the SSC surrogate at xi.

Parameters:

• qoi (string) – Name of the QoI.

• xi (array, shape (n_xi,)) – The location in the input space at which to evaluate the surrogate.

Returns:

The surrogate output at xi

Return type:

array

update_surrogate(qoi, data_frame, max_LEC_jobs=4, n_mc_LEC=5, max_ENO_jobs=4)

Update the SSC surrogate given new data. Given an EasyVVUQ dataframe, check the LEC condition, and compute the ENO interpolation stencils.

Parameters:

• qoi (string) – The name of the QoI on the basis of which the sampling plan is refined.

• data_frame (EasyVVUQ (pandas) data frame) – The code samples from the EasyVVUQ data frame.

• max_LEC_jobs (int, optional) – The number of LEC checks to perform in parallel. The default is 4.

• n_mc_LEC (int, optional) – The number of surrogate evaluations used in the LEC check. The default is 5.

• max_LEC_jobs (int, optional) – The number of ENO stencils to compute in parallel. The default is 4.

Returns:

• None. Stores the polynomials orders, interpolation stencils and

• the simplex probabilities in analysis.p_j, analysis.S_j and

• analysis.prob_j respectively.

class easyvvuq.analysis.ssc_analysis.SSCAnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)

Bases: AnalysisResults

supported_stats()

Types of statistics supported by the describe method.

Return type:

list of str

surrogate()

Return a SSC surrogate model.

Returns:

• A function that takes a dictionary of parameter - value pairs and returns

• a dictionary with the results (same output as decoder).

Module contents