---
title: "Creating Custom Road Datasets with trafficCAR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creating Custom Road Datasets with trafficCAR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6,
  fig.height = 4,
  dpi = 72,
  fig.retina = 1
)
```

## Overview

This vignette is written for **users of `trafficCAR`** who want to work with
road networks beyond the bundled examples.

You will learn how to:

1. Obtain road network data for a city
2. Save it as a GeoJSON file
3. Convert the GeoJSON into an `.rda` dataset (recommended for packages)
4. Save an `.rds` dataset (recommended for non-package projects)
5. Organize multiple city datasets (small / medium / large)
6. Use the datasets with `trafficCAR`

The recommended workflows are:

> **User project:** GeoJSON (raw) → `.rds` (fast)  
> **R package:** GeoJSON (raw) → `.rda` (CRAN-friendly)

---

## Step 1: Obtain road data for a city

A common source of road data is **OpenStreetMap**, accessed via the `osmdata`
package.

```{r, eval = FALSE}
# install.packages(c("osmdata", "sf"))
library(osmdata)
library(sf)
```

Choose a city name or bounding box.

```{r, eval = FALSE}
city <- "College Station, Texas, USA"

q <- opq(city) |>
  add_osm_feature(key = "highway")

osm <- osmdata_sf(q)
```

Extract road geometries:

```{r, eval = FALSE}
roads <- osm$osm_lines
```

---

## Step 2: Clean, validate, and inspect geometries

```{r, eval = FALSE}
roads <- roads[, c("highway", "name", "geometry")]
roads <- sf::st_make_valid(roads)

# Optional: simplify to reduce object size.
# Note: dTolerance is in the units of your coordinate reference system (CRS).
# For best results, consider transforming to a projected CRS with meter units first.
roads <- sf::st_simplify(roads, dTolerance = 10)

unique(sf::st_geometry_type(roads))
```

Only `LINESTRING` and `MULTILINESTRING` geometries are supported by
`trafficCAR`.

---

## Step 3: Write the dataset to GeoJSON (raw source)

```{r, eval = FALSE}
sf::st_write(
  roads,
  "roads_cstat.geojson",
  delete_dsn = TRUE,
  quiet = TRUE
)
```

---

## Step 4A: Save as `.rds` (recommended for user projects)

```{r, eval = FALSE}
roads_cstat <- sf::st_read("roads_cstat.geojson", quiet = TRUE)

saveRDS(roads_cstat, "roads_cstat.rds")
roads_cstat <- readRDS("roads_cstat.rds")
```

---

## Step 4B: Convert GeoJSON to `.rda` (recommended for R packages)

```{r, eval = FALSE}
library(usethis)

roads_cstat <- sf::st_read("roads_cstat.geojson", quiet = TRUE)
use_data(roads_cstat, overwrite = TRUE, compress = "xz")
```

---

## Step 5: Use the dataset in trafficCAR

```{r, eval = FALSE}
library(trafficCAR)

data(roads_small, package = "trafficCAR")
roads_cstat <- roads_small

segs <- roads_to_segments(
  roads_cstat,
  split_at_intersections = TRUE
)

adj <- build_adjacency(segs)
```

---

## Organizing multiple city datasets

### Example directory layout (package development)

```
data-raw/
  roads_cstat_small.geojson
  roads_cstat_small.R
data/
  roads_cstat_small.rda
```

### Example `data-raw` script

```{r eval=FALSE}
library(sf)
library(usethis)

roads_cstat_small <- sf::st_read(
  "data-raw/roads_cstat_small.geojson",
  quiet = TRUE
)

use_data(roads_cstat_small, overwrite = TRUE, compress = "xz")
```

---

## Using external GeoJSON files directly

```{r eval=FALSE}
library(sf)
library(trafficCAR)

roads <- sf::st_read("roads_cstat.geojson", quiet = TRUE)
segs <- roads_to_segments(roads)
```

---

## Summary

- Use **GeoJSON** as the authoritative raw format
- Store raw files in `data-raw/` or outside the package
- Use **`.rds`** for user projects and **`.rda`** for packages
- Apply geometry simplification and xz compression to reduce size