---
title: "Process groups"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Process groups}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4)
```

```{r setup, message = FALSE}
library(blueterra)
```

Process groups keep related terrain derivatives together so interpretation does
not rest on a single high-ranking variable. The labels are terrain-form
categories. They organize surface form for summaries and models; they are not
direct measurements of currents, sediment flux, habitat condition, or ecological
processes.

The catalog follows the process names used in the manuscript: seafloor aspect,
slope gradient, accumulation potential, transport potential, seafloor position,
seafloor rugosity, downslope pathway proximity, and curvature. Accumulation
potential replaces the older terrain-convergence wording. External layers named
`wetness_index_wbt`, `convergence_slope_index`, or
`convergence_slope_index_wbt` are assigned to `accumulation_potential`.

## Metric Catalog

```{r catalog}
catalog <- metric_catalog()
catalog[, c("metric", "label", "process_group", "scale_sensitive")]
```

The catalog records the source function, units, and interpretation notes for
the exported terrain metrics.

## Assigning Groups

```{r assign}
bathy <- read_bathy(blueterra_example("hitw"))
prepared <- prepare_bathy(bathy, depth_range = c(-220, -25), smooth = TRUE)
terrain <- derive_terrain(
  prepared,
  metrics = c("slope", "aspect", "northness", "eastness", "tri", "bpi",
              "curvature", "surface_area_ratio")
)

assign_process_groups(terrain)
summarize_process_groups(terrain)
```

The assignment is based on layer names. `standardize_metric_names()` is useful
when metric names come from external rasters or older project files.

```{r names}
standardize_metric_names(c("Slope degrees", "Broad BPI", "Curvature index"))
rename_metric_layers(c("slope_old", "curv_old"), c(slope_old = "slope_deg"))
```

## Representatives

Representative metrics are starting points for compact reporting. The final
choice should still follow raster resolution, sampling design, collinearity,
and the feature scale of the analysis.

```{r reps}
select_process_representatives(metrics_available = names(terrain))
select_process_representatives(
  representatives = c(seafloor_aspect = "northness", slope_gradient = "slope_deg")
)
```

```{r pca, eval=requireNamespace("ggplot2", quietly = TRUE), fig.alt="PCA scores for sampled terrain metrics."}
cells <- sample_terrain_cells(
  terrain[[c("slope_deg", "tri", "bpi_3x3", "curvature")]],
  size = 50,
  method = "regular"
)
pca <- terrain_pca(cells, vars = c("slope_deg", "tri", "bpi_3x3", "curvature"))
pca_axis_labels(pca)
plot_process_pca(pca, title = "Terrain PCA with Dominant Loading Labels")
```

## Custom Metrics

Custom metrics can be added to a stack when they share the same grid, CRS, and
extent. Catalog rows then place those layers into process groups for summaries
and model-ready tables.

```{r custom}
slope_tri <- derive_custom_metric(
  terrain,
  name = "slope_tri_index",
  expression = quote(slope_deg * tri)
)

extended <- add_metric_layers(terrain, slope_tri)

custom_catalog <- extend_metric_catalog(
  metric_catalog(),
  create_metric_catalog(
    metric = "slope_tri_index",
    label = "Slope-TRI index",
    process_group = "custom_relief",
    description = "Product of local slope and terrain ruggedness index.",
    units = "index",
    source_function = "derive_custom_metric",
    interpretation_notes = "Example index; define custom metrics from an explicit process model."
  )
)

assign_process_groups(extended, catalog = custom_catalog)
summarize_process_groups(extended, catalog = custom_catalog)
```