# Creating Custom Road Datasets with trafficCAR

## 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.

    # install.packages(c("osmdata", "sf"))
    library(osmdata)
    library(sf)

Choose a city name or bounding box.

    city <- "College Station, Texas, USA"

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

    osm <- osmdata_sf(q)

Extract road geometries:

    roads <- osm$osm_lines

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

    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)

    sf::st_write(
      roads,
      "roads_cstat.geojson",
      delete_dsn = TRUE,
      quiet = TRUE
    )

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

    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)

    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

    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

    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

    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