% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/predation_risk.R
\name{score_predation_risk}
\alias{score_predation_risk}
\title{Score predation and bioturbation pressure at survey locations}
\usage{
score_predation_risk(
  result,
  predator_data = NULL,
  fetch_live = FALSE,
  match_radius_m = 1000,
  species = "ostrea_edulis",
  verbose = TRUE
)
}
\arguments{
\item{result}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}} with \code{lat}, \code{lon}, and
optionally \code{depth_m} and \code{substrate} columns.}

\item{predator_data}{Dataframe of predator records (see Details), or NULL.}

\item{fetch_live}{Logical. Query EMODnet Biology API (default FALSE).}

\item{match_radius_m}{Numeric. Radius in metres within which predator
records are aggregated per survey cell (default 1000 m).}

\item{species}{Character. Target oyster species -- affects which predators
are most relevant (\code{"ostrea_edulis"} or \code{"magallana_gigas"}).}

\item{verbose}{Logical. Default TRUE.}
}
\value{
\code{result} with additional columns:
\itemize{
\item \code{predation_risk} [0,1]: composite risk index
\item \code{predation_risk_class}: "Low" / "Moderate" / "High" / "Severe"
\item \code{predation_risk_note}: text flag for management planning
\item \code{n_predator_records}: number of predator records within match_radius_m
}
}
\description{
Produces a predation risk index (0 = negligible, 1 = severe) based on
predator occurrence data, substrate rugosity, and depth. The output is
intended as an \strong{overlay} on ecological suitability -- high predation risk
does not reduce the habitat suitability score directly but is flagged in
a separate column for management planning (e.g. cage exclusion, deep
subtidal placement to avoid intertidal drills).

\strong{Input options (in priority order):}
\enumerate{
\item \code{predator_data} -- manually supplied dataframe with predator records
(see Details).
\item \code{fetch_live = TRUE} -- queries EMODnet Biology for \emph{Asterias rubens} and
\emph{Carcinus maenas} occurrence records within the survey extent. Requires
internet access and the \code{httr} package.
\item Neither -- returns a depth-proxy-only risk score with a warning.
}
}
\section{predator_data format}{

A dataframe with columns:
\itemize{
\item \code{lat}, \code{lon} -- coordinates
\item \code{species} -- species name or AphiaID (character)
\item \code{density} (optional) -- relative abundance / density index; if absent,
each record is treated as presence-only (density = 1)
\item \code{date} (optional) -- survey date (used to filter to relevant season)
}
}

\examples{
\donttest{
# Manual data
pred <- data.frame(lat=51.5, lon=-4.1, species="Asterias rubens", density=3)
result <- score_predation_risk(result, predator_data=pred, species="ostrea_edulis")

# Live EMODnet fetch
result <- score_predation_risk(result, fetch_live=TRUE)

# Depth-proxy only (no predator data)
result <- score_predation_risk(result)
}
}
