sobol.decomposition.lsd: Sobol variance decomposition sensitivity analysis
In LSDsensitivity: Sensitivity Analysis Tools for LSD Simulations

sobol.decomposition.lsd

R Documentation

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)

Marcelo C. Pereira [aut, cre] (<https://orcid.org/0000-0002-8069-2734>)

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

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

LSDsensitivity documentation built on Sept. 21, 2024, 1:07 a.m.