---
title: "Using evacpath in a new region"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using evacpath in a new region}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE, purl = FALSE)
```

For a new region, `evacpath` expects three core spatial inputs:

1. a hazard or inundation zone,
2. a road/pathway network, and
3. a DEM or elevation raster.

The most important requirement is that distance calculations should use a projected coordinate reference system in meters.

The workflow builds on open-source least-cost path methods for evacuation planning (Cordero et al. 2025) and uses `leastcostpath` for least-cost path and movement-potential modeling (Lewis 2023; Lewis 2021).

```{r setup}
library(evacpath)
```

## Minimal workflow

```{r minimal}
result <- run_evacpath(
  hazard_zone = "path/to/hazard_zone.gpkg",
  roads = "path/to/roads.gpkg",
  dem = "path/to/dem.tif",
  target_crs = "EPSG:XXXX",
  region_name = "New region",
  walking_speed_mps = 1.22
)
```

## Common customizations

```{r custom}
result <- run_evacpath(
  hazard_zone = "path/to/hazard_zone.gpkg",
  roads = "path/to/roads.gpkg",
  dem = "path/to/dem.tif",
  target_crs = "EPSG:XXXX",
  region_name = "New region",

  # Road and escape-point geometry assumptions
  road_buffer_m = 2,
  escape_buffer_m = 5,
  final_road_buffer_m = 3,

  # Origin-point density
  grid_resolution = 50,
  max_origins = NULL,

  # Travel-time assumption
  walking_speed_mps = 1.22,

  # Output clipping
  clip_mode = "road_hazard"
)
```

## Case-specific preprocessing

Keep region-specific choices outside the package. For example, if your DEM uses negative elevation for land, correct it before calling `run_evacpath()`. If your road layer contains piers or other unsuitable features, remove them with `clean_roads()`.

```{r preprocessing}
roads <- clean_roads(
  roads = "path/to/roads.gpkg",
  exclude = list(field = "road_type", values = c("pier", "private")),
  target_crs = "EPSG:XXXX"
)
```

## References

Cordero, E., Ruiz Vélez, R., Huérfano Moreno, V., Sherman, C., 2025. Enhancing tsunami evacuation strategies in Puerto Rico using open-source least-cost path analysis. J. Disaster Sci. Manag. 1, 18. https://doi.org/10.1007/s44367-025-00018-y

Lewis, J., 2023. leastcostpath: Modelling Pathways and Movement Potential Within a Landscape.

Lewis, J., 2021. Probabilistic Modelling for Incorporating Uncertainty in Least Cost Path Results: a Postdictive Roman Road Case Study. Journal of Archaeological Method and Theory 28, 911-924. https://doi.org/10.1007/s10816-021-09522-w