spectrum                 package:ts                 R Documentation

Spectral Density Estimation

Description:

     The `spectrum' function estimates the spectral density of a time
     series.

Usage:

     spectrum(x, method = c("pgram", "ar"), plot = TRUE, na.action = na.fail,
              ...)

Arguments:

       x: A univariate or multivariate time series.

  method: String specifying the method used to estimate the spectral
          density.  Allowed methods are `"pgram"' (the default) and
          `"ar"'.

    plot: logical. If `TRUE' then the spectral density is plotted.

na.action: `NA' action function.

     ...: Further arguments to specific spec methods or `plot.spec'.

Details:

     `spectrum' is a wrapper function which calls the methods
     `spec.pgram' and `spec.ar'.

     The spectrum here is defined with scaling `1/frequency(x)',
     following S-PLUS.  This makes the spectral density a density over
     the range `(-frequency(x)/2, +frequency(x)/2]', whereas a more
     common scaling is 2pi and range (-0.5, 0.5] (e.g., Bloomfield) or
     1 and range (-pi, pi].

     If available, a confidence interval will be plotted by
     `plot.spec': this is asymmetric, and the width of the centre mark
     indicates the equivalent bandwidth.

Value:

     An object of class `"spec"', which is a list containing at least
     the following components: 

    freq: vector of frequencies at which the spectral density is
          estimated. (Possibly approximate Fourier frequencies.) The
          units are the reciprocal of cycles per unit time (and not per
          observation spacing): see Details below.

    spec: Vector (for univariate series) or matrix (for multivariate
          series) of estimates of the spectral density at frequencies
          corresponding to `freq'.

     coh: `NULL' for univariate series. For multivariate time series, a
          matrix containing the squared coherency between different
          series. Column  i + (j - 1) * (j - 2)/2 of `coh' contains the
          squared coherency between columns i and j of `x', where i <
          j.

   phase: `NULL' for univariate series. For multivariate time series a
          matrix containing the cross-spectrum phase between different
          series. The format is the same as `coh'.

  series: The name of the time series.

  snames: For multivariate input, the names of the component series.

  method: The method used to calculate the spectrum.


     The result is returned invisibly if `plot' is true.

Note:

     The default plot for objects of class `"spec"' 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.

Author(s):

     Martyn Plummer, B.D. Ripley

References:

     Bloomfield, P. (1976) Fourier Analysis of Time Series: An
     Introduction. Wiley.

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

     Venables, W. N. and Ripley, B. D. (1997) Modern Applied Statistics
     with S-PLUS. Second edition. Springer. (Especially pages 437-442.)

See Also:

     `spec.ar', `spec.pgram'; `plot.spec'.

Examples:

     ## 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")

