---
title: "Getting started with potentiomap"
description: "A concise end-to-end introduction to observations, interpolation, contours, diagnostics, and support."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with potentiomap}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>", fig.bg = "white",
  dev.args = list(bg = "white"), fig.width = 8, fig.height = 6,
  dpi = 144, fig.align = "center"
)
```

potentiomap turns groundwater-level observations into mapped potentiometric
surfaces and related review products. This article uses small synthetic data.
It does not demonstrate a groundwater-flow model.

```{r prepare}
library(potentiomap)
data("synthetic_wells")

points <- ps_make_points(
  synthetic_wells,
  x = "x", y = "y", value = "gw_elevation", name_col = "well_id",
  crs = "EPSG:26916", head_unit = "m", output_unit = "m",
  vertical_datum = "synthetic example datum",
  surface_reference = "land_surface", metadata_mode = "strict"
)
```

Create a small IDW surface and retain diagnostics and prediction support.

```{r interpolate}
result <- ps_interpolate(
  points, methods = "IDW", grid_res = 300,
  return = "result", support = TRUE, support_max_distance = 1000
)
result
ps_diagnostics(result, "IDW")
result$support$summary
```

```{r first-map, fig.alt="Synthetic IDW potentiometric surface shaded blue at lower modeled heads and red at higher heads, with one-unit contours and observation wells."}
surface <- result$surfaces$IDW
contours <- ps_contours(surface, interval = 1)

par(bg = "white")
terra::plot(
  surface, col = hcl.colors(64, "RdYlBu", rev = TRUE),
  main = "First potentiometric surface"
)
terra::plot(contours, add = TRUE, col = "#263845", lwd = 1)
terra::plot(points, add = TRUE, pch = 21, bg = "white", cex = 0.75)
```

IDW is deterministic and distance based. TPS produces a smooth penalized
surface. Ordinary kriging assumes a constant unknown mean. Universal kriging
uses a specified spatial trend. Method selection should consider hydrogeology,
network geometry, sample density, model diagnostics, prediction support,
validation design, and map purpose.

The raster grid controls both detail and resource use. A smaller cell size can
greatly increase the number of predictions. For larger grids, use an on-disk
`terra` raster when practical, point `terraOptions(tempdir = ...)` to storage
with adequate free space, and review `terra::tmpFiles()` after interrupted work.
Do not change global `terra` options inside reusable functions without restoring
them. Remove only temporary files you have identified as safe to delete.

Export occurs only when an output directory is supplied. GeoPackage is the
recommended vector format.

```{r export}
output_dir <- file.path(tempdir(), "potentiomap-getting-started")
exports <- ps_export_surfaces(
  result, output_dir, out_stub = "synthetic", points = points,
  vector_format = "gpkg"
)
knitr::kable(data.frame(
  method = exports$method,
  raster = basename(exports$raster)
))
```

A finite raster is not proof that every cell is well supported. Inspect the
support classes and fitted-method diagnostics before using a mapped surface for
interpretation or decision making.