% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/backscatter.R
\name{classify_substrate_from_backscatter}
\alias{classify_substrate_from_backscatter}
\title{Classify seabed substrate hardness from near-seabed ADCP backscatter}
\usage{
classify_substrate_from_backscatter(
  df,
  backscatter_col,
  is_sv = FALSE,
  bs_min = NULL,
  bs_max = NULL,
  hard_thresh = 0.8,
  mixed_thresh = 0.5,
  soft_thresh = 0.2,
  output_col = "substrate_hardness",
  verbose = TRUE
)
}
\arguments{
\item{df}{Dataframe with at least one column of seabed backscatter values.}

\item{backscatter_col}{Character. Name of the backscatter column.}

\item{is_sv}{Logical. If TRUE, treats values as Sv (dB, typically negative);
hardness is derived from abs(Sv) after sign convention correction.
Default FALSE (raw instrument counts, higher = harder).}

\item{bs_min}{Numeric. Backscatter value mapped to hardness = 0 (softest).
Defaults to 5th percentile of observed data.}

\item{bs_max}{Numeric. Backscatter value mapped to hardness = 1 (hardest).
Defaults to 95th percentile of observed data.}

\item{hard_thresh}{Numeric. Hardness index above which substrate is "Hard"
(default 0.8).}

\item{mixed_thresh}{Numeric. Hardness index above which substrate is "Mixed"
(default 0.5).}

\item{soft_thresh}{Numeric. Hardness index above which substrate is "Soft"
(default 0.2); below is "Very Soft".}

\item{output_col}{Character. Base name for output columns. Two columns are
added: \verb{<output_col>_index} (numeric, 0-1) and \verb{<output_col>_class}
(character). Default \code{"substrate_hardness"}.}

\item{verbose}{Logical. Print classification summary (default TRUE).}
}
\value{
Input dataframe with \code{substrate_hardness_index} and
\code{substrate_hardness_class} columns appended. These map directly to the
\code{substrate_hardness} scored variable in the tolerance spec.
}
\description{
Uses the intensity of acoustic backscatter from the near-seabed bin(s) to
classify substrate type. Hard substrates (gravel, rock, shell hash) scatter
more sound energy than soft substrates (mud, fine sand). The function
converts raw backscatter (dB re 1 m^-1 or instrument counts) to a
categorical substrate class and a continuous hardness index [0, 1].

\strong{Classification thresholds (default, adjustable):}\tabular{lll}{
   Class \tab Hardness index \tab Typical substrate \cr
   Hard \tab 0.8 -- 1.0 \tab Rock, cobble, shell hash \cr
   Mixed \tab 0.5 -- 0.8 \tab Gravel/sand mix, maerl beds \cr
   Soft \tab 0.2 -- 0.5 \tab Sand, sandy mud \cr
   Very Soft \tab 0.0 -- 0.2 \tab Mud, fine silt \cr
}


The hardness index is a min-max normalisation of the mean near-seabed
backscatter across the bottom \code{n_bottom_bins} cells. If the column
contains calibrated volume backscatter (Sv in dB), set \code{is_sv = TRUE}
and a sign-flip is applied (less negative Sv = stronger return = harder).
}
\examples{
\donttest{
# ADCP data with near-seabed backscatter column
survey <- classify_substrate_from_backscatter(survey,
            backscatter_col = "bottom_backscatter_db",
            is_sv = TRUE)

# The substrate_hardness_index column feeds directly into predict_oyster()
# as the 'substrate_hardness' variable
names(survey)[names(survey) == "substrate_hardness_index"] <- "substrate_hardness"
result <- predict_oyster(survey, "ostrea_edulis")
}
}
