In ITSLeeds/od: Manipulate and Map Origin-Destination Data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

od

The goal of od is to provide functions and example datasets for working with origin-destination (OD) datasets. OD datasets represent "the volume of travel between zones or locations" (Carey et al. 1981) and are central to modelling city to global scale transport systems (Simini et al. 2012).

Installation

You can install the released version of od from CRAN with:

install.packages("od")

Install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("itsleeds/od", build_vignettes = TRUE)

The examples below provide a gentle introduction to the package. For a more detailed introduction to the package and OD data in general, see the od vignette online at itsleeds.github.io/od or by executing the following command after installing the package:

vignette("od")

You can find descriptions of each of the package's functions with reproducible examples on the package's web page: https://itsleeds.github.io/od/reference/index.html

Motivation

The package originated as a set of functions in the package stplanr for working with origin-destination data. The od2line() function, for example, takes a data frame and a spatial object as inputs and outputs geographic lines representing movement between origins and destinations:

library(od) # load example datasets
od_data_df # OD data as data frame
od_data_centroids[1:2, ]
desire_lines_stplanr = stplanr::od2line(od_data_df, od_data_centroids)
desire_lines_stplanr[1:2, 1:9]

It works great, and is plenty fast enough for most applications, but there are some issues with stplanr::od2line() (which also affect the other od_*() functions in stplanr):

The function is a commonly needed and low-level function, buried in a large package, reducing 'findability'
To get the function you must install stplanr plus its numerous dependencies
The function has not been optimised
It has no class definition of 'od' data

The od package addresses the first three of these issues (it may at some point define a class for od objects but there are no immediate plans to do so).

The equivalent code in the od package is as follows:

desire_lines_od = od_to_sf(od_data_df, od_data_centroids)

The result is an sfc object that has the same geometry as the output from od2line:

desire_lines_od$geometry[1:2]
desire_lines_stplanr$geometry[1:2]

These are 'desire lines' representing the shortest (straight line) path between two centroids and can plotted using geographic data and mapping packages such as sf, mapview, tmap and mapdeck, e.g.:

plot(desire_lines_od)
plot(desire_lines_stplanr$geometry)

By default the package uses the sfheaders package to create sf objects for speed. You can can also specify sf outputs as follows:

desire_lines_od_sf1 = od_to_sf(od_data_df, od_data_centroids)

Performance

Benchmark on a small dataset:

nrow(od_data_df)
bench::mark(check = FALSE, max_iterations = 100,
  stplanr = stplanr::od2line(od_data_df, od_data_zones),
  od = od_to_sfc(od_data_df, od_data_zones),
  od_sf1 = od_to_sf(od_data_df, od_data_zones),
  od_sf2 = od_to_sf(od_data_df, od_data_zones, package = "sf", crs = 4326)
)

Related open source projects

stplanr is an R package package designed to support transport planning, with a focus on geographic transport datasets and many functions for working with OD data in the od function family.
cartography is an R package with functions for working with OD data, including getLinkLayer()
gravity is an R package for developing 'gravity models' to estimate flow between zones
flowmap.gl, a JavaScript package for visualising OD data
Arabesque is another JavaScript project for working with OD data