% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/water_quality.R
\name{add_shellfish_classification}
\alias{add_shellfish_classification}
\title{Add shellfish water quality classification to scored result}
\usage{
add_shellfish_classification(
  result,
  class_col = NULL,
  classified_areas = NULL,
  fetch_live = FALSE,
  match_radius_deg = 0.05,
  verbose = TRUE
)
}
\arguments{
\item{result}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}} or \code{\link[=score_locations]{score_locations()}}.
Must contain \code{lat} and \code{lon}.}

\item{class_col}{Character. Name of an existing column in \code{result} containing
class values. If supplied, \code{classified_areas} and \code{fetch_live} are ignored.}

\item{classified_areas}{Dataframe with \code{lat}, \code{lon}, \code{shellfish_class}
columns. Used when \code{class_col} is NULL and \code{fetch_live = FALSE}.}

\item{fetch_live}{Logical. Query live FSA/DAERA API (default FALSE). Requires
internet access and the \code{httr} package. If fetch fails, falls back to
"Unclassified".}

\item{match_radius_deg}{Numeric. Spatial matching tolerance in decimal
degrees when using \code{classified_areas} (default 0.05 = ~5 km).}

\item{verbose}{Logical. Print matching summary (default TRUE).}
}
\value{
\code{result} with two additional columns:
\itemize{
\item \code{shellfish_class}: "A", "B", "C", "Prohibited", or "Unclassified"
\item \code{shellfish_class_penalty}: multiplier applied to economic viability
(1.0 for A, 0.80 for B, 0.60 for C, 0.0 for Prohibited, 0.70 for
Unclassified)
}
}
\description{
Attaches a regulatory shellfish harvesting classification (A/B/C/Prohibited)
to each row of a scored result dataframe. This classification affects the
economic viability score for aquaculture applications: Prohibited sites
receive viability = 0; Class C sites receive a 0.60 multiplier; Class B a
0.80 multiplier; Class A is unpenalised.

Classification can be supplied three ways (in priority order):
\enumerate{
\item \strong{\code{class_col}} -- name of an existing column in \code{result} already
containing classification values ("A", "B", "C", "Prohibited", or NA).
\item \strong{\code{classified_areas}} -- a dataframe with \code{lat}, \code{lon}, and
\code{shellfish_class} columns, spatially matched to result rows within
\code{match_radius_deg} degrees.
\item \strong{\code{fetch_live = TRUE}} -- queries the FSA England/Wales open data API
(requires internet). Requires \code{httr} package. Works only for sites
within the FSA/DAERA coverage area (England, Wales, Northern Ireland).
}

Unclassified or unmatched sites receive \code{shellfish_class = "Unclassified"}
and a penalty of 0.70 (precautionary principle).
}
\examples{
\donttest{
# Option 1: manual column already in data
result <- add_shellfish_classification(result, class_col = "water_class")

# Option 2: separate classified areas dataframe
areas <- data.frame(lat = c(51.5), lon = c(-4.2), shellfish_class = c("B"))
result <- add_shellfish_classification(result, classified_areas = areas)

# Option 3: live fetch (internet required)
result <- add_shellfish_classification(result, fetch_live = TRUE)
}
}
