Compute a detrended ("height above water") elevation raster

Three detrending methods are available; all return the DEM re-expressed as height above an estimated water-surface reference, on the grid of the DEM cropped to the analysis area.

computeDetrendedRaster(
  transectObject,
  rasterDir = NULL,
  method = c("crossSection", "streamLine", "gradeline"),
  engine = NULL,
  interpSmoothness = "Smooth",
  radius = NULL,
  minPoints = NULL,
  maxPoints = NULL,
  gradelineDegree = "auto"
)

Arguments

transectObject

Object created by generateCrossSections; "crossSection" additionally requires buildXSectionPlot to have run.

rasterDir

File path of the DEM (unused when the DEM is already stored on the transectObject by processSpace).

method

One of "crossSection", "streamLine", "gradeline".

engine

Interpolation engine: "idw", "nearest" (only for streamLine/gradeline), or "krige" (only for crossSection). Default: "krige" for crossSection (legacy behavior), "idw" otherwise.

interpSmoothness

"Smooth" or "Coarse" (crossSection method with engine = "krige" only).

radius, minPoints, maxPoints

IDW window (map units / point counts) for engine = "idw". Forcing at least minPoints source points per cell is what smooths the surface: each cell's reference elevation averages over a long stretch of stream (or several transects) instead of snapping to the closest few points. Defaults (NULL) are per method: 600/300/400 for streamLine/gradeline (a long window along the stream); 100/50/100 for crossSection (spans 2-3 transects without washing out the channel detail sampled along each transect).

gradelineDegree

Polynomial degree of the gradeline fit. The default "auto" fits degrees 1-6 and keeps the smallest degree whose successor improves the RMSE by less than 5% (an elbow rule). Note there is no purely statistical "best" degree here - the residuals from the gradeline are the signal you are mapping, so a criterion that maximizes fit (AIC/BIC, cross-validation) drifts toward high degrees and erases it. The diagnostic plot shows all candidate fits so the choice is visible; pass a number to pin the degree.

Value

A terra SpatRaster. Layer DetrendedElevation always; crossSection/krige adds KrigeVar. For "gradeline", the fit diagnostics are attached as attributes "gradelineFit" (the lm) and "gradelinePlot" (a ggplot of profile vs candidate gradelines).

Details

"crossSection"

(default; the original method) Interpolates the per-transect elevation deltas sampled along the cross sections. Requires buildXSectionPlot to have run. Faithfully tracks the local water surface at every transect, but is blind between/beyond transects. engine = "krige" (default) reproduces the classic 20-point gstat neighborhood, which shows banding between transects; engine = "idw" averages over minPoints+ deltas from several transects, removing the banding.

"streamLine"

The classic relative-elevation-model (REM) approach: a water-surface elevation (WSE) raster is built directly from the stream-line elevation points, then subtracted from the DEM. No cross sections needed. engine = "idw" (default) inverse-distance interpolates from a broad window of stream points (at least minPoints), which smooths the reference surface and avoids striping; engine = "nearest" assigns each cell the elevation of the single nearest stream point (exact at the channel, but banded at meander bends).

"gradeline"

Like "streamLine", but the stream elevations are first recast onto a smooth geomorphic gradeline - a polynomial fit of the longitudinal profile (degree chosen automatically by default). Local water-surface anomalies (headcuts, culvert backwater, incision) then appear as deviations instead of being absorbed into the reference surface.