% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sediment_stability.R
\name{score_sediment_stability}
\alias{score_sediment_stability}
\title{Score sediment stability and mobility at survey locations}
\usage{
score_sediment_stability(
  result,
  current_col = "current_ms",
  wave_hs_col = "wave_hs_m",
  depth_col = "depth_m",
  substrate_col = "substrate",
  d50_col = "d50_mm",
  wave_period_s = 8,
  drag_coef = 0.003,
  verbose = TRUE
)
}
\arguments{
\item{result}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}}. Must contain \code{lat}, \code{lon}.
Key optional columns (column names configurable via arguments):
\itemize{
\item \code{current_ms}: depth-averaged current speed (m/s)
\item \code{wave_hs_m}: significant wave height (m) -- from \code{score_wave_exposure()}
or direct measurement
\item \code{depth_m}: water depth (m) -- needed for wave orbital velocity
\item \code{substrate}: substrate classification string -- used to estimate d50
\item \code{d50_mm}: median grain diameter (mm) -- overrides substrate-derived d50
}}

\item{current_col}{Character. Column name for depth-averaged current speed
(m/s). Default \code{"current_ms"}.}

\item{wave_hs_col}{Character. Column name for significant wave height (m).
Default \code{"wave_hs_m"}.}

\item{depth_col}{Character. Column name for depth (m). Default \code{"depth_m"}.}

\item{substrate_col}{Character. Column name for substrate type. Default
\code{"substrate"}.}

\item{d50_col}{Character. Column name for measured median grain size (mm).
Default \code{"d50_mm"}. If present, overrides substrate-derived estimate.}

\item{wave_period_s}{Numeric. Peak wave period in seconds for orbital
velocity calculation. Default 8 s (typical NW European sea state).}

\item{drag_coef}{Numeric. Quadratic bed drag coefficient C_f. Default
0.003 (smooth mixed seabed; increase to 0.005-0.010 for rough rock/reef).}

\item{verbose}{Logical. Default TRUE.}
}
\value{
\code{result} with additional columns:
\itemize{
\item \code{shields_parameter}: Shields number theta at each site
\item \code{shields_critical}: critical Shields number theta_cr for the substrate d50
\item \code{mobility_ratio}: theta / theta_cr (> 1.0 = mobile; < 1.0 = stable)
\item \code{d50_mm_estimated}: grain size used (mm) -- measured or substrate-derived
\item \code{sediment_stability_score} [0,1]: 1 = fully stable, 0 = highly mobile
\item \code{sediment_mobility_class}: "Stable" / "Marginally stable" / "Mobile" / "Highly mobile"
\item \code{sediment_stability_note}: management flag
}
}
\description{
Calculates the Shields parameter and a sediment stability score [0,1] for
each survey location. High sediment mobility (theta >> theta_cr) indicates that
the seabed is frequently in motion, which is unfavourable for oyster
settlement, juvenile survival, and restoration reef persistence.
}
\section{Inputs required}{

At minimum, the function needs current velocity to estimate bed shear
stress. Grain size improves accuracy but can be estimated from the
substrate type column if not directly measured.
}

\examples{
\donttest{
# With current velocity and substrate type columns
result <- score_sediment_stability(result, current_col="current_ms", substrate_col="substrate")

# After score_wave_exposure() -- wave_hs_m column already present
result <- score_wave_exposure(result, fetch_km=15)
result <- score_sediment_stability(result)

# With measured grain size
result$d50_mm <- c(0.25, 2.5, 15.0, 0.08)
result <- score_sediment_stability(result)
}
}
