sobol_matrices: Creation of the sample matrices

In arnaldpuy/sensobol: Computation of Variance-Based Sensitivity Indices

Creation of the sample matrices

Description

It creates the sample matrices to compute Sobol' first and total-order indices. If needed, it also creates the sample matrices required to compute second, third and fourth-order indices.

Usage

sobol_matrices(
  matrices = c("A", "B", "AB"),
  N,
  params,
  order = "first",
  type = "QRN",
  ...
)

Arguments

matrices	Character vector with the required matrices. The default is matrices = c("A", "B", "AB").
N	Positive integer, initial sample size of the base sample matrix.
params	Character vector with the name of the model inputs.
order	One of "first", "second", "third" or "fourth" to create a matrix to compute first, second, third or up to fourth-order Sobol' indices. The default is order = "first".
type	Approach to construct the sample matrix. Options are: type = "QRN" (default): It uses \insertCiteSobol1967;textualsensobol Quasi-Random Numbers. through a call to the function sobol of the randtoolbox package. type = "LHS": It uses a Latin Hypercube Sampling Design \insertCiteMcKay1979sensobol through a call to the function randomLHS of the lhs package. type = "R": It uses random numbers.
...	Further arguments in sobol.

Details

Before calling sobol_matrices, the user must decide which estimators will be used to compute first and total-order indices, for this option conditions the design of the sample matrix and therefore the argument matrices. See Table 3 in the vignette for further details on the specific sampling designs required by the estimators.

The user can select one of the following sampling designs:

• \mathbf{A}, \mathbf{B}, \mathbf{A}_B^{(i)}.

• \mathbf{A}, \mathbf{B}, \mathbf{B}_A^{(i)}.

• \mathbf{A}, \mathbf{B}, \mathbf{A}_B^{(i)}, \mathbf{B}_A^{(i)}.

If order = "first", the function creates an (N, 2k) matrix according to the approach defined by type, where the leftmost and the rightmost k columns are respectively allocated to the \mathbf{A} and the \mathbf{B} matrix. Depending on the sampling design, it also creates k \mathbf{A}_B^{(i)} (\mathbf{B}_A^{(i)}) matrices, where all columns come from \mathbf{A} (\mathbf{B}) except the i-th, which comes from \mathbf{B} (\mathbf{A}). All matrices are returned row-binded.

If order = "second", \frac{k!}{2!(k-2)!} extra (N, k) \mathbf{A}_B^{(ij)} (\mathbf{B}_A^{(ij)}) matrices are created, where all columns come from \mathbf{A} (\mathbf{B}) except the i-th and j-th, which come from \mathbf{B} (\mathbf{A}). These matrices allow the computation of second-order effects, and are row-bound to those created for first and total-order indices.

If order = "third", \frac{k!}{3!(k-3)!} extra (N, k) \mathbf{A}_B^{(ijl)} (\mathbf{B}_A^{(ijl)}) matrices are bound below those created for the computation of second-order effects. In these matrices, all columns come from \mathbf{A} (\mathbf{B}) except the i-th, the j-th and the l-th, which come from \mathbf{B} (\mathbf{A}). These matrices are needed to compute third-order effects, and are row-bound below those created for second-order effects.

The same process applies to create the matrices to compute fourth-order effects.

All columns are distributed in (0,1). If the uncertainty in some parameter(s) is better described with another distribution, the user should apply the required quantile inverse transformation to the column of interest once the sample matrix is produced.

Value

A numeric matrix where each column is a model input distributed in (0,1) and each row a sampling point.

References

\insertAllCited

Examples

# Define settings
N <- 100; params <- paste("X", 1:10, sep = ""); order <-  "third"

# Create sample matrix using Sobol' Quasi Random Numbers.
mat <- sobol_matrices(N = N, params = params, order = order)

# Let's assume that the uncertainty in X3 is better described
# with a normal distribution with mean 0 and standard deviation 1:
mat[, 3] <- qnorm(mat[, 3], 0, 1)

arnaldpuy/sensobol documentation built on Feb. 24, 2024, 12:32 a.m.