---
title: "Interpolation diagnostics and prediction support"
description: "Review retained interpolation diagnostics and classify where a mapped prediction has limited spatial support."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Interpolation diagnostics and prediction support}
  %\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"
)
```

Different interpolation methods express different assumptions. potentiomap
retains available fit information and upstream condition text so those
assumptions can be reviewed.

```{r models}
library(potentiomap)
data("synthetic_wells")
points <- ps_make_points(
  synthetic_wells, "x", "y", "gw_elevation", "well_id", "EPSG:26916"
)

result <- suppressWarnings(ps_interpolate(
  points, methods = c("IDW", "TPS", "OK", "UK"), grid_res = 400,
  return = "result", support = TRUE, support_max_distance = 1000
))
summary(result)
result$conditions
```

IDW records its power and neighbor limit. When TPS selects its smoothing
parameter, supported generalized-cross-validation information is retained.
Ordinary and universal kriging retain empirical and fitted variogram objects,
their fitted parameters, and method-attributed conditions.

```{r selected-diagnostics}
ps_diagnostics(result, "TPS")[c(
  "selection_mode", "selected_lambda", "effective_degrees_of_freedom",
  "selected_at_search_boundary", "return_status"
)]

ps_diagnostics(result, "UK")[c(
  "coordinate_scaling", "model_matrix_rank", "condition_number",
  "observed_range", "predicted_range",
  "predicted_range_to_observed_range_ratio", "return_status"
)]
```

Quadratic-drift UK centers and scales coordinates by default. The condition
number, prediction-range ratio, and overshoot thresholds are heuristic review
flags, not formal acceptance tests. A warning does not automatically discard a
surface. Rank deficiency or nonfinite model components can make the requested
fit impossible, in which case the function returns a classed error rather than
another interpolation method.

```{r support}
knitr::kable(result$support$summary)
head(result$support$records)
```

```{r support-distance-map, fig.alt="Nearest-observation-distance raster for a synthetic monitoring network, with the training convex hull outlined and observation wells shown as points."}
distance <- result$support$rasters[["nearest_observation_distance"]]

par(bg = "white")
terra::plot(
  distance, col = hcl.colors(64, "YlGnBu"),
  main = "Local observation support: nearest-well distance"
)
terra::plot(
  terra::convHull(points), add = TRUE, border = "#9b3d2f",
  lwd = 2, lty = 2
)
terra::plot(points, add = TRUE, pch = 21, bg = "white", cex = 0.75)
legend(
  "topleft", legend = "Training convex hull", lty = 2, lwd = 2,
  col = "#9b3d2f", bty = "n"
)
```

The convex hull is a description of the training network, not an aquifer
boundary. Nearest-observation distances require projected coordinates by
default because longitude and latitude degrees are not linear ground-distance
units. Predictions are classified rather than automatically blanked.

The same support rasters can classify sections of modeled contours. Criteria
are supplied explicitly rather than inferred from universal distances.

```{r contour-support}
contours <- ps_contours(result$surfaces$IDW, interval = 1)
classified <- suppressWarnings(ps_contour_support(
  contours, support = result$support,
  supported_distance = 500, approximate_distance = 1200
))
knitr::kable(classified$summary)
```

See the [contour-support threshold comparison](https://el-cordero.github.io/potentiomap/articles/contour-support-thresholds.html)
for maps showing how tighter, broader, and network-relative distance criteria
change the same contour lines.

Distance-derived contour classes describe local observation support. They are
not statistical confidence intervals. An identified uncertainty raster can be
used as a separate criterion, but its meaning and units must be supplied and it
is not silently resampled or treated as interchangeable with distance.