---
title: "Introducing stplanr"
author: "Robin Lovelace"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introducing stplanr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography:
  - references.bib
  - stplanr-citation.bib
---

```{r, include=FALSE}
library(stplanr)
build <- curl::has_internet()
knitr::opts_chunk$set(eval = build)
```

# Introduction

The purpose of this vignette is to get you up-to-speed with the basics and provide useful links for doing transport research with R.

Initially, **stplanr** was developed to solve a real world problem: how to convert official data on travel behaviour into geographic objects that can be plotted on a map and analysed using methods from geographical information systems (GIS)?
Specifically, how can origin-destination (OD) data, such as the open datasets provided by the UK Data Services WICID portal (see [wicid.ukdataservice.ac.uk/](http://wicid.ukdataservice.ac.uk/)), be used to estimate cycling potential down to the street levels at city and national levels?
The research project that the initial work on **stplanr** was funded by was called the Propensity to Cycle Tool (PCT), which has now been deployed as a web application hosted at www.pct.bike and written-up as an academic paper [@lovelace_propensity_2017].

Since this basic functionality has been implemented (with the function `od2line()`) there have been many further developments in **stplanr**.
The package was reviewed through the rOpenSci package review process (see here for the details) and the package is now hosted on their site. See the website at [ropensci.github.io/stplanr](https://ropensci.github.io/stplanr/).
A more detailed overview of the package's aims and capabilities is contained in a [longer vignette](https://github.com/ropensci/stplanr/blob/master/vignettes/stplanr-paper.Rmd), which has since been published in the R Journal [@lovelace_stplanr_2018].

# Installing stplanr

If you're new to programming and transport data, we recommend using **stplanr** interactively in an Integrated Development Environment (IDE) such as RStudio to make life easier.
Steps to set-up a suitable R/RStudio environment are described in the package's [README](https://ropensci.github.io/stplanr/#installation).
Broader guidance on R set-up can be found in sections [2.3](https://csgillespie.github.io/efficientR/set-up.html#r-version) and [2.5](https://csgillespie.github.io/efficientR/set-up.html#rstudio) of the book [Efficient R Programming](https://csgillespie.github.io/efficientR/set-up.html) [@gillespie_efficient_2016].

Once you have an R set-up you are happy with, the latest version can be installed from CRAN in the usual way:

```{r, eval=FALSE}
install.packages("stplanr")
```

The development version can be installed as follows:

```{r, eval=FALSE}
remotes::install_github("ropensci/stplanr")
```

Load the package as follows:

```{r}
library(stplanr)
```

**stplanr** contains many datasets for testing and demonstrating how R can be used for transport planning.
The names of these datasets (which are loaded 'lazily' into your namespace when you attach **stplanr**) are listed below:

```{r}
data(package = "stplanr")$result[, "Item"]
```

A more complete list of functions in the package can be found here: https://ropensci.github.io/stplanr/reference/index.html.

# OD data to desire lines and routes

Transport data can take many forms.
R is an appropriate language for handling transport data, as it can read-in data in such a wide range of formats, e.g. with packages such as **haven** and **foreign**.
This section focusses on OD datasets, and their conversion to *desire lines* and *routes* because these are foundational data types for many transport research applications. (**stplanr** also contains functions for: the analysis of road traffic casualty data, interfacing with various routing APIs, 'travel watershed' analyis and access to Google's Travel Matrix API.)

Origin-destination (OD) data is simply data in the following form:

```{r}
od_eg = read.csv(text = 
  "origin, destination, V1, V2
  1, 2, 100, 3
  1, 3, 50, 5"
  )
knitr::kable(od_eg)
```

What this example OD table means is that 100 units of 'V1' and 3 units of V2 travel between zone 1 and zone 2. There is also movement represented between Zone 1 and 3. 

This dataset can also be represent as an 'od matrix', where rows represent the origins and columns destinations. However, for multiple variables (e.g. modes of transport) and to prevent giant and unwieldy sparse matrices, the 'long' form represented above is much more common.

Now, imagine that V1 represents the total number of people travelling between the origin and destination and that V2 represents the number who regularly cycle. From this we can get a good indication of where people cycle at the desire line level. (Note: a good source of open OD data has been made available from the [wicid.ukdataservice.ac.uk](http://wicid.ukdataservice.ac.uk/) website).

To extract useful information from this OD dataset, we need to be able to place the lines on the map. What kind of place does a desire line originate from? What about the destination? What is the environment like that it passes through? To answer all these questions we need a geographic representation of the OD table illustrated above.

# Converting OD data to desire lines with R

One problem with OD data is that the rows do not tend to have geography inherently built in. They could contain a variables called `lat_origin`, `lon_origin`, `lat_destination` and `lon_destination`. But generally they only contain the IDs of geographic zones.

Work is needed to convert the OD data into 'desire lines'. Desire lines are straight lines between the origin and destination and represent where people would go if they were not constrained by the route network (see Figure 3 from [this paper](https://www.jtlu.org/index.php/jtlu/article/download/862/826)).

To show how these desire lines are created, we'll switch to using real OD data provided by **stplanr**. The first three of these is shown below:

```{r}
head(flow[c(1:3, 12)])
```

This shows that, between zone E02002361 and E02002361 (i.e. intrazonal flow) there were 109 people travelling to work by all modes in the 2011 census. 2 of them cycled. The equivalent numbers for the OD pair E02002361 to E02002371 were 44 and 3. But how to make this data geographical?

For that we need another dataset, also provided by **stplanr**:

```{r}
head(cents_sf)
```

The `cents` dataset is *spatial*, illustrated by it's class: a `SpatialPointsDataFrame`, from the **sp** package.
Because **stplanr** loads **sp**, the dataset will be plotted as a map by default, as illustrated below:

```{r}
library(sf)
plot(st_geometry(cents_sf))
```

**stplanr** creates desire lines using the `od2line()` function, which links geographical and non-geographical datasets together. In this case, it will join the non-geographical `flow` data with the geographical `cents` data plotted above. Let's take a single OD pair, E02002361 to E02002371, the fourth row represented in the table above, to see how this works:

```{r}
flow_single_line = flow[4,] # select only the first line
desire_line_single = od2line(flow = flow_single_line, zones = cents)
```

This can be plotted as follows:

```{r}
desire_line_single = st_as_sf(desire_line_single)
plot(st_geometry(desire_line_single), lwd = 5)
plot(cents_sf, add = TRUE, cex = 5)
```

Note that the R *function* `od2line()` is generic in the sense that it will work the same if you give it a single OD pair or a table representing thousands of desire lines.
The following command creates desire lines longer than than 2km in distance via the `geo_length()` function --- omitting 'internal flows' via the `sel` object below --- represented in the dataset `flowlines`:

```{r}
l = od2line(flow = flow, zones = cents_sf)
# identify 'intrazone flows'
sel_intra = l$Area.of.residence == l$Area.of.workplace
# find distances
l_distances = geo_length(l)
summary(l_distances)
sel_dist = l_distances > 2000
sel = !sel_intra & sel_dist
l = l[sel, ]
```

This creates the geographic data object `l`, which can be visualised as follows:

```{r, eval=FALSE}
plot(l)
```

Now the data is set-up, we can change the visual appearance of the desire lines with a single extra argument passed to the plotting function. Let's make width depend on the total number of people travelling along the desire line:

```{r}
lwd = l$All / mean(l$All)
plot(st_geometry(l), lwd = lwd)
```

Another useful visulisation involves setting the colour relative to the number of people cycling:

```{r}
plot(l["Bicycle"], lwd = lwd)
```

Finally, we can convert these desire lines into routes as follows (other `route_*` functions can be used, but may require API keys to work - see `?route_cyclestreets` for details):

```{r, message=FALSE, warning=FALSE}
# if the next line returns FALSE the code will not run
(has_internet = curl::has_internet() )
(cs_key = nchar(Sys.getenv("CYCLESTREETS")))
if(has_internet & cs_key == 32) {
  r = line2route(l, route_fun = route_cyclestreets)
} else {
  r = routes_fast[sel, ]
}
```

These routes contain the same information on origin and destination, but have additional spatial information about the route network. The routes can be plotted in the same way as the desire lines were plotted, (with buildings shown for context):

```{r, out.width="500", out.height="500"}
r_sf = st_sf(l, geometry = st_as_sfc(r))
plot(r_sf["Bicycle"], lwd = lwd * 3, reset = FALSE)
```

```{r, out.width="500", out.height="500", echo=FALSE, eval=FALSE}
# alternative showing buildings:
r_sf = st_sf(l, geometry = st_as_sfc(r))
if(require(osmdata)) {
  buildings = opq(st_bbox(l)) %>% 
  add_osm_feature(key = "building", value = "industrial") %>% 
  osmdata_sf()
}
plot(r_sf["Bicycle"], lwd = lwd * 3, reset = FALSE)
plot(st_geometry(buildings$osm_polygons), col = "grey", add = TRUE)
```

The next stage is to aggregate these lines together to create a 'route network'.
This, and many other functions, are described in the [stplanr-paper vignette](https://github.com/ropensci/stplanr/blob/master/vignettes/stplanr-paper.Rmd).

# Context and discussion

This section outlines some of the wider motivations underlying the package.

As settlements worldwide have grown and become more complex, the process of planning has had to adapt. Planners today are specialists, in sub-fields such as Emergency, Logistics, Healthcare, Urban and Transport Planning. And the 'art' of planning has become more of a science, with its own array of specialist hardware and software.

The process of Transport Planning has undergone a particularly dramatic revolution. Transport interventions such as new bridges, ports and active travel routes are no longer decided based on the intuition of public sector or political authorities. Decisions are now the result of a long socio-technical process involving public consultation, cost-benefit analyses and computer modelling and visualisation. With the ongoing digital revolution, the importance of this last stage has grown, to the point where transport planning is now a highly technical process, employing dozens of software developers in large planning organisations. There is now a multi-billion pound global transport planning consultancy industry, to support the decision-making process. Yet the fruits of all this labour are unavailable to the vast majority of citizens worldwide, and transport planning decisions which go against the best available evidence keep getting made.

This is the context which motivated the development of **stplanr**. Its aim is simple: to provide an accessible toolbox for transport planning. It is hoped that it will be useful for practitioners and researchers alike as part of the transition to open source software taking place in the tech industry, which is gradually filtering down into other sectors of the economy, notably 'Big Data' in
consultancies.

A further motivation is that the best available evidence suggests the future of civilisation depends on our ability to transition away from fossile fuels.
The transport sector is the fastest growing source of emissions by sector, and represents a major roadblock in the path towards a zero-carbon economy. Transport systems are also a major cause of ill health, by enabling sedentary lifestyles and causing numerous road traffic casualties. Knowledge of these impacts motivated the word 'sustainable' in the package's name: by focussing on active travel and public transport modes, **stplanr** encourages the design of transport interventions that reduce dependence on fossil fuels.

# Further resources

**stplanr** is focussed on spatial data. The reason for this is that almost all transport data, from the spatial distribution of bus stops to the routes that pedestrians take between home and work, contains a spatial element. Representing this spatial data in a formal *class system* has many advantages, including sensible defaults for plotting the spatial data on a map.

We use **sp** and **sf** because these support the range of vector data formats common in transport planning (points, lines, zones). 
See *stplanr: A package for transport planning*, a [paper publised in the R Journal](https://journal.r-project.org/archive/2018/RJ-2018-053/index.html), for more on this [@lovelace_stplanr_2018].

To get the best out of **stplanr** it helps to have a strong understanding of spatial data in R in general. Chapter 2 of the open source book [*Geocomputation with R*](http://geocompr.robinlovelace.net/) provides an introductory tutorial on the basics of spatial data with R and contains references to more advanced tutorials which may come in handy as your spatial data analysis skills progress.
Further information on geographic data for transport applications can be found in the same book.
See http://geocompr.robinlovelace.net/transport.html.

# Contributing

We welcome your contributions, whether it's filing a bug or feature request in the [issue tracker](https://github.com/ropensci/stplanr/issues), putting in a pull request to improve performance or documentation, or simply letting us know how you're using **stplanr** in your work by citing it or dropping us an email.

# References

