Merge pull request #94 from rOpenSpain/93-use-cases-vignette

93 use cases vignette

.Rbuildignore

@@ -23,3 +23,8 @@ README.qmd
 \.gif$
 ^tools$
 ^_pkgdown\.yaml$
+^vignettes/disaggregation\.qmd$
+^vignettes/flowmaps-interactive\.qmd$
+^vignettes/flowmaps-static\.qmd$
+^man/figures/card\.png$
+^man/figures/.*flowmapblue.*

DESCRIPTION

@@ -52,10 +52,14 @@ Suggests:
  hexSticker,
  mapSpain,
  quarto,
- testthat (>= 3.0.0)
+ remotes,
+ scales,
+ testthat (>= 3.0.0),
+ tidyverse
 VignetteBuilder:
  quarto
 Config/testthat/edition: 3
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
+Config/Needs/website: rmarkdown

_pkgdown.yml

@@ -20,7 +20,7 @@ articles:
  - v1-2020-2021-mitma-data-codebook
  - v2-2022-onwards-mitma-data-codebook
  - convert
- - uses
+ - disaggregation
  - flowmaps-static
  - flowmaps-interactive
 

vignettes/uses.qmd → vignettes/disaggregation.qmd

@@ -1,10 +1,11 @@
 ---
-title: "Use cases"
-output: rmarkdown::html_vignette
+title: "OD data disaggregation"
 vignette: >
- %\VignetteIndexEntry{Use cases}
+ %\VignetteIndexEntry{OD data disaggregation}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
+bibliography: references.bib
+number-sections: true
 format:
  html:
  toc: true
@@ -14,6 +15,15 @@ execute:
  eval: false
 ---
 
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>"
+)
+```
+
+
 ```{r setup}
 remotes::install_dev("tmap")
 library(spanishoddata)
@@ -24,7 +34,12 @@ library(tmap)
 
 # Introduction
 
-This vignette serves as a place to showcase use cases of the package.
+This vignette demonstrates origin-destination (OD) data disaggregation using the `{odjitter}` package.
+The package is an implementation of the method described in the paper "Jittering: A Computationally Efficient Method for Generating Realistic Route Networks from Origin-Destination Data" [@lovelace2022jittering] for adding value to OD data by disaggregating desire lines.
+This can be especially useful for transport planning purposes in which high levels of geographic resolution are required (see also the [`od2net`](https://od2net.org/){target="_blank"} for direct network generation from OD data).
+
+# Data preparation
+
 We'll start by loading a week's worth of origin-destination data for the city of Salamanca, building on the example in the README (note: these chunks are not evaluated):
 
 ```{r}
@@ -89,7 +104,7 @@ map_net <- osmactive::plot_osm_tmap(cycle_net)
 map_net
 ```
 
-![](osm.png)
+![](media/osm.png)
 
 We can use the road network to disaggregate the desire lines:
 
@@ -116,9 +131,9 @@ od_jittered |>
  theme_void()
 ```
 
-![](disaggregated.png)
+![](media/disaggregated.png)
 
-The results show that you can add value to the OD data by disaggregating the desire lines with the `odjitter` package.
+The results show that you can add value to the OD data by disaggregating the desire lines with the `{odjitter}` package.
 This can be useful for understanding the spatial distribution of trips within a zone for transport planning.
 
 We have plotted the disaggregated desire lines on top of the major road network in Salamanca.

vignettes/references.bib

@@ -77,3 +77,11 @@ @Manual{flowmapblue_r
  url = {https://github.com/FlowmapBlue/flowmapblue.R},
  doi = {10.32614/CRAN.package.flowmapblue},
 }
+
+@article{lovelace2022jittering,
+ title={Jittering: A computationally efficient method for generating realistic route networks from origin-destination data},
+ author={Lovelace, Robin and F{\'e}lix, Rosa and Carlino, Dustin},
+ journal={Findings},
+ year={2022},
+ publisher={Findings Press}
+}