Learn R Programming

stplanr

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, as outlined in a paper about the package, and the potential for open source software in transport planning in general, published in the R Journal.

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), a web application to explore current travel patterns and cycling potential at zone, desire line, route and route network levels (see www.pct.bike and click on a region to try it out). The basis of the methods underlying the PCT is origin-destination data, which are used to highlight where many short distance trips are being made, and estimate how many could switch to cycling. The results help identify where cycleways are most needed, an important component of sustainable transport planning infrastructure engineering and policy design.

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 provides some basics.

Much of the work supports research undertaken at the Leeds’ Institute for Transport Studies (ITS) but stplanr should be useful to transport researchers and practitioners needing free, open and reproducible methods for working with geographic data everywhere.

Key functions

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:

library(stplanr)

Let’s take a look at this data:

od_data_sample[1:3, 1:3] # typical form of flow data
#> # A tibble: 3 × 3
#>   geo_code1 geo_code2   all
#>   <chr>     <chr>     <dbl>
#> 1 E02002361 E02002361   109
#> 2 E02002361 E02002363    38
#> 3 E02002361 E02002367    10
cents_sf[1:3,] # points representing origins and destinations
#>       geo_code  MSOA11NM percent_fem  avslope             geometry
#> 1708 E02002384 Leeds 055    0.458721 2.856563 -1.546463, 53.809517
#> 1712 E02002382 Leeds 053    0.438144 2.284782 -1.511861, 53.811611
#> 1805 E02002393 Leeds 064    0.408759 2.361707 -1.524205, 53.804098

These datasets can be combined as follows:

travel_network <- od2line(flow = od_data_sample, zones = cents_sf)
w <- flow$all / max(flow$all) *10
plot(travel_network, lwd = w)

stplanr has many functions for working with OD data. See the stplanr-od vignette for details.

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_cyclestreets and route_osrm():

Routing can be done using a range of back-ends and using lat/lon or desire line inputs with the route() function, as illustrated by the following commands which calculates the route between Fleet Street and Southwark Street over the River Thames on Blackfriars Bridge in London:

library(osrm)
#> Data: (c) OpenStreetMap contributors, ODbL 1.0 - http://www.openstreetmap.org/copyright
#> Routing: OSRM - http://project-osrm.org/
trip <- route(
  from = c(-0.11, 51.514),
  to = c(-0.10, 51.506),
  route_fun = osrmRoute,
  returnclass = "sf"
  )
#> Warning: "returnclass" is deprecated.
#> Most common output is sf
plot(trip)

You can also use and place names, found using the Google Map API:

trip2 <- route(
  from = "Leeds",
  to = "Bradford",
  route_fun = osrmRoute,
  returnclass = "sf"
  )
#> Warning: "returnclass" is deprecated.
#> Most common output is sf
plot(trip2)

We can replicate this call multiple times with the l argument in route():

desire_lines <- travel_network[2:6, ]

Next, we’ll calculate the routes:

routes <- route(
  l = desire_lines,
  route_fun = osrmRoute,
  returnclass = "sf"
  )
#> Warning: "returnclass" is deprecated.
#> Warning: "returnclass" is deprecated.
#> Warning: "returnclass" is deprecated.
#> Warning: "returnclass" is deprecated.
#> Warning: "returnclass" is deprecated.
plot(sf::st_geometry(routes))
plot(desire_lines, col = "red", add = TRUE)
#> Warning in plot.sf(desire_lines, col = "red", add = TRUE): ignoring all but the
#> first attribute

For more examples, example("route").

overline() 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 demonstrated in the following code chunk.

routes$foot <- desire_lines$foot
rnet <- overline(routes, attrib = "foot")

The resulting route network, with segment totals calculated from overlapping parts for the routes for walking, can be visualised as follows:

plot(rnet["foot"], lwd = rnet$foot)

The above plot represents the number walking trips made (the ‘flow’) along particular segments of a transport network.

Policy applications

The examples shown above, based on tiny demonstration datasets, may not seem particularly revolutionary. At the city scale, however, this type of analysis can be used to inform sustainable transport policies, as described in papers describing the Propensity to Cycle Tool (PCT), and its application to calculate cycling to school potential across England.

Results generated by stplanr are now part of national government policy: the PCT is the recommended tool for local and regional authorities developing strategic cycle network under the Cycling and Walking Infrastructure Strategy (CWIS), which is part of the Infrastructure Act 2015. stplanr is helping dozens of local authorities across the UK to answer the question: where to prioritise investment in cycling? In essence, stplanr was designed to support sustainable transport policies.

There are many other research and policy questions that functions in stplanr, and other open source software libraries and packages, can help answer. At a time of climate, health and social crises, it is important that technology is not only sustainable itself (e.g. as enabled by open source communities and licenses) but that it contributes to a sustainable future.

Installation

To install the stable version, use:

install.packages("stplanr")

The development version can be installed using devtools:

# install.packages("devtools") # if not already installed
devtools::install_github("ropensci/stplanr")
library(stplanr)

Installing stplanr on Linux and Mac

stplanr depends on sf. Installation instructions for Mac, Ubuntu and other Linux distros can be found here: https://github.com/r-spatial/sf#installing

Funtions, help and contributing

The current list of available functions can be seen on the package’s website at docs.ropensci.org/stplanr/, or with the following command:

lsf.str("package:stplanr", all = TRUE)

To get internal help on a specific function, use the standard way.

?od2line

To contribute, report bugs or request features, see the issue tracker.

Further resources / tutorials

Want to learn how to use open source software for reproducible sustainable transport planning work? Now is a great time to learn. Transport planning is a relatively new field of application in R. However, there are already some good resources on the topic, including (any further suggestions: welcome):

Meta

  • Please report issues, feature requests and questions to the github issue tracker
  • License: MIT
  • Get citation information for stplanr in R doing citation(package = 'stplanr')
  • This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Copy Link

Version

Install

install.packages('stplanr')

Monthly Downloads

1,827

Version

1.2.2

License

MIT + file LICENSE

Issues

24

Pull Requests

2

Stars

422

Forks

66

Maintainer

Robin Lovelace

Last Published

August 22nd, 2024

Functions in stplanr (1.2.2)

geo_projected

Perform GIS functions on a temporary, projected version of a spatial object
islines

Do the intersections between two geometries create lines?
line_midpoint

Find the mid-point of lines
gsection

Function to split overlapping SpatialLines into segments
od_aggregate_from

Summary statistics of trips originating from zones in OD data
is_linepoint

Identify lines that are points
line_segment

Divide an sf object with LINESTRING geometry into regular segments
od2odf

Extract coordinates from OD data
mats2line

Convert 2 matrices to lines
od_data_sample

Example of origin-destination data from UK Census
n_segments

Vectorised function to calculate number of segments given a max segment length
geo_length

Calculate line length of line with geographic or projected CRS
od_id_order

Generate ordered ids of OD pairs so lowest is always first This function is slow on large datasets, see szudzik_pairing for faster alternative
geo_select_aeq

Select a custom projected CRS for the area of interest
od_id

Combine two ID values to create a single ID number
od_data_routes

Example segment-level route data
line2points

Convert a spatial (linestring) object to points
od_coords

Create matrices representing origin-destination coordinates
read_table_builder

Import and format Australian Bureau of Statistics (ABS) TableBuilder files
line_bearing

Find the bearing of straight lines
line_cast

Convert multilinestring object into linestrings
line_breakup

Break up line objects into shorter segments
line2df

Convert geographic line objects to a data.frame with from and to coords
line_via

Add geometry columns representing a route via intermediary points
line_segment1

Segment a single line, using lwgeom or rsgeo
od_aggregate_to

Summary statistics of trips arriving at destination zones in OD data
geo_toptail

Clip the first and last n metres of SpatialLines
od_coords2line

Convert origin-destination coordinates into desire lines
points2odf

Convert a series of points into a dataframe of origins and destinations
rnet_subset

Subset one route network based on overlaps with another
quadrant

Split a spatial object into quadrants
od_oneway

Aggregate od pairs they become non-directional
od_to_odmatrix

Convert origin-destination data from long to wide format
route_dodgr

Route on local data using the dodgr package
route

Plan routes on the transport network
n_vertices

Retrieve the number of vertices in sf objects
%>%

Pipe operator
rnet_add_node

Add a node to route network
overline_intersection

Convert series of overlapping lines into a route network
rnet_boundary_points

Get points at the beginner and end of linestrings
route_average_gradient

Return average gradient across a route
rnet_breakup_vertices

Break up an sf object with LINESTRING geometry.
rnet_connected

Keep only segments connected to the largest group in a network
od_data_lines

Example of desire line representations of origin-destination data from UK Census
rnet_cycleway_intersection

Example of cycleway intersection data showing problems for SpatialLinesNetwork objects
odmatrix_to_od

Convert origin-destination data from wide to long format
od2line

Convert origin-destination data to spatial lines
route_network_small

Spatial lines dataset representing a small route network
route_osrm

Plan routes on the transport network using the OSRM server
route_rolling_gradient

Calculate rolling average gradient from elevation data at segment level
points2flow

Convert a series of points into geographical flows
onewaygeo

Aggregate flows so they become non-directional (by geometry - the slow way)
route_google

Find shortest path using Google services
route_split_id

Split route based on the id or coordinates of one of its vertices
route_split

Split route in two at point on or near network
osm_net_example

Example of OpenStreetMap road network
rnet_merge

Merge route networks, keeping attributes with aggregating functions
rnet_join

Join route networks
points2line

Convert a series of points, or a matrix of coordinates, into a line
route_sequential_dist

Calculate the sequential distances between sequential coordinate pairs
overline

Convert series of overlapping lines into a route network
rnet_group

Assign segments in a route network to groups
routes_fast_sf

Spatial lines dataset of commuter flows on the travel network
rnet_get_nodes

Extract nodes from route network
route_bikecitizens

Get a route from the BikeCitizens web service
routes_slow_sf

Spatial lines dataset of commuter flows on the travel network
route_rolling_average

Return smoothed averages of vector
route_rolling_diff

Return smoothed differences between vector values
route_slope_matrix

Calculate the gradient of line segments from a matrix of coordinates
route_slope_vector

Calculate the gradient of line segments from distance and elevation vectors
rnet_overpass

Example of overpass data showing problems for SpatialLinesNetwork objects
route_nearest_point

Find nearest route to a given point
rnet_roundabout

Example of roundabout data showing problems for SpatialLinesNetwork objects
toptail_buff

Clip the beginning and ends of sf LINESTRING objects
zones_sf

Spatial polygons of home locations for flow analysis.
stplanr-package

stplanr: Sustainable Transport Planning with R
stplanr-deprecated

Deprecated functions in stplanr
route_network_sf

Spatial lines dataset representing a route network
angle_diff

Calculate the angular difference between lines and a predefined bearing
flow

Data frame of commuter flows
bbox_scale

Scale a bounding box
bind_sf

Rapid row-binding of sf objects
geo_bb_matrix

Create matrix representing the spatial bounds of an object
geo_bb

Flexible function to generate bounding boxes
geo_buffer

Perform a buffer operation on a temporary projected CRS
geo_code

Convert text strings into points on the map
cents_sf

Spatial points representing home locations
flow_dests

Data frame of invented commuter flows with destinations in a different layer than the origins
destinations_sf

Example destinations data
flowlines_sf

Spatial lines dataset of commuter flows