R: Monte Carlo Estimation of Sobol' Indices (formulas of...
sobolmartinez
R Documentation
Monte Carlo Estimation of Sobol' Indices (formulas of Martinez (2011))
Description
sobolmartinez implements the Monte Carlo estimation of
the Sobol' indices for both first-order and total indices using
correlation coefficients-based formulas, at a total cost of
(p + 2) * n model evaluations.
These are called the Martinez estimators.
Usage
sobolmartinez(model = NULL, X1, X2, nboot = 0, conf = 0.95, ...)
## S3 method for class 'sobolmartinez'
tell(x, y = NULL, return.var = NULL, ...)
## S3 method for class 'sobolmartinez'
print(x, ...)
## S3 method for class 'sobolmartinez'
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, or zero to use theoretical
formulas based on confidence interfaces of correlation coefficient
(Martinez, 2011).
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 sobolmartinez: any other arguments for model
which are passed unchanged each time it is called
Details
This estimator supports missing values (NA or NaN) which can occur during the
simulation of the model on the design of experiments (due to code failure)
even if Sobol' indices are no more rigorous variance-based sensitivity
indices if missing values are present. In this case, a warning is displayed.
This version of sobolmartinez also supports matrices and
three-dimensional arrays as output of model. Bootstrapping (including
bootstrap confidence intervals) is also supported for matrix or array output.
However, theoretical confidence intervals (for nboot = 0) are only
supported for vector output. 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
sobolmartinez returns a list of class "sobolmartinez",
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 normalized 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
J-M. Martinez, 2011, Analyse de sensibilite globale par decomposition
de la variance, Presentation in the meeting of GdR Ondes and GdR MASCOT-NUM,
January, 13th, 2011, Institut Henri Poincare, Paris, France.