

   spectrum {ts}                                R Documentation

   SSppeeccttrraall DDeennssiittyy EEssttiimmaattiioonn

   DDeessccrriippttiioonn::

        The `spectrum' function estimates the spectral density
        of a time series. This is a wrapper function which
        calls the methods `spec.pgram' and `spec.ar'.

        The generic function `plot' has a method for `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.

   UUssaaggee::

        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"), ...)

   AArrgguummeennttss::

          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.

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

   spec.obj: An object of class `spec'.

        add: logical. If `TRUE' then lines are added to the
             existing plot.

         ci: Coverage probability for confidence interval.
             Plotting of the confidence bar is omitted unless
             `ci' is strictly positive.

        log: If `"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 `"yes"' unless `options(ts.S.compat
             = TRUE)' has been set, when it is `"dB"'.

   ci.col, ci.lty: Colour for plotting confidence bar, colour
             and line type for confidence intervals for
             coherency and phase.

   plot.type: For multivariate time series, the type of plot
             required. Only the first character is needed.

        ...: Further graphical parameters.

   DDeettaaiillss::

        The spectrum here is defined with scaling `1/fre-
        quency(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.

   VVaalluuee::

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

       freq: vector of frequencies at which the spectral den-
             sity is estimated. (Possibly approximate Fourier
             frequencies.)

       spec: Vector (for univariate series) or matrix (for mul-
             tivariate 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.

   NNoottee::

        The default plot for `spec' objects is quite complex,
        including an error bar and default title, subtitle and
        axis labels. The defaults can all be overridden by sup-
        plying the appropriate graphical parameters.

   AAuutthhoorr((ss))::

        Martyn Plummer, B.D. Ripley

   RReeffeerreenncceess::

        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 pp. 437-442.)

   SSeeee AAllssoo::

        `spec.pgram'

   EExxaammpplleess::

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

