\Header{spectrum}{Spectral Density Estimation}
\alias{plot.spec}{spectrum}
\methalias{plot.spec.coherency}{spectrum}
\methalias{plot.spec.phase}{spectrum}
\alias{spec}{spectrum}
\keyword{ts}{spectrum}
\begin{Description}\relax
The \code{spectrum} function estimates the spectral density of a
time series. This is a wrapper function which calls the methods
\code{\Link{spec.pgram}} and \code{\Link{spec.ar}}.

The generic function \code{plot} has a method for \code{spec} objects:
for multivariate time series it plots the marginal spectra of the
series or pairs plots of the coherency and phase of the cross-spectra.\end{Description}
\begin{Usage}
\begin{verbatim}
spectrum(x, method = c("pgram","ar"), plot = TRUE, ...)
plot.spec(spec.obj, add=FALSE, ci=0.95,
          log = c("yes", "dB", "no"), ci.col = "blue", ci.lty = 3, 
          plot.type = c("marginal", "coherency", "phase"), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A univariate or multivariate time series.
\item[\code{method}] String specifying the method used to estimate the spectral 
density. Allowed methods are "pgram" (the default) and "ar".
\item[\code{plot}] logical. If \code{TRUE} then the spectral density is plotted.
\item[\code{...}] Further arguments to specific spec methods or
\code{plot.spec}.
\item[\code{spec.obj}] An object of class \code{spec}.
\item[\code{add}] logical. If \code{TRUE} then lines are added to the
existing plot.
\item[\code{ci}] Coverage probability for confidence interval. Plotting of the
confidence bar is omitted unless \code{ci} is strictly positive.
\item[\code{log}] If \code{"dB"}, plot on log10 (decibel) scale (as S-PLUS),
otherwise use conventional log scale or linear scale. Logical values
are also accepted.  The default is \code{"yes"} unless
\code{options(ts.S.compat = TRUE)} has been set, when it is
\code{"dB"}.
\item[\code{ci.col, ci.lty}] Colour for plotting confidence bar, colour and
line type for confidence intervals for coherency and phase.
\item[\code{plot.type}] For multivariate time series, the type of plot
required. Only the first character is needed.
\item[\code{...}] Further graphical parameters.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The spectrum here is defined with scaling \code{1/frequency(x)},
following S-PLUS. This makes the spectral density a density over the
range \code{(-frequency(x)/2, +frequency(x)/2]}, whereas a more
common scaling is \eqn{2\pi}{} and range  \eqn{(-0.5, 0.5]}{}
(e.g. Bloomfield) or 1 and range \eqn{(-\pi, \pi]}{}.

If available, a confidence interval will be plotted by
\code{plot.spec}: this is asymmetric, and the width of the centre
mark indicates the equivalent bandwidth.\end{Details}
\begin{Value}
An object of class \code{spec}, which is a list containing at
least the following elements:
\begin{ldescription}
\item[\code{freq}] vector of frequencies at which the spectral
density is estimated. (Possibly approximate Fourier frequencies.)
\item[\code{spec}] Vector (for univariate series) or matrix (for multivariate
series) of estimates of the spectral density at frequencies
corresponding to \code{freq}.
\item[\code{coh}] \code{NULL} for univariate series. For multivariate time
series, a matrix containing the \emph{squared} coherency
between different
series. Column \eqn{ i + (j - 1) * (j - 2)/2}{} of \code{coh}
contains the squared coherency between columns \eqn{i}{} and \eqn{j}{}
of \code{x}, where \eqn{i > j}{}.
\item[\code{phase}] \code{NULL} for univariate series. For multivariate
time series a matrix containing the cross-spectrum phase between
different series. The format is the same as \code{coh}.
\item[\code{series}] The name of the time series.
\item[\code{snames}] For multivariate input, the names of the component series.
\item[\code{method}] The method used to calculate the spectrum.
\end{ldescription}


The result is returned invisibly if \code{plot} is true.\end{Value}
\begin{Note}\relax
The default plot for \code{spec} objects is quite complex, including an
error bar and default title, subtitle and axis labels. The defaults can
all be overridden by supplying the appropriate graphical parameters.\end{Note}
\begin{Author}\relax
Martyn Plummer, B.D. Ripley\end{Author}
\begin{References}\relax
Bloomfield, P. (1976) \emph{Fourier Analysis of Time Series: An
Introduction.} Wiley.

Brockwell, P. J. and Davis, R. A. (1991) \emph{Time Series: Theory and
Methods.} Second edition. Springer.

Venables, W. N. and Ripley, B. D. (1997) \emph{Modern Applied
Statistics with S-PLUS.} Second edition. Springer. (Especially
pp. 437--442.)\end{References}
\begin{SeeAlso}\relax
\code{\Link{spec.pgram}}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Examples from Venables & Ripley
## spec.pgram
par(mfrow=c(2,2))
data(lh)
spectrum(lh)
spectrum(lh, spans=3)
spectrum(lh, spans=c(3,3))
spectrum(lh, spans=c(3,5))

data(UKLungDeaths)
spectrum(ldeaths)
spectrum(ldeaths, spans=c(3,3))
spectrum(ldeaths, spans=c(3,5))
spectrum(ldeaths, spans=c(5,7))
spectrum(ldeaths, spans=c(5,7), log="dB", ci=0.8)

# for multivariate examples see the help for spec.pgram

## spec.ar
spectrum(lh, method="ar")
spectrum(ldeaths, method="ar")
\end{ExampleCode}
\end{Examples}

