Package 'hydromeso'

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

x	Numeric depth values, a table, a SpatVector, a SpatRaster, or a supported file path.
velocity	Numeric velocity values or a velocity raster/path.
depth_col, velocity_col	Table/vector column selectors.
...	Arguments passed to the type-specific classifier.

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

depth	A SpatRaster or raster path. It may contain both selected layers when velocity = NULL.
velocity	A separate SpatRaster or path, or NULL.
scheme	A validated meso_scheme; values must use its units.
depth_layer, velocity_layer	Optional layer names or positions.
align	"error" or "velocity_to_depth".
aoi	Optional SpatVector or vector path.
mask_aoi	If TRUE, crop and polygon-mask; otherwise rectangular crop.
assume_crs	Optional CRS assigned only to inputs missing a CRS. This does not transform coordinates and emits a message.
dry_threshold, invalid	Classification controls.
filename	Optional output filename.
overwrite	Permit overwriting filename.
...	Additional terra::writeRaster() options.

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

depth, velocity	Multilayer SpatRaster objects, lists of rasters, or lists of raster paths.
scenario_names	Optional unique names that explicitly define both lists.
positional	Permit explicit position-based pairing when names are absent.
scheme	A meso_scheme.
...	Passed to classify_mesohabitat_raster().

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

x	A data frame, matrix, or path to a CSV file.
depth_col, velocity_col	Column names or one-based positions.
scheme	A validated meso_scheme.
class_col, label_col	Names for appended output fields.
keep_input	Keep all input columns; if FALSE, return selected inputs and classifications only.
overwrite	Permit replacing existing output columns.
dry_threshold, invalid	Passed to classify_mesohabitat_values().
...	Additional arguments passed to utils::read.csv() for a path.

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

depth, velocity	Numeric vectors in the units declared by scheme. Length-one inputs may be deliberately recycled; other unequal lengths fail.
scheme	A validated meso_scheme.
dry_threshold	NULL to preserve the scheme exactly, or a nonnegative depth at or below which classifications become NA.
invalid	Either "error" (default) or "NA" for negative and infinite observations. Values are never clamped or replaced with zero.

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

x	A terra::SpatVector or vector dataset path supported by terra.
depth_col, velocity_col	Attribute names or positions.
scheme, class_col, label_col, overwrite, dry_threshold, invalid	As in classify_mesohabitat_table().
layer	Optional layer name when reading a multi-layer vector dataset.
...	Additional arguments passed to terra::vect() for a path.

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

before, after	Single-layer classified SpatRaster objects.
align	"error" (default) or "after_to_before"; explicit alignment uses nearest-neighbor resampling because class values are categorical.

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

depth, velocity	Optional numeric values.
depth_from, depth_to	One of "m", "cm", or "ft".
velocity_from, velocity_to	One of "m/s", "cm/s", or "ft/s".

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

rules	A data frame with class_id, label, depth_min, depth_max, velocity_min, and velocity_max.
name	Nonempty scheme name.
description	Optional description.
depth_units, velocity_units	Nonempty unit labels.
citation	Optional source citation.
source_doi	Optional source DOI.
allow_gaps	Whether uncovered regions at nonnegative depth and velocity are permitted.
allow_negative	Whether negative rule minima are permitted.

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

x	A meso_scheme.

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

paths

Logical. If FALSE (default), return loaded SpatRaster objects. If TRUE, return their installed GeoTIFF paths.

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

depth, velocity	Multilayer SpatRaster objects or scenario lists.
na.rm	Remove missing values in the cellwise medians.
scheme	A meso_scheme.
...	Passed to classify_mesohabitat_raster().

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

scheme

A meso_scheme.

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

x	A classified multilayer SpatRaster.
ties	"NA" (default) or "lowest_class".
na.rm	Ignore missing scenarios.

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

scheme	A meso_scheme.
xlim, ylim	Optional finite velocity and depth limits.
reverse_depth_axis	Reverse the displayed depth axis only when TRUE.
palette	Named class colors.
...	Additional arguments passed to graphics::plot.default().

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

x	A classified table, SpatVector, or SpatRaster.
depth_col, velocity_col	Table columns for depth and velocity.
class_col, label_col	Classification columns.
scheme	A meso_scheme.
palette	Named colors.
legend	Show one shared legend below the plot or plot panels.
legend_ncol	Number of columns in the shared legend.
legend_cex	Legend text size multiplier.
...	Additional plotting 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

x	A classified data frame, SpatVector, or SpatRaster.
class_col, label_col	Classification field names for tables/vectors.
denominator	Raster percentage denominator: "classified", "non_na", or "mask". The first two are equivalent for a classified raster; "mask" uses analysis_mask area.
analysis_mask	Optional raster mask.

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

x	A meso_scheme object.

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

x	A classified data frame, SpatVector, or SpatRaster.
filename	Output path.
overwrite	Permit replacement.
sidecar	Write a CSV class table beside the output.
create_dir	Create missing parent directories only when TRUE.
scheme	A meso_scheme used for the sidecar.
...	Format-specific writer arguments.

Value

The normalized output path, invisibly.

---