# Process groups

    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

    catalog <- metric_catalog()
    catalog[, c("metric", "label", "process_group", "scale_sensitive")]
    #> # A tibble: 50 × 4
    #>    metric     label      process_group   scale_sensitive
    #>    <chr>      <chr>      <chr>           <lgl>
    #>  1 bathy      Bathymetry base_bathymetry TRUE
    #>  2 hillshade  Hillshade  base_bathymetry TRUE
    #>  3 aspect_deg Aspect     seafloor_aspect TRUE
    #>  4 aspect_rad Aspect     seafloor_aspect TRUE
    #>  5 northness  Northness  seafloor_aspect TRUE
    #>  6 eastness   Eastness   seafloor_aspect TRUE
    #>  7 aspect_cos Northness  seafloor_aspect TRUE
    #>  8 aspect_sin Eastness   seafloor_aspect TRUE
    #>  9 slope_deg  Slope      slope_gradient  TRUE
    #> 10 slope_rad  Slope      slope_gradient  TRUE
    #> # ℹ 40 more rows

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

## Assigning Groups

    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)
    #> # A tibble: 9 × 7
    #>   metric metric_standard label process_group description source_function matched
    #>   <chr>  <chr>           <chr> <chr>         <chr>       <chr>           <lgl>
    #> 1 slope… slope_deg       Slope slope_gradie… Local stee… derive_slope    TRUE
    #> 2 aspec… aspect_deg      Aspe… seafloor_asp… Local down… derive_aspect   TRUE
    #> 3 north… northness       Nort… seafloor_asp… Cosine tra… derive_northne… TRUE
    #> 4 eastn… eastness        East… seafloor_asp… Sine trans… derive_eastness TRUE
    #> 5 tri    tri             Terr… seafloor_rug… Local terr… derive_tri      TRUE
    #> 6 bpi_3… bpi_3x3         Fine… seafloor_pos… Fine-scale… derive_bpi      TRUE
    #> 7 bpi_1… bpi_11x11       Broa… seafloor_pos… Broad-scal… derive_bpi      TRUE
    #> 8 curva… curvature       Curv… curvature     Laplacian-… derive_curvatu… TRUE
    #> 9 surfa… surface_area_r… Surf… seafloor_rug… Approximat… derive_surface… TRUE
    summarize_process_groups(terrain)
    #> # A tibble: 5 × 3
    #>   process_group     n_metrics metrics
    #>   <chr>                 <int> <chr>
    #> 1 curvature                 1 curvature
    #> 2 seafloor_aspect           3 aspect_deg, northness, eastness
    #> 3 seafloor_position         2 bpi_3x3, bpi_11x11
    #> 4 seafloor_rugosity         2 tri, surface_area_ratio
    #> 5 slope_gradient            1 slope_deg

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

    standardize_metric_names(c("Slope degrees", "Broad BPI", "Curvature index"))
    #> [1] "slope_degrees"   "broad_bpi"       "curvature_index"
    rename_metric_layers(c("slope_old", "curv_old"), c(slope_old = "slope_deg"))
    #> [1] "slope_deg" "curv_old"

## 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.

    select_process_representatives(metrics_available = names(terrain))
    #> # A tibble: 5 × 9
    #>   metric     label               process_group description units source_function
    #>   <chr>      <chr>               <chr>         <chr>       <chr> <chr>
    #> 1 curvature  Curvature           curvature     Laplacian-… inpu… derive_curvatu…
    #> 2 aspect_deg Aspect              seafloor_asp… Local down… degr… derive_aspect
    #> 3 bpi_3x3    Fine-scale BPI      seafloor_pos… Fine-scale… inpu… derive_bpi
    #> 4 tri        Terrain Ruggedness… seafloor_rug… Local terr… inpu… derive_tri
    #> 5 slope_deg  Slope               slope_gradie… Local stee… degr… derive_slope
    #> # ℹ 3 more variables: requires_optional_dependency <lgl>,
    #> #   scale_sensitive <lgl>, interpretation_notes <chr>
    select_process_representatives(
      representatives = c(seafloor_aspect = "northness", slope_gradient = "slope_deg")
    )
    #> # A tibble: 9 × 9
    #>   metric                   label process_group description units source_function
    #>   <chr>                    <chr> <chr>         <chr>       <chr> <chr>
    #> 1 flowacc                  Conv… accumulation… Terrain-de… index external
    #> 2 bathy                    Bath… base_bathyme… Input bath… inpu… as_bathy
    #> 3 curvature                Curv… curvature     Laplacian-… inpu… derive_curvatu…
    #> 4 downslope_distance_to_s… Down… downslope_pa… Modeled do… map … external
    #> 5 tpi                      Topo… seafloor_pos… Cell posit… inpu… derive_tpi
    #> 6 roughness                Roug… seafloor_rug… Local rang… inpu… derive_roughne…
    #> 7 stream_power_index_wbt   Terr… transport_po… Compound t… index external
    #> 8 northness                Nort… seafloor_asp… Cosine tra… unit… derive_northne…
    #> 9 slope_deg                Slope slope_gradie… Local stee… degr… derive_slope
    #> # ℹ 3 more variables: requires_optional_dependency <lgl>,
    #> #   scale_sensitive <lgl>, interpretation_notes <chr>

    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)
    #>                               PC1                               PC2
    #> "PC1 (77.9%; bpi_3x3, slope_deg)"     "PC2 (20.6%; tri, curvature)"
    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.

    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)
    #> # A tibble: 10 × 7
    #>    metric        metric_standard label process_group description source_function
    #>    <chr>         <chr>           <chr> <chr>         <chr>       <chr>
    #>  1 slope_deg     slope_deg       Slope slope_gradie… Local stee… derive_slope
    #>  2 aspect_deg    aspect_deg      Aspe… seafloor_asp… Local down… derive_aspect
    #>  3 northness     northness       Nort… seafloor_asp… Cosine tra… derive_northne…
    #>  4 eastness      eastness        East… seafloor_asp… Sine trans… derive_eastness
    #>  5 tri           tri             Terr… seafloor_rug… Local terr… derive_tri
    #>  6 bpi_3x3       bpi_3x3         Fine… seafloor_pos… Fine-scale… derive_bpi
    #>  7 bpi_11x11     bpi_11x11       Broa… seafloor_pos… Broad-scal… derive_bpi
    #>  8 curvature     curvature       Curv… curvature     Laplacian-… derive_curvatu…
    #>  9 surface_area… surface_area_r… Surf… seafloor_rug… Approximat… derive_surface…
    #> 10 slope_tri_in… slope_tri_index Slop… custom_relief Product of… derive_custom_…
    #> # ℹ 1 more variable: matched <lgl>
    summarize_process_groups(extended, catalog = custom_catalog)
    #> # A tibble: 6 × 3
    #>   process_group     n_metrics metrics
    #>   <chr>                 <int> <chr>
    #> 1 curvature                 1 curvature
    #> 2 custom_relief             1 slope_tri_index
    #> 3 seafloor_aspect           3 aspect_deg, northness, eastness
    #> 4 seafloor_position         2 bpi_3x3, bpi_11x11
    #> 5 seafloor_rugosity         2 tri, surface_area_ratio
    #> 6 slope_gradient            1 slope_deg