UncertaintyQuantification¶

The uncertainpy.UncertaintyQuantification class is used to define the problem, perform the uncertainty quantification and sensitivity analysis, and save and visualize the results. UncertaintyQuantification combines the three main components required to perform an uncertainty quantification and sensitivity analysis:

The model we want to examine.

The parameters of the model.

Specifications of features in the model output.

The model and parameters are required components, while the feature specifications are optional.

Among others, UncertaintyQuantification takes the arguments:

UQ = un.UncertaintyQuantification(
        model=Model(...),                        # Required
        parameters=Parameters(...),              # Required
        features=Features(...)                   # Optional
)

The arguments are given as instances of their corresponding Uncertainpy classes (Models, Parameters, and Features).

After the problem is set up, an uncertainty quantification and sensitivity analysis can be performed by using the uncertainpy.UncertaintyQuantification.quantify() method. Among others, quantify takes the optional arguments:

data = UQ.quantify(
    method="pc"|"mc",
    pc_method="collocation"|"spectral",
    rosenblatt=False|True
)

The method argument allows the user to choose whether Uncertainpy should use polynomial chaos expansions ("pc") or quasi-Monte Carlo ("mc") methods to calculate the relevant statistical metrics. If polynomial chaos expansions are chosen, pc_method further specifies whether point collocation ("collocation") or spectral projection ("spectral") methods are used to calculate the expansion coefficients. Finally, rosenblatt (False or True) determines if the Rosenblatt transformation should be used. If nothing is specified, Uncertainpy by default uses polynomial chaos expansions based on point collocation without the Rosenblatt transformation.

The results from the uncertainty quantification are returned in data, as a Data object(see Data). The results are also automatically saved in a folder named data, and figures automatically plotted and saved in a folder named figures, both in the current directory. The returned data object is therefore not necessary to use.

Polynomial chaos expansions are recommended as long as the number of uncertain parameters is small (typically \(>20\)), as polynomial chaos expansions in these cases are much faster than quasi-Monte Carlo methods. Additionally, sensitivity analysis is currently not yet available for studies based on the quasi-Monte Carlo method. Which of the polynomial chaos expansions methods to choose is problem dependent, but in general the pseudo-spectral method is faster than point collocation, but has lower stability. We therefore generally recommend the point collocation method.

We note that there is no guarantee each set of sampled parameters produces a valid model or feature output. For example, a feature such as the spike width will not be defined in a model evaluation that produces no spikes. In such cases, Uncertainpy gives a warning which includes the number of runs that failed to return a valid output, and performs the uncertainty quantification and sensitivity analysis using the reduced set of valid runs. Point collocation (as well as the quasi-Monte Carlo method) are robust towards missing values as long as the number of results remaining is high enough, another reason the point collocation method is recommend. However, if a large fraction of the simulations fail, the user could consider redefining the problem (e.g., by using narrower parameter distributions).

API Reference¶

class uncertainpy.UncertaintyQuantification(model, parameters, features=None, uncertainty_calculations=None, create_PCE_custom=None, custom_uncertainty_quantification=None, CPUs=u'max', logger_level=u'info', logger_filename=u'uncertainpy.log', backend=u'auto')[source]¶

Perform an uncertainty quantification and sensitivity analysis of a model and features of the model.

It implements both quasi-Monte Carlo methods and polynomial chaos expansions using either point collocation or the pseudo-spectral method. Both of the polynomial chaos expansion methods have support for the rosenblatt transformation to handle dependent input parameters.

Parameters:	model ({None, Model or Model subclass instance, model function}) – Model to perform uncertainty quantification on. For requirements see Model.run. Default is None. parameters ({None, Parameters instance, list of Parameter instances, list with [[name, value, distribution], …]}) – Either None, a Parameters instance or a list of the parameters that should be created. The two lists are similar to the arguments sent to Parameters. Default is None. features ({None, Features or Features subclass instance, list of feature functions}, optional) – Features to calculate from the model result. If None, no features are calculated. If list of feature functions, all will be calculated. Default is None. uncertainty_calculations (UncertaintyCalculations or UncertaintyCalculations subclass instance, optional) – An UncertaintyCalculations class or subclass that implements (custom) uncertainty quantification and sensitivity analysis methods. create_PCE_custom (callable, optional) – A custom method for calculating the polynomial chaos approximation. For the requirements of the function see `UncertaintyCalculations.create_PCE_custom`. Overwrites existing `create_PCE_custom` method. Default is None. custom_uncertainty_quantification (callable, optional) – A custom method for calculating uncertainties. For the requirements of the function see `UncertaintyCalculations.custom_uncertainty_quantification`. Overwrites existing `custom_uncertainty_quantification` method. Default is None. CPUs ({int, None, “max”}, optional) – The number of CPUs to use when calculating the model and features. If None, no multiprocessing is used. If “max”, the maximum number of CPUs on the computer (multiprocess.cpu_count()) is used. Default is “max”. logger_level ({“info”, “debug”, “warning”, “error”, “critical”, None}, optional) – Set the threshold for the logging level. Logging messages less severe than this level is ignored. If None, no logging to file is performed Default logger level is “info”. logger_filename (str) – Name of the logfile. If None, no logging to file is performed. Default is “uncertainpy.log”. backend ({“auto”, “hdf5”, “exdir”}, optional) – The fileformat used to save and load data to/from file. “auto” assumes the filenames ends with either “.h5” for HDF5 files or “.exdir” for Exdir files. If unknown fileextension defaults to saving data as HDF5 files. “hdf5” saves and loads files from HDF5 files. “exdir” saves and loads files from Exdir files. Default is “auto”.
Variables:	model (Model or Model subclass) – The model to perform uncertainty quantification on. parameters (Parameters) – The uncertain parameters. features (Features or Features subclass) – The features of the model to perform uncertainty quantification on. uncertainty_calculations (UncertaintyCalculations or UncertaintyCalculations subclass) – UncertaintyCalculations object responsible for performing the uncertainty quantification calculations. data (Data) – A data object that contains the results from the uncertainty quantification. Contains all model and feature evaluations, as well as all calculated statistical metrics.
Raises:	`ValueError` – If unsupported backend is chosen.

See also

uncertainpy.features, uncertainpy.Parameter, uncertainpy.Parameters, uncertainpy.models, uncertainpy.core.UncertaintyCalculations

uncertainpy.core.UncertaintyCalculations.create_PCE_custom: Requirements for create_PCE_custom
uncertainpy.models.Model.run: Requirements for the model run function.

custom_uncertainty_quantification(plot=u'condensed_first', figure_folder=u'figures', figureformat=u'.png', save=True, data_folder=u'data', filename=None, **custom_kwargs)[source]¶

Perform a custom uncertainty quantification and sensitivity analysis, implemented by the user.

Parameters:

plot ({“condensed_first”, “condensed_total”, “condensed_no_sensitivity”, “all”, “evaluations”, None}, optional) – Type of plots to be created. “condensed_first” is a subset of the most important plots and only plots each result once, and contains plots of the first order Sobol indices. “condensed_total” is similar, but with the total order Sobol indices, and “condensed_no_sensitivity” is the same without any Sobol indices plotted. “all” creates every plot. “evaluations” plots the model and feature evaluations. None plots nothing. Default is “condensed_first”.
figure_folder (str, optional) – Name of the folder where to save all figures. Default is “figures”.
figureformat (str) – The figure format to save the plots in. Supports all formats in matplolib. Default is “.png”.
save (bool, optional) – If the data should be saved. Default is True.
data_folder (str, optional) – Name of the folder where to save the data. Default is “data”.
filename ({None, str}, optional) – Name of the data file. If None the model name is used. Default is None.
**custom_kwargs – Any number of arguments for the custom uncertainty quantification.

Raises:

NotImplementedError – If the custom uncertainty quantification method have not been implemented.

Notes

For details on how to implement the custom uncertainty quantification method see UncertaintyCalculations.custom_uncertainty_quantification.

The plots created are intended as quick way to get an overview of the results, and not to create publication ready plots. Custom plots of the data can easily be created by retrieving the data from the Data class.

uncertainpy.core.UncertaintyCalculations.custom_uncertainty_quantification(): Requirements for custom_uncertainty_quantification

features¶

Features to calculate from the model result.

Parameters:	new_features ({None, Features or Features subclass instance, list of feature functions}) – Features to calculate from the model result. If None, no features are calculated. If list of feature functions, all will be calculated.
Returns:	features – Features to calculate from the model result. If None, no features are calculated.
Return type:	{None, Features object}

load(filename)[source]¶

Load data from disk.

Parameters:	filename (str) – Name of the stored data file.

See also

uncertainpy.Data(): Data class

model¶

Model to perform uncertainty quantification on. For requirements see Model.run.

Parameters:	new_model ({None, Model or Model subclass instance, model function}) – Model to perform uncertainty quantification on.
Returns:	model – Model to perform uncertainty quantification on.
Return type:	Model or Model subclass instance

monte_carlo(uncertain_parameters=None, nr_samples=10000, seed=None, plot=u'condensed_first', figure_folder=u'figures', figureformat=u'.png', save=True, data_folder=u'data', filename=None)[source]¶

Perform an uncertainty quantification using the quasi-Monte Carlo method.

Parameters:	uncertain_parameters ({None, str, list}, optional) – The uncertain parameter(s) to use when performing the uncertainty quantification. If None, all uncertain parameters are used. Default is None. nr_samples (int, optional) – Number of samples for the quasi-Monte Carlo sampling. nr_samples is used for the uncertainty quantification and `(nr_samples/2)(nr_uncertain_parameters + 2)` samples is used for the sensitivity analysis. Default nr_samples is 104. seed* (int, optional) – Set a random seed. If None, no seed is set. Default is None. plot ({“condensed_first”, “condensed_total”, “condensed_no_sensitivity”, “all”, “evaluations”, None}, optional) – Type of plots to be created. “condensed_first” is a subset of the most important plots and only plots each result once, and contains plots of the first order Sobol indices. “condensed_total” is similar, but with the total order Sobol indices, and “condensed_no_sensitivity” is the same without any Sobol indices plotted. “all” creates every plot. “evaluations” plots the model and feature evaluations. None plots nothing. Default is “condensed_first”. figure_folder (str, optional) – Name of the folder where to save all figures. Default is “figures”. figureformat (str) – The figure format to save the plots in. Supports all formats in matplolib. Default is “.png”. save (bool, optional) – If the data should be saved. Default is True. data_folder (str, optional) – Name of the folder where to save the data. Default is “data”. filename ({None, str}, optional) – Name of the data file. If None the model name is used. Default is None.
Returns:	data – A data object that contains the results from the uncertainty quantification. Contains all model and feature evaluations, as well as all calculated statistical metrics.
Return type:	Data
Raises:	`ValueError` – If a common multivariate distribution is given in Parameters.distribution and not all uncertain parameters are used.

Notes

Which method to choose is problem dependent, but as long as the number of uncertain parameters is low (less than around 20 uncertain parameters) polynomial chaos methods are much faster than Monte Carlo methods. Above this Monte Carlo methods are the best.

In the quasi-Monte Carlo method we quasi-randomly draw (nr_samples/2)*(nr_uncertain_parameters + 2) (nr_samples=10**4 by default) parameter samples using Saltelli’s sampling scheme. We require this number of samples to be able to calculate the Sobol indices. We evaluate the model for each of these parameter samples and calculate the features from each of the model results. This step is performed in parallel to speed up the calculations. Then we use nr_samples of the model and feature results to calculate the mean, variance, and 5th and 95th percentile for the model and each feature. Lastly, we use all calculated model and each feature results to calculate the Sobol indices using Saltellie’s approach.

The plots created are intended as quick way to get an overview of the results, and not to create publication ready plots. Custom plots of the data can easily be created by retrieving the data from the Data class.

Sensitivity analysis is currently not yet available for the quasi-Monte Carlo method.

uncertainpy.core.UncertaintyCalculations.monte_carlo(): Uncertainty quantification using quasi-Monte Carlo methods

monte_carlo_single(uncertain_parameters=None, nr_samples=10000, seed=None, plot=u'condensed_first', save=True, data_folder=u'data', figure_folder=u'figures', figureformat=u'.png', filename=None)[source]¶

Perform an uncertainty quantification for a single parameter at the time using the quasi-Monte Carlo method.

Parameters:	uncertain_parameters ({None, str, list}, optional) – The uncertain parameter(s) to use when performing the uncertainty quantification. If None, all uncertain parameters are used. Default is None. nr_samples (int, optional) – Number of samples for the quasi-Monte Carlo sampling. nr_samples is used for the uncertainty quantification and `(nr_samples/2)(nr_uncertain_parameters + 2)` samples is used for the sensitivity analysis. Default nr_samples is 104. seed* (int, optional) – Set a random seed. If None, no seed is set. Default is None. plot ({“condensed_first”, “condensed_total”, “condensed_no_sensitivity”, “all”, “evaluations”, None}, optional) – Type of plots to be created. “condensed_first” is a subset of the most important plots and only plots each result once, and contains plots of the first order Sobol indices. “condensed_total” is similar, but with the total order Sobol indices, and “condensed_no_sensitivity” is the same without any Sobol indices plotted. “all” creates every plot. “evaluations” plots the model and feature evaluations. None plots nothing. Default is “condensed_first”. figure_folder (str, optional) – Name of the folder where to save all figures. Default is “figures”. figureformat (str) – The figure format to save the plots in. Supports all formats in matplolib. Default is “.png”. save (bool, optional) – If the data should be saved. Default is True. data_folder (str, optional) – Name of the folder where to save the data. Default is “data”. filename ({None, str}, optional) – Name of the data file. If None the model name is used. Default is None.
Returns:	data_dict – A dictionary that contains the data objects for each single parameter calculation.
Return type:	dict
Raises:	`ValueError` – If a common multivariate distribution is given in Parameters.distribution and not all uncertain parameters are used.

Notes

Which method to choose is problem dependent, but as long as the number of uncertain parameters is low (less than around 20 uncertain parameters) polynomial chaos methods are much faster than Monte Carlo methods. Above this Monte Carlo methods are the best.

In the quasi-Monte Carlo method we quasi-randomly draw (nr_samples/2)*(nr_uncertain_parameters + 2) (nr_samples=10**4 by default) parameter samples using Saltelli’s sampling scheme. We require this number of samples to be able to calculate the Sobol indices. We evaluate the model for each of these parameter samples and calculate the features from each of the model results. This step is performed in parallel to speed up the calculations. Then we use nr_samples of the model and feature results to calculate the mean, variance, and 5th and 95th percentile for the model and each feature. Lastly, we use all calculated model and each feature results to calculate the Sobol indices using Saltellie’s approach.

The plots created are intended as quick way to get an overview of the results, and not to create publication ready plots. Custom plots of the data can easily be created by retrieving the data from the Data class.

Sensitivity analysis is currently not yet available for the quasi-Monte Carlo method.

uncertainpy.core.UncertaintyCalculations.monte_carlo(): Uncertainty quantification using quasi-Monte Carlo methods

parameters¶

Model parameters.

Parameters:	new_parameters ({None, Parameters instance, list of Parameter instances, list [[name, value, distribution], …]}) – Either None, a Parameters instance or a list of the parameters that should be created. The two lists are similar to the arguments sent to Parameters. Default is None.
Returns:	parameters – Parameters of the model. If None, no parameters have been set.
Return type:	{None, Parameters}

plot(type=u'condensed_first', folder=u'figures', figureformat=u'.png')[source]¶

Create plots for the results of the uncertainty quantification and sensitivity analysis. self.data must exist and contain the results.

Parameters:

data (Data) – A data object that contains the results from the uncertainty quantification.
type ({“condensed_first”, “condensed_total”, “condensed_no_sensitivity”, “all”, “evaluations”, None}, optional) – Type of plots to be created. “condensed_first” is a subset of the most important plots and only plots each result once, and contains plots of the first order Sobol indices. “condensed_total” is similar, but with the total order Sobol indices, and “condensed_no_sensitivity” is the same without any Sobol indices plotted. “all” creates every plot. “evaluations” plots the model and feature evaluations. None plots nothing. Default is “condensed_first”.
folder (str) – Name of the folder where to save all figures. Default is “figures”.
figureformat (str) – The figure format to save the plots in. Supports all formats in matplolib. Default is “.png”.

Notes

These plots are intended as quick way to get an overview of the results, and not to create publication ready plots. Custom plots of the data can easily be created by retrieving the data from the Data class.

polynomial_chaos(method=u'collocation', rosenblatt=u'auto', uncertain_parameters=None, polynomial_order=4, nr_collocation_nodes=None, quadrature_order=None, nr_pc_mc_samples=10000, allow_incomplete=True, seed=None, plot=u'condensed_first', figure_folder=u'figures', figureformat=u'.png', save=True, data_folder=u'data', filename=None, **custom_kwargs)[source]¶

Perform an uncertainty quantification and sensitivity analysis using polynomial chaos expansions.

Parameters:	method ({“collocation”, “spectral”, “custom”}, optional) – The method to use when creating the polynomial chaos approximation, if the polynomial chaos method is chosen. “collocation” is the point collocation method “spectral” is pseudo-spectral projection, and “custom” is the custom polynomial method. Default is “collocation”. rosenblatt ({“auto”, bool}, optional) – If the Rosenblatt transformation should be used. The Rosenblatt transformation must be used if the uncertain parameters have dependent variables. If “auto” the Rosenblatt transformation is used if there are dependent parameters, and it is not used of the parameters have independent distributions. Default is “auto”. uncertain_parameters ({None, str, list}, optional) – The uncertain parameter(s) to use when performing the uncertainty quantification. If None, all uncertain parameters are used. Default is None. polynomial_order (int, optional) – The polynomial order of the polynomial approximation. Default is 4. nr_collocation_nodes ({int, None}, optional) – The number of collocation nodes to choose, if polynomial chaos with point collocation is used. If None, nr_collocation_nodes = 2* number of expansion factors + 2. Default is None. quadrature_order ({int, None}, optional) – The order of the Leja quadrature method, if polynomial chaos with pseudo-spectral projection is used. If None, `quadrature_order = polynomial_order + 2`. Default is None. nr_pc_mc_samples (int, optional) – Number of samples for the Monte Carlo sampling of the polynomial chaos approximation, if the polynomial chaos method is chosen. allow_incomplete (bool, optional) – If the polynomial approximation should be performed for features or models with incomplete evaluations. Default is True. seed (int, optional) – Set a random seed. If None, no seed is set. Default is None. plot ({“condensed_first”, “condensed_total”, “condensed_no_sensitivity”, “all”, “evaluations”, None}, optional) – Type of plots to be created. “condensed_first” is a subset of the most important plots and only plots each result once, and contains plots of the first order Sobol indices. “condensed_total” is similar, but with the total order Sobol indices, and “condensed_no_sensitivity” is the same without any Sobol indices plotted. “all” creates every plot. “evaluations” plots the model and feature evaluations. None plots nothing. Default is “condensed_first”. figure_folder (str, optional) – Name of the folder where to save all figures. Default is “figures”. figureformat (str) – The figure format to save the plots in. Supports all formats in matplolib. Default is “.png”. save (bool, optional) – If the data should be saved. Default is True. data_folder (str, optional) – Name of the folder where to save the data. Default is “data”. filename ({None, str}, optional) – Name of the data file. If None the model name is used. Default is None. **custom_kwargs – Any number of arguments for the custom polynomial chaos method, `create_PCE_custom`.
Returns:	data – A data object that contains the results from the uncertainty quantification. Contains all model and feature evaluations, as well as all calculated statistical metrics.
Return type:	Data
Raises:	`ValueError` – If a common multivariate distribution is given in Parameters.distribution and not all uncertain parameters are used. `ValueError` – If method not one of “collocation”, “spectral” or “custom”. `NotImplementedError` – If custom pc method is chosen and have not been implemented.

Notes

Which method to choose is problem dependent, but as long as the number of uncertain parameters is low (less than around 20 uncertain parameters) polynomial chaos methods are much faster than Monte Carlo methods. Above this Monte Carlo methods are the best.

For polynomial chaos, the pseudo-spectral method is faster than point collocation, but has lower stability. We therefore generally recommend the point collocation method.

The model and feature do not necessarily give results for each node. The collocation method are robust towards missing values as long as the number of results that remain is high enough. The pseudo-spectral method on the other hand, is sensitive to missing values, so allow_incomplete should be used with care in that case.

The plots created are intended as quick way to get an overview of the results, and not to create publication ready plots. Custom plots of the data can easily be created by retrieving the data from the Data class.

Changing the parameters of the polynomial chaos methods should be done with care, and implementing custom methods is only recommended for experts.

uncertainpy.core.UncertaintyCalculations.polynomial_chaos(): Uncertainty quantification using polynomial chaos expansions
uncertainpy.core.UncertaintyCalculations.create_PCE_custom(): Requirements for create_PCE_custom

polynomial_chaos_single(method=u'collocation', rosenblatt=u'auto', polynomial_order=4, uncertain_parameters=None, nr_collocation_nodes=None, quadrature_order=None, nr_pc_mc_samples=10000, allow_incomplete=True, seed=None, plot=u'condensed_first', figure_folder=u'figures', figureformat=u'.png', save=True, data_folder=u'data', filename=None)[source]¶

Perform an uncertainty quantification and sensitivity analysis for a single parameter at the time using polynomial chaos expansions.

Parameters:	method ({“collocation”, “spectral”, “custom”}, optional) – The method to use when creating the polynomial chaos approximation, if the polynomial chaos method is chosen. “collocation” is the point collocation method “spectral” is pseudo-spectral projection, and “custom” is the custom polynomial method. Default is “collocation”. rosenblatt ({“auto”, bool}, optional) – If the Rosenblatt transformation should be used. The Rosenblatt transformation must be used if the uncertain parameters have dependent variables. If “auto” the Rosenblatt transformation is used if there are dependent parameters, and it is not used of the parameters have independent distributions. Default is “auto”. uncertain_parameters ({None, str, list}, optional) – The uncertain parameter(s) to performing the uncertainty quantification for. If None, all uncertain parameters are used. Default is None. polynomial_order (int, optional) – The polynomial order of the polynomial approximation. Default is 4. nr_collocation_nodes ({int, None}, optional) – The number of collocation nodes to choose, if polynomial chaos with point collocation is used. If None, nr_collocation_nodes = 2* number of expansion factors + 2. Default is None. quadrature_order ({int, None}, optional) – The order of the Leja quadrature method, if polynomial chaos with pseudo-spectral projection is used. If None, `quadrature_order = polynomial_order + 2`. Default is None. nr_pc_mc_samples (int, optional) – Number of samples for the Monte Carlo sampling of the polynomial chaos approximation, if the polynomial chaos method is chosen. allow_incomplete (bool, optional) – If the polynomial approximation should be performed for features or models with incomplete evaluations. Default is True. seed (int, optional) – Set a random seed. If None, no seed is set. Default is None. plot ({“condensed_first”, “condensed_total”, “condensed_no_sensitivity”, “all”, “evaluations”, None}, optional) – Type of plots to be created. “condensed_first” is a subset of the most important plots and only plots each result once, and contains plots of the first order Sobol indices. “condensed_total” is similar, but with the total order Sobol indices, and “condensed_no_sensitivity” is the same without any Sobol indices plotted. “all” creates every plot. “evaluations” plots the model and feature evaluations. None plots nothing. Default is “condensed_first”. figure_folder (str, optional) – Name of the folder where to save all figures. Default is “figures”. figureformat (str) – The figure format to save the plots in. Supports all formats in matplolib. Default is “.png”. save (bool, optional) – If the data should be saved. Default is True. data_folder (str, optional) – Name of the folder where to save the data. Default is “data”. filename ({None, str}, optional) – Name of the data file. If None the model name is used. Default is None. **custom_kwargs – Any number of arguments for the custom polynomial chaos method, `create_PCE_custom`.
Returns:	data_dict – A dictionary that contains the data for each single parameter calculation.
Return type:	dict
Raises:	`ValueError` – If a common multivariate distribution is given in Parameters.distribution and not all uncertain parameters are used. `ValueError` – If method not one of “collocation”, “spectral” or “custom”. `NotImplementedError` – If custom pc method is chosen and have not been implemented.

Notes

Which method to choose is problem dependent, but as long as the number of uncertain parameters is low (less than around 20 uncertain parameters) polynomial chaos methods are much faster than Monte Carlo methods. Above this Monte Carlo methods are the best.

For polynomial chaos, the pseudo-spectral method is faster than point collocation, but has lower stability. We therefore generally recommend the point collocation method.

The model and feature do not necessarily give results for each node. The collocation method are robust towards missing values as long as the number of results that remain is high enough. The pseudo-spectral method on the other hand, is sensitive to missing values, so allow_incomplete should be used with care in that case.

The plots created are intended as quick way to get an overview of the results, and not to create publication ready plots. Custom plots of the data can easily be created by retrieving the data from the Data class.

Changing the parameters of the polynomial chaos methods should be done with care, and implementing custom methods is only recommended for experts.

uncertainpy.core.UncertaintyCalculations.polynomial_chaos(): Uncertainty quantification using polynomial chaos expansions
uncertainpy.core.UncertaintyCalculations.create_PCE_custom(): Requirements for create_PCE_custom

quantify(method=u'pc', pc_method=u'collocation', rosenblatt=u'auto', uncertain_parameters=None, polynomial_order=4, nr_collocation_nodes=None, quadrature_order=None, nr_pc_mc_samples=10000, nr_mc_samples=10000, allow_incomplete=True, seed=None, single=False, plot=u'condensed_first', figure_folder=u'figures', figureformat=u'.png', save=True, data_folder=u'data', filename=None, **custom_kwargs)[source]¶

Perform an uncertainty quantification and sensitivity analysis using polynomial chaos expansions or quasi-Monte Carlo methods.

Parameters:	method ({“pc”, “mc”, “custom”}, optional) – The method to use when performing the uncertainty quantification and sensitivity analysis. “pc” is polynomial chaos method, “mc” is the quasi-Monte Carlo method and “custom” are custom uncertainty quantification methods. Default is “pc”. pc_method ({“collocation”, “spectral”, “custom”}, optional) – The method to use when creating the polynomial chaos approximation, if the polynomial chaos method is chosen. “collocation” is the point collocation method “spectral” is pseudo-spectral projection, and “custom” is the custom polynomial method. Default is “collocation”. rosenblatt ({“auto”, bool}, optional) – If the Rosenblatt transformation should be used. The Rosenblatt transformation must be used if the uncertain parameters have dependent variables. If “auto” the Rosenblatt transformation is used if there are dependent parameters, and it is not used of the parameters have independent distributions. Default is “auto”. uncertain_parameters ({None, str, list}, optional) – The uncertain parameter(s) to use when performing the uncertainty quantification. If None, all uncertain parameters are used. Default is None. polynomial_order (int, optional) – The polynomial order of the polynomial approximation. Default is 4. nr_collocation_nodes ({int, None}, optional) – The number of collocation nodes to choose, if polynomial chaos with point collocation is used. If None, nr_collocation_nodes = 2* number of expansion factors + 2. Default is None. quadrature_order ({int, None}, optional) – The order of the Leja quadrature method, if polynomial chaos with pseudo-spectral projection is used. If None, `quadrature_order = polynomial_order + 2`. Default is None. nr_pc_mc_samples (int, optional) – Number of samples for the Monte Carlo sampling of the polynomial chaos approximation, if the polynomial chaos method is chosen. Default is 104. nr_mc_samples** (int, optional) – Number of samples for the quasi-Monte Carlo sampling, if the quasi-Monte Carlo method is chosen. nr_mc_samples is used for the uncertainty quantification and `(nr_mc_samples/2)(nr_uncertain_parameters + 2)` samples is used for the sensitivity analysis. Default nr_mc_samples is 104. allow_incomplete* (bool, optional) – If the polynomial approximation should be performed for features or models with incomplete evaluations. Default is True. seed (int, optional) – Set a random seed. If None, no seed is set. Default is None. single (bool) – If an uncertainty quantification should be performed with only one uncertain parameter at the time. Requires that the values of each parameter is set. Default is False. plot ({“condensed_first”, “condensed_total”, “condensed_no_sensitivity”, “all”, “evaluations”, None}, optional) – Type of plots to be created. “condensed_first” is a subset of the most important plots and only plots each result once, and contains plots of the first order Sobol indices. “condensed_total” is similar, but with the total order Sobol indices, and “condensed_no_sensitivity” is the same without any Sobol indices plotted. “all” creates every plot. “evaluations” plots the model and feature evaluations. None plots nothing. Default is “condensed_first”. figure_folder (str, optional) – Name of the folder where to save all figures. Default is “figures”. figureformat (str) – The figure format to save the plots in. Supports all formats in matplolib. Default is “.png”. save (bool, optional) – If the data should be saved. Default is True. data_folder (str, optional) – Name of the folder where to save the data. Default is “data”. filename ({None, str}, optional) – Name of the data file. If None the model name is used. Default is None. **custom_kwargs – Any number of arguments for either the custom polynomial chaos method, `create_PCE_custom`, or the custom uncertainty quantification, `custom_uncertainty_quantification`.
Returns:	data – A data object that contains the results from the uncertainty quantification. Contains all model and feature evaluations, as well as all calculated statistical metrics. If single = True, then returns a dictionary that contains the data objects for each single parameter calculation.
Return type:	Data, dict containing data objects
Raises:	`ValueError` – If a common multivariate distribution is given in Parameters.distribution and not all uncertain parameters are used. `ValueError` – If method not one of “pc”, “mc” or “custom”. `ValueError` – If pc_method not one of “collocation”, “spectral” or “custom”. `NotImplementedError` – If custom method or custom pc method is chosen and have not been implemented.

Notes

Which method to choose is problem dependent, but as long as the number of uncertain parameters is low (less than around 20 uncertain parameters) polynomial chaos methods are much faster than Monte Carlo methods. Above this Monte Carlo methods are the best.

For polynomial chaos, the pseudo-spectral method is faster than point collocation, but has lower stability. We therefore generally recommend the point collocation method.

The model and feature do not necessarily give results for each node. The collocation method and quasi-Monte Carlo methods are robust towards missing values as long as the number of results that remain is high enough. The pseudo-spectral method on the other hand, is sensitive to missing values, so allow_incomplete should be used with care in that case.

In the quasi-Monte Carlo method we quasi-randomly draw (nr_mc_samples/2)*(nr_uncertain_parameters + 2) (nr_mc_samples=10**4 by default) parameter samples using Saltelli’s sampling scheme. We require this number of samples to be able to calculate the Sobol indices. We evaluate the model for each of these parameter samples and calculate the features from each of the model results. This step is performed in parallel to speed up the calculations. Then we use nr_mc_samples of the model and feature results to calculate the mean, variance, and 5th and 95th percentile for the model and each feature. Lastly, we use all calculated model and each feature results to calculate the Sobol indices using Saltellie’s approach.

The plots created are intended as quick way to get an overview of the results, and not to create publication ready plots. Custom plots of the data can easily be created by retrieving the data from the Data class.

Changing the parameters of the polynomial chaos methods should be done with care, and implementing custom methods is only recommended for experts.

uncertainpy.core.UncertaintyCalculations.polynomial_chaos(): Uncertainty quantification using polynomial chaos expansions
uncertainpy.core.UncertaintyCalculations.monte_carlo(): Uncertainty quantification using quasi-Monte Carlo methods
uncertainpy.core.UncertaintyCalculations.create_PCE_custom(): Requirements for create_PCE_custom
uncertainpy.core.UncertaintyCalculations.custom_uncertainty_quantification(): Requirements for custom_uncertainty_quantification

save(filename, folder=u'data')[source]¶

Save data to disk.

Parameters:	filename (str) – Name of the data file. folder (str, optional) – The folder to store the data in. Creates the folder if it does not exist. Default is “/data”.

See also

uncertainpy.Data(): Data class

uncertainty_calculations¶

The class for performing the calculations for the uncertainty quantification and sensitivity analysis.

Parameters:	new_uncertainty_calculations (UncertaintyCalculations or UncertaintyCalculations subclass instance) – New UncertaintyCalculations object responsible for performing the uncertainty quantification calculations.
Returns:	uncertainty_calculations – UncertaintyCalculations object responsible for performing the uncertainty quantification calculations.
Return type:	UncertaintyCalculations or UncertaintyCalculations subclass instance