% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/misc.R
\name{makeFilter}
\alias{makeFilter}
\title{Make a Digital Filter}
\usage{
makeFilter(
  type = c("blackman-harris", "rectangular", "hamming", "hann"),
  m,
  normalize = TRUE,
  asKernel = TRUE
)
}
\arguments{
\item{type}{a string indicating the type of filter to use.  (See Harris
(1978) for a comparison of these and similar filters.) The choices for
the present function are as follows.
\itemize{
\item \code{"blackman-harris"} yields a modified raised-cosine filter designated
as "4-Term (-92 dB) Blackman-Harris" by Harris (1978; coefficients given in
the table on page 65).  This is also called "minimum 4-sample Blackman
Harris" by that author, in his Table 1.
\item \code{"rectangular"} for a flat filter.  (This is just for convenience.  Note that
\code{\link{kernel}}\verb{("daniell",....)} gives the same result, in kernel form.)
\item \code{"hamming"} for a raised-cosine filter designed by Hamming. The
mathematical form is \code{a-(1-a)*cos(2*pi*i/(m-1))} where \code{a} is 0.54 and \code{i} is
\code{seq(0,m-1)}.
\item \code{"hann"} for a cosine filter that tapers to zero at the ends, i.e.
of the same mathematical form as \code{"hamming"}, but with
\code{a} equal to 0.5.
}}

\item{m}{length of filter.}

\item{normalize}{logical value indicating whether to return numbers that sum
to 1.  This is TRUE by default, which is useful if the purpose is to lowpass
filter a timeseries without altering power in the pass-band.  However,
\code{normalize=FALSE} is the right choice if the purpose is to window a
timeseries, e.g. in computing a spectral estimate using Welch's method (see
\code{\link[=pwelch]{pwelch()}}).}

\item{asKernel}{boolean, set to \code{TRUE} to get a smoothing kernel for
the return value.}
}
\value{
If \code{asKernel} is \code{FALSE}, this returns a vector of filter
coefficients, symmetric about the midpoint. The vector will sum to 1 if
\code{normalize=TRUE} (i.e. by default).  The return value may be used with
\code{\link[=filter]{filter()}}, which should be provided with argument \code{circular=TRUE} to avoid
phase offsets.  If \code{asKernel} is TRUE and if \code{normalize} is FALSE, an error
is reported.  On the other hand, if \code{asKernel} is TRUE and \code{normalize} is
FALSE, then the return value is a smoothing kernel, which can be applied to a
timeseries with \code{\link[=kernapply]{kernapply()}}, whose bandwidth can be determined with
\code{\link[=bandwidth.kernel]{bandwidth.kernel()}}, and which has both print and plot methods.
}
\description{
The results can be used in two different ways.  CASE 1: for filtering, using
\code{\link[=filter]{filter()}} or \code{\link[=convolve]{convolve()}} or (for the \code{asKernal=TRUE} case) using
\code{\link[=kernapply]{kernapply()}}.  For the Blackman-Harris filter, the half-power frequency is
at \code{1/m} cycles per time unit, as shown in the \dQuote{Examples} section.
When using \code{\link[=filter]{filter()}} or \code{\link[=kernapply]{kernapply()}} with these filters, use
\code{circular=TRUE}. CASE 2: for windowing, if \code{normalize} is set to FALSE, as
for example in computing a Welch spectral estimate.
}
\examples{
library(oce)

# Demonstrate step-function response
y <- c(rep(1, 10), rep(-1, 10))
x <- seq_along(y)
plot(x, y, type = "o", ylim = c(-1.05, 1.05))
BH <- makeFilter("blackman-harris", 11, asKernel = FALSE)
H <- makeFilter("hamming", 11, asKernel = FALSE)
yBH <- stats::filter(y, BH)
lines(x, yBH, type = "o", col = 2)
yH <- stats::filter(y, H)
lines(x, yH, type = "o", col = 3)
grid()
legend("topright",
    col = 1:3, bg = "white",
    legend = c("input", "Blackman Harris", "Hamming")
)
}
\references{
F. J. Harris, 1978.  On the use of windows for harmonic analysis
with the discrete Fourier Transform.  \emph{Proceedings of the IEEE}, 66(1),
51-83 (\verb{http://web.mit.edu/xiphmont/Public/windows.pdf}.)
}
\author{
Dan Kelley
}
