pivot_measure: Pivot Measure

Description

Calculate the pivot measure of the optimal transport between two-dimensional grids.

Usage

pivot_measure(x, ...)
# S3 method for otgrid
pivot_measure(
  x,
  y,
  p.1 = 2,
  p.2 = p.1,
  max.it = 100,
  tol = 1e-04,
  threads = 1,
  start.pivot = c("independent", "northwestcorner"),
  dual.method = c("discrete", "epsilon-discrete", "epsilon-histogram"),
  dual.params = list(),
  return.it = FALSE,
  ...
)
# S3 method for data.frame
pivot_measure(x, a, b, p.1 = 2, p.2 = p.1, ...)

Value

an object of class "otgridtransport" that contains the following elements:

`from`	an object of class `"otgrid"` the mass is transported from.
`to`	an object of class `"otgrid"` the mass is transported to.
`p.1`	the first power \(\geq 1\) of the cost function.
`p.2`	the second power \(\geq 1\) of the cost function.
`pivot`	a matrix representing the pivot measure.

If the Frank-Wolfe algorithm is used to approximate the pivot measure, the element conv indicates whether or not we can ensured that the error is less or equal to the given precision tol.

If return.it = TRUE, then it also contains the vectors costs and dualgaps of costs and dual gaps in each iteration.

Also note that the functions print and plot are available for objects of class "otgridtransport".

Arguments

x: an object of class "otgrid" the mass is to be transported from or a data frame with columns from, to and mass specifying the optimal transport plan.
...: further arguments (currently unused).
y: an object of class "otgrid" the mass is to be transported to.
p.1: the first power \(\geq 1\) of the cost.
p.2: the second power \(\geq 1\) of the cost.
max.it: the maximum number of iterations.
tol: the desired accuracy.
threads: number of threads to use.
start.pivot: the start pivot to use: matrix representing an actual coupling or "independent" or "northwestcorner".
dual.method: the name of the dual calculators to use: "discrete", "epsilon-discrete" or "epsilon-histogram".
dual.params: list of parameters for the dual calculators.
return.it: logical value specifying whether or not the costs and dual gaps in each iteration are to be returned .
a: an object of class "otgrid" the mass is to be transported from.
b: an object of class "otgrid" the mass is to be transported to.

Details

Denote with \(X_1 \times X_2\) and \(Y_1 \times Y_2\) the two-dimensional grids that x and y lie on, respectively. The pivot measure is a measure on \(Y_1 \times X_2\) that specifies the whole transport between x and y given that the cost is of the separable form \(c(x, y) = | x_1 - y_1 |^{p_1} + | x_2 - y_2 |^{p_2}\).

The pivot measure is approximated using the Frank-Wolfe algorithm. The algorithm starts with an initial guess (start.pivot), e.g., the independent coupling ("independent") or the north-west-corner rule ("northwestcorner"). Then, in each iteration step, the dual solutions of multiple one-dimensional transport problems are calculated and combined to give the gradient. To ensure differentiability, the dual solutions must be unique. There are three different calculators for the dual solutions, of which the last two ensure uniqueness:

name	description	`dual.params`
`"discrete"`	the distributions are basically unchanged, due to rounding errors the support points are moved by a small positive amount.	`right.margin = 1e-15`
`"epsilon-discrete"`	additionally, the support is made connected by uniformly adding \(\varepsilon\) mass.	+ `eps = 1e-8`
`"epsilon-histogram"`	additionally, each point mass is distributed uniformly in a bin around said point	+ `width = 1e-8`

A pivot measure can also be computed from an optimal transport plan.

Finally, the pivot measure can be used to calculate the full transport plan and cost.

Examples

Run this code

x <- otgrid(rbind(c(0, 0, 0, 0, 0, 0, 0, 0, 0),
                 c(0, 0, 1, 0, 0, 0, 0, 0, 0),
                 c(0, 1, 2, 1, 0, 0, 0, 0, 0),
                 c(0, 0, 1, 0, 0, 0, 0, 0, 0), 
                  0, 0, 0, 0, 0))
y <- otgrid(rbind(0, 0, 0, 0,
                 c(0, 0, 0, 0, 0, 0, 0, 0, 0),
                 c(0, 0, 0, 0, 0, 0, 1, 0, 0),
                 c(0, 0, 0, 0, 0, 1, 2, 1, 0),
                 c(0, 0, 0, 0, 0, 0, 1, 0, 0), 0))

pm <- pivot_measure(x, y, p.1 = 1, p.2 = 2, dual.method = "epsilon-discrete")

print(pm)
plot(pm)

# use pivot measure to calculate cost and plan
pm <- transport_cost(pm)
pm <- transport_df(pm)
print(pm)

# calculate pivot from plan
pm2 <- pivot_measure(pm$df, x, y)
plot(pm2)