% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/filter_mnirs.R
\name{filter_butter}
\alias{filter_butter}
\title{Apply a Butterworth digital filter}
\usage{
filter_butter(
  x,
  order = 2L,
  W,
  type = c("low", "high", "stop", "pass"),
  edges = c("rev", "rep1", "none"),
  na.rm = FALSE,
  ...
)
}
\arguments{
\item{x}{A numeric vector.}

\item{order}{An integer defining the filter order (\emph{default} \code{order = 2}).}

\item{W}{A one- or two-element numeric vector defining the filter cutoff
frequency(ies) as a fraction of the Nyquist frequency (see \emph{Details}).}

\item{type}{A character string indicating the digital filter type (see
\emph{Details}).
\describe{
\item{\code{"low"}}{For a \emph{low-pass} filter (the \emph{default}).}
\item{\code{"high"}}{For a \emph{high-pass} filter.}
\item{\code{"stop"}}{For a \emph{stop-band} (band-reject) filter.}
\item{\code{"pass"}}{For a \emph{pass-band} filter.}
}}

\item{edges}{A character string indicating edge detection padding for \code{x}.
\describe{
\item{\code{"rev"}}{Will pad \code{x} with the preceding 5\% data in reverse
sequence (\emph{the default}).}
\item{\code{"rep1"}}{Will pad \code{x} by repeating the last preceding value.}
\item{\code{"none"}}{Will return the unpadded \code{\link[signal:filtfilt]{signal::filtfilt()}} output.}
}}

\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{...}{Additional method-specific arguments must be specified
(see \emph{Details}).}
}
\value{
A numeric vector the same length as \code{x}.
}
\description{
Apply a Butterworth digital filter to vector data with \code{\link[signal:butter]{signal::butter()}}
and \code{\link[signal:filtfilt]{signal::filtfilt()}} which handles 'edges' better at the start and end
of the data.
}
\details{
Applies a centred (two-pass symmetrical) Butterworth digital filter from
\code{\link[signal:butter]{signal::butter()}} and \code{\link[signal:filtfilt]{signal::filtfilt()}}.

Filter \code{type} defines how the desired signal frequencies are either
passed or rejected from the output signal. \emph{Low-pass} and \emph{high-pass}
filters allow only frequencies \emph{lower} or \emph{higher} than the cutoff
frequency \code{W} to be passed through as the output signal, respectively.
\emph{Stop-band} defines a critical range of frequencies which are rejected
from the output signal. \emph{Pass-band} defines a critical range of
frequencies which are passed through as the output signal.

The filter order (number of passes) is defined by \code{order}, typically in
the range \verb{order = [1, 10]}. Higher filter order tends to capture more
rapid changes in amplitude, but also causes more distortion around
those change points in the signal. General advice is to use the
lowest filter order which sufficiently captures the desired rapid
responses in the data.

The critical (cutoff) frequency is defined by \code{W}, a numeric value for
\emph{low-pass} and \emph{high-pass} filters, or a two-element vector
\code{c(low, high)} defining the lower and upper bands for \emph{stop-band} and
\emph{pass-band} filters. \code{W} represents the desired fractional cutoff
frequency in the range \verb{W = [0, 1]}, where \code{1} is the Nyquist
frequency, i.e., half the sample rate of the data in Hz.

Missing values (\code{NA}) in \code{x} will cause an error unless \code{na.rm = TRUE}.
Then \code{NA}s will be ignored and passed through to the returned vector.
}
\examples{
set.seed(13)
sin <- sin(2 * pi * 1:150 / 50) * 20 + 40
noise <- rnorm(150, mean = 0, sd = 6)
noisy_sin <- sin + noise
without_edge_detection <- filter_butter(
    x = noisy_sin,
    order = 2,
    W = 0.1,
    edges = "none"
)
with_edge_detection <- filter_butter(
    x = noisy_sin,
    order = 2,
    W = 0.1,
    edges = "rep1"
)

\dontshow{if (rlang::is_installed("ggplot2")) withAutoprint(\{ # examplesIf}
ggplot2::ggplot(data.frame(), ggplot2::aes(x = seq_along(noise))) +
    theme_mnirs() +
    scale_colour_mnirs(name = NULL) +
    ggplot2::geom_line(ggplot2::aes(y = noisy_sin)) +
    ggplot2::geom_line(
        ggplot2::aes(y = without_edge_detection, colour = "without_edge_detection")
    ) +
    ggplot2::geom_line(
        ggplot2::aes(y = with_edge_detection, colour = "with_edge_detection")
    )
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[signal:filtfilt]{signal::filtfilt()}}, \code{\link[signal:butter]{signal::butter()}}
}
