---
title: "Bottlenecks and route validation"
description: "Map modeled route density and compare modeled routes with reference lines."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Bottlenecks and route validation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
bottleneck_outputs <- data.frame(
  object = c("density_raster", "high_density_raster", "high_density_polygons", "summary"),
  purpose = c(
    "Count of modeled route overlap on the selected raster grid.",
    "Cells meeting the selected density threshold.",
    "Optional polygons outlining selected high-density cells.",
    "Route count, density threshold, and high-density area metrics."
  )
)
figure_html <- function(name, alt) {
  path <- system.file("extdata", name, package = "evacpath")
  if (!nzchar(path)) stop("Installed example figure is unavailable.", call. = FALSE)
  knitr::asis_output(sprintf(
    '<figure><img src="%s" alt="%s" style="width: 100%%; height: auto;"><figcaption>%s</figcaption></figure>',
    knitr::image_uri(path), alt, alt
  ))
}
```

Route-density analysis can identify **modeled high-use corridors**. It does not
measure observed pedestrian traffic unless modeled routes are compared with
independent route or movement data.

## Retain modeled routes

Route geometries are optional because they can increase memory use. Request them
when the result will be used for corridor analysis.

```{r routes}
result <- run_evacpath(
  hazard_zone = hazard_zone,
  roads = roads,
  dem = dem,
  target_crs = "EPSG:32748",
  keep_routes = TRUE
)
```

## Map modeled high-use corridors

```{r bottlenecks}
bottlenecks <- map_evac_bottlenecks(
  evac_result = result,
  quantile_threshold = 0.9
)

bottlenecks$summary
bottlenecks$high_density_polygons
```

```{r bottlenecks-figure, echo = FALSE, eval = TRUE, results = "asis"}
figure_html("pkgdown-example-corridors.png", "Modeled high-use corridors from the compact packaged example.")
```

```{r bottleneck-outputs, echo = FALSE, eval = TRUE}
knitr::kable(bottleneck_outputs, col.names = c("Output", "Purpose"))
```

The threshold selects high-density raster cells from route overlap. Inspect the
template resolution, threshold choice, and underlying route set before
describing a corridor as a planning bottleneck.

## Compare with reference routes

`validate_evac_routes()` accepts `sf` line layers. It can match by an ID column
or compare each modeled route with the nearest reference route.

```{r validation}
validation <- validate_evac_routes(
  modeled_routes = modeled_routes,
  reference_routes = reference_routes,
  method = "all",
  buffer_m = 25,
  by = "route_id"
)

validation$summary
```

Buffer overlap measures how much modeled line length falls within a reference
route buffer. Hausdorff distance measures geometric separation. Path deviation
index is attempted when the route pair is compatible with `leastcostpath`.