% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sobol_matrices.R
\name{sobol_matrices}
\alias{sobol_matrices}
\title{Creation of the sample matrices}
\usage{
sobol_matrices(
  matrices = c("A", "B", "AB"),
  N,
  params,
  order = "first",
  type = "QRN",
  groups = NULL,
  ...
)
}
\arguments{
\item{matrices}{Character vector with the required matrices. The default
is \code{matrices = c("A", "B", "AB")}.}

\item{N}{Positive integer, initial sample size of the base sample matrix.}

\item{params}{Character vector with the name of the model inputs.}

\item{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
\code{order = "first"}. When \code{groups} is supplied, the order refers to
interactions between groups, not between individual parameters.}

\item{type}{Approach to construct the sample matrix. Options are:
\itemize{
\item \code{type = "QRN"} (default): It uses \insertCite{Sobol1967;textual}{sensobol} Quasi-Random Numbers.
through a call to the function \code{\link[randtoolbox]{sobol}} of the \code{randtoolbox} package.
\item \code{type = "LHS"}: It uses a Latin Hypercube Sampling Design
\insertCite{McKay1979}{sensobol} through a call
to the function \code{\link[lhs]{randomLHS}} of the \code{lhs} package.
\item \code{type = "R"}: It uses random numbers.
}}

\item{groups}{Optional grouping of the parameters into a strict partition.
Either \code{NULL} (the default; each parameter is its own group, i.e.
the standard Sobol' design), a named list of character vectors of parameter
names (e.g. \code{groups = list(g1 = "X1", g2 = c("X2", "X3"))}), or a
character vector of length \code{length(params)} aligned with \code{params}
that labels each parameter with its group (e.g.
\code{groups = c("g1", "g2", "g2")}). Every parameter in \code{params} must
appear in exactly one group. When \code{groups} is supplied, conditional
matrices swap all columns belonging to a group simultaneously, which is the
standard device used to handle correlated inputs in Sobol'-based sensitivity
analysis by moving them together.}

\item{...}{Further arguments in \code{\link[randtoolbox]{sobol}}.}
}
\value{
A numeric matrix where each column is a model input distributed in (0,1) and each row
a sampling point.
}
\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. Indices can be computed for individual parameters
or for groups of parameters (e.g. to handle correlated inputs by moving them
together).
}
\details{
Before calling \code{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 \code{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:
\itemize{
\item \eqn{\mathbf{A}}, \eqn{\mathbf{B}}, \eqn{\mathbf{A}_B^{(i)}}.
\item \eqn{\mathbf{A}}, \eqn{\mathbf{B}}, \eqn{\mathbf{B}_A^{(i)}}.
\item \eqn{\mathbf{A}}, \eqn{\mathbf{B}}, \eqn{\mathbf{A}_B^{(i)}}, \eqn{\mathbf{B}_A^{(i)}}.
}

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

If \code{order = "second"}, \eqn{\frac{k!}{2!(k-2)!}} extra \eqn{(N, k)} \eqn{\mathbf{A}_B^{(ij)}}
(\eqn{\mathbf{B}_A^{(ij)}}) matrices are created, where all columns come from \eqn{\mathbf{A}}
(\eqn{\mathbf{B}}) except the \eqn{i}-th and \eqn{j}-th, which come from \eqn{\mathbf{B}}
(\eqn{\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 \code{order = "third"}, \eqn{\frac{k!}{3!(k-3)!}} extra \eqn{(N, k)} \eqn{\mathbf{A}_B^{(ijl)}}
(\eqn{\mathbf{B}_A^{(ijl)}}) matrices are bound below those created
for the computation of second-order effects. In these matrices, all columns come from \eqn{\mathbf{A}}
(\eqn{\mathbf{B}}) except the \eqn{i}-th, the \eqn{j}-th and the \eqn{l}-th, which come from \eqn{\mathbf{B}}
(\eqn{\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.

When \code{groups} is supplied, the construction is identical except that the
index \eqn{i} (or \eqn{(i,j)}, \eqn{(i,j,l)}, \eqn{(i,j,l,m)}) ranges over
groups rather than individual parameters: a single conditional matrix
\eqn{\mathbf{A}_B^{(g)}} swaps all columns of group \eqn{g} from
\eqn{\mathbf{A}} to \eqn{\mathbf{B}} simultaneously. The number of conditional
matrices appended therefore depends on the number of groups \eqn{G} rather
than on \eqn{k}: \eqn{G} for first-order, \eqn{\binom{G}{2}} for second-order,
and so on. Downstream, \code{\link{sobol_indices}} interprets each conditional
block as a group-wise effect.

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.
}
\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)

# Grouped design: treat X2 and X3 as a single group (e.g. because they
# are correlated and should be moved together).
params <- paste("X", 1:4, sep = "")
groups <- list(g1 = "X1", g2 = c("X2", "X3"), g3 = "X4")
mat_g <- sobol_matrices(N = 100, params = params, groups = groups)
}
\references{
\insertAllCited{}
}
