sobol_indices: Computation of Sobol' indices

View source: R/sobol_indices.R

sobol_indicesR Documentation

Computation of Sobol' indices

Description

It allows to compute Sobol' indices up to the fourth-order using state-of-the-art estimators.

Usage

sobol_indices(
  matrices = c("A", "B", "AB"),
  Y,
  N,
  params,
  first = "saltelli",
  total = "jansen",
  order = "first",
  boot = FALSE,
  R = NULL,
  parallel = "no",
  ncpus = 1,
  conf = 0.95,
  type = "norm"
)

Arguments

matrices

Character vector with the required matrices. The default is matrices = c("A", "B", "AB"). See sobol_matrices.

Y

Numeric vector with the model output obtained from the matrix created with sobol_matrices. The numeric vector should not contain any NA or NaN values.

N

Positive integer, the initial sample size of the base sample matrix created with sobol_matrices.

params

Character vector with the name of the model inputs.

first

Estimator to compute first-order indices. Options are:

  • first = "saltelli" \insertCiteSaltelli2010asensobol.

  • first = "jansen" \insertCiteJansen1999sensobol.

  • first = "sobol" \insertCiteSobol1993sensobol.

  • first = "azzini" \insertCiteAzzini2020sensobol.

total

Estimator to compute total-order indices. Options are:

  • total = "jansen" \insertCiteJansen1999sensobol.

  • total = "sobol" \insertCiteSobol2001sensobol.

  • total = "homma" \insertCiteHomma1996sensobol.

  • total = "janon" \insertCiteJanon2014sensobol.

  • total = "glen" \insertCiteGlen2012sensobol.

  • total = "azzini" \insertCiteAzzini2020sensobol.

  • total = "saltelli" \insertCiteSaltelli2008sensobol.

order

Whether to compute "first", "second", "third" or fourth-order Sobol' indices. Default is order = "first".

boot

Logical. If TRUE, the function bootstraps the Sobol' indices. If FALSE, it provides point estimates. Default is boot = FALSE.

R

Positive integer, number of bootstrap replicas. Default is NULL.

parallel

The type of parallel operation to be used (if any). If missing, the default is taken from the option "boot.parallel" (and if that is not set, "no"). For more information, check the parallel option in the boot function of the boot package.

ncpus

Positive integer: number of processes to be used in parallel operation: typically one would chose this to the number of available CPUs. Check the ncpus option in the boot function of the boot package.

conf

Confidence interval if boot = TRUE. Number between 0 and 1. Default is conf = 0.95.

type

Method to compute the confidence interval if boot = TRUE. Default is "norm". Check the type option in the boot function of the boot package.

Details

Any first and total-order estimator can be combined with the appropriate sampling design. Check Table 3 of the vignette for a summary of all possible combinations, and Tables 1 and 2 for a mathematical description of the estimators. If the analyst mismatches estimators and sampling designs, the function will generate an error and urge to redefine the sample matrices or the estimators.

For all estimators except \insertCiteAzzini2020;textualsensobol's and \insertCiteJanon2014;textualsensobol's, sobol_indices() calculates the sample mean as

\hat{f}_0=\frac{1}{2N} \sum_{v=1}^{N}(f(\mathbf{A})_v + f(\mathbf{B})_v)\,,

where N is the row dimension of the base sample matrix, and the unconditional sample variance as

\hat{V}(y) = \frac{1}{2N-1} \sum{v=1}^{N} ((f(\mathbf{A})_v - \hat{f})^2 + (f(\mathbf{B})_v - \hat{f})^2)\,,

where f(\mathbf{A})_v (f(\mathbf{B})_v) indicates the model output y obtained after running the model f in the v-th row of the \mathbf{A} (\mathbf{B}) matrix.

For the Azzini estimator,

\hat{V}(y) = \sum_{v=1}^{N} (f(\mathbf{A})_v - f(\mathbf{B})_v)^2 + (f(\mathbf{B}_A^{(i)})_v - f(\mathbf{A}_B^{(i)})_v) ^ 2

and for the Janon estimator,

\hat{V}(y)=\frac{1}{N} \sum_{v=1}^{N} \frac{f(\mathbf{A})_v^2 + f(\mathbf{A}_B^{(i)})_v^2}{2}-f_0^2

where f(\mathbf{A}_B^{(i)})_v (f(\mathbf{B}_A^{(i)})_v) is the model output obtained after running the model f in the v-th row of an \mathbf{A}_B^{(i)})_v (\mathbf{B}_A^{(i)})_v) matrix, where all columns come from \mathbf{A} (\mathbf{B}) except the i-th, which comes from \mathbf{B} (\mathbf{A}).

Value

A sensobol object.

References

\insertAllCited

See Also

Check the function boot for further details on the bootstrapping with regards to the methods available for the computation of confidence intervals in the type argument.

Examples

# Define settings
N <- 1000; params <- paste("X", 1:3, sep = ""); R <- 10

# Create sample matrix
mat <- sobol_matrices(N = N, params = params)

# Compute Ishigami function
Y <- ishigami_Fun(mat)

# Compute and bootstrap Sobol' indices
ind <- sobol_indices(Y = Y, N = N, params = params, boot = TRUE, R = R)

sensobol documentation built on May 29, 2024, 10:05 a.m.