easyvvuq.analysis package¶
Submodules¶
easyvvuq.analysis.base module¶
Provides a base class for all analysis elements.
- class easyvvuq.analysis.base.BaseAnalysisElement[source]¶
Bases:
BaseElement
Base class for all EasyVVUQ analysis elements.
- analyse(data_frame=None)[source]¶
Perform analysis on input data_frame.
- Parameters:
data_frame (pandas DataFrame) – Input data for analysis.
- Return type:
AnalysisResults instance
- element_category()[source]¶
Element type for logging and verification.
- Returns:
Element category.
- 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)[source]¶
Bases:
BaseAnalysisElement
- analyse(data_frame=None)[source]¶
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
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')[source]¶
Bases:
BaseAnalysisElement
- analyse(data_frame=None)[source]¶
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
- 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)[source]¶
Bases:
BaseAnalysisElement
- analyse(data_frame=None)[source]¶
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
- easyvvuq.analysis.ensemble_boot.bootstrap(data, stat_func, alpha=0.05, sample_size=None, n_samples=1000, pivotal=False)[source]¶
- 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)[source]¶
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')[source]¶
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)[source]¶
Bases:
BaseAnalysisElement
- analyse(data_frame=None)[source]¶
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:
- class easyvvuq.analysis.fd_analysis.PCEAnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)[source]¶
Bases:
QMCAnalysisResults
Analysis results for the FDAnalysis class.
- get_distribution(qoi)[source]¶
Returns a distribution for the given qoi.
- Parameters:
qoi (str) – QoI name
- Return type:
A ChaosPy PDF
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)[source]¶
Bases:
BaseAnalysisElement
- analyse(data_frame=None)[source]¶
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)[source]¶
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.
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)[source]¶
Bases:
BaseAnalysisElement
The analysis part of the MCMC method in EasyVVUQ
- Parameters:
sampler (MCMCSampler) – An instance of MCMCSampler used to generate MCMC samples.
- class easyvvuq.analysis.mcmc.MCMCAnalysisResults(chains)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Bases:
BaseAnalysisElement
- analyse(data_frame=None)[source]¶
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:
- class easyvvuq.analysis.pce_analysis.PCEAnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)[source]¶
Bases:
QMCAnalysisResults
Analysis results for the PCEAnalysis class.
- get_distribution(qoi)[source]¶
Returns a distribution for the given qoi.
- Parameters:
qoi (str) – QoI name
- Return type:
A ChaosPy PDF
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)[source]¶
Bases:
BaseAnalysisElement
- analyse(data_frame)[source]¶
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)[source]¶
Checks if
None
ornumpy.nan
exists in values. ReturnsTrue
if any there are at least one occurrence ofNone
ornumpy.nan
. :Parameters: values (array_like, list, number) – values where to check for occurrences ofNone
ornp.nan
.Can be irregular and have any number of nested elements.
- Returns:
True
if values has at least one occurrence ofNone
ornumpy.nan
.- Return type:
bool
- create_mask(samples)[source]¶
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.
- get_samples(data_frame)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Bases:
AnalysisResults
Analysis results for the QMCAnalysis Method. Refer to the AnalysisResults base class documentation for details on using it.
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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()[source]¶
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()[source]¶
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)[source]¶
Bases:
BaseAnalysisElement
- SC2PCE(samples, qoi, verbose=True, **kwargs)[source]¶
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)[source]¶
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()[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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’
——-
- generalized_pce_coefs(l_norm, pce_coefs, comb_coef)[source]¶
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_moments(qoi)[source]¶
- 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)[source]¶
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)[source]¶
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)[source]¶
- Parameters:
qoi (str) – name of quantity of interest
- Return type:
array of all samples of qoi
- get_sobol_indices(qoi, typ='first_order')[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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_stat_convergence()[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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
- class easyvvuq.analysis.sc_analysis.SCAnalysisResults(raw_data=None, samples=None, qois=None, inputs=None)[source]¶
Bases:
AnalysisResults
- easyvvuq.analysis.sc_analysis.lagrange_poly(x, x_i, j)[source]¶
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)[source]¶
Taken from: https://docs.python.org/3/library/itertools.html#recipes
- Parameters:
iterable (iterable) – Input sequence
easyvvuq.analysis.ssc_analysis module¶
ANALYSIS CLASS FOR THE SSC SAMPLER
- class easyvvuq.analysis.ssc_analysis.SSCAnalysis(sampler=None, qoi_cols=None)[source]¶
Bases:
BaseAnalysisElement
SSc analysis class.
- adapt_locally(n_new_samples=1)[source]¶
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)[source]¶
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
- get_moments(qoi, n_mc)[source]¶
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)[source]¶
- Parameters:
qoi (str) – name of quantity of interest
- Return type:
array of all samples of qoi
- load_samples(data_frame)[source]¶
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)[source]¶
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()[source]¶
Plot the 1D or 2D sampling plan and color code the simplices according to their polynomial order.
- Return type:
None.
- save_state(filename)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Bases:
AnalysisResults