sobolGP: Kriging-based sensitivity analysis
In sensitivity: Global Sensitivity Analysis of Model Outputs and Importance Measures

sobolGP

R Documentation

Kriging-based sensitivity analysis

Description

Perform a kriging-based global sensitivity analysis taking into account both the meta-model and the Monte-Carlo errors. The Sobol indices are estimated with a Monte-Carlo integration and the true function is substituted by a kriging model. It is built thanks to the function km of the package DiceKriging. The complete conditional predictive distribution of the kriging model is considered (not only the predictive mean).

Usage

sobolGP(
	model,
	type="SK",
	MCmethod="sobol",
	X1,
	X2, 
	nsim=100,
	nboot=1,
	conf = 0.95,
	sequential = FALSE, 
	candidate, 
	sequential.tot=FALSE,
	max_iter = 1000) 

## S3 method for class 'sobolGP'
ask(x, tot = FALSE, ...)

## S3 method for class 'sobolGP'
tell(x, y=NULL, xpoint=NULL, newcandidate=NULL, ...)

## S3 method for class 'sobolGP'
print(x, ...)

## S3 method for class 'sobolGP'
plot(x,...)

Arguments

`model`	an object of class `"km"` specifying the kriging model built from package `"DiceKriging"` (see `km`).
`type`	a character string giving the type of the considered kriging model. `"SK"` refers to simple kriging and `"UK"` refers to universal kriging (see `km`).
`MCmethod`	a character string specifying the Monte-Carlo procedure used to estimate the Sobol indices. The avaible methods are : `"sobol"`, `"sobol2002"`, `"sobol2007"`, `"sobolEff"` and `"soboljansen"`.
`X1`	a matrix representing the first random sample.
`X2`	a matrix representing the second random sample.
`nsim`	an integer giving the number of samples for the conditional Gaussian process. It is used to quantify the uncertainty due to the kriging approximation.
`nboot`	an integer representing the number of bootstrap replicates. It is used to quantify the uncertainty due to the Monte-Carlo integrations. We recommend to set `nboot = 100`.
`conf`	a numeric representing the confidence intervals taking into account the uncertainty due to the bootstrap procedure and the Gaussian process samples.
`sequential`	a boolean. If `sequential=TRUE`, the procedure provides a new point where to perform a simulation. It is the one minimizing the sum of the MAIN effect estimate variances. The variance is taken with respect to the conditional Gaussian process. The new point is selected in the points `candidate`.
`candidate`	a matrix representing the candidate points where the best new point to be simulated is selected. The lines represent the points and the columns represent the dimension.
`sequential.tot`	a boolean. If `sequential.tot=TRUE`, the procedure provides a new point where to perform the simulation. It is the one minimizing the sum of the TOTAL effect estimate. The variance is taken with respect to the conditional Gaussian process. The new point is selected in the points `candidate`.
`max_iter`	a numeric giving the maximal number of iterations for the propagative Gibbs sampler. It is used to simulate the realizations of the Gaussian process.
`x`	an object of class S3 `"sobolGP"` obtaining from the procedure `sobolGP`. It stores the results of the Kriging-based global sensitivity analysis.
`tot`	a boolean. If `tot=TRUE`, the procedure ask provides a point relative to the uncertainty of the total Sobol' indices (instead of first order' ones).
`xpoint`	a matrix representing a new point added to the kriging model.
`y`	a numeric giving the response of the function at `xpoint`.
`newcandidate`	a matrix representing the new candidate points where the best point to be simulated is selected. If `newcandidate=NULL`, these points correspond to `candidate` without the new point `xpoint`.
`...`	any other arguments to be passed

Details

The function ask provides the new point where the function should be simulated. Furthermore, the function tell performs a new kriging-based sensitivity analysis when the point x with the corresponding observation y is added.

Value

An object of class S3 sobolGP.

call : a list containing the arguments of the function sobolGP :
- X1 : X1
- X2 : X2
- conf : conf
- nboot : nboot
- candidate : candidate
- sequential : sequential
- max_iter : max_iter
- sequential.tot : sequential.tot
- model : model
- tot : tot
- method : MCmethod
- type : type
- nsim : nsim
S : a list containing the results of the kriging-based sensitivity analysis for the MAIN effects:
- mean : a matrix giving the mean of the Sobol index estimates.
- var : a matrix giving the variance of the Sobol index estimates.
- ci : a matrix giving the confidence intervals of the Sobol index estimates according to conf.
- varPG : a matrix giving the variance of the Sobol index estimates due to the Gaussian process approximation.
- varMC : a matrix giving the variance of the Sobol index estimates due to the Monte-Carlo integrations.
- xnew : if sequential=TRUE, a matrix giving the point in candidate which is the best to simulate.
- xnewi : if sequential=TRUE, an integer giving the index of the point in candidate which is the best to simulate.
T : a list containing the results of the kriging-based sensitivity analysis for the TOTAL effects:
- mean : a matrix giving the mean of the Sobol index estimates.
- var : a matrix giving the variance of the Sobol index estimates.
- ci : a matrix giving the confidence intervals of the Sobol index estimates according to conf.
- varPG : a matrix giving the variance of the Sobol index estimates due to the Gaussian process approximation.
- varMC : a matrix giving the variance of the Sobol index estimates due to the Monte-Carlo integrations.
- xnew : if sequential.tot=TRUE, a matrix giving the point in candidate which is the best to simulate.
- xnewi : if sequential.tot=TRUE, an integer giving the index of the point in candidate which is the best to simulate.

Author(s)

Loic Le Gratiet, EDF R&D

References

L. Le Gratiet, C. Cannamela and B. Iooss (2014), A Bayesian approach for global sensitivity analysis of (multifidelity) computer codes, SIAM/ASA J. Uncertainty Quantification 2-1, pp. 336-363.

Examples



library(DiceKriging)

#--------------------------------------#
# kriging model building
#--------------------------------------#

d <- 2; n <- 16
design.fact <- expand.grid(x1=seq(0,1,length=4), x2=seq(0,1,length=4))
y <- apply(design.fact, 1, branin) 

m <- km(design=design.fact, response=y)

#--------------------------------------#
# sobol samples & candidate points
#--------------------------------------#

n <- 1000
X1 <- data.frame(matrix(runif(d * n), nrow = n))
X2 <- data.frame(matrix(runif(d * n), nrow = n))

candidate <- data.frame(matrix(runif(d * 100), nrow = 100))

#--------------------------------------#
# Kriging-based Sobol
#--------------------------------------#

nsim <- 10 # put nsim <- 100
nboot <- 10 # put nboot <- 100

res <- sobolGP(
model = m,
type="UK",
MCmethod="sobol",
X1,
X2,
nsim = nsim,
conf = 0.95,
nboot = nboot,
sequential = TRUE,
candidate,
sequential.tot=FALSE,
max_iter = 1000
) 

res
plot(res)

x <- ask(res)
y <- branin(x)

# The following line doesn't work (uncorrected bug: 
#     unused argument in km(), passed by update(), eval(), tell.sobolGP() ??)
#res.new <- tell(res,y,x)
#res.new

sensitivity documentation built on Sept. 11, 2024, 9:09 p.m.