% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/variable_importance.R
\name{sensitivity_analysis}
\alias{sensitivity_analysis}
\title{Partial dependence / sensitivity analysis for a scored variable}
\usage{
sensitivity_analysis(
  predicted,
  species,
  variable,
  n_steps = 100L,
  background = NULL,
  season = NULL,
  verbose = TRUE
)
}
\arguments{
\item{predicted}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}} containing \code{lat}, \code{lon},
\code{suitability}, and per-variable score/weight columns.}

\item{species}{Character. Species key (e.g. \code{"ostrea_edulis"}). Used to
retrieve tolerance parameters for the scoring function.}

\item{variable}{Character. Name of the focal variable to vary (e.g.
\code{"temperature"}, \code{"salinity"}, \code{"depth"}).}

\item{n_steps}{Integer. Number of evenly spaced values across the variable's
biological range (default 100).}

\item{background}{Named list. Fixed values for all other variables. If NULL
(default), uses column medians from \code{predicted}.}

\item{season}{Character or NULL. Season to apply for seasonal variables
(e.g. \code{"summer"}). NULL = no seasonal override.}

\item{verbose}{Logical. Default TRUE.}
}
\value{
A dataframe with columns:
\itemize{
\item \code{x}: focal variable value
\item \code{suitability}: predicted suitability at that value
\item \code{variable}: focal variable name
\item \code{species}: species key
}

Suitable for plotting with \code{ggplot2} or base R \code{plot()}.
}
\description{
Computes the marginal response curve for a single environmental variable:
suitability is predicted at a grid of values for the focal variable, while
all other variables are held at their observed median (or a specified
background value). This reveals the shape of the scoring function as
actually applied to a real dataset.

Partial dependence is a standard diagnostic for SDM publication (Elith et al.
2008; Zurell et al. 2020 ODMAP protocol). Use it to verify that predicted
responses match ecological expectations before submission.
}
\examples{
\donttest{
result <- predict_oyster(survey, "ostrea_edulis")

# Temperature response curve
temp_pd <- sensitivity_analysis(result, "ostrea_edulis", "temperature")
plot(temp_pd$x, temp_pd$suitability, type="l",
     xlab="Temperature (degrees C)", ylab="Suitability",
     main="Partial dependence: temperature")

# Salinity response (summer)
sal_pd <- sensitivity_analysis(result, "ostrea_edulis", "salinity",
                               season = "summer")

# ggplot2 version
library(ggplot2)
ggplot(temp_pd, aes(x, suitability)) +
  geom_line(colour="steelblue", linewidth=1.2) +
  geom_ribbon(aes(ymin=0, ymax=suitability), alpha=0.2, fill="steelblue") +
  labs(x="Temperature (degrees C)", y="Suitability [0-1]") +
  theme_minimal()
}
}
\references{
Elith et al. (2008) J Animal Ecology 77:802-813.
Zurell et al. (2020) Ecography 43:1261-1277.
}
