add_flowmap_list: Add a list of flow maps to a ggplot, creating a list of plots

In flowmapper: Draw Flows (Migration, Goods, Money, Information) on 'ggplot2' Plots

Add a list of flow maps to a ggplot, creating a list of plots

Description

Usage

add_flowmap_list(
  p,
  flowdat = NULL,
  od = NULL,
  nodes = NULL,
  outline_linewidth = 0.01,
  alpha = 0.8,
  nodes_alpha = 0.8,
  outline_col = "black",
  k_nodes = NULL,
  node_buffer_factor = 1.2,
  node_radius_factor = 1,
  edge_offset_factor = 1,
  node_fill_factor = NULL,
  edge_width_factor = 1.2,
  arrow_point_angle = 45,
  add_legend = "none",
  legend_nudge_x = 0,
  legend_nudge_y = 0,
  legend_col = "gray",
  legend_gradient = FALSE
)

Arguments

p	The plot to which the flowmap should be added.
flowdat	A list of input dataframes. See details below.
od	As an alternative to flowdat, a list of dataframes with the origin-destination pairs and the flow between them. Must contain the columns o, d, value. nodes must be provided as well. See details below.
nodes	As an alternative to flowdat, a list of dataframes with the nodes of the network. Must contain the columns name, x, y. See details below.
outline_linewidth	The linewidth of the outline of the arrows.
alpha	Opacity of the edges.
nodes_alpha	Opacity of the nodes.
outline_col	Color of the outline of the edges.
k_nodes	Number of clusters to group nodes into. If defined, nodes will be clustered hierarchically based on spatial proximity. By default, no clustering will be applied.
node_buffer_factor	Controls the distance between the nodes and the edges ( in multiple of the nodes' radii).
node_radius_factor	Controls the size of the nodes.
edge_offset_factor	Controls the distance between the parallel arrows.
node_fill_factor	Controls the downscaling of the fill of the nodes ( as to not outshine the edges ).
edge_width_factor	Controls the width of the edges.
arrow_point_angle	Controls the pointiness of the edges.
add_legend	Add a legend for width to the plot? Must be one of "none","bottom","top","left", or "right". (Experimental)
legend_nudge_x	Adjusts the horizontal position of the legend in map units.
legend_nudge_y	Adjusts the vertical position of the legend in map units.
legend_col	If add_legend, sets a monotone color for the legend. By default is "gray".
legend_gradient	If TRUE, the legend color will be a gradient from min to max flow. If FALSE, the legend will be a single color.

Details

This function creates a list of ggplot objects, each containing a flow map based on the provided data, which match in scales and are thus comparable. It is designed to work with a list of dataframes, where each dataframe represents for example a different day. The function prepares the data for plotting and then adds the flow map to the ggplot object. The function requires as inputs a list of input dataframes flowdat which contain for every combination of two nodes a and b the coordinates of these nodes as well as the intensity of flow between those nodes in both directions (a to b, b to a). The dataframe should have the following columns:

• id_a: The unique id of node a

• id_b: The unique id of node b

• xa: The x coordinate of node a

• ya: The y coordinate of node a

• xb: The x coordinate of node b

• yb: The y coordinate of node b

• flow_ab: The intensity of flow from node a to node b

• flow_ba: The intensity of flow from node b to node a

Alternatively, the function can take as input a list of dataframes od which contain the origin-destination pairs and the flow between them. The dataframe should have the following columns:

• o: The unique id of the origin node

• d: The unique id of the destination node

• value: The intensity of flow between the origin and destination

In this case, the function also requires a list of dataframes nodes which contain the coordinates of the nodes. The dataframe should have the following columns:

• name: The unique id of the node

• x: The x coordinate of the node

• y: The y coordinate of the node

The function will impose coord_equal() on the ggplot.

Inspired by flowmap.gl.

Value

A list of ggplots, each corresponding to the input ggplot with an additional polygon layer for the flow arrows and an additional polygon layer for the nodes. One output is generated for each input element (in flowdat, od, or nodes).

Author(s)

Johannes Mast

Examples

flowdatA <-
data.frame(
  id_a = c("X1","X2","X3","X3","X1"),
  id_b = c("X8","X7","X1","X8","X7"),
  xa = c(2,14,10,10,2),
  ya = c(6,10,9,9,6),
  xb = c(10,4,2,10,4),
  yb = c(4,10,6,4,10),
  flow_ab = c(2,1,1,1,1),
  flow_ba = c(8,1,1,1,2))

flowdatB <-
  data.frame(
    id_a = c("X1","X2","X3","X3","X1"),
    id_b = c("X8","X7","X1","X8","X7"),
    xa = c(2,14,10,10,2),
    ya = c(6,10,9,9,6),
    xb = c(10,4,2,10,4),
    yb = c(4,10,6,4,10),
    flow_ab = c(2,3,2,0.2,1),
    flow_ba = c(3,3,2,1,5))


flowdatC <-
  data.frame(
    id_a = c("X1","X2","X3","X3","X1"),
    id_b = c("X8","X7","X1","X8","X7"),
    xa = c(2,14,10,10,2),
    ya = c(6,10,9,9,6),
    xb = c(10,4,2,10,4),
    yb = c(4,10,6,4,10),
    flow_ab = c(1,1,2,1,1)/2,
    flow_ba = c(3,3,2,1,5)/3)


list_of_flowdats <- list(flowdatA, flowdatB, flowdatC)

library(ggplot2)
base_plot <-
  ggplot()+
  theme_bw()+
  coord_equal()

flowmap_plots <-
  base_plot |>
  add_flowmap_list(list_of_flowdats,
                   legend_gradient = TRUE,
                   add_legend = "bottom",
                   k_nodes = 3)

flowmapper documentation built on June 11, 2025, 5:08 p.m.