% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/survey_compare.R
\name{compare_surveys}
\alias{compare_surveys}
\title{Compare suitability scores across multiple surveys or monitoring years}
\usage{
compare_surveys(
  surveys,
  cell_deg = 0.001,
  stable_threshold = 0.05,
  verbose = TRUE
)
}
\arguments{
\item{surveys}{Named list of dataframes from \code{\link[=predict_oyster]{predict_oyster()}}. Names
should be meaningful labels (e.g. survey year or site name).}

\item{cell_deg}{Numeric. Spatial rounding tolerance in decimal degrees for
matching cells across surveys (default 0.001 approx. 111 m).}

\item{stable_threshold}{Numeric. Absolute suitability change below which a
cell is considered "stable" rather than improved/degraded (default 0.05).}

\item{verbose}{Logical. Print comparison summary (default TRUE).}
}
\value{
Named list: \code{summary} (dataframe), \code{spatial} (dataframe),
\code{change} (dataframe or NULL if only one survey).
}
\description{
Takes a named list of \code{predict_oyster()} result dataframes and produces a
single comparative summary suitable for trend monitoring, multi-site
selection, or regulatory reporting. Common spatial cells are matched across
surveys and a change analysis is run between consecutive surveys if ordered
chronologically.

The function returns a list with three elements:
\itemize{
\item \code{summary} -- one row per survey with mean suitability, class breakdown,
and data completeness stats.
\item \code{spatial} -- all surveys joined on shared lat/lon cells, with suitability
columns per survey and \code{trend_slope} (linear regression of suitability
over survey index for each cell).
\item \code{change} -- pairwise change table (only if surveys are in order; each
consecutive pair shows mean score difference and fraction of cells
that improved, degraded, or were stable).
}
}
\examples{
\donttest{
r2022 <- predict_oyster(survey_2022, "ostrea_edulis")
r2023 <- predict_oyster(survey_2023, "ostrea_edulis")
r2024 <- predict_oyster(survey_2024, "ostrea_edulis")

comp <- compare_surveys(
  surveys = list("2022" = r2022, "2023" = r2023, "2024" = r2024)
)

comp$summary        # mean scores by year
comp$change         # year-on-year change

# Pass to generate_report() for a full comparative HTML report
generate_report(r2024, "monitoring_report.html",
                title = "Kames Bay 3-Year Monitoring")
}
}
