Skip to contents

Calculate lower bounds for Optimal Transport sensitivity indices

Source: R/utils.R
lower_bound.Rd

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
)

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:

  • "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 from transport package.

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.

Value

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

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")
#> Using default values for solver sinkhorn 
dummy_lb <- lower_bound(y, M, bound = "dummy")
#> Using `rnorm` to generate the dummy
#> Using default values for solver sinkhorn 

# 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")
#> Using default values for solver transport