sobolowen: Monte Carlo Estimation of Sobol' Indices (improved formulas of Owen (2013)

Description

sobolowen implements the Monte Carlo estimation of the Sobol' indices for both first-order and total indices at the same time (alltogether $2 p$ indices). Take as input 3 independent matrices. These are called the Owen estimators.

Usage

sobolowen(model = NULL, X1, X2, X3, nboot = 0, conf = 0.95, varest = 2, ...)
# S3 method for sobolowen
tell(x, y = NULL, return.var = NULL, varest = 2, ...)
# S3 method for sobolowen
print(x, ...)
# S3 method for sobolowen
plot(x, ylim = c(0, 1), ...)
# S3 method for sobolowen
ggplot(data, mapping = aes(), ylim = c(0, 1), ..., environment
                 = parent.frame())

Value

sobolowen returns a list of class "sobolowen", containing all the input arguments detailed before, plus the following components:

call: the matched call.
X: a data.frame containing the design of experiments.
y: the response used
V: the estimations of Variances of the Conditional Expectations (VCE) with respect to each factor and also with respect to the complementary set of each factor ("all but $X_{i}$ ").
S: the estimations of the Sobol' first-order indices.
T: the estimations of the Sobol' total sensitivity indices.

Users can ask more ouput variables with the argument

return.var (for example, bootstrap outputs V.boot,

S.boot and T.boot).

Arguments

model: a function, or a model with a predict method, defining the model to analyze.
X1: the first random sample.
X2: the second random sample.
X3: the third random sample.
nboot: the number of bootstrap replicates.
conf: the confidence level for bootstrap confidence intervals.
varest: choice for the variance estimator for the denominator of the Sobol' indices. varest=1 is for a classical estimator. varest=2 (default) is for the estimator proposed in Janon et al. (2012).
x: a list of class "sobolowen" storing the state of the sensitivity study (parameters, data, estimates).
data: a list of class "sobolowen" storing the state of the sensitivity study (parameters, data, estimates).
y: a vector of model responses.
return.var: a vector of character strings giving further internal variables names to store in the output object x.
ylim: y-coordinate plotting limits.
mapping: Default list of aesthetic mappings to use for plot. If not specified, must be supplied in each layer added to the plot.
environment: [Deprecated] Used prior to tidy evaluation.
...: any other arguments for model which are passed unchanged each time it is called

Author

Taieb Touati and Bernardo Ramos

References

A. Owen, 2013, Better estimations of small Sobol' sensitivity indices, ACM Transactions on Modeling and Computer Simulations (TOMACS), 23(2), 11.

Janon, A., Klein T., Lagnoux A., Nodet M., Prieur C. (2012), Asymptotic normality and efficiency of two Sobol index estimators. Accepted in ESAIM: Probability and Statistics.

Examples

Run this code

# Test case : the non-monotonic Sobol g-function

# The method of sobolowen requires 3 samples
# There are 8 factors, all following the uniform distribution
# on [0,1]

library(boot)
n <- 1000
X1 <- data.frame(matrix(runif(8 * n), nrow = n))
X2 <- data.frame(matrix(runif(8 * n), nrow = n))
X3 <- data.frame(matrix(runif(8 * n), nrow = n))

# sensitivity analysis

# \donttest{
x <- sobolowen(model = sobol.fun, X1, X2, X3, nboot = 10) # put nboot=100
print(x)
plot(x)

library(ggplot2)
ggplot(x)
# }

Run the code above in your browser using DataLab

The Learning Leader's Guide to AI Literacy