% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/batch_compare.R
\name{compare_species}
\alias{compare_species}
\title{Compare suitability across multiple oyster species}
\usage{
compare_species(
  data,
  species = NULL,
  output_dir = NULL,
  min_data_quality = "low",
  verbose = TRUE
)
}
\arguments{
\item{data}{A dataframe or CSV path accepted by \code{\link[=predict_oyster]{predict_oyster()}}.}

\item{species}{Character vector of species keys to compare. Defaults to all
species currently in the oystermapR database (see \code{\link[=list_species]{list_species()}}).
Passing \code{NULL} uses all available species.}

\item{output_dir}{Character or \code{NULL}. If a directory path is supplied,
individual GeoTIFF heatmaps are exported for each species into that folder.
Default \code{NULL} (no rasters written).}

\item{min_data_quality}{Character. Minimum data quality tier to include:
\code{"low"}, \code{"medium"}, or \code{"high"} (default \code{"low"} -- include all species).
Set to \code{"high"} to restrict to well-characterised species only.}

\item{verbose}{Logical. Print a comparison summary per species (default \code{TRUE}).}
}
\value{
A dataframe with all original survey columns plus:
\itemize{
\item \verb{suit_<species_key>}: suitability score [0, 1] per species
\item \verb{class_<species_key>}: suitability class per species
\item \code{best_species}: key of the species with the highest suitability at each
location (NA if all excluded)
\item \code{best_suitability}: the highest suitability score across all species
\item \code{n_species_high}: number of species scoring "High" at each location
(useful for identifying robust multi-species sites)
}
}
\description{
Runs \code{\link[=predict_oyster]{predict_oyster()}} for every specified species against the same survey
dataset and returns a combined comparison table -- one row per survey
location, one suitability column per species. An optional summary prints
which species is best-suited to each location.

This is the tool to use when you haven't yet decided which species to stock,
or when you want to identify areas where multiple species overlap in
suitability (robust site selection).
}
\examples{
\donttest{
# Compare all supported species
comparison <- compare_species(survey)

# Compare only well-characterised species
comparison <- compare_species(survey, min_data_quality = "high")

# Compare specific species and export per-species heatmaps
comparison <- compare_species(
  survey,
  species    = c("ostrea_edulis", "magallana_gigas"),
  output_dir = "comparison_maps/"
)

# Find sites suitable for both O. edulis AND M. gigas
both_high <- subset(comparison, n_species_high >= 2)
}
}
