\name{oceFilter}
\alias{oceFilter}
\title{Filter a time-series, possibly recursively}
\description{Filter a time-series, possibly recursively}
\usage{oceFilter(x, a=1, b, zero.phase=FALSE)}
\arguments{
\item{x}{a vector of numeric values, to be filtered as a time series.}
\item{a}{a vector of numeric values, giving the \eqn{a}{a} coefficients
  (see \dQuote{Details}).}
\item{b}{a vector of numeric values, giving the \eqn{b}{b} coefficients
  (see \dQuote{Details}).} 
\item{zero.phase}{boolean, set to \code{TRUE} to run the filter
  forwards, and then backwards, thus removing any phase shifts
  associated with the filter.}
}

\details{The filter is defined as e.g.  \eqn{y[i]=b[1]*x[i] +
    b[2]*x[i-1] + b[3]*x[i-2] + ... - a[2]*y[i-1] - a[3]*y[i-2] -
    a[4]*y[i-3] - ...}{y[i]=b[1]*x[i] + b[2]*x[i-1] + b[3]*x[i-2] +
    ... - a[2]*y[i-1] - a[3]*y[i-2] - a[4]*y[i-3] - ...}, where some of
    the illustrated terms will be omitted if the lengths of \code{a} and
    \code{b} are too small, and terms are dropped at the start of the
    time series where the index on \code{x} would be less than 1.

  By contrast with the \code{\link{filter}} function of R,
  \code{oceFilter} lacks the option to do a circular filter.  As a
  consequence, \code{oceFilter} introduces a phase lag.  One way to
  remove this lag is to run the filter forwards and then backwards, as
  in the \dQuote{Examples}.  However, the result is still problematic,
  in the sense that applying it in the reverse order would yield a
  different result.  (Matlab's \code{filtfilt} shares this problem.)}

\note{The first value in the \code{a} vector is ignored, and if
  \code{length(a)} equals 1, a non-recursive filter results.} 

\value{A numeric vector of the filtered results, \eqn{y}{y}, as denoted
  in \dQuote{Details}.}

\examples{
library(oce)
par(mar=c(4,4,1,1))
b <- rep(1,5)/5
a <- 1
x <- seq(0, 10)
y <- ifelse(x == 5, 1, 0)
f1 <- oceFilter(y, a, b)
plot(x, y, ylim=c(-0, 1.5), pch="o", type='b')
points(x, f1, pch="x", col="red")

# remove the phase lag
f2 <- oceFilter(y, a, b, TRUE)
points(x, f2, pch="+", col="blue")

legend("topleft", col=c("black","red","blue"), pch=c("o","x","+"),
       legend=c("data","normal filter", "zero-phase filter"))
mtext("note that normal filter rolls off at end")

}

\author{Dan Kelley}
\keyword{misc}
