sobol.decomposition.lsd {LSDsensitivity}

Sobol variance decomposition sensitivity analysis

Description

This function performs the global sensitivity analysis of a previously fitted meta-model using the Sobol variance decomposition method (Saltelli et al., 2008). If no model is supplied, uses a B-spline smoothing interpolation model.

Usage

sobol.decomposition.lsd( data, model = NULL, krig.sa = FALSE, sa.samp = 1000 )

Arguments

data

an object created by a previous call to read.doe.lsd which contains all the required experimental data for the analysis.

model

an object created by a previous call to kriging.model.lsd or polynomial.model.lsd which contains the meta-model estimated hyper-parameters. If no model is supplied (the default), performs the decomposition directly over the experimental data assuming a B-spline smoothing interpolation model.

krig.sa

logical: use alternative Kriging-specific algorithm if TRUE (see sobolGP). Default is FALSE. Applicable only to Kriging meta-models.

sa.samp

integer: number of samples to use in sensitivity analysis. The default is 1000.

Details

This function performs the global sensitivity analysis on a meta-model, previously estimated with kriging.model.lsd or polynomial.model.lsd, using the Sobol variance decomposition method (Saltelli et al., 2008).

This function is a wrapper to the functions fast99 and sobolGP in sensitivity-package.

Value

The function returns an object/list of class kriging-sa or polynomial-sa, according to the input meta-model, containing several items:

metamodel

an object/list of class fast99 containing the estimated total and conditional variances for all the meta-model factors.

sa

a print-ready data frame with the Sobol indexes for each factor.

topEffect

a vector containing the indexes to the three most influential factors, automatically calculated (if factorX = 0) or according to the order pre-selected by the user.

If no model is supplied and a B-spline smoothing interpolation model cannot be fitted, returns NULL.

Note

See the note in LSDsensitivity-package for step-by-step instructions on how to perform the complete sensitivity analysis process using LSD and R.

Author(s)

NA

References

Saltelli A, Ratto M, Andres T, Campolongo F, Cariboni J, Gatelli D, Saisana M, Tarantola S (2008) Global sensitivity analysis: the primer. Wiley, New York

See Also

read.doe.lsd(), kriging.model.lsd(), polynomial.model.lsd()

fast99(), sobolGP() in sensitivity-package

Examples

# get the example directory name
path <- system.file( "extdata/sobol", package = "LSDsensitivity" )

# Steps to use this function:
# 1. define the variables you want to use in the analysis
# 2. load data from a LSD simulation saved results using read.doe.lsd
# 3. fit a Kriging (or polynomial) meta-model using kriging.model.lsd
# 4. perform the sensitivity analysis applying sobol.decomposition.lsd

lsdVars <- c( "var1", "var2", "var3" )         # the definition of existing variables

dataSet <- read.doe.lsd( path,                 # data files folder
                         "Sim3",               # data files base name (same as .lsd file)
                         "var3",               # variable name to perform the sensitivity analysis
                         does = 2,             # number of experiments (data + external validation)
                         saveVars = lsdVars )  # LSD variables to keep in dataset

model <- kriging.model.lsd( dataSet )          # estimate best Kriging meta-model

SA <- sobol.decomposition.lsd( dataSet,        # LSD experimental data set
                               model )         # estimated meta-model

print( SA$topEffect )                          # indexes to the top 3 factors
print( SA$sa )                                 # Sobol indexes table
barplot( t( SA$sa ) )                          # plot Sobol indexes chart