% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/predict_oyster.R
\name{predict_oyster}
\alias{predict_oyster}
\title{Predict oyster growth suitability from environmental survey data}
\usage{
predict_oyster(
  data,
  species,
  output_geotiff = FALSE,
  resolution = 2e-04,
  contours = TRUE,
  verbose = FALSE
)
}
\arguments{
\item{data}{A dataframe or a file path to a CSV file. Must contain at minimum:
\itemize{
\item \strong{\code{lon}} / \strong{\code{lng}} / \strong{\code{longitude}} -- longitude in decimal degrees
\item \strong{\code{lat}} / \strong{\code{latitude}} -- latitude in decimal degrees
\item \strong{\code{date}} -- observation date (any format coercible by \code{as.Date()})
Additional environmental columns are matched automatically; see
\strong{Column Naming} below.
}}

\item{species}{Character string identifying the target oyster species.
Accepts the key (\code{"ostrea_edulis"}), latin name, or common name.
Use \code{\link[=list_species]{list_species()}} to see all available options.}

\item{output_geotiff}{Logical or character. If \code{TRUE}, exports a GeoTIFF to
the current working directory as \verb{<species>_suitability.tif}. If a
character string, it is used as the file path. If \code{FALSE} (default), no
raster file is written.}

\item{resolution}{Numeric. Raster cell size in degrees for GeoTIFF output
(default \code{0.001}, approximately 100 m at mid-latitudes). Ignored when
\code{output_geotiff = FALSE}.}

\item{contours}{Logical. If \code{TRUE} (default), contour lines are computed
and embedded in the GeoTIFF export. Ignored when \code{output_geotiff = FALSE}.}

\item{verbose}{Logical. If \code{TRUE}, prints a per-variable scoring summary
after processing (default \code{FALSE}).}
}
\value{
A dataframe (invisibly) with all original columns plus:
\itemize{
\item \strong{\code{season}}: detected season at each location/date.
\item \strong{\code{excluded}}: logical, \code{TRUE} if the location fails a hard exclusion.
\item \strong{\code{exclusion_reason}}: character, reason(s) for exclusion or \code{NA}.
\item \strong{\code{suitability}}: numeric [0, 1], overall weighted suitability score.
\item \strong{\code{suitability_class}}: factor, one of "High", "Moderate", "Low",
"Very Low", "Excluded".
\item \strong{\verb{score_<variable>}}: per-variable component scores.
}

If \code{output_geotiff} is set, a GeoTIFF is written to disk and its path is
printed to the console.
}
\description{
The primary user-facing function of \code{oystermapR}. Accepts a tabular dataset
(CSV file path or dataframe) containing spatial coordinates and environmental
measurements, applies species-specific exclusion and weighted scoring rules,
and returns a scored dataframe alongside an optional GeoTIFF heatmap for
QGIS visualisation.
}
\section{Column Naming}{

Column names are matched case-insensitively. Recognised synonyms:\tabular{ll}{
   Variable \tab Recognised column names \cr
   Longitude \tab \code{lon}, \code{lng}, \code{longitude}, \code{x} \cr
   Latitude \tab \code{lat}, \code{latitude}, \code{y} \cr
   Date \tab \code{date}, \code{datetime}, \code{timestamp} \cr
   Temperature (degrees C) \tab \code{temperature}, \code{temp}, \code{temp_c} \cr
   Salinity (PSU) \tab \code{salinity}, \code{sal}, \code{salinity_psu} \cr
   Dissolved oxygen (mg/L) \tab \code{dissolved_oxygen}, \code{do}, \code{do_mgl}, \code{oxygen} \cr
   Depth (m) \tab \code{depth}, \code{depth_m} \cr
   Current velocity (m/s) \tab \code{current_velocity}, \code{velocity}, \code{current}, \code{u_mean} \cr
   Shear stress (N/m^2) \tab \code{shear_stress}, \code{tau}, \code{bed_shear}, \code{shear} \cr
   Chlorophyll-a (ugg/L) \tab \code{chlorophyll_a}, \code{chla}, \code{chl_a}, \code{chlorophyll} \cr
   Turbidity (NTU) \tab \code{turbidity}, \code{ntu}, \code{turb} \cr
   Slope (degrees) \tab \code{slope}, \code{slope_deg} \cr
   Roughness / rugosity \tab \code{roughness}, \code{rugosity} \cr
   Substrate hardness \tab \code{substrate_hardness}, \code{hardness}, \code{bottom_hardness} \cr
   Sediment type \tab \code{sediment_type}, \code{sediment}, \code{substrate_type} \cr
   Benthic communities \tab \code{benthic_communities}, \code{benthic}, \code{community} \cr
   Biotope \tab \code{biotope}, \code{biotopes}, \code{habitat} \cr
   Fishing intensity \tab \code{fishing_intensity}, \code{fishing}, \code{fishing_observed} \cr
}
}

\examples{
# Minimal runnable example using the bundled Example Bay survey data
\donttest{
adcp_f  <- system.file("extdata", "example_bay_adcp.csv",      package = "oystermapR")
bathy_f <- system.file("extdata", "example_bay_soundings.xyz", package = "oystermapR")
ctd_f   <- system.file("extdata", "example_bay_ctd.csv",       package = "oystermapR")
adcp   <- read_nortek_adcp(adcp_f,    verbose = FALSE)
bathy  <- read_soundings_xyz(bathy_f, verbose = FALSE)
ctd    <- read_generic_csv(ctd_f,     verbose = FALSE)
survey <- merge_sensor_data(adcp = adcp, bathy = bathy, ctd = ctd)
result <- predict_oyster(survey, "ostrea_edulis", verbose = FALSE)
table(result$suitability_class)
}

\donttest{
# Using your own CSV file
result <- predict_oyster(
  data    = "my_survey.csv",
  species = "ostrea_edulis",
  output_geotiff = "oyster_suitability.tif"
)
}
}
