---
title: "Get started with evacpath"
description: "Run a compact road-constrained evacuation model with packaged data."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with evacpath}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`evacpath` estimates road-constrained pedestrian distance to safety and converts
that modeled distance into an evacuation-time surface. A practical workflow
needs a hazard zone, a road or pathway network, an elevation raster, and a
projected coordinate reference system (CRS) in meters.

## Install and load

```{r install}
install.packages("evacpath")
library(evacpath)
library(terra)
```

## Load the packaged example data

The package includes small example inputs for learning the workflow. They are
not a substitute for local hazard, road, terrain, or evacuation-planning data.

```{r inputs}
dem <- rast(system.file("extdata/dem.tif", package = "evacpath"))
roads <- vect(system.file("extdata/rds.gpkg", package = "evacpath"))
inundation <- rast(system.file(
  "extdata/tsunami_inundation_depth.tif",
  package = "evacpath"
))

zones <- prepare_tsunami_zones(
  inundation = inundation,
  dem = dem,
  target_crs = "EPSG:32748"
)
```

The compact run used for the figures and summaries below is clipped to a small
projected window. It uses 40 sampled road origins and 12 candidate safety exits.

```{r input-summary, echo = FALSE, eval = TRUE}
knitr::kable(input_summary, col.names = c("Input", "Example value"))
```

## Run the workflow

For a first pass, use a modest number of origins and destinations. Remove or
raise those limits only after reviewing the input layers and assumptions.

```{r run}
result <- run_evacpath(
  hazard_zone = zones$hazard_zone,
  escape_zone = zones$escape_zone,
  roads = roads,
  dem = zones$dem,
  target_crs = "EPSG:32748",
  max_origins = 100,
  max_destinations = 25,
  walking_speed_mps = 1.22
)
```

```{r modeled-time-figure, echo = FALSE, eval = TRUE, results = "asis"}
figure_html("pkgdown-example-time.png", "Modeled evacuation time to safety for the compact packaged example.")
```

The example summary is a description of the modeled road-origin results, not a
measure of observed evacuation behavior.

```{r time-summary, echo = FALSE, eval = TRUE}
knitr::kable(time_summary, col.names = c("Modeled output", "Example value"))
```

## What you get back

`run_evacpath()` returns a named list. The main layers are summarized below so
you can inspect or write only the outputs needed for the analysis.

```{r output-objects, echo = FALSE, eval = TRUE}
knitr::kable(output_objects, col.names = c("Object", "Purpose"))
```

Use `result$evac_polygons`, `result$distance_points`, `result$time_grid`, and
`result$escape_points` for the mapped and point outputs. Run
`diagnose_evac_model()` before interpreting a result to make coordinate-system,
geometry, extent, and reachability checks explicit.