fortify.sim_list: Turn a collection of spatial interaction models into a data frame

Description

This function extracts from a collection of spatial interaction models (represented by a sim_list) a data frame in a long format, with one flow per row. This can be seen a collection oriented version of fortify.sim(). The resulting data frame is used by autoplot.sim_list() to produce summary graphics.

Usage

# S3 method for sim_list
fortify(
  model,
  data,
  flows = c("full", "destination", "attractiveness"),
  with_names = FALSE,
  normalisation = c("none", "origin", "full"),
  ...
)

Value

a data frame, see details

Arguments

model: a collection of spatial interaction models, a sim_list
data: not used
flows: "full" (default), "destination" or "attractiveness", see details.
with_names: specifies whether the extracted data frame includes location names (FALSE by default), see details.
normalisation: when flows="full", the flows can be reported without normalisation (normalisation="none", the default value) or they can be normalised, either to sum to one for each origin location (normalisation="origin") or to sum to one globally (normalisation="full").
...: additional parameters, not used currently

Details

The data frame produced by the method depends on the values of flows and to a lesser extent on the value of with_names. In all cases, the data frame has a configuration column that identify from which spatial interaction model the other values have been extracted: this is the index of the model in the original sim_list. Depending on flows we have the following representations:

if flows="full": this is the default case for which the full flow matrix of each spatial interaction model is extracted. The data frame contains 4 columns:
- origin_idx: identifies the origin location by its index from 1 to the number of origin locations
- destination_idx: identifies the destination location by its index from 1 to the number of destination locations
- flow: the flow between the corresponding location. By default, flows are normalised by origin location (when normalisation="origin"): the total flows originating from each origin location is normalised to 1. If normalisation="full", this normalisation is global: the sum of all flows in each model is normalised to 1. If normalisation="none" flows are not normalised.
- configuration: the spatial interaction model index
if flows="destination" or flows="attractiveness", the data frame contains 3 or 4 columns:
- destination: identifies the destination location by its index from 1 to the number of destination locations
- flow or attractiveness depending on the value of "flows": this contains either the destination_flow() or the attractiveness() of the destination location
- configuration: the spatial interaction model index
- name: the destination location names if with_names=TRUE (the column is not present if with_names=FALSE)

The normalisation operated when flows="full" can improve the readability of the graphical representation proposed in autoplot.sim_list() when the production constraints differ significantly from one origin location to another.

Examples

Run this code

positions <- matrix(rnorm(10 * 2), ncol = 2)
distances <- as.matrix(dist(positions))
production <- rep(1, 10)
attractiveness <- c(2, rep(1, 9))
flows_1 <- blvim(distances, production, 1.5, 1, attractiveness)
flows_2 <- blvim(distances, production, 1.25, 2, attractiveness)
all_flows <- sim_list(list(flows_1, flows_2))
ggplot2::fortify(all_flows) ## somewhat similar to a row bind of sim_df results
ggplot2::fortify(all_flows, flows = "destination")
destination_names(all_flows) <- letters[1:10]
ggplot2::fortify(all_flows, flows = "attractiveness", with_names = TRUE)