pivot_measure {gridOT}

Pivot Measure

Description

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

Usage

pivot_measure(x, ...)

## S3 method for class '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 class 'data.frame'
pivot_measure(x, a, b, p.1 = 2, p.2 = p.1, ...)

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.

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".

See Also

transport plan transport_df, transport cost transport_cost, two-dimensional grid otgrid, plot plot.otgridtransport

Examples

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)