% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hab_risk.R
\name{score_hab_risk}
\alias{score_hab_risk}
\title{Score harmful algal bloom risk at survey locations}
\usage{
score_hab_risk(
  result,
  hab_data = NULL,
  fetch_live = FALSE,
  date_range = NULL,
  match_radius_m = 5000,
  species = "ostrea_edulis",
  verbose = TRUE
)
}
\arguments{
\item{result}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}}. Must contain \code{lat}, \code{lon}.
Optional: \code{din_ug_l} (dissolved inorganic nitrogen ugg/L) and
\code{temp_surface_c} / \code{temp_bottom_c} for stratification index.}

\item{hab_data}{Dataframe of historical HAB events (see Details), or NULL.}

\item{fetch_live}{Logical. Query ICES HAB database (default FALSE).}

\item{date_range}{Character vector length 2 \code{c("YYYY-MM-DD","YYYY-MM-DD")}.
Date range for live fetch or for filtering manually supplied \code{hab_data}.
Default: last 10 years.}

\item{match_radius_m}{Numeric. Radius in metres for event aggregation
(default 5000 m = 5 km, consistent with ICES monitoring station spacing).}

\item{species}{Character. Target species -- affects toxin severity weights
(\code{"ostrea_edulis"} or \code{"magallana_gigas"}).}

\item{verbose}{Logical. Default TRUE.}
}
\value{
\code{result} with additional columns:
\itemize{
\item \code{hab_risk} [0,1]: composite risk index
\item \code{hab_risk_class}: "Low" / "Moderate" / "High" / "Critical"
\item \code{hab_closure_days_per_year}: estimated days/year with shellfish closures
\item \code{hab_dominant_toxin}: most frequently recorded toxin class at the site
\item \code{hab_risk_note}: management flag
}
}
\description{
Produces a HAB risk index (0 = negligible, 1 = severe) based on historical
bloom event frequency and, where available, nutrient and stratification data.

\strong{Input options (in priority order):}
\enumerate{
\item \code{hab_data} -- manually supplied dataframe of historical HAB events
(see Details).
\item \code{fetch_live = TRUE} -- queries the ICES HAB database for event records
within the survey extent and a specified date range. Requires internet
access and the \code{httr} package.
\item Neither -- returns a fixed background-level risk (0.1) with a warning.
}
}
\section{hab_data format}{

A dataframe with columns:
\itemize{
\item \code{lat}, \code{lon} -- event coordinates (decimal degrees)
\item \code{date} -- event date (Date or character "YYYY-MM-DD")
\item \code{genus} (optional) -- bloom genus (e.g. "Alexandrium", "Pseudo-nitzschia")
\item \code{toxin} (optional) -- toxin class (PSP, ASP, DSP, AZP) -- affects severity weight
\item \code{closure_days} (optional) -- number of days the area was closed; default 1
per event if absent
}
}

\examples{
\donttest{
# Manual data
hab <- data.frame(lat=52.1, lon=-4.5, date="2022-07-15",
                  genus="Alexandrium", toxin="PSP", closure_days=14)
result <- score_hab_risk(result, hab_data=hab, species="ostrea_edulis")

# Live ICES fetch
result <- score_hab_risk(result, fetch_live=TRUE,
                         date_range=c("2015-01-01","2024-12-31"))
}
}
