gsaot (version 0.2.0)

lower_bound: Calculate lower bounds for Optimal Transport sensitivity indices

Description

Calculate lower bounds for Optimal Transport sensitivity indices

Usage

lower_bound(
  y,
  M,
  bound = "dummy",
  dummy_optns = NULL,
  cost = "L2",
  discrete_out = FALSE,
  solver = "sinkhorn",
  solver_optns = NULL,
  scaling = TRUE
)

Value

An object of class gsaot_indices for bound="dummy" or a scalar for bound="entropic".

Arguments

y

An array or a matrix containing the output values.

M

A scalar representing the number of partitions for continuous inputs.

bound

(default "dummy") A string defining the type of lower bound to compute. Should be "dummy" or "entropic". See details for more information.

dummy_optns

(default NULL) A list containing the options on the distribution of the dummy variable. See details for more information.

cost

(default "L2") A string or function defining the cost function of the Optimal Transport problem. It should be "L2" or a function taking as input y and returning a cost matrix. If cost="L2", ot_indices uses the squared Euclidean metric.

discrete_out

(default FALSE) Logical, by default the output sample in y are equally weighted. If discrete_out=TRUE, the function tries to create an histogram of the realizations and to use the histogram as weights. It works if the output is discrete or mixed and the number of realizations is large. The advantage of this option is to reduce the dimension of the cost matrix.

solver

Solver for the Optimal Transport problem. Currently supported options are:

• "1d", the one-dimensional analytic solution.

• "wasserstein-bures", the Wasserstein-Bures solution.

• "sinkhorn" (default), the Sinkhorn's solver cuturi2013sinkhorngsaot.

• "sinkhorn_log", the Sinkhorn's solver in log scale peyre2019computationalgsaot.

• "transport", a solver of the non regularized OT problem using transport::transport().

solver_optns

(optional) A list containing the options for the Optimal Transport solver. See details for allowed options and default ones.

scaling

(default TRUE) Logical that sets whether or not to scale the cost matrix.

Details

The function allows the computation of two different lower bounds. With bound="dummy", the function samples from a distribution defined in dummy_optns (by default a standard normal), independent from the output y and then computes the indices using the algorithm specified in solver. Under the hood, lower_bound calls the other available functions in the package:

• ot_indices_1d() (for solver="1d")

• ot_indices_wb() (for solver="wasserstein-bures")

• ot_indices() (for solver %in% c("sinkhorn", "sinkhorn_log", "wasserstein")) The user can choose the distribution of the dummy variable using the argument dummy_optns. dummy_optns should be a named list with at least a term called "distr" defining the sampling function. The other terms in the list are used as arguments to the sampling function. With bound="entropic", the function computes the lower bound of the entropic indices. In this case, solver should be either "sinkhorn" or "sinkhorn_log"

Examples

N <- 1000

mx <- c(1, 1, 1)
Sigmax <- matrix(data = c(1, 0.5, 0.5, 0.5, 1, 0.5, 0.5, 0.5, 1), nrow = 3)

x1 <- rnorm(N)
x2 <- rnorm(N)
x3 <- rnorm(N)

x <- cbind(x1, x2, x3)
x <- mx + x %*% chol(Sigmax)

A <- matrix(data = c(4, -2, 1, 2, 5, -1), nrow = 2, byrow = TRUE)
y <- t(A %*% t(x))

M <- 25

sink_lb <- lower_bound(y, M, bound = "entropic")
dummy_lb <- lower_bound(y, M, bound = "dummy")

# Custom sampling funtion and network simplex solver
dummy_optns <- list(distr = "rgamma", shape = 3)
dummy_lb_cust <- lower_bound(y, M, bound = "dummy",
                                  dummy_optns = dummy_optns,
                                  solver = "transport")