FocusArea-function: Compute the KWD tranport distance within a given focus area

Description Usage Arguments Details Value See Also Examples

Description

This function computes the Kantorovich-Wasserstein distance within a given focus area embedded into a large region described as a grid map. Both the focus and the embedding areas are are described by spatial histograms, similarly to the input data of the other functions of this package.

The grid map is described by the two lists Xs and Ys of N coordinates, which specify the coordinates of the centroid of every single tile. For each tile i with coordinates Xs[i], Ys[i], we have an entry in the two lists of weights W1 and W2, one for the first histograms, and the other for the second histogram.

The two lists of coordinates Xs and Ys are passed to the focusArea function as a matrix with N rows and two columns. The two lists of weights W1 and W2 are passed as a matrix with N rows and two columns, a column for each histogram.

The focus area is specified by three parameters: the coordinates x and y of the center of the focus area, and the (circular) radius of the focus area. The pair of coordinates (x,y) must correspond to a pair of coordinates contained in the vectors Xs,Ys. Every tile whose distance is less or equal to the radius will be included in the focus area.

The focus area by default is circular, that is, the area is based on a L_2 norm. By setting the parameter area to the value linf it is possible to obtain a squared focus area, induced by the norm L_infinity.

Usage

1
2
3
4
5
6
focusArea(Coordinates, Weights, x, y, radius,
           L = 3, recode = TRUE,
           method = "approx",    algorithm = "colgen",
           model="mincostflow",  verbosity = "silent",
           timelimit = 14400,    opt_tolerance = 1e-06,
           area = "l2")

Arguments

Coordinates

A Matrix with N rows and two columns:

  • Coordinates[,1]: (First Column) Vector of horizontal coordinates of the centroids of each tile of the map (Xs). Data type: vector of positive integers.

  • Coordinates[,2]: (Second Column) Vector of vertical coordinates of the centroids of each tile of the map (Ys). Data type: vector of positive integers.

Weights

A Matrix of positive weights of the tiles specified by Coordinates.

  • Weights[,1]: (First Column) Weights of the embedding spatial histogram, a weight for each tile located at position Xs[i], Ys[i] for i=1,...N. Data type: vector of positive doubles.

  • Weights[,2]: (Second Column) Weights of the spatial histogram of the focus area, a weight for each tile located at position Xs[i], Ys[i] for i=1,...N. All the weights outside the focus area should be equal to zero. Data type: vector of positive doubles.

x

Horizontal coordinate of the centroid of the focus area.

y

Vertical coordinate of the centroid of the focus area.

radius

The radius of the focus area.

L

Approximation parameter. Higher values of L give a more accurate solution, but they require a longer running time. Data type: positive integer.

recode

If equal to True, recode the input coordinates as consecutive integers.

method

Method for computing the KW distances: exact or approx.

algorithm

Algorithm for computing the KW distances: fullmodel or colgen.

model

Model for building the underlying network: bipartite or mincostflow.

verbosity

Level of verbosity of the log: silent, info, or debug.

timelimit

Time limit in second for running the solver.

opt_tolerance

Numerical tolerance on the negative reduced cost for the optimal solution.

area

Type of norm for delimiting the focus area: l2 denotes a circular area of radius, linf denotes a squared area.

Details

The function focusArea(Coordinates, Weights, x, y, radius, ...) computes the KW distance within a focus area by implicitly considering the surrounding larger area. The mass contained within the focus area is transported to a destination either within or outside the focus area. All the mass contained outside the focus area could be used to balance the mass within the focus area.

Value

Return an R List with the following named attributes:

See Also

See also compareOneToOne, compareOneToMany, compareAll, Histogram2D, and Solver.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# Define a simple example
library(SpatialKWD)

# Random coordinates
N = 90
Xs <- as.integer(runif(N, 0, 31))
Ys <- as.integer(runif(N, 0, 31))
coordinates <- matrix(c(Xs, Ys), ncol=2, nrow=N)

# Random weights
test1 <- matrix(runif(2*N, 0, 1), ncol=2, nrow=N)

# Compute distance
print("Compare one-to-one with exact algorithm:")
d <- focusArea(coordinates, Weights=test1,
                x=15, y=15, radius=5,
                method="exact", recode=TRUE, verbosity = "info")
cat("runtime:", d$runtime, " distance:", d$distance,
    " nodes:", d$nodes, " arcs:", d$arcs, "\n")

SpatialKWD documentation built on May 7, 2021, 5:07 p.m.