CompareOneToMany-function: Compare a reference spatial histogram to other histograms
In SpatialKWD: Spatial KWD for Large Spatial Maps

CompareOneToMany-function

R Documentation

Compare a reference spatial histogram to other histograms

Description

This function computes the Kantorovich-Wasserstein among a single reference histogram and a given list of other spatial histograms. All the histograms are defined over the same grid map.

The grid map is described by the two lists of N coordinates Xs and Ys, which specify the coordinates of the centroid of each tile of the map. For each tile i with coordinates Xs[i], Ys[i], we have a positive weight for each histogram.

The two lists of coordinates are passed to compareOneToMany as a matrix with N rows and two columns. The weights of the histograms are passed as a single matrix with N rows and M columns, where the first column is the reference histogram.

Usage

compareOneToMany(Coordinates, Weights, L = 3, recode = TRUE,
           method = "approx",    algorithm = "colgen",
           model="mincostflow",  verbosity = "silent",
           timelimit = 14400,    opt_tolerance = 1e-06,
           unbalanced = FALSE, unbal_cost = 1e+09, convex = TRUE)

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 reference 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:M]`: (Remaining Columns) Weights of the spatial histograms to be compared with the reference histogram. Data type: vector of positive doubles.
`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.
`unbalanced`	If equal to `True`, solve the problem with unbalanced masses.
`unbal_cost`	Cost for the arcs going from each point to the extra artificial bin.
`convex`	If equal to `True`, compute the convex hull of the input points.

Details

The function compareOneToMany(Coordinates, Weights, ...) computes the distances among a reference spatial histogram and a given set of other histograms. All the histograms are specified by the M columns of matrix Weights, and where the support points (i.e., centroids of each tile of the map) are defined by the coordinates given in Xs and Ys in the two columns of matrix Coordinates. The algorithm used to compute such distance depends on the parameters specified as optional arguments of the function.

The most important is the parameter L, which by default is equal to 3 (see compareOneToOne).

Value

Return an R List with the following named attributes:

distances: An array of M-1 KW-distances among the input histograms.
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 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
m <- 3
test2 <- matrix(runif((m+1)*N, 0, 1), ncol=(m+1))

# Compute distance
print("Compare one-to-many with approximate algorithm:")
d <- compareOneToMany(coordinates, Weights=test2, L=3, method="approx")
cat("L: 3, runtime:", d$runtime, " distances:", d$distance, "\n")

SpatialKWD documentation built on Dec. 9, 2022, 5:08 p.m.