---
title: "Modeling assumptions"
description: "Review coordinate systems, routing settings, and interpretation limits."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Modeling assumptions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
scenario_summary <- utils::read.csv(system.file(
  "extdata/pkgdown-example-scenario-summary.csv", package = "evacpath"
))
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
  ))
}
```

Evacuation maps are conditional on the spatial inputs and modeling choices that
produce them. Record those choices and inspect their effects before using a map
for planning.

## Coordinate reference system

Use a projected CRS in meters. Buffers, grid resolution, route distance, and
walking-speed conversion are not meaningful in longitude and latitude degrees.

## Hazard, terrain, and road inputs

- Define the hazard zone for the question being asked; for tsunami modeling,
  distinguish the land-only origin zone from the escape boundary.
- Confirm the digital elevation model sign convention before using land and
  water thresholds. Do not assume every source uses positive values for land.
- Review road attributes and remove unsuitable features such as piers or routes
  that are not usable by pedestrians.

## Buffers and origin density

`road_buffer_m` controls how far movement can extend from the road centerline.
`escape_buffer_m` provides local access around candidate escape points.
`grid_resolution` controls the sampling density of origins; finer grids increase
runtime and should be justified by the terrain and road data resolution.

## Conductance and least-cost paths

`make_conductance_surface()` uses a slope-based conductance surface from
`leastcostpath`. The following arguments affect route geometry rather than just
the final time conversion:

```{r lcp}
run_evacpath(
  ...,
  lcp_cost_function = "tobler",
  lcp_neighbours = 16,
  lcp_crit_slope = 12,
  lcp_max_slope = NULL
)
```

`walking_speed_mps` converts modeled route distance into time. It should be set
to the population and planning scenario of interest.

```{r assumptions-scenarios-figure, echo = FALSE, eval = TRUE, results = "asis"}
figure_html("pkgdown-example-scenarios.png", "Scenario sensitivity in modeled evacuation time.")
```

The compact packaged run below shows the distinction: slower walking changes
time conversion, while a different routing neighbourhood can also change
modeled distance and route geometry.

```{r assumption-result, echo = FALSE, eval = TRUE}
knitr::kable(
  scenario_summary[, c(
    "scenario", "lcp_neighbours", "walking_speed_mps", "median_evac_time",
    "max_evac_time"
  )],
  digits = 2,
  col.names = c("Scenario", "LCP neighbours", "Walking speed",
                "Median min.", "Maximum min.")
)
```

## Output clipping

`clip_mode = "hazard"` maps the time surface across the full hazard zone.
`"road_hazard"` limits output to the road-buffer area, `"hazard_plus_roads"`
retains both, and `"none"` leaves the Voronoi output unclipped. Choose the mode
that matches the intended map interpretation.