% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/interpolation.R
\name{interpolate_survey}
\alias{interpolate_survey}
\title{Interpolate survey measurements to a regular grid before scoring}
\usage{
interpolate_survey(
  survey,
  vars = NULL,
  resolution_m = 100,
  method = c("auto", "kriging", "idw"),
  kriging_min_n = 50L,
  idw_power = 2,
  idw_max_radius_m = NULL,
  verbose = TRUE
)
}
\arguments{
\item{survey}{Dataframe with \code{lat}, \code{lon}, and measurement columns.}

\item{vars}{Character vector of column names to interpolate. Default: all
numeric columns except \code{lat} and \code{lon}.}

\item{resolution_m}{Numeric. Grid cell size in metres (default 100 m).
Coarsen for sparse surveys (> 500 m) or refine for dense ADCP grids (50 m).}

\item{method}{Character. \code{"auto"} (default -- kriging if possible, IDW
fallback), \code{"kriging"} (force kriging; error if insufficient data), or
\code{"idw"} (always use IDW).}

\item{kriging_min_n}{Integer. Minimum observations required to attempt
kriging (default 50).}

\item{idw_power}{Numeric. IDW distance decay exponent (default 2).}

\item{idw_max_radius_m}{Numeric. Maximum search radius for IDW neighbours
in metres (default 5 * resolution_m).}

\item{verbose}{Logical. Print per-variable method used and diagnostics
(default TRUE).}
}
\value{
A dataframe on a regular grid with interpolated values, a \code{method}
column per variable (\verb{interp_method_<var>}), and kriging variance columns
(\verb{krige_var_<var>}) where kriging was used.
}
\description{
Converts sparse point observations (CTD casts, ADCP profiles) to a regular
grid by spatial interpolation. The interpolated grid is returned in the same
dataframe format as the raw survey, and can be passed directly to
\code{\link[=predict_oyster]{predict_oyster()}}.

\strong{Method selection} (applied per variable independently):
\itemize{
\item \strong{Ordinary kriging} is used when >= 50 non-NA observations are available
for a variable, the \code{gstat} and \code{sp} packages are installed, and the
variogram can be fitted without error. Kriging is the best linear
unbiased estimator (BLUE) under the assumption of spatial stationarity --
it minimises mean squared prediction error and returns a kriging variance
for each cell.
\item \strong{IDW} (Inverse Distance Weighting, p = 2) is used as a fallback when
kriging cannot be applied. It is fast, deterministic, and requires no
model fitting, but produces no uncertainty estimate and can create
bull's-eye artefacts around isolated observations.
}

Kriging variograms are fitted automatically using \code{gstat::fit.variogram()}
with a Matern model (default) -- the most flexible and statistically
justified model for environmental data. If automatic fitting fails, a
spherical model is tried; if that also fails, IDW is used.
}
\examples{
\donttest{
# Auto method -- kriging for dense variables, IDW for sparse
grid <- interpolate_survey(survey, resolution_m = 100)
result <- predict_oyster(grid, "ostrea_edulis")

# Force IDW (fast, no gstat needed)
grid <- interpolate_survey(survey, resolution_m = 200, method = "idw")

# Inspect which method was used per variable
unique(grid$interp_method_temperature)

# Kriging variance -- high values = uncertain interpolation
hist(grid$krige_var_temperature)
}
}
