R: Compute the KWD tranport distance within a given focus area

FocusArea-function {SpatialKWD}

R Documentation

Compute the KWD tranport distance within a given focus area

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

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:

distance: The value of the KW-distance between the two input areas.
status: Status of the solver used to compute the distances.
runtime: Overall runtime in seconds to compute all the distances.
iterations: Overall number of iterations of the Capacitated Network Simplex algorithm.
nodes: Number of nodes in the network model used to compute the distances.
arcs: Number of arcs in the network model used to compute the distances.

Examples

# 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")

[Package SpatialKWD version 0.4.1 Index]