Add draft vignette (#26)

Co-authored-by: Francesco Nattino <[email protected]>
Co-authored-by: Francesco Nattino <[email protected]>

.gitignore

@@ -4,3 +4,4 @@
 .httr-oauth
 .DS_Store
 .quarto
+inst/doc

DESCRIPTION

@@ -14,15 +14,19 @@ Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
 Suggests:
-    testthat (>= 3.0.0),
+    ggplot2,
+    knitr,
+    osmdata,
+    rmarkdown,
     sfnetworks,
-    osmdata
+    testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Imports:
     dplyr,
     rlang,
     sf,
     sfheaders
-Depends: 
+VignetteBuilder: knitr
+Depends:
     R (>= 2.10)
 LazyData: true

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/using-rcoins.Rmd

@@ -0,0 +1,97 @@
+---
+title: "Tracing continuous streets using rcoins"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Tracing continuous streets using rcoins}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(rcoins)
+library(sf)
+library(ggplot2)
+```
+
+In this article we demonstrate how to trace continuous streets using the `stroke()` function. The function takes an `sf` object of streets and returns a new `sf` object with continuous streets.
+
+```{r}
+# Load streets from example data
+streets <- bucharest$streets
+```
+
+## Tracing on the entire network
+
+If we run the `stroke()` function with the default values, strokes will be calculated on the network as a whole.
+
+```{r}
+# Trace continuous streets
+continuous_streets <- stroke(streets)
+```
+
+To visualise the strokes in a more intuitive way, we map the line weight in the plot to the length of the strokes. The thicker a line is, the longer the stroke.
+
+```{r echo=FALSE}
+length <- sf::st_length(continuous_streets)
+ggplot() +
+  geom_sf(data = continuous_streets, aes(linewidth = as.numeric(length))) +
+  scale_linewidth_continuous(name = "Continuous lines", range = c(0.1, 1.2)) +
+  xlim(418500, 437500) +
+  ylim(4909800, 4931500) +
+  coord_sf(datum = st_crs(32635)) +
+  labs(title = "Continuous streets along the main street network of Bucharest",
+       subtitle = "Lineweight by length",
+       caption = "Data: OpenStreetMap")
+```
+
+## Tracing from specified streets
+
+To trace continuous streets from a given set of streets, we can add the edge indices in the `from_edge` argument. We demonstrate this by tracing all continuous streets crossing river Dâmbovița in Bucharest. We load the river centerline from the package data.
+
+```{r}
+# Load river centerline from example data
+river_centerline <- bucharest$river_centerline
+
+crossing_edges <- which(st_intersects(streets,
+                                      river_centerline,
+                                      sparse = FALSE))
+
+# Trace continuous streets crossing the river
+continuous_streets_crossing <- stroke(streets, from_edge = crossing_edges,
+                                      angle_threshold = 120)
+```
+
+Note that the input argument `angle_threshold` sets the minimum internal angle between consecutive line segments that can be considered part of a continuous stroke.
+
+We plot the street network and emphasize the continuous streets crossing the river.
+
+```{r echo=FALSE}
+ggplot() +
+  geom_sf(data = river_centerline, linewidth = 1, colour = "blue") +
+  geom_sf(data = streets, linewidth = 0.2, colour = "black") +
+  geom_sf(data = continuous_streets_crossing, linewidth = 2, colour = "red") +
+  xlim(418500, 437500) +
+  ylim(4909800, 4931500) +
+  coord_sf(datum = st_crs(32635)) +
+  labs(title = "Continuous streets crossing River Dâmbovița in Bucharest",
+       subtitle = "Crossing streets thicker",
+       caption = "Data: OpenStreetMap")
+```
+
+## Maintaining the initial structure
+
+The `flow_mode` argument allows us to maintain the initial structure of the streets. With `flow_mode = FALSE` (the default), the function will split the initial streets in individual line segments and calculate the continuous streets purely based on minimum angle deviations. With `flow_mode = TRUE`, the function will not break the initial line strings, but only group and connect them on the basis of minimum angle deviations.
+
+<!-- Question: is there a situation when we want `flow_mode = TRUE` without `attribute_mode = TRUE`? If not, we may want to drop this argument, or at least not present it in the vignette. -->
+
+## Tracing with attributes
+
+By enabling `flow_mode` and `attributes` arguments, `stroke` will still group streets on the basis of minimum-angle connectivity, but return group labels instead of the new aggregated geometries. This is useful if we want to keep attributes such as degree of the initial streets ("primary", "secondary", "tertiary", etc.) in the resulting continuous streets to calculate, for instance, the relationship between street degree and street length.
+