
# potentiomap

<img class="github-readme-logo" src="man/figures/logo.png" align="right" width="160" alt="potentiomap hexagon logo" />

<!-- badges: start -->

[![CRAN
status](https://www.r-pkg.org/badges/version/potentiomap)](https://CRAN.R-project.org/package=potentiomap)
[![DOI](https://img.shields.io/badge/DOI-10.32614%2FCRAN.package.potentiomap-blue)](https://doi.org/10.32614/CRAN.package.potentiomap)
[![R-CMD-check](https://github.com/el-cordero/potentiomap/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/el-cordero/potentiomap/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

`potentiomap` turns groundwater-level observations into auditable
potentiometric-surface analyses, validation and uncertainty summaries,
monitoring-network diagnostics, contours, profiles, and GIS-ready
products.

[Website](https://el-cordero.github.io/potentiomap/) ·
[Examples](https://el-cordero.github.io/potentiomap/articles/) ·
[Function
reference](https://el-cordero.github.io/potentiomap/reference/) ·
[Source](https://github.com/el-cordero/potentiomap) ·
[Issues](https://github.com/el-cordero/potentiomap/issues) ·
[CRAN](https://CRAN.R-project.org/package=potentiomap)

## What it provides

- preparation of measured head and positive depth-to-water observations;
- observation QA, monitoring-event selection, and explicit screen
  grouping;
- TPS, IDW, ordinary-kriging, universal-kriging, and custom
  interpolation;
- variograms, external drift, validation, nested tuning, and retained
  fits;
- prediction support, model-conditional uncertainty, method ensembles,
  and disagreement summaries;
- event change, vertical gradients, well influence, network thinning,
  and constrained candidate-site ranking;
- depth surfaces, transect profiles, and plot-ready cross-sections;
- contours that can be divided into supported, approximate, and
  unsupported sections using user-defined criteria;
- checked downgradient arrow symbols, open GIS styles, and technical
  reports.

Existing surface and contour workflows remain available with their
ordinary return values. Rich result objects are optional when
diagnostics, support, and manifests are needed.

<figure class="pm-home-overview">

<img src="man/figures/home-overview.png" alt="Two synthetic maps: a potentiometric surface with observation wells, contours, and model-gradient arrows; and contour segments drawn with line patterns for user-defined support classes." />
<figcaption>

A reproducible overview from the installed synthetic data: a fitted
surface (left) and checked model-gradient symbols with contours (right).
Arrow length is a display convention, not groundwater velocity or a
traced flow path.
</figcaption>

</figure>

## Installation

> **Version note:** CRAN currently serves `potentiomap` 0.1.0. This
> website documents 0.2.0 while that release is being reviewed. Use CRAN
> for the published release, or install the 0.2.0 source from GitHub
> when you need the features documented here.

``` r
install.packages("potentiomap")
```

``` r
install.packages("pak")
pak::pak("el-cordero/potentiomap")
```

## Minimal workflow

``` r
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"
)

surface <- ps_interpolate(points, methods = "TPS", grid_res = 100)$TPS
contours <- ps_contours(surface, interval = 1)
ps_quicklook(surface, contours = contours, points = points)
```

For complete, executable walkthroughs with printed outputs and maps, use
the [Examples](https://el-cordero.github.io/potentiomap/articles/)
section:

- [Five-minute quick
  start](https://el-cordero.github.io/potentiomap/articles/quick-start.html)
- [Compare interpolation
  methods](https://el-cordero.github.io/potentiomap/articles/interpolation-methods.html)
- [Diagnostics and prediction
  support](https://el-cordero.github.io/potentiomap/articles/diagnostics-and-support.html)
- [Contours and hydraulic-gradient
  arrows](https://el-cordero.github.io/potentiomap/articles/contours-and-arrows.html)
- [Expanded 0.2.0 validation, uncertainty, monitoring-network, and
  profile articles](https://el-cordero.github.io/potentiomap/articles/)
- [Public USGS groundwater
  example](https://el-cordero.github.io/potentiomap/articles/real-world-usgs.html)
- [Output
  gallery](https://el-cordero.github.io/potentiomap/articles/output-gallery.html)

## Scientific scope

`potentiomap` is not a groundwater-flow or contaminant-transport model.
Interpolated surfaces depend on monitoring-network geometry, data
quality, aquifer selection, screened intervals, boundary conditions, and
method assumptions.

Prediction-support classes describe support available for a mapped
result; they do not establish that a contour is correct and are not
statistical confidence intervals. Hydraulic-gradient arrows point toward
decreasing modeled head. Their length is a display convention, not
velocity, travel time, or a traced groundwater path.

Cross-validation describes its recorded prediction task, not automatic
area-wide map accuracy. Kriging variance is model conditional, method
spread is not statistical uncertainty, modeled head change is not
storage change, and network rankings are not globally optimal drilling
plans.

## Documentation and support

- [Documentation](https://el-cordero.github.io/potentiomap/)
- [Function
  reference](https://el-cordero.github.io/potentiomap/reference/)
- [Issue tracker](https://github.com/el-cordero/potentiomap/issues)
- [Contributing
  guide](https://github.com/el-cordero/potentiomap/blob/main/CONTRIBUTING.md)
- [Code of
  Conduct](https://github.com/el-cordero/potentiomap/blob/main/CODE_OF_CONDUCT.md)
- [Support
  guide](https://github.com/el-cordero/potentiomap/blob/main/SUPPORT.md)
- [Security
  policy](https://github.com/el-cordero/potentiomap/blob/main/SECURITY.md)

Do not post confidential well coordinates, client data, private site
identifiers, or restricted environmental data in public issues.

Run `citation("potentiomap")` for the package citation.
