---
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 OSM data
bucharest <- get_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 example 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.