Package {hydromeso}

Title:	Classify Fluvial Mesohabitats from Depth and Velocity
Version:	0.1.0
Date:	2026-07-19
Description:	Classifies hydraulic conditions into nominal fluvial mesohabitat categories using water depth and velocity. It implements the eight-class scheme in the preprint by Cordero and Harris <doi:10.2139/ssrn.7100727>, supports validated rectangular custom schemes, and works with tabular and spatial data through 'terra'. Outputs describe hydraulic classes and do not by themselves establish biological habitat quality or species occurrence.
License:	GPL-3
URL:	https://el-cordero.github.io/hydromeso/, https://github.com/el-cordero/hydromeso
BugReports:	https://github.com/el-cordero/hydromeso/issues
Encoding:	UTF-8
Language:	en-US
LazyData:	true
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1)
Imports:	terra
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/Needs/website:	pkgdown
NeedsCompilation:	no
Packaged:	2026-07-19 22:33:37 UTC; ec
Author:	Elvin Cordero [aut, cre]
Maintainer:	Elvin Cordero <elvin.cordero@seamountgeo.com>
Repository:	CRAN
Date/Publication:	2026-07-28 16:50:10 UTC

hydromeso: Classify Fluvial Mesohabitats from Depth and Velocity

Description

hydromeso applies validated rectangular depth-velocity rules to numeric, tabular, vector, and raster hydraulic data. The default eight-class scheme implements the thresholds used by Cordero and Harris (Preprint), with the broader depth-velocity mesohabitat framework informed by Aadland (1993).

Details

The output is a hydraulic mesohabitat classification based on depth and velocity only. It does not independently establish biological habitat quality or species occurrence. Biological interpretation also depends on species, life stage, stream type, substrate, cover, connectivity, water quality, temperature, flow regime, model resolution, and local validation. Raster outputs inherit uncertainty from hydraulic models and input data; alignment and interpolation can affect cells near thresholds. Class IDs are nominal identifiers rather than ordinal scores.

Author(s)

Maintainer: Elvin Cordero elvin.cordero@seamountgeo.com (ORCID)

References

Cordero, E. and Harris, A. (Preprint). Semi-Supervised and Supervised Machine Learning Approaches to Predicting Fluvial Mesohabitats from Satellite Data. SSRN preprint. doi:10.2139/ssrn.7100727.

Aadland, L. P. (1993). Stream Habitat Types: Their Fish Assemblages and Relationship to Flow. North American Journal of Fisheries Management, 13(4), 790-806. doi:10.1577/1548-8675(1993)013<0790:SHTTFA>2.3.CO;2.

See Also

meso_scheme_default(), classify_mesohabitat()

Classify fluvial mesohabitats

Description

Main dispatcher for numeric values, tables, spatial vectors, and rasters. All forms use the same lower-inclusive, upper-exclusive rule engine.

Usage

classify_mesohabitat(
  x,
  velocity = NULL,
  depth_col = NULL,
  velocity_col = NULL,
  ...
)

Arguments

Value

The corresponding classified data frame, SpatVector, or categorical SpatRaster.

See Also

classify_mesohabitat_values(), classify_mesohabitat_table(), classify_mesohabitat_vector(), classify_mesohabitat_raster()

Examples

classify_mesohabitat(c(0.2, 0.8), c(0.1, 0.4))

Classify depth and velocity rasters

Description

Supports separate rasters or a selected pair in one multilayer raster. Depth is always the geometry template. Continuous velocity is aligned only when explicitly requested and always with bilinear interpolation.

Usage

classify_mesohabitat_raster(
  depth,
  velocity = NULL,
  scheme = meso_scheme_default(),
  depth_layer = NULL,
  velocity_layer = NULL,
  align = c("error", "velocity_to_depth"),
  aoi = NULL,
  mask_aoi = TRUE,
  assume_crs = NULL,
  dry_threshold = NULL,
  invalid = c("error", "NA"),
  filename = "",
  overwrite = FALSE,
  ...
)

Arguments

Value

A categorical integer SpatRaster on the (possibly AOI-cropped) depth geometry, with a complete class table.

See Also

classify_mesohabitat_series(), write_mesohabitat()

Examples

d <- terra::rast(nrows = 2, ncols = 4, xmin = 0, xmax = 4, ymin = 0, ymax = 2,
                 crs = "EPSG:32615", vals = c(0.2, 0.8, 1.5, 0.2, 0.2, 0.8, 0.8, 1.5))
v <- d
terra::values(v) <- c(0.1, 0.1, 0.1, 0.4, 0.8, 0.4, 0.8, 0.8)
classify_mesohabitat_raster(d, v)

Classify paired hydraulic raster scenarios

Description

Named scenarios are paired by unique names. Unnamed inputs are rejected unless positional pairing is explicitly requested.

Usage

classify_mesohabitat_series(
  depth,
  velocity,
  scenario_names = NULL,
  positional = FALSE,
  scheme = meso_scheme_default(),
  ...
)

Arguments

Value

A categorical multilayer SpatRaster, one layer per scenario.

See Also

mesohabitat_from_median_hydraulics(), modal_mesohabitat()

Examples

d <- terra::rast(nrows = 1, ncols = 2, vals = c(0.2, 0.8), crs = "EPSG:32615")
v <- terra::rast(d); terra::values(v) <- c(0.1, 0.4)
classify_mesohabitat_series(list(low = d), list(low = v))

Classify a table of depth and velocity observations

Description

Classify a table of depth and velocity observations

Usage

classify_mesohabitat_table(
  x,
  depth_col,
  velocity_col,
  scheme = meso_scheme_default(),
  class_col = "mesohabitat_class",
  label_col = "mesohabitat",
  keep_input = TRUE,
  overwrite = FALSE,
  dry_threshold = NULL,
  invalid = c("error", "NA"),
  ...
)

Arguments

Value

A data frame in the original row order.

See Also

classify_mesohabitat_vector(), write_mesohabitat()

Examples

x <- data.frame(site = letters[1:3], d = c(0.2, 0.8, 2), v = c(0.1, 0.4, 0.7))
classify_mesohabitat_table(x, "d", "v")

Classify numeric depth and velocity values

Description

Applies one authoritative rule-table engine. Lower bounds are inclusive, upper bounds are exclusive, missing inputs remain missing, and zero depth and velocity are classified mathematically (Class 1 under the default scheme).

Usage

classify_mesohabitat_values(
  depth,
  velocity,
  scheme = meso_scheme_default(),
  dry_threshold = NULL,
  invalid = c("error", "NA")
)

Arguments

Value

A data frame containing depth, velocity, integer mesohabitat_class, and unordered factor mesohabitat.

References

Cordero, E. and Harris, A. (Preprint). SSRN. doi:10.2139/ssrn.7100727.

See Also

classify_mesohabitat(), classify_mesohabitat_table(), convert_hydraulic_units()

Examples

classify_mesohabitat_values(c(0.2, 0.61, 1.37), c(0.1, 0.61, 0.3))

Classify spatial vector features from depth and velocity attributes

Description

Geometry, CRS, feature order, and existing attributes are retained. Points, lines, and polygons are accepted because classification uses attributes.

Usage

classify_mesohabitat_vector(
  x,
  depth_col,
  velocity_col,
  scheme = meso_scheme_default(),
  class_col = "mesohabitat_class",
  label_col = "mesohabitat",
  overwrite = FALSE,
  dry_threshold = NULL,
  invalid = c("error", "NA"),
  layer = NULL,
  ...
)

Arguments

Value

A terra::SpatVector with integer class and label attributes.

See Also

classify_mesohabitat_raster(), write_mesohabitat()

Examples

x <- data.frame(x = 1:3, y = 1:3, depth = c(0.2, 0.8, 2),
                velocity = c(0.1, 0.4, 0.7))
v <- terra::vect(x, geom = c("x", "y"), crs = "EPSG:32615")
classify_mesohabitat_vector(v, "depth", "velocity")

Compare two classified mesohabitat rasters

Description

Reports nominal transitions, gains and losses by class, unchanged area, and percentage changed. Numeric differences between IDs are never interpreted.

Usage

compare_mesohabitat(before, after, align = c("error", "after_to_before"))

Arguments

Value

A list of ordinary data frames and scalar area metrics.

See Also

summarize_mesohabitat()

Convert hydraulic depth and velocity units

Description

Explicitly converts values before classification. The default scheme remains defined at exactly 0.61 and 1.37 m and 0.30 and 0.61 m/s; converted imperial values can differ slightly at rounded published boundaries.

Usage

convert_hydraulic_units(
  depth = NULL,
  velocity = NULL,
  depth_from = "m",
  depth_to = "m",
  velocity_from = "m/s",
  velocity_to = "m/s"
)

Arguments

Value

A list with converted depth and velocity.

Examples

convert_hydraulic_units(depth = 2, velocity = 1,
                        depth_from = "ft", velocity_from = "ft/s")

Synthetic hydraulic observations

Description

A small redistributable data frame with every default mesohabitat class, exact and adjacent threshold cases, coordinates, and missing values. Depth is in metres and velocity is in metres per second. Coordinates are synthetic UTM Zone 15N metres (EPSG:32615).

Usage

hydromeso_example

Format

A data frame with 18 rows and four variables:

x

Synthetic easting.

y

Synthetic northing.

depth

Water depth in metres.

velocity

Velocity in metres per second.

Source

Created synthetically for this package.

Examples

hydromeso_example
classify_mesohabitat_table(hydromeso_example, "depth", "velocity")

Construct a mesohabitat classification scheme

Description

Creates and validates a rectangular classification in depth-velocity space. Every lower bound is inclusive and every upper bound is exclusive. Class IDs are nominal identifiers, not ecological ranks.

Usage

meso_scheme(
  rules,
  name = "Custom mesohabitat scheme",
  description = NULL,
  depth_units = "m",
  velocity_units = "m/s",
  citation = NULL,
  source_doi = NULL,
  allow_gaps = FALSE,
  allow_negative = FALSE
)

Arguments

Value

An object of class meso_scheme.

See Also

validate_meso_scheme(), meso_scheme_default(), classify_mesohabitat_values()

Examples

rules <- data.frame(
  class_id = c(1L, 2L), label = c("Slow", "Fast"),
  depth_min = c(0, 0), depth_max = c(Inf, Inf),
  velocity_min = c(0, 0.5), velocity_max = c(0.5, Inf)
)
meso_scheme(rules, name = "Two velocity classes")

Default eight-class fluvial mesohabitat scheme

Description

Returns the exact depth-velocity classification used by Cordero and Harris (Preprint). The broader depth-velocity framework is informed by Aadland (1993), whose paper describes six habitat types and should not be read as the source of the two added high-velocity class names. Inputs must be metres and metres per second unless explicitly converted before classification.

Usage

meso_scheme_default()

Value

A validated meso_scheme with eight nominal classes.

References

Cordero, E. and Harris, A. (Preprint). Semi-Supervised and Supervised Machine Learning Approaches to Predicting Fluvial Mesohabitats from Satellite Data. SSRN. doi:10.2139/ssrn.7100727.

Aadland, L. P. (1993). Stream Habitat Types: Their Fish Assemblages and Relationship to Flow. North American Journal of Fisheries Management, 13, 790-806. doi:10.1577/1548-8675(1993)013<0790:SHTTFA>2.3.CO;2.

See Also

meso_scheme(), plot_meso_scheme()

Examples

meso_scheme_default()

Extract the rules from a mesohabitat scheme

Description

Extract the rules from a mesohabitat scheme

Usage

meso_scheme_rules(x)

Arguments

Value

A plain data frame containing the rule table.

Examples

meso_scheme_rules(meso_scheme_default())

Load example HEC-RAS hydraulic rasters

Description

Loads a compact pair of depth and velocity GeoTIFFs derived from the 31 May 2022 HEC-RAS model output used by Cordero and Harris (Preprint). The sample shows the Big Blue-Kansas Rivers confluence near Manhattan, Kansas. Source cells were cropped to the manuscript's detailed visualization extent, aggregated from 3-foot to 18-foot cells, and converted to metres and metres per second. The raster geometry remains in the source project's documented NAD 1983 (CORS96) StatePlane Kansas North coordinate system.

Usage

mesohabitat_example_rasters(paths = FALSE)

Arguments

Value

A named list with depth and velocity rasters or file paths.

References

Cordero, E. and Harris, A. (Preprint). Semi-Supervised and Supervised Machine Learning Approaches to Predicting Fluvial Mesohabitats from Satellite Data. SSRN. doi:10.2139/ssrn.7100727.

Examples

x <- mesohabitat_example_rasters()
classify_mesohabitat_raster(x$depth, x$velocity)

Create a synthetic example spatial vector

Description

Create a synthetic example spatial vector

Usage

mesohabitat_example_vector()

Value

A point terra::SpatVector in EPSG:32615 made from hydromeso_example.

Examples

mesohabitat_example_vector()

Mesohabitat derived from median hydraulic surfaces

Description

Calculates cellwise median depth and median velocity, then classifies those hydraulic surfaces. This is not a numeric median of nominal class IDs and should not be called "median mesohabitat".

Usage

mesohabitat_from_median_hydraulics(
  depth,
  velocity,
  na.rm = TRUE,
  scheme = meso_scheme_default(),
  ...
)

Arguments

Value

A named list containing median_depth, median_velocity, and mesohabitat_from_median_hydraulics.

See Also

classify_mesohabitat_series(), modal_mesohabitat()

Stable mesohabitat class colors

Description

Stable mesohabitat class colors

Usage

mesohabitat_palette(scheme = meso_scheme_default())

Arguments

Value

A named character vector keyed by class label.

Modal mesohabitat across scenarios

Description

Computes the most frequent nominal class per cell. It never calculates a numeric median of class IDs.

Usage

modal_mesohabitat(x, ties = c("NA", "lowest_class"), na.rm = TRUE)

Arguments

Value

A single categorical SpatRaster.

Plot a mesohabitat classification scheme

Description

Plot a mesohabitat classification scheme

Usage

plot_meso_scheme(
  scheme = meso_scheme_default(),
  xlim = NULL,
  ylim = NULL,
  reverse_depth_axis = FALSE,
  palette = mesohabitat_palette(scheme),
  ...
)

Arguments

Value

The scheme, invisibly.

Plot classified mesohabitat output

Description

Plot classified mesohabitat output

Usage

plot_mesohabitat(
  x,
  depth_col = "depth",
  velocity_col = "velocity",
  class_col = "mesohabitat_class",
  label_col = "mesohabitat",
  scheme = .scheme_from_object(x),
  palette = mesohabitat_palette(scheme),
  legend = TRUE,
  legend_ncol = 4,
  legend_cex = 0.75,
  ...
)

Arguments

Value

x, invisibly.

Summarize mesohabitat classes

Description

Summarizes classified tables, vectors, rasters, and raster scenarios. Raster areas use terra::cellSize() and are valid for projected or geographic grids.

Usage

summarize_mesohabitat(
  x,
  class_col = "mesohabitat_class",
  label_col = "mesohabitat",
  denominator = c("classified", "non_na", "mask"),
  analysis_mask = NULL
)

Arguments

Value

An ordinary data frame.

See Also

compare_mesohabitat()

Validate a mesohabitat classification scheme

Description

Performs deterministic breakpoint-based checks of rule structure, metadata, overlaps, gaps, and reachability. The nonnegative depth-velocity plane is the required domain unless gaps are allowed. No random sampling is used.

Usage

validate_meso_scheme(x)

Arguments

Value

The validated object, invisibly.

See Also

meso_scheme()

Examples

validate_meso_scheme(meso_scheme_default())

Write classified mesohabitat output

Description

Dispatches to a categorical GeoTIFF or other raster format, a terra vector format, or CSV. Shapefile output uses short safe class field names to avoid silent truncation.

Usage

write_mesohabitat(
  x,
  filename,
  overwrite = FALSE,
  sidecar = TRUE,
  create_dir = FALSE,
  scheme = .scheme_from_object(x),
  ...
)

Arguments

Value

The normalized output path, invisibly.