% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/resample_mnirs.R
\name{resample_mnirs}
\alias{resample_mnirs}
\title{Re-sample an \emph{{mnirs}} data frame}
\usage{
resample_mnirs(
  data,
  time_channel = NULL,
  sample_rate = NULL,
  resample_rate = sample_rate,
  method = c("none", "linear", "locf"),
  verbose = TRUE
)
}
\arguments{
\item{data}{A data frame of class \emph{"mnirs"} containing time series data and
metadata.}

\item{time_channel}{A character string naming the time or sample column.
Must match a column name in \code{data} exactly.
\itemize{
\item If \code{NULL} (default), the \code{time_channel} metadata attribute of \code{data} is
used.
}}

\item{sample_rate}{A numeric sample rate in Hz.
\itemize{
\item If \code{NULL} (default), the \code{sample_rate} metadata attribute of \code{data} will
be used if detected, or the sample rate will be estimated from
\code{time_channel}.
}}

\item{resample_rate}{An \emph{optional} sample rate (Hz) for the output data
frame. If \code{NULL} (\emph{default}) resamples to the existing \code{sample_rate},
which regularises any irregular samples without changing the rate.}

\item{method}{A character string specifying how new samples are filled.
Default is \emph{"none"}. Filling must be opted into explicitly (see \emph{Details}):
\describe{
\item{\code{"none"}}{Matches each new sample to the nearest original
\code{time_channel} value without any interpolation, to within tolerance of
half a sample-interval. New samples are returned as \code{NA}.}
\item{\code{"locf"}}{(\emph{"Last observation carried forward"}). Fills new and
missing samples with the most recent valid non-\code{NA} value to the left,
or the nearest valid value to the right for leading \code{NA}s. Safe for
numeric, integer, and character columns.}
\item{\code{"linear"}}{Fills new and missing samples via linear interpolation
using \code{\link[stats:approxfun]{stats::approx()}}. Suitable for numeric columns only; non-numeric
columns will fall back to \code{"locf"} behaviour.}
}}

\item{verbose}{Logical. Default is \code{TRUE}. Display or silence (if \code{FALSE})
warnings and information messages helpful for troubleshooting. Ad
global default can be set via \code{options(mnirs.verbose = FALSE)}.}
}
\value{
A \link[tibble:tibble-package]{tibble} of class \code{"mnirs"}. Metadata are
stored as attributes and can be accessed with \code{attributes(data)}.
}
\description{
Up- or down-sample an \emph{"mnirs"} data frame to a new sample rate, filling
new samples via nearest-neighbour matching or interpolation.
}
\details{
This function uses \code{\link[=replace_missing]{replace_missing()}} (based on \code{\link[stats:approxfun]{stats::approx()}}) to
interpolate across new samples in the resampled data range.
\subsection{Sample rate and time channel}{

\code{time_channel} and \code{sample_rate} are retrieved automatically from \code{data}
of class \emph{"mnirs"}, if not defined explicitly.

Otherwise, \code{sample_rate} will be estimated from the values in \code{time_channel}.
However, this may return unexpected values, and it is safer to define
\code{sample_rate} explicitly or retrieve it from \emph{"mnirs"} metadata.
}

\subsection{Default behaviour}{

When \code{resample_rate} is omitted, the output has the same \code{sample_rate} as
the input but with a regular, evenly-spaced \code{time_channel}. This is useful
for regularising data that contains missing or repeated samples without
changing the nominal rate.
}

\subsection{Column handling}{

Numeric columns are interpolated according to \code{method} (see
\code{?replace_missing}). Non-numeric columns (e.g. character event labels,
integer lap numbers) are always filled by last-observation-carried-forward,
regardless of \code{method}:
\itemize{
\item For \code{method = "none"}, existing rows are matched to the nearest original
values of \code{time_channel} without interpolation or filling, meaning newly
created samples and any \code{NA}s in the original data are returned as \code{NA}.
\item When down-sampling, numeric columns use time-weighted averaging.
Non-numeric columns use the first valid value in each output bin.
}
}
}
\examples{
## read example data
data <- read_mnirs(
    file_path = example_mnirs("moxy_ramp"),
    nirs_channels = c(smo2 = "SmO2 Live"),
    time_channel = c(time = "hh:mm:ss"),
    verbose = TRUE
)

## note warning about irregular sampling
data

data_resampled <- resample_mnirs(
    data,               ## blank channels will be retrieved from metadata
    resample_rate = 2,  ## blank by default will resample to `sample_rate`
    method = "linear",  ## linear interpolation across resampled indices
    verbose = TRUE      
)

## note the altered `time` values resolving the above warning
data_resampled

}
