% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/filter_mnirs.R
\name{filter_ma}
\alias{filter_ma}
\alias{filter_moving_average}
\title{Apply a moving average filter}
\usage{
filter_ma(
  x,
  t = seq_along(x),
  width = NULL,
  span = NULL,
  partial = FALSE,
  na.rm = FALSE,
  verbose = TRUE,
  ...
)

filter_moving_average(
  x,
  t = seq_along(x),
  width = NULL,
  span = NULL,
  partial = FALSE,
  na.rm = FALSE,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{x}{A numeric vector of the response variable.}

\item{t}{An \emph{optional} numeric vector of the predictor variable (e.g. time).
Default is \code{seq_along(x)}.}

\item{width}{An integer defining the local window in number of samples
centred on \code{idx}, between
\verb{[idx - floor(width/2), idx + floor(width/2)]}.}

\item{span}{A numeric value defining the local window time span around
\code{idx} in units of \code{time_channel} or \code{t}, between
\verb{[t - span/2, t + span/2]}.}

\item{partial}{Logical; default is \code{FALSE}, requires local windows to have
complete number of samples specified by \code{width} or \code{span}. If \code{TRUE},
processes available samples within the local window. See \emph{Details}.}

\item{na.rm}{Logical; default is \code{FALSE}, propagates any \code{NA}s to the
returned vector. If \code{TRUE}, ignores \code{NA}s and processes available valid
samples within the local window. May return errors or warnings. (see
\emph{Details}).}

\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)}.}

\item{...}{Additional arguments.}
}
\value{
A numeric vector the same length as \code{x}.
}
\description{
Apply a simple moving average smoothing filter to vector data.
\code{filter_moving_average()} is an alias of \code{filter_ma()}.
}
\details{
\subsection{Rolling window}{

Applies a centred (symmetrical) moving average filter in a local
window, defined by either \code{width} as the number of samples around
\code{idx} between \verb{[idx - floor(width/2), idx + floor(width/2)]}. Or by
\code{span} as the timespan in units of \code{time_channel} between
\verb{[t - span/2, t + span/2]}.
}

\subsection{Partial windows}{

The default \code{partial = FALSE} requires a complete number of samples
specified by \code{width} or \code{span} (estimated from the sample rate of \code{t} when
\code{span} is used). \code{NA} is returned if fewer samples are present in the
local window.

Setting \code{partial = TRUE} allows computation with only a single valid sample,
such as at edge conditions. But these values will be more sensitive to
noise and should be used with caution.
}

\subsection{Missing values}{

\code{na.rm} controls whether missing values (\code{NA}s) within each local window are
either propagated to the returned vector when \code{na.rm = FALSE} (the default),
or ignored before processing if \code{na.rm = TRUE}.
}
}
\examples{
x <- c(1, 3, 2, 5, 4, 6, 5, 7)
t <- c(0, 1, 2, 4, 5, 6, 7, 10)  ## irregular time with gaps

## width: centred window of 3 samples
filter_ma(x, width = 3)

## partial = TRUE fills edge values with a narrower window
filter_ma(x, width = 3, partial = TRUE)

## span: centred window of 2 time-units (accounts for irregular sampling)
filter_ma(x, t, span = 2)

## na.rm = FALSE (default): any NA in the window propagates to the result
x_na <- c(1, NA, 3, 4, 5, NA, 7, 8)
filter_ma(x_na, width = 3, na.rm = FALSE)

## na.rm = TRUE: skip NAs and return the local mean of local valid values
filter_ma(x_na, width = 3, partial = TRUE, na.rm = TRUE)

}
