Functionality and data access tools for transport planning, including origin-destination analysis, route allocation and modelling travel patterns.
stplanr is a package for sustainable transport planning with R.
It provides functions for solving common problems in transport planning and modelling, such as how to best get from point A to point B. The overall aim is to provide a reproducible, transparent and accessible toolkit to help people better understand transport systems and inform policy.
The initial work on the project was funded by the Department of Transport (DfT) as part of the development of the Propensity to Cycle Tool (PCT). The PCT uses origin-destination data as the basis of spatial analysis and modelling work to identify where bicycle paths are most needed. See the package vignette (e.g. via
vignette("introducing-stplanr")) or an academic paper on the Propensity to Cycle Tool (PCT) for more information on how it can be used. This README gives some basics.
stplanr should be useful to researchers everywhere. The function
route_graphhopper(), for example, works anywhere in the world using the graphhopper routing API and
read_table_builder() reads-in Australian data. We welcome contributions that make transport research easier worldwide.
Data frames representing flows between origins and destinations must be combined with geo-referenced zones or points to generate meaningful analyses and visualisations of 'flows' or origin-destination (OD) data. stplanr facilitates this with
od2line(), which takes flow and geographical data as inputs and outputs spatial data. Some example data is provided in the package:
Let's take a look at this data:
flow[1:3, 1:3] # typical form of flow data#> 920573 E02002361 E02002361 109#> 920575 E02002361 E02002363 38#> 920578 E02002361 E02002367 10cents[1:3,] # points representing origins and destinations#> class : SpatialPointsDataFrame#> features : 3#> extent : -1.546463, -1.511861, 53.8041, 53.81161 (xmin, xmax, ymin, ymax)#> coord. ref. : +init=epsg:4326 +proj=longlat +datum=WGS84 +no_defs +ellps=WGS84 +towgs84=0,0,0#> variables : 4#> names : geo_code, MSOA11NM, percent_fem, avslope#> min values : E02002382, Leeds 053, 0.408759, 2.284782#> max values : E02002393, Leeds 064, 0.458721, 2.856563
These datasets can be combined as follows:
travel_network <- od2line(flow = flow, zones = cents)w <- flow$All / max(flow$All) *10plot(travel_network, lwd = w)
The package can also allocate flows to the road network, e.g. with CycleStreets.net and the OpenStreetMap Routing Machine (OSRM) API interfaces. These are supported in
route_*() functions such as
Route functions take lat/lon inputs:
trip <-route_osrm(from = c(-1, 53), to = c(-1.1, 53))
and place names, found using the Google Map API:
We can replicate this call multiple times using
intrazone <- travel_network$Area.of.residence == travel_network$Area.of.workplacetravel_network <- travel_network[!intrazone,]t_routes <- line2route(travel_network, route_fun = route_osrm)plot(t_routes)
Another way to visualise this is with the leaflet package:
library(leaflet)leaflet() %>% addTiles() %>% addPolylines(data = t_routes)
For more examples,
overline is a function which takes a series of route-allocated lines, splits them into unique segments and aggregates the values of overlapping lines. This can represent where there will be most traffic on the transport system, as illustrated below.
t_routes$All <- travel_network$Allrnet <- overline(t_routes, attrib = "All", fun = sum)lwd <- rnet$All / mean(rnet$All)plot(rnet, lwd = lwd)points(cents)
To install the stable version, use:
The development version can be installed using devtools:
# install.packages("devtools") # if not already installeddevtools::install_github("ropensci/stplanr")library(stplanr)
stplanr depends on rgdal, which can be tricky to install.
On Ubuntu rgdal can be installed with:
sudo apt-get install r-cran-rgdal
Using apt-get ensures the system dependencies, such as gdal are also installed.
On Mac, homebrew can install gdal. Full instructions are provided here.
The current list of available functions can be seen with:
lsf.str("package:stplanr", all = TRUE)
To get internal help on a specific function, use the standard way.
stplanr imports many great packages that it depends on. Many thanks to the developers of these tools:
desc = read.dcf("DESCRIPTION")headings = dimnames(desc)[]fields = which(headings %in% c("Depends", "Imports", "Suggests"))pkgs = paste(desc[fields], collapse = ", ")pkgs = gsub("\n", " ", pkgs)strsplit(pkgs, ",")[]#>  "sp" " R (>= 3.0)" " curl"#>  " readr" " dplyr" " httr"#>  " jsonlite" " stringi" " stringr"#>  " lubridate" " maptools" " raster"#>  " rgdal" " rgeos" " openxlsx"#>  " methods" " R.utils" " geosphere"#>  " Rcpp (>= 0.12.1)" " igraph" " nabor"#>  " rlang" " sf" " testthat"#>  " knitr" " rmarkdown" " dodgr"
time_sleepwaits a period between each route request
dl_stats19(), see #270
line_via()for identifying intermediary points on a transport network
SpatialLinesNetwork()fixed (see #249)
geo_length()returns numeric vector of line lengths from sp or sf objects.
?route_graphhopperno longer mentions the depreciated 'bike2' profile - see #246
?route_osrmmentions that the public API only routes for cars - see #246
introducing-stplanrvignette to show new function and make more robust
sf::st_length(), used in
sfNetworkobjects: now only plots the geometry by default.
plot()for spatial networks.
sum_network_routes()fixed (see #240).
library(stplanr), making it less tied to sp. This is a continuation of the work to support sf and will make it easier for the package to work with alternative representations of geographic data.
geo_select_aeq.sf()was fixed by Jakub Nowosad in pull #238
od_aggregate.sf()was fixed making it much faster
bb2poly(). The new function can return polygons, points and matrix objects determined by the
outputargument. It also allows bounding boxes to be extended in metres, and scaled in x and y dimensions.
geo_code()now uses nominatim by default to find locations on the maps.
od_coords()takes a wide range of input data types to return a consistent output representing OD data as a data frame of origin and destination coordinates. This is used behind the scenes to make other functions more modular.
Plans for the next release
route()function for routing. This is more flexible and user-friendly than the existing
route_*()functions it enhances.
route_cyclestreet()now also called (correctly)
geo_code()function replaces dependency on RGoogleMaps
sum_network_routes()so it runs quicker - see pull/177.
find_network_nodes()- see e.g.
_each()dplyr functions replaced with equivalent
_allfunctions. See here for more.
introducing-stplanrvignette has been updated. It now provides a more basic introduction for people new to R for spatial and transport data.
line2route()has been refactored to improve error detection and allow
n_processesarguments. Thanks @nikolai-b. See pull/151 for details.
line_match()function added, a wrapper around
rgeos::gDistance(), to find similar routes.
sp_aggregate()have been added, to enable OD data to be aggregated to new geographic levels.
bidirectional = TRUEreturns a different result in
onewayid()is now a generic function, meaning it can handle spatial and non-spatial data
line2route()allow you to specify variables to join-by - also has updated and more sensible defaults
od_id_order()to put origin-destination ids in order, to identify 2 way duplicates (split out from
av_inclinebeing wrong now fixed
example(od2line)for an example.
destinationsfor showing how OD matrix with destinations can be converted to spatial data
list_outputallows the route information to be saved as a list, allowing
save_raw = TRUE(which does not return a
Spatialobject) to be passed to the
reproject() is a simple wrapper around
spTransform() that uses
crs_select_aeq() to convert a spatial object in geographic (lat/lon) coordinates
into on with projected coordinates, with units of 1 m. This is useful for various
spatial operations, such as finding the length and area of an object.
gprojected(), a function for performing GIS operations on a temporary, projected, version
of spatial objects.
line_bearing() to return the bearing of lines based on start and end points.
angle_diff() for finding the angular difference between lines: are they roughly parallel or perpendicular?
line2df() now works on lines with multiple vertices and is faster.
Fixes in the examples used to illustrate how
Update to OSRM functions to support API v5.
byvars in the
overline() function, to allow disaggregation of results by a grouping variable (see
Faster implementation of
od2line2(). Plan is to replace the original if no issues are found with new implementation.
od2odf() which converts OD data into a dataframe of origins and destinations (feeds
od2line2() but also useful as self-standing function).
buff_geo() allows the results to be exported to any coordinate reference system (CRS).
gprojected() generalises concept of
buff_geo(), building on
crs_select_aeq() to allow any GIS query to be conducted on a temporary projected version of spatial objects with geographical CRSs.
od_dist() can quickly calculate Euclidean distances of OD pairs without converting to spatial objects.
Bug fix in
onewayid() so it captures all lines.
Various improvements to documentation and code.
Interface to the Google Distance Matrix
API with dist_google.
New transport planning API added, with
route_transportapi_public (for testing).
line2route, allowing it to accept different routing funtions via the new argument
route_fun (for testing - tested with
route_fun = route_cyclestreet).
New functions for creating origin-destination data frames (
point2odf) and SpatialLinesDataFrames (
is_linepoint for identifying the number of vertices in spatial objects and whether the 'line' is really a point.
line2routerefactored, with 10 fold speed increases on large (1000+) batches of lines.
Addition of new class definition
SpatialLinesNetwork, methods for
summary and functions
allowing fast route calculations via igraph and other network analysis
Functions for removing beginning and end of lines:
toptailgs. Helper functions
Functionality for reading in the UK's stats19 data:
functions download, unzip and re-categorise the data.
read_table functions added for reading Australian OD data.
decode_gl added to decode Google polylines and other functions for
querying and reading data from OSRM services.
gtfs2sldf added to import GTFS routes as SpatialLinesDataFrames.