-
Notifications
You must be signed in to change notification settings - Fork 4
/
README.Rmd
130 lines (94 loc) · 5.63 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# od
<!-- badges: start -->
<!-- [![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html) -->
[![CRAN status](https://www.r-pkg.org/badges/version/od)](https://itsleeds.github.io/od/)
[![rstudio mirror downloads](https://cranlogs.r-pkg.org/badges/od)](https://github.com/r-hub/cranlogs.app)
[![Codecov test coverage](https://codecov.io/gh/itsleeds/od/branch/master/graph/badge.svg)](https://app.codecov.io/gh/itsleeds/od?branch=master)
[![R build status](https://github.com/itsleeds/od/workflows/R-CMD-check/badge.svg)](https://github.com/itsleeds/od/actions)
[![Dependencies](https://tinyverse.netlify.com/badge/od)](https://cran.r-project.org/package=od)
[![R-CMD-check](https://github.com/itsleeds/od/workflows/R-CMD-check/badge.svg)](https://github.com/itsleeds/od/actions)
<!-- badges: end -->
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](https://doi.org/10.1287/trsc.15.1.32)) and are central to modelling city to global scale transport systems (Simini et al. [2012](https://doi.org/10.1038/nature10856)).
## Installation
You can install the released version of od from [CRAN](https://CRAN.R-project.org) with:
``` r
install.packages("od")
```
Install the development version from [GitHub](https://github.com/) with:
``` r
# 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](https://itsleeds.github.io/od/articles/od.html) or by executing the following command after installing the package:
```{r, eval=FALSE}
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:
```{r}
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:
```{r}
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`:
```{r}
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.:
```{r, out.width="50%", fig.show='hold'}
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:
```{r}
desire_lines_od_sf1 = od_to_sf(od_data_df, od_data_centroids)
```
## Performance
### Benchmark on a small dataset:
```{r, message=FALSE}
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](https://github.com/ropensci/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](https://docs.ropensci.org/stplanr/reference/index.html#section-work-with-od-data).
- [cartography](https://riatelab.github.io/cartography/) is an R package with functions for working with OD data, including [`getLinkLayer()`](https://riatelab.github.io/cartography/docs/reference/getLinkLayer.html)
- [gravity](https://pacha.dev/gravity/) is an R package for developing 'gravity models' to estimate flow between zones
- [flowmap.gl](https://github.com/teralytics/flowmap.gl), a JavaScript package for visualising OD data
- [Arabesque](http://arabesque.ifsttar.fr/) is another JavaScript project for working with OD data
## Code of Conduct
Please note that the od project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.