% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tidal_correction.R
\name{auto_tidal_correct}
\alias{auto_tidal_correct}
\title{Automatically predict and apply tidal correction from harmonic constituents}
\usage{
auto_tidal_correct(
  df,
  datetime_col = "date",
  depth_col = "depth",
  max_port_dist_km = 75,
  keep_raw = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{df}{A dataframe with at minimum a depth and a datetime column.
Typically the output of \code{\link[=merge_sensor_data]{merge_sensor_data()}}.}

\item{datetime_col}{Character. Name of the datetime column (default
\code{"date"}). Values should be UTC or treated as UTC.}

\item{depth_col}{Character. Name of the depth column to correct
(default \code{"depth"}).}

\item{max_port_dist_km}{Numeric. Maximum distance in km from the survey
centroid to the nearest standard port. If the nearest port is further
than this, no correction is applied and a warning is issued
(default \code{75} km).}

\item{keep_raw}{Logical. Retain original depths in a \code{depth_raw_m} column
(default \code{TRUE}).}

\item{verbose}{Logical. Print port selection, distance, and prediction
summary (default \code{TRUE}).}
}
\value{
The input dataframe with depths corrected to Chart Datum, plus
a \code{tidal_height_pred_m} column containing the predicted tidal height
used for each row.
}
\description{
Finds the nearest standard port to the survey area, checks whether it is
within a configurable distance threshold, predicts tidal heights for every
survey timestamp using embedded 5-constituent harmonic models
(M2, S2, N2, K1, O1), and applies \code{\link[=correct_to_chart_datum]{correct_to_chart_datum()}} automatically.

No external data or internet connection is required. Harmonic constituent
data (amplitude and Greenwich phase lag) for 31 UK and European ports are
embedded in the package.

\strong{Accuracy:} 5-constituent predictions are typically accurate to +/-0.15--0.35 m
at the standard port. Accuracy degrades with distance from the port and in
areas with complex tidal dynamics (e.g. the Bristol Channel, inner fjords).
For safety-critical work, use official UKHO EasyTide predictions and supply
them manually via \code{\link[=correct_to_chart_datum]{correct_to_chart_datum()}}.

\strong{Requirements:} The dataframe must contain a datetime column. Values must
be parseable by \code{\link[=as.POSIXct]{as.POSIXct()}} (e.g. \code{"2024-06-15 10:30:00"} or
\code{"2024-06-15"}). Date-only strings default to noon UTC.
}
\examples{
\donttest{
# Automatic correction -- finds nearest port, predicts heights, corrects depths
survey_corrected <- auto_tidal_correct(survey, datetime_col = "date")

# Tighten the distance threshold (only trust ports within 40 km)
survey_corrected <- auto_tidal_correct(survey, max_port_dist_km = 40)

# See which port was selected and inspect predicted heights
survey_corrected$tidal_height_pred_m
}
}
\seealso{
\code{\link[=correct_to_chart_datum]{correct_to_chart_datum()}} for manual correction,
\code{\link[=tidal_port_info]{tidal_port_info()}} for port datum reference data.
}
