Compute the diversity of the destination locations in a spatial interaction model

This function computes the diversity of the destination locations according to different definitions that all aim at estimating a number of active destinations, i.e., the number of destination locations that receive a "significant fraction" of the total flow or that are attractive enough. The function applies also to a collection of spatial interaction models as represented by a sim_list.

Usage

diversity(
  sim,
  definition = c("shannon", "renyi", "ND", "RW"),
  order = 1L,
  activity = c("destination", "attractiveness"),
  ...
)

# S3 method for class 'sim'
diversity(
  sim,
  definition = c("shannon", "renyi", "ND", "RW"),
  order = 1L,
  activity = c("destination", "attractiveness"),
  ...
)

# S3 method for class 'sim_list'
diversity(
  sim,
  definition = c("shannon", "renyi", "ND", "RW"),
  order = 1L,
  activity = c("destination", "attractiveness"),
  ...
)

Arguments

sim: a spatial interaction model object (an object of class sim) or a collection of spatial interaction models (an object of class sim_list)
definition: diversity definition "shannon" (default), "renyi" (see details) or a definition supported by terminals()
order: order of the Rényi entropy, used only when definition="renyi"
activity: specifies whether the diversity is computed based on the destination flows (for activity="destination", the default case) or on the attractivenesses (for activity="attractiveness").
...: additional parameters

Value

the diversity of destination flows (one value per spatial interaction model)

Details

In general, the activity of a destination location is measured by its incoming flow a.k.a. its destination flow. If $Y$ is a flow matrix, the destination flows are computed as follows

$$\forall j,\quad D_j=\sum_{i=1}^{n}Y_{ij},$$

for each destination $j$ (see destination_flow()). This is the default calculation mode in this function (when the parameter activity is set to "destination").

For dynamic models produced by blvim(), the destination attractivenesses can be also considered as activity measures. When convergence occurs, the values are identical, but prior convergence they can be quite different. When activity is set to "attractiveness", the diversity measures are computed using the same formula as below but with $D_j$ replaced by $Z_j$ (as given by attractiveness()).

To compute their diversity using entropy based definitions, the activities are first normalised to be interpreted as a probability distribution over the destination locations. For instance for destination flows, we use

$$\forall j,\quad p_j=\frac{D_j}{\sum_{k=1}^n D_k}.$$

The most classic diversity index is given by the exponential of Shannon's entropy (parameter definition="shannon"). This gives

$$\text{diversity}(p, \text{Shannon})=\exp\left(-\sum_{k=1}^n p_k\ln p_k\right).$$

Rényi generalized entropy can be used to define a collection of other diversity metrics. The Rényi diversity of order $\gamma$ is the exponential of the Rényi entropy of order $\gamma$ of the $p$ distribution, that is

$$\text{diversity}(p, \text{Rényi}, \gamma)=\exp\left(\frac{1}{1-\gamma}\ln \left(\sum_{k=1}^np_k^\gamma\right)\right).$$

This is defined directly only for $\gamma\in]0,1[\cup ]1,\infty[$, but extensions to the limit case are straightforward:

$\gamma=1$ is Shannon's entropy/diversity
$\gamma=0$ is the max-entropy, here $\ln(n)$ and thus the corresponding diversity is the number of locations
$\gamma=\infty$ is the min-entropy, here $-\log \max_{k}p_k$ and thhe corresponding diversity is $\frac{1}{\max_{k}p_k}$

The definition parameter specifies the diversity used for calculation. The default value is shannon for Shannon's entropy (in this case the order parameter is not used). Using renyi gives access to all Rényi diversities as specified by the order parameter. Large values of order tend to generate underflows in the calculation that will trigger the use of the min-entropy instead of the exact Rényi entropy.

In addition to those entropy based definition, terminal based calculations are also provided. Using any definition supported by the terminals() function, the diversity is the number of terminals identified. Notice this applies only to interaction models in which origin and destination locations are identical, i.e. when the model is not bipartite. In addition, the notion of terminals is based on destination flows and cannot be used with activities based on attractivenesses. definition can be:

"ND" for the original Nystuen and Dacey definition
"RW" for the variant by Rihll and Wilson

See terminals() for details.

When applied to a collection of spatial interaction models (an object of class sim_list) the function uses the same parameters (definition and order) for all models and returns a vector of diversities. This is completely equivalent to grid_diversity().

References

Jost, L. (2006), "Entropy and diversity", Oikos, 113: 363-375. doi:10.1111/j.2006.0030-1299.14714.x

Examples

distances <- french_cities_distances[1:15, 1:15] / 1000 ## convert to km
production <- log(french_cities$population[1:15])
attractiveness <- rep(1, 15)
flows <- blvim(distances, production, 1.5, 1 / 100, attractiveness,
  bipartite = FALSE
)
diversity(flows)
#> [1] 5.612398
sim_converged(flows)
#> [1] TRUE
## should be identical because of convergence
diversity(flows, activity = "attractiveness")
#> [1] 5.612397
diversity(flows, "renyi", 2)
#> [1] 4.734579
diversity(flows, "RW")
#> [1] 7