soboljansen: Monte Carlo Estimation of Sobol' Indices (improved formulas...

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/soboljansen.R

Description

soboljansen 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) * n model evaluations. These are called the Jansen estimators.

Usage

1
2
3
4
5
6
7
soboljansen(model = NULL, X1, X2, nboot = 0, conf = 0.95, ...)
## S3 method for class 'soboljansen'
tell(x, y = NULL, return.var = NULL, ...)
## S3 method for class 'soboljansen'
print(x, ...)
## S3 method for class 'soboljansen'
plot(x, ylim = c(0, 1), y_col = NULL, y_dim3 = NULL, ...)

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.

y_col

an integer defining the index of the column of x$y to be used for plotting the corresponding sensitivity indices (only applies if x$y is a matrix or an array). If set to NULL (as per default) and x$y is a matrix or an array, the first column (respectively the first element in the second dimension) of x$y is used (i.e. y_col = 1).

y_dim3

an integer defining the index in the third dimension of x$y to be used for plotting the corresponding sensitivity indices (only applies if x$y is an array). If set to NULL (as per default) and x$y is a three-dimensional array, the first element in the third dimension of x$y is used (i.e. y_dim3 = 1).

...

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

Details

This estimator is good for large first-order indices, and (large and small) total indices.

This version of soboljansen also supports matrices and three-dimensional arrays as output of model. If the model output is a matrix or an array, V, S and T are matrices or arrays as well (depending on the type of y and the value of nboot).

The bootstrap outputs V.boot, S.boot and T.boot can only be returned if the model output is a vector (using argument return.var). For matrix or array output, these objects can't be returned.

Value

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

either a vector, a matrix or a three-dimensional array of model responses (depends on the output of model).

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 Xi").

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).

Author(s)

Bertrand Iooss, with contributions from Frank Weber (2016)

References

M.J.W. Jansen, 1999, Analysis of variance designs for model output, Computer Physics Communication, 117, 35–43.

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, sobol2007, sobolmartinez, sobolEff, sobolmara,sobolMultOut

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# 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 <- soboljansen(model = sobol.fun, X1, X2, nboot = 100)
print(x)
plot(x)

# Only for demonstration purposes: a model function returning a matrix
sobol.fun_matrix <- function(X){
  res_vector <- sobol.fun(X)
  cbind(res_vector, 2 * res_vector)
}
x_matrix <- soboljansen(model = sobol.fun_matrix, X1, X2)
plot(x_matrix, y_col = 2)
title(main = "y_col = 2")

# Also only for demonstration purposes: a model function returning a
# three-dimensional array
sobol.fun_array <- function(X){
  res_vector <- sobol.fun(X)
  res_matrix <- cbind(res_vector, 2 * res_vector)
  array(data = c(res_matrix, 5 * res_matrix), 
        dim = c(length(res_vector), 2, 2))
}
x_array <- soboljansen(model = sobol.fun_array, X1, X2)
plot(x_array, y_col = 2, y_dim3 = 2)
title(main = "y_col = 2, y_dim3 = 2")

Example output

Call:
soboljansen(model = sobol.fun, X1 = X1, X2 = X2, nboot = 100)

Model runs: 10000 

First order indices:
     original          bias std. error   min. c.i. max. c.i.
X1 0.70510560 -2.980557e-03 0.02157328  0.67182260 0.7530908
X2 0.16888010  6.803931e-04 0.04540535  0.08512102 0.2787165
X3 0.06957699 -1.954903e-04 0.04548145 -0.01360140 0.1755525
X4 0.05406456 -4.251372e-05 0.04365694 -0.03161598 0.1552828
X5 0.02414501  6.798895e-04 0.04503713 -0.06455088 0.1252298
X6 0.02491597  8.600211e-04 0.04492792 -0.06419410 0.1253226
X7 0.02474485  5.531349e-04 0.04489046 -0.06369776 0.1253469
X8 0.02478907  6.993809e-04 0.04505401 -0.06422925 0.1252628

Total indices:
       original          bias   std. error    min. c.i.    max. c.i.
X1 7.962357e-01 -2.655226e-03 4.541135e-02 6.998596e-01 0.8916391776
X2 2.521104e-01  1.836790e-03 1.806566e-02 2.147706e-01 0.2856607909
X3 3.287089e-02  2.815536e-04 2.225300e-03 2.657600e-02 0.0362166047
X4 9.518038e-03  3.013315e-05 5.609307e-04 8.371943e-03 0.0107176601
X5 1.079425e-04  4.386588e-07 6.642384e-06 9.291376e-05 0.0001193625
X6 9.437603e-05  7.623766e-07 6.247064e-06 8.100292e-05 0.0001077074
X7 1.072195e-04 -2.485171e-07 6.381759e-06 9.509517e-05 0.0001196787
X8 1.068912e-04  1.881664e-07 7.909110e-06 8.826713e-05 0.0001199697

sensitivity documentation built on Sept. 24, 2017, 1:05 a.m.