% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/climate_projection.R
\name{project_suitability}
\alias{project_suitability}
\title{Project suitability under future climate scenarios}
\usage{
project_suitability(
  result,
  tolerances,
  scenarios = c("rcp26", "rcp45", "rcp85"),
  custom_deltas = NULL,
  horizon = "2050s",
  verbose = TRUE
)
}
\arguments{
\item{result}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}} (the baseline).}

\item{tolerances}{Species tolerance list from \code{\link[=get_species_tolerances]{get_species_tolerances()}}.}

\item{scenarios}{Character vector of built-in scenario names, or NULL to
use \code{custom_deltas} only. Built-in: \code{"rcp26"}, \code{"rcp45"}, \code{"rcp85"}.
Default: all three.}

\item{custom_deltas}{Named list of custom scenarios. Each element is a
named numeric vector of deltas keyed to column names, e.g.
\code{list(my_scenario = c(temperature = 1.5, salinity = -0.3))}.}

\item{horizon}{Character. Label for the time horizon, used in output names
only (default \code{"2050s"}).}

\item{verbose}{Logical. Print scenario comparison table (default TRUE).}
}
\value{
Named list:
\itemize{
\item One dataframe per scenario (named by scenario key) with \code{suitability},
\code{suitability_class}, and \code{suitability_delta} columns.
\item \code{"summary"} -- dataframe comparing mean suitability, class breakdown,
and net change vs baseline across all scenarios.
}
}
\description{
Re-scores survey locations under user-specified climate perturbations to
assess how habitat suitability may change under warming and related
oceanographic shifts. Perturbations are applied as additive deltas to
temperature and salinity, and multiplicative factors to other variables.

Built-in scenarios align with UKCP18 marine projections for NW European
shelf seas:\tabular{llll}{
   Scenario \tab SST delta \tab Salinity delta \tab Notes \cr
   RCP2.6/SSP1 \tab +0.5degrees C \tab 0.0 PSU \tab Low emissions, best case \cr
   RCP4.5/SSP2 \tab +1.2degrees C \tab -0.2 PSU \tab Intermediate emissions \cr
   RCP8.5/SSP5 \tab +2.5degrees C \tab -0.5 PSU \tab High emissions, worst case \cr
   Custom \tab user \tab user \tab Supply your own deltas \cr
}


The function runs \code{score_locations()} for each scenario and returns a list
with one result dataframe per scenario, plus a comparison summary and a
\code{suitability_delta} column (projected minus baseline) for each.
}
\examples{
\donttest{
result <- predict_oyster(survey, "ostrea_edulis")
tol    <- get_species_tolerances("ostrea_edulis")

# Project under all three UKCP18-aligned scenarios
proj <- project_suitability(result, tol)

# Mean suitability change by scenario
proj$summary

# High-risk cells: currently High but drops to Low under RCP8.5
vulnerable <- subset(proj$rcp85,
  result$suitability_class == "High" & suitability_class == "Low")

# Custom scenario (e.g. local downscaled projection)
proj2 <- project_suitability(result, tol, scenarios = NULL,
  custom_deltas = list(
    ukcp18_p95 = c(temperature = 3.2, salinity = -0.8)))
}
}
