Package {blueterra}

blueterra: Process-oriented geomorphometry for submerged terrain

Description

blueterra derives, organizes, summarizes, and visualizes terrain metrics from user-supplied bathymetric or elevation rasters. It is intended for submerged-landscape geomorphometry after a raster has already been obtained.

Details

The package accepts terra::SpatRaster objects, local raster file paths, and other raster inputs readable by terra. Vector workflows use terra::SpatVector objects or local vector files readable by terra::vect().

Depth convention is explicit. Some bathymetric rasters store depth as negative elevation, while other workflows use positive depth. Functions preserve the input sign unless a conversion function or argument asks for a sign change.

Terrain derivatives are sensitive to CRS, raster resolution, smoothing, and focal-window scale. Use projected coordinate systems when distance, slope, area, or buffering operations depend on linear units.

Author(s)

Maintainer: Elvin Cordero elvin.cordero@seamountgeo.com

Other contributors:

• SeaMount Geospatial Labs [copyright holder]

See Also

Useful links:

• https://el-cordero.github.io/blueterra/

• https://github.com/el-cordero/blueterra

• Report bugs at https://github.com/el-cordero/blueterra/issues

Add metric layers to an existing raster stack

Description

Combines precomputed metric rasters with an existing metric stack after checking grid geometry.

Usage

add_metric_layers(
  metrics,
  ...,
  names = NULL,
  overwrite = FALSE,
  check_geometry = TRUE
)

Arguments

Details

Custom metrics must be on the same raster grid as the stack they extend. Geometry checks are enabled by default because summaries, PCA tables, and process-group assignments assume cell-aligned layers.

Value

A combined terra::SpatRaster.

See Also

derive_custom_metric(), create_metric_catalog()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
metrics <- derive_terrain(bathy, metrics = c("slope", "tri"))
index <- derive_custom_metric(metrics, "slope_tri_index", expression = quote(slope_deg * tri))
add_metric_layers(metrics, index)

Coerce common raster inputs to a bathymetry raster

Description

Accepts a terra::SpatRaster or a local raster file path and returns a terra::SpatRaster.

Usage

as_bathy(x, ..., check = TRUE)

Arguments

Details

as_bathy() preserves raster values and metadata when possible. It does not flip signs, project CRS, or filter depths unless another function explicitly requests that behavior.

Value

A terra::SpatRaster.

See Also

read_bathy(), validate_bathy()

Examples

as_bathy(blueterra_example("bathy"))

Assign metrics to process groups

Description

Matches raster layer names or character metric names to the metric catalog.

Usage

assign_process_groups(
  x,
  catalog = metric_catalog(),
  groups = NULL,
  unmatched = "unassigned"
)

Arguments

Details

Matching uses standardized lower-case metric names. Unmatched metrics are returned with process_group = unmatched so users can inspect custom layers.

Value

A tibble with one row per supplied metric.

See Also

metric_catalog(), summarize_process_groups()

Examples

terrain <- derive_terrain(read_bathy(blueterra_example("bathy")))
assign_process_groups(terrain)

Balance samples across groups

Description

Down-samples or samples with replacement so each group has the same number of rows.

Usage

balance_samples(data, group, n = NULL, replace = FALSE, seed = NULL)

Arguments

Value

A tibble.

See Also

prepare_model_matrix()

Examples

df <- data.frame(group = rep(c("a", "b"), c(2, 5)), value = seq_len(7))
balance_samples(df, group = "group")

Summarize a bathymetric or elevation raster

Description

Returns a compact table describing raster dimensions, extent, CRS, resolution, layer names, and value range.

Usage

bathy_info(x)

Arguments

Value

A tibble with one row per raster layer.

See Also

validate_bathy(), check_bathy_crs()

Examples

bathy_info(blueterra_example("bathy"))

Locate package example files

Description

Returns the path to a small file installed with blueterra.

Usage

blueterra_example(
  name = c("hitw", "hoyo", "slope", "sampling_rectangles", "bathy", "zones", "sites",
    "synthetic_bathy", "synthetic_zones")
)

blueterra_examples()

blueterra_extdata(file = NULL)

Arguments

Details

The primary examples are reduced analysis rasters and sampling rectangles from the southwest Puerto Rico shelf margin near La Parguera. The synthetic files are retained for numerical tests where a simple known surface is useful.

Value

A normalized local file path.

blueterra_examples() returns a tibble describing installed example files.

See Also

read_bathy()

Examples

hitw <- blueterra_example("hitw")
rectangles <- blueterra_example("sampling_rectangles")
file.exists(c(hitw, rectangles))
blueterra_examples()

Configure blueterra runtime options

Description

Returns or sets package options used by examples and helper functions.

Usage

blueterra_options(...)

Arguments

Details

Options affect only local package behavior and do not write outside paths provided by the user.

Value

A named list with current option values, invisibly when setting.

Examples

blueterra_options()
old <- blueterra_options(blueterra.progress = FALSE)
blueterra_options(blueterra.progress = old$blueterra.progress)

Check raster CRS for geomorphometry

Description

Reports whether a bathymetric or elevation raster has a CRS and whether that CRS appears to be geographic longitude/latitude.

Usage

check_bathy_crs(x, require_projected = FALSE, warn_lonlat = TRUE)

Arguments

Details

Many terrain metrics can be calculated on any numeric grid, but metric interpretation is usually strongest in projected coordinate systems with linear units. Buffers, distances, slope, surface-area ratios, and focal windows are all scale-sensitive.

Value

A tibble with CRS status fields.

See Also

prepare_bathy(), project_bathy()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
check_bathy_crs(bathy)

Check bathymetry value conventions

Description

Summarizes raster value ranges and records the intended depth convention when supplied by the user.

Usage

check_bathy_units(x, units = NULL, positive_depth = NULL)

Arguments

Details

This function does not infer or alter scientific meaning. It reports the observed range and the user-supplied convention so downstream workflows can be explicit.

Value

A tibble with value range and convention fields.

See Also

set_depth_positive(), set_depth_negative()

Examples

check_bathy_units(blueterra_example("bathy"), units = "m", positive_depth = FALSE)

Create and validate metric catalog rows

Description

Builds catalog rows for custom metrics and checks that metric catalogs follow the schema used by metric_catalog().

Usage

create_metric_catalog(
  metric,
  label = metric,
  process_group,
  description = NA_character_,
  units = NA_character_,
  source_function = NA_character_,
  requires_optional_dependency = FALSE,
  scale_sensitive = TRUE,
  interpretation_notes = NA_character_
)

extend_metric_catalog(catalog = metric_catalog(), ...)

validate_metric_catalog(catalog)

Arguments

Details

Custom process groups are user-defined terrain-form categories. The catalog records how custom layers should be grouped and interpreted without changing raster values.

Value

A tibble with the same columns as metric_catalog().

See Also

assign_process_groups(), summarize_process_groups()

Examples

row <- create_metric_catalog(
  metric = "slope_tri_index",
  process_group = "custom_relief",
  description = "Product of local slope and terrain ruggedness index."
)
validate_metric_catalog(row)
extend_metric_catalog(metric_catalog(), row)

Crop, mask, resample, and project bathymetry

Description

Small wrappers around terra raster-preparation operations with bathymetry input validation.

Usage

crop_bathy(x, extent, filename = "", overwrite = FALSE)

mask_bathy(x, mask, filename = "", overwrite = FALSE)

resample_bathy(x, y, method = "bilinear", filename = "", overwrite = FALSE)

project_bathy(x, crs, method = "bilinear", filename = "", overwrite = FALSE)

Arguments

Details

These helpers preserve depth sign and raster values except for interpolation effects introduced by resampling or projection.

Value

A terra::SpatRaster.

See Also

prepare_bathy()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
zones <- terra::vect(blueterra_example("zones"))
crop_bathy(bathy, terra::ext(zones[zones$site_id == "slope", ]))

Filter or convert bathymetric depth values

Description

Keeps raster values within a depth or elevation range, or explicitly changes sign convention.

Usage

depth_filter(
  x,
  depth_range,
  positive_depth = NULL,
  filename = "",
  overwrite = FALSE
)

invert_depth(x, filename = "", overwrite = FALSE)

set_depth_positive(x, filename = "", overwrite = FALSE)

set_depth_negative(x, filename = "", overwrite = FALSE)

Arguments

Details

depth_filter() does not flip signs. Use set_depth_positive(), set_depth_negative(), or invert_depth() for explicit sign changes.

Value

A terra::SpatRaster.

See Also

check_bathy_units()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
depth_filter(bathy, c(-80, -30))
set_depth_positive(bathy)

Derive bathymetric position index

Description

Computes a local bathymetric position index from the difference between each cell and its focal-neighborhood mean.

Usage

derive_bpi(
  x,
  inner_radius = NULL,
  outer_radius = NULL,
  window = NULL,
  scale = c("fine", "broad", "custom"),
  normalize = FALSE,
  filename = "",
  overwrite = FALSE,
  ...
)

derive_multiscale_bpi(
  x,
  windows = c(3, 11),
  normalize = FALSE,
  filename = "",
  overwrite = FALSE,
  ...
)

Arguments

Details

The calculation is ⁠cell value - focal mean⁠. Positive values therefore mean higher-than-neighborhood values when the raster is elevation-like. For positive-depth rasters, interpretation is reversed unless users convert the sign convention first.

Value

A single-layer terra::SpatRaster.

See Also

derive_multiscale_bpi(), derive_tpi()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
derive_bpi(bathy, window = 5)

Derive a custom metric from raster layers

Description

Creates a single custom metric layer from an expression or a user-supplied R function.

Usage

derive_custom_metric(
  metrics,
  name,
  expression = NULL,
  fun = NULL,
  ...,
  overwrite = FALSE
)

Arguments

Details

Expressions must be quoted, for example quote(slope_deg * rugosity_vrm_3x3). Character strings are not evaluated. This keeps the workflow explicit and avoids treating text as code.

Value

A single-layer terra::SpatRaster named name.

See Also

add_metric_layers()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
metrics <- derive_terrain(bathy, metrics = c("slope", "tri", "bpi"))
derive_custom_metric(metrics, "slope_tri_index", expression = quote(slope_deg * tri))

relief <- derive_custom_metric(metrics, "relief_index", fun = function(r) {
  out <- r[["tri"]] + abs(r[["bpi_3x3"]])
  names(out) <- "relief_index"
  out
})
relief

Build a stack of terrain metrics

Description

Computes selected metrics and returns them as a named raster stack.

Usage

derive_metric_stack(
  x,
  metrics = "default",
  scales = NULL,
  units = c("degrees", "radians"),
  neighbors = 8,
  positive_depth = NULL,
  filename = "",
  overwrite = FALSE,
  progress = TRUE
)

Arguments

Details

"default" currently expands to bathymetry, slope, aspect, northness, eastness, hillshade, roughness, TRI, TPI, fine BPI, broad BPI, curvature, and surface-area ratio. All metrics are derived locally from the supplied raster.

Value

A terra::SpatRaster.

See Also

derive_terrain()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
derive_metric_stack(bathy, metrics = "default")

Derive individual terrain metrics

Description

Convenience wrappers around terra terrain functions and lightweight geomorphometry formulas.

Usage

derive_slope(
  x,
  units = c("degrees", "radians"),
  neighbors = 8,
  filename = "",
  overwrite = FALSE
)

derive_aspect(
  x,
  units = c("degrees", "radians"),
  neighbors = 8,
  filename = "",
  overwrite = FALSE
)

derive_northness(x, neighbors = 8, filename = "", overwrite = FALSE)

derive_eastness(x, neighbors = 8, filename = "", overwrite = FALSE)

derive_hillshade(
  x,
  angle = 45,
  direction = 315,
  neighbors = 8,
  filename = "",
  overwrite = FALSE
)

derive_roughness(x, filename = "", overwrite = FALSE)

derive_tri(x, filename = "", overwrite = FALSE)

derive_tpi(x, filename = "", overwrite = FALSE)

derive_rugosity(x, window = 3, neighbors = 8, filename = "", overwrite = FALSE)

derive_curvature(x, filename = "", overwrite = FALSE)

derive_surface_area_ratio(x, neighbors = 8, filename = "", overwrite = FALSE)

Arguments

Details

Functions preserve the input raster sign. For example, slope depends on the magnitude of local gradients, while BPI/TPI interpretation depends on whether the raster stores elevation-like values or positive depth.

derive_curvature() computes a simple Laplacian-style local curvature index using a four-neighbor focal kernel. It is not profile curvature or plan curvature. derive_surface_area_ratio() uses 1 / cos(slope) from the terrain slope layer and clamps near-zero cosine values to avoid pathological ratios at extreme slopes.

Value

A single-layer terra::SpatRaster, except where documented otherwise.

See Also

derive_terrain(), derive_bpi()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
derive_slope(bathy)
derive_northness(bathy)

Derive bathymetric terrain metrics

Description

Computes one or more terrain metrics from a user-supplied bathymetric or elevation raster.

Usage

derive_terrain(
  x,
  metrics = "default",
  scales = NULL,
  units = c("degrees", "radians"),
  neighbors = 8,
  positive_depth = NULL,
  filename = "",
  overwrite = FALSE,
  progress = TRUE
)

Arguments

Details

Terrain metrics are scale-sensitive. Slope, curvature, rugosity, TPI, BPI, roughness, and surface-area style metrics depend on grid resolution, smoothing, and focal-window size. Use projected coordinate systems when distances or slopes are interpreted in real linear units.

Value

A terra::SpatRaster containing named metric layers.

See Also

derive_metric_stack(), derive_bpi(), metric_catalog()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
terrain <- derive_terrain(bathy, metrics = c("slope", "aspect", "bpi"))
names(terrain)

Estimate mean surface orientation from a bathymetric raster

Description

Estimates the mean aspect direction of a raster surface and converts that compass bearing to the line-angle convention used by make_transects().

Usage

estimate_surface_orientation(
  bathy,
  area = NULL,
  orientation_weight = c("slope", "none"),
  min_slope = 0,
  return = c("transect_angle", "bearing", "both")
)

Arguments

Details

Aspect is treated as a compass bearing where northness is cos(aspect) and eastness is sin(aspect). Mean circular components are converted to a compass bearing with atan2(eastness, northness). Transect lines are undirected, so the line angle is normalized to ⁠[0, 180)⁠. A south-facing mean aspect near 180 degrees therefore produces a transect angle near 90 degrees.

Value

A numeric angle for "transect_angle" or "bearing", or a tibble with bearing_deg, transect_angle_deg, orientation_weight, min_slope, and n_orientation_cells when return = "both".

See Also

make_transects(), derive_aspect(), derive_slope()

Examples

bathy <- read_bathy(blueterra_example("hitw"))
zones <- terra::vect(blueterra_example("zones"))
hitw <- zones[zones$site_id == "hitw", ]
estimate_surface_orientation(bathy, hitw)

Extract terrain cells in isobath corridors

Description

Extracts raster cell values under corridor polygons.

Usage

extract_isobath_corridors(metrics, corridors, ...)

Arguments

Value

A tibble with corridor identifiers and extracted raster values.

See Also

summarize_isobath_terrain(), summarize_terrain()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
terrain <- derive_terrain(bathy, metrics = c("slope", "bpi"))
corridors <- make_isobath_corridors(bathy, depths = -50, width = 5)
extract_isobath_corridors(terrain, corridors)

Extract isobaths from a raster

Description

Converts raster contour levels to line features.

Usage

extract_isobaths(
  x,
  depths,
  positive_depth = NULL,
  as = c("SpatVector", "sf"),
  ...
)

Arguments

Details

Depth convention is explicit. For rasters stored as negative elevation, either pass negative depths or set positive_depth = FALSE when passing positive depth labels.

Value

Isobath line features as terra::SpatVector by default.

See Also

make_isobath_corridors()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
extract_isobaths(bathy, depths = c(-40, -60))

Extract terrain values at points

Description

Extracts raster values at point locations.

Usage

extract_terrain_points(metrics, points, method = "bilinear", ...)

Arguments

Value

A tibble with point attributes and raster values.

See Also

sample_terrain_cells()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
zones <- terra::vect(blueterra_example("zones"))
pts <- terra::centroids(zones)
extract_terrain_points(bathy, pts)

Build isobath corridors

Description

Buffers isobath contour lines to create depth-following corridor polygons.

Usage

make_isobath_corridors(
  x,
  depths,
  width,
  smooth = FALSE,
  as = c("SpatVector", "sf"),
  positive_depth = NULL,
  ...
)

Arguments

Details

width is interpreted in the CRS map units. Projected CRS are strongly recommended. If the raster uses longitude/latitude, the function warns before buffering because distance interpretation may be misleading.

Value

Isobath corridor polygons as terra::SpatVector by default.

See Also

extract_isobaths(), summarize_isobath_terrain()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
make_isobath_corridors(bathy, depths = c(-40, -60), width = 5)

Create transects across polygon zones

Description

Builds regularly spaced straight transects through polygon features.

Usage

make_transects(
  area,
  spacing,
  angle = NULL,
  bathy = NULL,
  orientation = c("auto", "surface", "bbox", "manual"),
  orientation_weight = c("slope", "none"),
  min_slope = 0,
  length = NULL,
  id_field = NULL,
  as = c("SpatVector", "sf")
)

Arguments

Details

Transect spacing and length are interpreted in map units. Use a projected CRS for metric distances. Candidate lines are created through each polygon bounding box and clipped to the polygon with terra::intersect().

With angle = NULL and a supplied bathy raster, the default transect direction is estimated from the mean surface aspect within each polygon. Aspect is converted to northness and eastness, averaged as circular components, and converted to the mathematical line angle used for transect generation. For example, a south-facing mean aspect near 180 degrees yields a transect angle near 90 degrees, producing north-south transects in projected coordinates. The estimated angle and source metadata are stored on the output lines so the orientation can be inspected.

Value

A terra::SpatVector by default. If as = "sf", an sf object is returned and the optional sf package must be installed.

See Also

estimate_surface_orientation(), sample_transects(), extract_cross_sections()

Examples

zones <- terra::vect(blueterra_example("zones"))
bathy <- read_bathy(blueterra_example("bathy"))
transects <- make_transects(zones[1, ], spacing = 50, bathy = bathy)
transects

manual <- make_transects(zones[1, ], spacing = 50, angle = 90)
manual[, c("angle_deg", "angle_source")]

Terrain metric catalog

Description

Returns a catalog of terrain metrics, labels, process groups, assumptions, and source functions used by blueterra.

Usage

metric_catalog()

process_groups()

Details

The catalog is an interpretation aid, not a claim that terrain metrics directly measure ecological or oceanographic processes. Groups such as seafloor aspect, slope gradient, accumulation potential, seafloor position, seafloor rugosity, downslope pathway proximity, transport potential, and curvature describe terrain form and terrain-routing proxies. Accumulation, pathway, and transport interpretations require separate validation and are not direct current or sediment-flux measurements.

Value

A tibble with columns metric, label, process_group, description, units, source_function, requires_optional_dependency, scale_sensitive, and interpretation_notes.

See Also

derive_terrain(), assign_process_groups()

Examples

metric_catalog()
process_groups()

Terrain metric catalog data

Description

A compact table describing the metrics returned by core blueterra functions and their process-oriented interpretation groups.

Usage

metric_catalog_data

Format

A tibble with columns:

metric

Stable metric name.

label

Human-readable label.

process_group

Process-oriented terrain group.

description

Metric description.

units

Expected units.

source_function

Function that derives the metric.

requires_optional_dependency

Whether an optional dependency is needed.

scale_sensitive

Whether interpretation depends on raster scale.

interpretation_notes

Important interpretation notes.

Details

Use metric_catalog() to retrieve this table in normal workflows.

Label PCA axes with variance and dominant loadings

Description

Builds axis labels for plot_process_pca() from a terrain_pca() object.

Usage

pca_axis_labels(
  pca,
  components = c("PC1", "PC2"),
  top_n = 2,
  unique = TRUE,
  include_variance = TRUE
)

Arguments

Details

Variables are ranked by absolute loading for each component. These labels are descriptive aids for ordination plots; they do not replace inspection of the full loading table.

Value

A named character vector of axis labels.

See Also

terrain_pca(), plot_process_pca()

Examples

df <- data.frame(a = rnorm(10), b = rnorm(10), c = rnorm(10))
pca_axis_labels(terrain_pca(df))

Plot bathymetry and terrain rasters

Description

Creates ggplot2 maps for bathymetry and derived terrain metrics using terra rasters and vectors. Hillshade can be drawn as a semitransparent visual relief layer, and bathymetric contours, sampling rectangles, transects, or other terra::SpatVector geometries can be overlaid.

Usage

plot_bathy(
  x,
  hillshade = TRUE,
  hillshade_alpha = 0.3,
  contours = TRUE,
  contour_interval = NULL,
  contour_color = "white",
  contour_linewidth = 0.25,
  vectors = NULL,
  vector_color = "white",
  vector_linewidth = 0.5,
  labels = NULL,
  label_field = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  legend_title = "Bathymetry",
  max_cells = getOption("blueterra.max_plot_cells", 10000)
)

plot_metric(
  x,
  metric = NULL,
  bathy = NULL,
  hillshade = TRUE,
  hillshade_alpha = 0.3,
  contours = FALSE,
  contour_interval = NULL,
  contour_color = "white",
  contour_linewidth = 0.25,
  vectors = NULL,
  vector_color = "white",
  vector_linewidth = 0.5,
  labels = NULL,
  label_field = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  legend_title = NULL,
  max_cells = getOption("blueterra.max_plot_cells", 10000)
)

plot_terrain_map(
  bathy,
  metric = NULL,
  vectors = NULL,
  contours = TRUE,
  contour_interval = 20,
  hillshade = TRUE,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  ...
)

plot_hillshade(x, max_cells = getOption("blueterra.max_plot_cells", 10000))

plot_sampling_rectangles(bathy, rectangles, label_field = "site_id", ...)

plot_transects(bathy, transects, color_by = NULL, show_legend = FALSE, ...)

plot_metric_stack(x, max_cells = getOption("blueterra.max_plot_cells", 10000))

Arguments

Details

Plotting functions require ggplot2, which is suggested rather than imported. Large rasters are regularly sampled before plotting to keep examples and interactive work responsive. Hillshade is used only as a visual relief layer; it is not a terrain predictor unless a user explicitly derives and analyzes it as one.

Value

A ggplot object.

See Also

derive_terrain(), plot_metric_stack()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  bathy <- read_bathy(blueterra_example("bathy"))
  zones <- terra::vect(blueterra_example("zones"))
  plot_bathy(bathy, vectors = zones, labels = TRUE, label_field = "site_id")
}

Plot sampled cross-sections

Description

Plots raster values against transect distance.

Usage

plot_cross_sections(
  samples,
  value_col = NULL,
  group_col = "transect_id",
  color_col = NULL,
  show_legend = TRUE,
  points = FALSE,
  mean_profile = FALSE,
  mean_profile_na_rm = TRUE,
  normalize_distance = FALSE,
  profile_direction = c("top_to_bottom", "bottom_to_top", "as_sampled", "max_to_min",
    "min_to_max", "high_to_low", "low_to_high"),
  positive_depth = NULL,
  depth_increases_down = TRUE,
  title = NULL,
  subtitle = NULL,
  caption = NULL
)

Arguments

Value

A ggplot object.

See Also

sample_transects(), plot_depth_profile()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  bathy <- read_bathy(blueterra_example("bathy"))
  zones <- terra::vect(blueterra_example("zones"))
  transects <- make_transects(zones[1, ], spacing = 100, bathy = bathy)
  samples <- sample_transects(transects, bathy, n = 5)
  plot_cross_sections(samples)
}

Plot a depth profile

Description

Plots sampled raster values along a transect profile or against depth.

Usage

plot_depth_profile(
  data,
  distance_col = "distance",
  depth_col = NULL,
  value_col = NULL,
  group_col = NULL,
  points = TRUE,
  line = TRUE,
  profile_layout = c("auto", "distance", "metric_by_depth"),
  profile_direction = c("top_to_bottom", "bottom_to_top", "as_sampled", "max_to_min",
    "min_to_max", "high_to_low", "low_to_high"),
  positive_depth = NULL,
  depth_increases_down = TRUE,
  title = NULL,
  subtitle = NULL,
  caption = NULL
)

Arguments

Details

With profile_layout = "distance", the y-axis can be any sampled raster variable: elevation, depth, slope, rugosity, BPI, curvature, or a custom metric. With profile_layout = "metric_by_depth", depth or elevation is placed on the y-axis and the selected terrain metric is placed on the x-axis. Metadata columns such as transect angle, offset, width, and height are ignored during automatic value-column inference.

Value

A ggplot object.

See Also

sample_transects()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  df <- data.frame(distance = 1:5, depth = -c(10, 12, 20, 25, 30))
  plot_depth_profile(df, depth_col = "depth")

  metric_df <- data.frame(
    distance = 1:5,
    bathy_m = -c(10, 12, 20, 25, 30),
    slope_deg = c(4, 6, 9, 12, 15)
  )
  plot_depth_profile(metric_df, depth_col = "bathy_m", value_col = "slope_deg")
}

Plot isobath corridors

Description

Plots isobath corridor polygons, optionally over hillshaded bathymetry with contour lines. The hillshade layer is visual context only.

Usage

plot_isobath_corridors(
  corridors,
  bathy = NULL,
  isobaths = NULL,
  hillshade = TRUE,
  background_contours = FALSE,
  source_isobaths = TRUE,
  isobath_color = "black",
  isobath_linewidth = 0.6,
  corridor_color = "white",
  corridor_linewidth = 0.45,
  corridor_fill = NA,
  corridor_alpha = 0.2,
  labels = TRUE,
  label_field = NULL,
  title = "Isobath Corridors",
  subtitle = NULL,
  caption = NULL,
  contours = NULL,
  ...
)

Arguments

Value

A ggplot object.

See Also

make_isobath_corridors(), plot_bathy()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  bathy <- read_bathy(blueterra_example("bathy"))
  corridors <- make_isobath_corridors(bathy, depths = -50, width = 5)
  isobaths <- extract_isobaths(bathy, depths = -50)
  plot_isobath_corridors(corridors, bathy, isobaths = isobaths)
}

Plot process density

Description

Plots density curves for one or more process-group metrics.

Usage

plot_process_density(data, value, group = NULL)

Arguments

Value

A ggplot object.

See Also

assign_process_groups()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  df <- data.frame(value = rnorm(20), process = rep(c("a", "b"), each = 10))
  plot_process_density(df, value = "value", group = "process")
}

Plot terrain PCA

Description

Plots the first two principal component score axes from terrain_pca().

Usage

plot_process_pca(
  pca,
  color_col = NULL,
  shape_col = NULL,
  label_loadings = TRUE,
  loading_arrows = TRUE,
  top_loadings = 3,
  axis_labels = c("loadings", "variance", "plain"),
  title = NULL,
  subtitle = NULL,
  caption = NULL
)

Arguments

Value

A ggplot object.

See Also

terrain_pca()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  df <- data.frame(a = rnorm(20), b = rnorm(20), c = rnorm(20))
  plot_process_pca(terrain_pca(df))
}

Plot terrain summaries

Description

Plots a summary column from summarize_terrain() or related functions.

Usage

plot_terrain_summary(summary, value, group = NULL)

Arguments

Value

A ggplot object.

See Also

summarize_terrain()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  df <- data.frame(zone_id = 1:3, slope_mean = c(5, 7, 2))
  plot_terrain_summary(df, value = "slope_mean")
}

Prepare a bathymetric or elevation raster

Description

Applies common preprocessing steps for terrain analysis: optional projection, resampling, cropping, masking, depth filtering, sign conversion, smoothing, and optional file-backed output.

Usage

prepare_bathy(
  x,
  crs = NULL,
  resolution = NULL,
  extent = NULL,
  mask = NULL,
  depth_range = NULL,
  positive_depth = NULL,
  method = "bilinear",
  smooth = FALSE,
  smooth_window = 3,
  filename = "",
  overwrite = FALSE
)

Arguments

Details

prepare_bathy() never automatically reprojects or flips depth signs. Those operations occur only when crs or positive_depth are supplied. Distance- based geomorphometry should generally be performed in a projected CRS with linear units.

Value

A terra::SpatRaster.

See Also

crop_bathy(), mask_bathy(), depth_filter()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
prepared <- prepare_bathy(bathy, depth_range = c(-90, -20), smooth = TRUE)
prepared

Prepare a model matrix from terrain data

Description

Converts a terrain table to a numeric predictor matrix and optional response vector.

Usage

prepare_model_matrix(
  data,
  vars = NULL,
  response = NULL,
  scale = FALSE,
  na.rm = TRUE
)

Arguments

Value

A list with x, y, and data.

See Also

sample_terrain_cells(), terrain_pca()

Examples

df <- data.frame(y = c(0, 1, 0), slope = c(1, 2, 3), bpi = c(0.2, 0.1, 0.4))
prepare_model_matrix(df, response = "y")

Read a bathymetric or elevation raster

Description

Reads a local raster file with terra::rast() and optionally validates that the result is usable as a bathymetric or elevation surface.

Usage

read_bathy(path, ..., check = TRUE)

Arguments

Details

read_bathy() is data-source agnostic. The input can be any local raster format supported by terra, including GeoTIFF and many GDAL-readable files. The function treats the raster as a user-supplied terrain surface and preserves its values, CRS, resolution, and vertical sign convention.

Value

A terra::SpatRaster.

See Also

as_bathy(), validate_bathy(), prepare_bathy()

Examples

path <- blueterra_example("bathy")
bathy <- read_bathy(path)
bathy

Sample terrain raster cells

Description

Draws random or regular samples from raster cells and returns a table.

Usage

sample_terrain_cells(
  metrics,
  size,
  method = c("random", "regular"),
  na.rm = TRUE,
  xy = TRUE,
  seed = NULL
)

Arguments

Value

A tibble of sampled cell values.

See Also

extract_terrain_points(), prepare_model_matrix()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
sample_terrain_cells(bathy, size = 10)

Sample rasters along transects

Description

Extracts raster values along transect lines at regular distances.

Usage

sample_transects(
  transects,
  x,
  spacing = NULL,
  n = NULL,
  method = "bilinear",
  drop_na = FALSE
)

extract_cross_sections(
  transects,
  x,
  spacing = NULL,
  n = NULL,
  method = "bilinear"
)

Arguments

Details

If spacing and n are both NULL, twenty points are sampled per transect. Distances are measured from the first line vertex and are in map units. Transect attribute columns, including orientation metadata created by make_transects(), are preserved in the sampled table.

Value

A tibble with transect identifiers, distances, coordinates, and raster values.

See Also

make_transects(), summarize_cross_sections()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
zones <- terra::vect(blueterra_example("zones"))
transects <- make_transects(zones[1, ], spacing = 100, bathy = bathy)
sample_transects(transects, bathy, n = 5)

Select representative metrics for each process group

Description

Chooses a small set of catalog metrics for process-oriented summaries.

Usage

select_process_representatives(
  catalog = metric_catalog(),
  groups = NULL,
  metrics_available = NULL,
  representatives = NULL
)

Arguments

Details

The default representative is the first implemented metric in the catalog for each process group. Users should review and override representatives based on their raster resolution, focal scales, and scientific question.

Value

A tibble with one representative metric per process group.

See Also

metric_catalog(), assign_process_groups()

Examples

select_process_representatives()

Smooth a bathymetric or elevation raster

Description

Applies a square moving-window mean filter.

Usage

smooth_bathy(x, window = 3, na.rm = TRUE, filename = "", overwrite = FALSE)

Arguments

Details

Smoothing changes local gradients and can strongly affect slope, curvature, rugosity, TPI, and BPI. Use it deliberately and report the window size.

Value

A terra::SpatRaster.

See Also

prepare_bathy()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
smooth_bathy(bathy, window = 3)

Standardize or rename metric layers

Description

Converts metric names to stable snake-case names or applies a user-supplied dictionary.

Usage

standardize_metric_names(x)

rename_metric_layers(x, dictionary = NULL)

Arguments

Details

Standardization is conservative and does not change raster values. Use this helper to make layer names predictable before joining to the metric catalog or exporting model-ready tables.

Value

An object of the same broad type as x.

See Also

metric_catalog()

Examples

standardize_metric_names(c("Slope (deg)", "Broad BPI"))

Summarize sampled cross-sections

Description

Summarizes raster values sampled along transects.

Usage

summarize_cross_sections(
  samples,
  value_col = NULL,
  group_col = "transect_id",
  fun = c("mean", "sd", "min", "max", "median"),
  na.rm = TRUE,
  normalize_distance = FALSE,
  n_bins = 50
)

Arguments

Value

A tibble with one row per group.

See Also

sample_transects()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
zones <- terra::vect(blueterra_example("zones"))
transects <- make_transects(zones[1, ], spacing = 100, bathy = bathy)
samples <- sample_transects(transects, bathy, n = 5)
summarize_cross_sections(samples)

Summarize terrain by depth bands

Description

Groups raster cells into depth or elevation bands and summarizes metric values within each band.

Usage

summarize_depth_bands(
  bathy,
  metrics = NULL,
  breaks,
  positive_depth = NULL,
  fun = c("mean", "sd", "min", "max", "median"),
  na.rm = TRUE
)

Arguments

Details

Depth bands are sensitive to vertical sign convention. For negative-elevation bathymetry, use negative breaks or set positive_depth = TRUE with positive depth breaks.

Value

A tibble with one row per depth band and metric.

See Also

depth_filter(), summarize_terrain()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
summarize_depth_bands(bathy, breaks = c(-90, -60, -30, 0))

Summarize terrain by isobath corridor

Description

Computes summary statistics for metric rasters inside corridor polygons.

Usage

summarize_isobath_terrain(
  metrics,
  corridors,
  fun = c("mean", "sd", "min", "max", "median"),
  na.rm = TRUE,
  exact = FALSE,
  ...
)

Arguments

Value

A tibble with one row per corridor.

See Also

make_isobath_corridors(), summarize_terrain()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
terrain <- derive_terrain(bathy, metrics = c("slope", "bpi"))
corridors <- make_isobath_corridors(bathy, depths = -50, width = 5)
summarize_isobath_terrain(terrain, corridors)

Summarize process group representation

Description

Counts available metrics by process group.

Usage

summarize_process_groups(x, catalog = metric_catalog(), groups = NULL)

Arguments

Details

This function summarizes which process groups are represented by a metric stack. It does not compute raster statistics; use summarize_terrain() for spatial summaries.

Value

A tibble with process group counts.

See Also

assign_process_groups(), summarize_terrain()

Examples

terrain <- derive_terrain(read_bathy(blueterra_example("bathy")))
summarize_process_groups(terrain)

Summarize terrain metrics by polygon zones

Description

Computes summary statistics for raster metrics inside polygons, buffers, or corridor features.

Usage

summarize_terrain(
  metrics,
  zones,
  fun = c("mean", "sd", "min", "max", "median"),
  na.rm = TRUE,
  exact = FALSE,
  ...
)

summarize_terrain_by_zone(
  metrics,
  zones,
  fun = c("mean", "sd", "min", "max", "median"),
  na.rm = TRUE,
  exact = FALSE,
  ...
)

Arguments

Details

summarize_terrain() does not assume specific zones, depth ranges, or ecological labels. For distance-sensitive summaries, use zones and rasters in a projected CRS.

Value

A tibble with zone identifiers, zone attributes, and wide summary columns named metric_function.

See Also

summarize_depth_bands(), extract_terrain_points()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
terrain <- derive_terrain(bathy, metrics = c("slope", "bpi"))
zones <- terra::vect(blueterra_example("zones"))
summarize_terrain(terrain, zones)

Correlation table for terrain variables

Description

Computes pairwise correlations among numeric terrain variables.

Usage

terrain_correlation(
  data,
  vars = NULL,
  method = "pearson",
  use = "pairwise.complete.obs"
)

Arguments

Value

A tibble with variable pairs and correlation coefficients.

See Also

terrain_pca()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
terrain <- derive_terrain(bathy, metrics = c("slope", "bpi", "roughness"))
cells <- sample_terrain_cells(terrain, size = 30)
terrain_correlation(cells)

Terrain effect sizes

Description

Computes standardized differences between two groups for numeric terrain variables.

Usage

terrain_effect_size(data, group, vars = NULL, method = "cohens_d", ...)

Arguments

Details

Cohen's d is computed as the difference in group means divided by pooled standard deviation. Exactly two non-missing groups are required.

Value

A tibble with one row per variable.

See Also

terrain_pca()

Examples

df <- data.frame(group = rep(c("a", "b"), each = 5), slope = 1:10)
terrain_effect_size(df, group = "group", vars = "slope")

Principal components analysis for terrain tables

Description

Runs PCA on numeric terrain variables and returns tidy scores, loadings, variance explained, and the fitted model.

Usage

terrain_pca(
  data,
  vars = NULL,
  center = TRUE,
  scale. = TRUE,
  metadata_cols = NULL,
  keep_metadata = TRUE,
  ...
)

Arguments

Details

Rows with incomplete values in selected variables are omitted before PCA. PCA is descriptive and should be interpreted with scale, CRS, and sampling design in mind.

Value

A list with scores, loadings, variance, model, vars, and complete_rows.

See Also

prepare_model_matrix(), terrain_correlation()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
terrain <- derive_terrain(bathy, metrics = c("slope", "bpi", "roughness"))
cells <- sample_terrain_cells(terrain, size = 30)
terrain_pca(cells)

Run PCA overall and within groups

Description

Fits one terrain PCA across all rows and one PCA within each group level.

Usage

terrain_pca_by_group(
  data,
  group,
  vars = NULL,
  center = TRUE,
  scale. = TRUE,
  min_rows = 5,
  ...
)

Arguments

Details

Group-specific PCA is useful for checking whether ordination structure is dominated by one site or sampling frame. Groups with fewer than min_rows rows are omitted with a warning.

Value

A named list with overall and groups. groups is a named list of PCA objects.

See Also

terrain_pca(), plot_process_pca()

Examples

df <- data.frame(site = rep(c("a", "b"), each = 8), slope = rnorm(16),
                 tri = rnorm(16), bpi = rnorm(16))
terrain_pca_by_group(df, group = "site")

Validate a bathymetric or elevation raster

Description

Checks that an object is a readable terra::SpatRaster with dimensions, layers, and values suitable for terrain analysis.

Usage

validate_bathy(
  x,
  require_crs = FALSE,
  require_values = TRUE,
  allow_multi = FALSE
)

Arguments

Details

Validation does not decide whether values represent positive depth or negative elevation. Use check_bathy_units(), set_depth_positive(), or set_depth_negative() when sign convention matters.

Value

Invisibly returns the input raster.

See Also

check_bathy_crs(), check_bathy_units()

Examples

bathy <- read_bathy(blueterra_example("bathy"))
validate_bathy(bathy)