forked from ropensci/stplanr
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
193 lines (140 loc) · 6.23 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "vignettes/README-"
)
```
[](https://travis-ci.org/ropensci/stplanr) [](https://cran.r-project.org/package=stplanr)
[](https://github.com/metacran/cranlogs.app)
[](https://github.com/ropensci/onboarding/issues/10)
```{r, echo=FALSE, message=FALSE}
library(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.
The initial work on the project was funded by the Department of Transport
([DfT](https://www.gov.uk/government/organisations/department-for-transport))
as part of the development of the Propensity to Cycle Tool
([PCT](http://pct.bike/)). 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)](http://dx.doi.org/10.5198/jtlu.2016.862)
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](https://graphhopper.com/) routing API and
`read_table_builder()` reads-in Australian data. We welcome contributions that make
transport research easier worldwide.
## 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:
```{r, results='hide', message=FALSE}
library(stplanr)
data(cents, flow)
```
Let's take a look at this data:
```{r}
flow[1:3, 1:3] # typical form of flow data
cents[1:3,] # points representing origins and destinations
```
These datasets can be combined as follows:
```{r plot1, warning=FALSE}
travel_network <- od2line(flow = flow, zones = cents)
w <- flow$All / max(flow$All) *10
plot(travel_network, lwd = w)
```
The package can also allocate flows to the road network, e.g. with [CycleStreets.net](https://www.cyclestreets.net/api/) and the OpenStreetMap Routing Machine ([OSRM](https://github.com/Project-OSRM/osrm-backend)) API interfaces.
These are supported in `route_*()` functions such as `route_cyclestreets` and `route_osrm()`:
Route functions take lat/lon inputs:
```{r, eval=FALSE}
trip <-
route_osrm(from = c(-1, 53), to = c(-1.1, 53))
```
and place names, found using the Google Map API:
```{r cycle-trip, message=FALSE, warning=FALSE, eval=FALSE, echo=FALSE}
if(!Sys.getenv("CYCLESTREET") == ""){
trip <- route_cyclestreet("Bradford, UK", "Leeds, Yorkshire", plan = "balanced")
plot(trip)
}
```
We can replicate this call multiple times using `line2route`.
```{r plot2, results='hide', message=FALSE}
intrazone <- travel_network$Area.of.residence == travel_network$Area.of.workplace
travel_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:
```{r, eval=FALSE}
library(leaflet)
leaflet() %>% addTiles() %>% addPolylines(data = t_routes)
```
For more examples, `example("line2route")`.
`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.
```{r rnet, warning=FALSE}
t_routes$All <- travel_network$All
rnet <- overline(t_routes, attrib = "All", fun = sum)
lwd <- rnet$All / mean(rnet$All)
plot(rnet, lwd = lwd)
points(cents)
```
## Installation
To install the stable version, use:
```{r, eval=FALSE}
install.packages("stplanr")
```
The development version can be installed using **devtools**:
```{r, eval=FALSE}
# install.packages("devtools") # if not already installed
devtools::install_github("ropensci/stplanr")
library(stplanr)
```
stplanr depends on rgdal, which can be tricky to install.
### Installing rgdal on Ubuntu and Mac
On Ubuntu rgdal can be installed with:
```
sudo apt-get install r-cran-rgdal
```
Using apt-get ensures the system dependencies, such as
[gdal](http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries) are also installed.
On Mac, homebrew can install gdal. Full instructions are provided
[here](https://github.com/ropensci/geojsonio#install).
## Funtions, help and contributing
The current list of available functions can be seen with:
```{r, eval=FALSE}
lsf.str("package:stplanr", all = TRUE)
```
To get internal help on a specific function, use the standard way.
```{r, eval=FALSE}
?od2line
```
## Dependencies
**stplanr** imports many great packages that it depends on. Many thanks to the developers of these tools:
```{r}
desc = read.dcf("DESCRIPTION")
headings = dimnames(desc)[[2]]
fields = which(headings %in% c("Depends", "Imports", "Suggests"))
pkgs = paste(desc[fields], collapse = ", ")
pkgs = gsub("\n", " ", pkgs)
strsplit(pkgs, ",")[[1]]
```
## Meta
* Please report issues, feature requests and questions to the [github issue tracker](https://github.com/ropensci/stplanr/issues)
* License: MIT
* Get citation information for `stplanr` in R doing `citation(package = 'stplanr')`
* This project is released with a [Contributor Code of Conduct](CONDUCT.md).
By participating in this project you agree to abide by its terms.
<!-- [](http://ropensci.org) -->