% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oystermapR-package.R
\docType{package}
\name{oystermapR-package}
\alias{oystermapR}
\alias{oystermapR-package}
\title{oystermapR: Predict and Map Oyster Growth Suitability}
\description{
\code{oystermapR} provides a rule-based, AHP-weighted suitability scoring
pipeline for predicting where conditions are most likely to support oyster
growth. Users supply a tabular dataset of environmental and physical
measurements (collected in the field or from remote sensing), specify a
target species, and receive:
\itemize{
\item Per-location suitability scores [0, 1]
\item Categorical suitability classes (High / Moderate / Low / Very Low / Excluded)
\item Per-variable component scores for diagnosis and reporting
\item A GeoTIFF raster file for heatmap visualisation in QGIS
\item A QGIS colour-ramp style file (.qml)
\item Contour lines for overlay mapping
\item A formatted PDF or HTML report
}
}
\section{Supported species}{
\tabular{llll}{
   Key \tab Latin name \tab Common name \tab Region \cr
   \code{ostrea_edulis} \tab \emph{Ostrea edulis} \tab European flat oyster \tab NE Atlantic, North Sea, Mediterranean \cr
   \code{magallana_gigas} \tab \emph{Magallana gigas} \tab Pacific oyster \tab Cosmopolitan (introduced) \cr
   \code{crassostrea_angulata} \tab \emph{Crassostrea angulata} \tab Portuguese oyster \tab Iberian Peninsula, W Atlantic \cr
   \code{ostrea_stentina} \tab \emph{Ostrea stentina} \tab Denticulate flat oyster \tab Mediterranean, Mar Menor \cr
   \code{ostrea_lurida} \tab \emph{Ostrea lurida} \tab Olympia oyster \tab NE Pacific: Alaska to Baja California \cr
}


Use \code{\link[=list_species]{list_species()}} to see all species with their data quality ratings.
}

\section{Typical workflow}{


\if{html}{\out{<div class="sourceCode r">}}\preformatted{library(oystermapR)

# Load your survey data
df <- read.csv("my_survey.csv")

# Run the prediction
result <- predict_oyster(
  data           = df,
  species        = "ostrea_edulis",
  output_geotiff = "oyster_suitability.tif",
  verbose        = TRUE
)

# Inspect high-suitability sites
subset(result, suitability_class == "High")

# Export matching QGIS colour style
export_qml_style("oyster_suitability.tif")
}\if{html}{\out{</div>}}
}

\section{Sensor compatibility}{

The package is designed around data collectable with:
\itemize{
\item \strong{Nortek Signature 500 ADCP} -- current velocity, shear stress, turbidity
proxy (read with \code{\link[=read_nortek_adcp]{read_nortek_adcp()}})
\item \strong{Ping 3DSS iDX450 PRO Bathymetric Sonar} -- depth, slope, roughness
(read with \code{\link[=read_sonar_tif]{read_sonar_tif()}})
\item \strong{Lowrance + BioBase} -- depth, bottom hardness, vegetation, sidescan
\item \strong{Salinity/temperature probes} -- temperature, salinity, dissolved oxygen
}
}

\section{Validation and model diagnostics}{

Validation functions for research-grade use:
\itemize{
\item \code{\link[=validate_against_records]{validate_against_records()}}: AUC, TSS, Brier score, F1, sensitivity,
specificity vs known presence/absence records.
\item \code{\link[=spatial_block_cv]{spatial_block_cv()}}: Spatial block cross-validation (Roberts et al. 2017)
-- avoids inflated AUC from spatially autocorrelated data.
\item \code{\link[=permutation_importance]{permutation_importance()}}: Variable importance by AUC drop after
permuting each scored variable.
\item \code{\link[=sensitivity_analysis]{sensitivity_analysis()}}: Partial dependence curve -- suitability vs a
single variable while others are held at their median.
}
}

\section{Bayesian tolerance updating}{

Tolerance parameters (optimal ranges) can be updated from field observations:
\itemize{
\item \code{\link[=update_species_tolerances]{update_species_tolerances()}}: MAP + Laplace approximation (fast) or
RWMH MCMC (full posterior). Sequential -- posterior becomes next prior.
\item \code{\link[=get_tolerance_posteriors]{get_tolerance_posteriors()}}: Retrieve updated parameters with 95\% CIs.
\item \code{\link[=save_tolerance_update]{save_tolerance_update()}} / \code{\link[=load_tolerance_update]{load_tolerance_update()}}: Persist across sessions.
\item \code{\link[=reset_tolerance_update]{reset_tolerance_update()}}: Revert to built-in prior parameters.
}
}

\section{Risk and disturbance modules}{

Optional scored overlays (all \code{fetch_live = FALSE} by default):
\itemize{
\item \code{\link[=score_predation_risk]{score_predation_risk()}}: Starfish, crab, snail predation pressure.
\item \code{\link[=score_hab_risk]{score_hab_risk()}}: Harmful algal bloom risk (PSP/ASP/DSP/AZP).
\item \code{\link[=score_anthropogenic_disturbance]{score_anthropogenic_disturbance()}}: Bottom trawling (ICES VMS SAR),
anchor damage, dredging/extraction.
\item \code{\link[=score_wave_exposure]{score_wave_exposure()}}: JONSWAP wave height from fetch and wind speed.
\item \code{\link[=score_sediment_stability]{score_sediment_stability()}}: Shields parameter mobility analysis.
\item \code{\link[=add_shellfish_classification]{add_shellfish_classification()}}: UK/EU harvesting area classification
(Class A/B/C/Prohibited; EC Regulation 854/2004).
}
}

\section{Live data integration}{

Set credentials once; all live fetches are off by default:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{oystermapR_live_config(cmems_user = "...", cmems_password = "...")
result_live <- fetch_live_environmental_data(survey)
}\if{html}{\out{</div>}}
}

\section{Multi-species comparison}{

\itemize{
\item \code{\link[=compare_species]{compare_species()}}: Compare suitability across multiple species at the
same locations.
\item \code{\link[=compare_surveys]{compare_surveys()}}: Compare two survey datasets for the same species.
\item \code{\link[=composite_seasonal]{composite_seasonal()}}: Merge summer/winter surveys into a composite score.
}
}

\references{
Roberts D.R. et al. (2017) Cross-validation strategies for data with
temporal, spatial, hierarchical, or phylogenetic structure. Ecography
40:913-929. \doi{10.1111/ecog.02881}

Breiman L. (2001) Random Forests. Machine Learning 45:5-32.

Gelman A. et al. (2013) Bayesian Data Analysis, 3rd ed. CRC Press.

Eigaard O.R. et al. (2017) The footprint of bottom trawling in European
waters. ICES J Mar Sci 74:1700-1710.

Hasselmann K. et al. (1973) Measurements of wind-wave growth and swell
decay during the Joint North Sea Wave Project (JONSWAP). Dtsch
Hydrogr Z Suppl A8.
}
\seealso{
Useful links:
\itemize{
  \item \url{https://github.com/trissyboats/oystermapR}
  \item Report bugs at \url{https://github.com/trissyboats/oystermapR/issues}
}

}
\author{
\strong{Maintainer}: T Tucker \email{tristantucker48@gmail.com} (\href{https://orcid.org/0009-0008-5190-6423}{ORCID})

}
\keyword{internal}
