sensitivity (version 1.28.0)

sobol2007: Monte Carlo Estimation of Sobol' Indices (improved formulas of Mauntz: Sobol et al. (2007) and Saltelli et al. (2010))

Description

sobol2007 implements the Monte Carlo estimation of the Sobol' indices for both first-order and total indices at the same time (alltogether \(2p\) indices), at a total cost of \((p+2) \times n\) model evaluations. These are called the Mauntz estimators.

Usage

sobol2007(model = NULL, X1, X2, nboot = 0, conf = 0.95, ...)
# S3 method for sobol2007
tell(x, y = NULL, return.var = NULL, ...)
# S3 method for sobol2007
print(x, ...)
# S3 method for sobol2007
plot(x, ylim = c(0, 1), ...)
  # S3 method for sobol2007
plotMultOut(x, ylim = c(0, 1), ...)
# S3 method for sobol2007
ggplot(x, ylim = c(0, 1), ...)

Value

sobol2007 returns a list of class "sobol2007", 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.

nboot

the number of bootstrap replicates.

conf

the confidence level for bootstrap confidence intervals.

x

a list of class "sobol" 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.

...

any other arguments for model which are passed unchanged each time it is called

Author

Bertrand Iooss

Details

This estimator is good for small first-order and total indices.

BE CAREFUL! This estimator suffers from a conditioning problem when estimating the variances behind the indices computations. This can seriously affect the Sobol' indices estimates in case of largely non-centered output. To avoid this effect, you have to center the model output before applying "sobol2007". Functions "sobolEff", "soboljansen" and "sobolmartinez" do not suffer from this problem.

References

I.M. Sobol, S. Tarantola, D. Gatelli, S.S. Kucherenko and W. Mauntz, 2007, Estimating the approximation errors when fixing unessential factors in global sensitivity analysis, Reliability Engineering and System Safety, 92, 957--960.

A. Saltelli, P. Annoni, I. Azzini, F. Campolongo, M. Ratto and S. Tarantola, 2010, Variance based sensitivity analysis of model output. Design and estimator for the total sensitivity index, Computer Physics Communications 181, 259--270.

See Also

sobol, sobol2002, sobolSalt, soboljansen, sobolmartinez, sobolEff, sobolmara,sobolMultOut

Examples

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

# The method of sobol requires 2 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))

# sensitivity analysis

x <- sobol2007(model = sobol.fun, X1, X2, nboot = 100)
print(x)
plot(x)

library(ggplot2)
ggplot(x)