sobolroauc {sensitivity}

Sobol' Indices estimation under inequality constraints

Description

sobolroauc deals with the estimation of Sobol' sensitivity indices when there exists one or multiple sets of constrained factors. Constraints within a set are expressed as inequality constraints (simplex constraint). This function generalizes the procedure of Tissot and Prieur (2015) to estimate either all first-order indices or all closed second-order indices at a total cost of 2 \times N model evaluations. For closed second-order indices N=q^{2} where q \geq d-1 is a prime number denoting the number of levels of the orthogonal array, and where d indicates the number of independent factors or sets of factors.

Usage

sobolroauc(model = NULL, factors, constraints = NULL, N, p = 1, order, 
            tail = TRUE, conf = 0.95, nboot = 0, ...)
## S3 method for class 'sobolroauc'
tell(x, y = NULL, ...)
## S3 method for class 'sobolroauc'
print(x, ...)
## S3 method for class 'sobolroauc'
plot(x, ylim = c(0,1), ...)
## S3 method for class 'sobolroauc'
ggplot(data, mapping = aes(), ylim = c(0, 1), ..., environment
                 = parent.frame())

Arguments

model

a function, or a model with a predict method, defining the model to analyze.

factors

an integer giving the number of factors, or a vector of character strings giving their names.

constraints

a list giving the sets of constrained factors (see "Details").

N

an integer giving the size of each replicated design (for a total of 2 \times N model evaluations).

p

an integer giving the number of model outputs.

order

an integer giving the order of the indices (1 or 2).

tail

a boolean specifying the method used to choose the number of levels of the orthogonal array (see "Warning messages").

conf

the confidence level for confidence intervals.

nboot

the number of bootstrap replicates.

x

a list of class "sobolroauc" storing the state of the sensitivity study (parameters, data, estimates).

data

a list of class "sobolroauc" storing the state of the sensitivity study (parameters, data, estimates).

y

a vector of model responses.

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.

Details

constraints list the sets of factors depending on each other through inequality constraints (see "Examples"). A same factor is not allowed to appear in multiple sets. Factors not appearing in constraints are assumed to be independent and follow each a uniform distribution on [0,1]. One Sobol' index is estimated for each independent factor or set of factors.

Missing values (i.e NA values) in the model responses are automatically handled by the function.

This function also supports multidimensional outputs (matrices in y or as output of model). In this case, aggregated Sobol' indices are returned (see sobolMultOut).

Value

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

call

the matched call.

X

a data.frame containing the design of experiments (concatenation of two replicated designs).

y

the responses used.

OA

the orthogonal array constructed (NULL if order=1).

V

the estimations of Variances of the Conditional Expectations (VCE) with respect to each factor.

S

the estimations of the Sobol' indices.

Warning messages

"The value entered for N is not the square of a prime number. It has been replaced by: "

when order=2, the number of levels of the orthogonal array must be a prime number. If N is not a square of a prime number, then this warning message indicates that it was replaced depending on the value of tail. If tail=TRUE (resp. tail=FALSE) the new value of N is equal to the square of the prime number preceding (resp. following) the square root of N.

"The value entered for N is not satisfying the constraint N \geq (d-1)^2. It has been replaced by: "

when order=2, the following constraint must be satisfied N \geq (d-1)^{2} where d is the number of independent factors or sets of factors. This warning message indicates that N was replaced by the square of the prime number following (or equals to) d-1.

Author(s)

Laurent Gilquin

References

L. Devroye, 1986, Non-Uniform Random Variate Generation. Springer-Verlag.

J. Jacques, C. Lavergne and N. Devictor, 2006, Sensitivity Analysis in presence of model uncertainty and correlated inputs. Reliability Engineering & System Safety, 91:1126-1134.

L. Gilquin, C. Prieur and E. Arnaud, 2015, Replication procedure for grouped Sobol' indices estimation in dependent uncertainty spaces, Information and Inference, 4:354-379.

J.Y. Tissot and C. Prieur, 2015, A randomized orthogonal orray-based procedure for the estimation of first- and second-order Sobol' indices, J. Statist. Comput. Simulation, 85:1358-1381.

See Also

sobolroalhs, sobolmara

Examples

library(boot)
library(numbers)

# Test case: the non-monotonic Sobol g-function
# (there are 8 factors, all following the uniform distribution on [0,1])

# Suppose we have the inequality constraints: X1 <= X3 and X4 <= X6.

# first-order sensitivity indices
x <- sobolroauc(model = sobol.fun, factors = 8, constraints = list(c(1,3),c(4,6)), 
                N = 1000, order = 1, nboot=100)
print(x)
plot(x)

library(ggplot2)
ggplot(x)

# closed second-order sensitivity indices
x <- sobolroauc(model = sobol.fun, factors = 8, constraints = list(c(1,3),c(4,6)), 
                N = 1000, order = 2, nboot=100)
print(x)
ggplot(x)