# FocusArea-function: Compute the KWD tranport distance within a given focus area In SpatialKWD: Spatial KWD for Large Spatial Maps

 FocusArea-function 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.

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

### 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,