% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tidal_correction.R
\name{correct_to_chart_datum}
\alias{correct_to_chart_datum}
\title{Correct survey depths to Chart Datum (LAT)}
\usage{
correct_to_chart_datum(
  df,
  tidal_height_m = NULL,
  depth_col = "depth",
  datetime_col = NULL,
  keep_raw = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{df}{A dataframe containing at minimum a depth column. Typically the
output of \code{\link[=merge_sensor_data]{merge_sensor_data()}} before passing to \code{\link[=predict_oyster]{predict_oyster()}}.}

\item{tidal_height_m}{Numeric scalar or vector. Tidal height above Chart
Datum at the time of survey, in \strong{metres}. If a scalar, the same offset
is applied to all rows. If a vector, must be the same length as \code{nrow(df)}.
Use \code{NULL} to skip correction (a warning will be issued).}

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

\item{datetime_col}{Character or \code{NULL}. Name of a datetime column in \code{df}.
If supplied, it is used only for informational messages -- tidal heights
must still be supplied by the user. Default \code{NULL}.}

\item{keep_raw}{Logical. If \code{TRUE}, retains the original depth values in a
column named \code{depth_raw_m} alongside the corrected \code{depth} column
(default \code{TRUE}).}

\item{verbose}{Logical. Print correction summary (default \code{TRUE}).}
}
\value{
The input dataframe with the depth column corrected to Chart Datum.
If \code{keep_raw = TRUE}, the original values are preserved as \code{depth_raw_m}.
}
\description{
Converts water depths recorded during a survey to depths below Chart Datum
(approximately Lowest Astronomical Tide, LAT) by adding the tidal height
above Chart Datum at the time of survey. This removes bias introduced by
surveying at different states of the tide.

\strong{Formula:} \code{depth_CD = depth_surveyed + tidal_height_m}

\strong{Finding your tidal height:}
\itemize{
\item UK: UKHO EasyTide (easytide.ukho.gov.uk) -- free 7-day predictions for
any standard port. Download the predicted heights for your survey period.
\item Ireland: Marine Institute tide gauges (data.marine.ie)
\item France/EU: SHOM (shom.fr) or Copernicus Marine (marine.copernicus.eu)
\item Any port: apps such as PocketTides, Tides Near Me, or TidePod give
height-above-CD predictions for named ports.
}

For a typical loch or sheltered bay survey, reading the tidal height from a
tide table for the nearest standard port at the mid-point of the survey is
sufficient. For multi-day surveys or those spanning a full tidal cycle,
supply per-row heights matched to the survey timestamp.
}
\examples{
\donttest{
# Survey conducted around high water at Oban -- tidal height ~3.1 m above CD
survey_corrected <- correct_to_chart_datum(survey, tidal_height_m = 3.1)

# Per-row heights from a tide gauge CSV matched to survey timestamps
tide_series <- read.csv("oban_tide_gauge.csv")
# (match to survey rows by timestamp -- user responsibility)
survey_corrected <- correct_to_chart_datum(
  survey,
  tidal_height_m = tide_series$height_m
)
}
}
