spec.pgram               package:stats               R Documentation

Estimate Spectral Density of a Time Series by a Smoothed
Periodogram

Description:

     'spec.pgram' calculates the periodogram using a fast Fourier
     transform, and optionally smooths the result with a series of
     modified Daniell smoothers (moving averages giving half weight to
     the end values).

Usage:

     spec.pgram(x, spans = NULL, kernel, taper = 0.1,
                pad = 0, fast = TRUE, demean = FALSE, detrend =TRUE,
                plot = TRUE, na.action = na.fail, ...)

Arguments:

       x: univariate or multivariate time series.

   spans: vector of odd integers giving the widths of modified Daniell
          smoothers to be used to smooth the periodogram.

  kernel: alternatively, a kernel smoother of class '"tskernel"'.

   taper: proportion of data to taper.  A split cosine bell taper is
          applied to this proportion of the data at the beginning and
          end of the series.

     pad: proportion of data to pad. Zeros are added to the end of the
          series to increase its length by the proportion 'pad'.

    fast: logical; if 'TRUE', pad the series to a highly composite
          length.

  demean: logical. If 'TRUE', subtract the mean of the series.

 detrend: logical. If 'TRUE', remove a linear trend from the series.
          This will also remove the mean.

    plot: plot the periodogram?

na.action: 'NA' action function.

     ...: graphical arguments passed to 'plot.spec'.

Details:

     The raw periodogram is not a consistent estimator of the spectral
     density, but adjacent values are asymptotically independent. Hence
     a consistent estimator can be derived by smoothing the raw
     periodogram, assuming that the spectral density is smooth.

     The series will be automatically padded with zeros until the
     series length is a highly composite number in order to help the
     Fast Fourier Transform. This is controlled by the 'fast' and not
     the 'pad' argument.

     The periodogram at zero is in theory zero as the mean of the
     series is removed (but this may be affected by tapering): it is
     replaced by an interpolation of adjacent values during smoothing,
     and no value is returned for that frequency.

Value:

     A list object of class '"spec"' (see 'spectrum') with the
     following additional components: 

  kernel: The 'kernel' argument, or the kernel constructed from
          'spans'.

      df: The distribution of the spectral density estimate can be
          approximated by a chi square distribution with 'df' degrees
          of freedom.

bandwidth: The equivalent bandwidth of the kernel smoother as defined
          by Bloomfield (1976, page 201).

   taper: The value of the 'taper' argument.

     pad: The value of the 'pad' argument.

 detrend: The value of the 'detrend' argument.

  demean: The value of the 'demean' argument.


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

Author(s):

     Originally Martyn Plummer; kernel smoothing by Adrian Trapletti,
     synthesis by 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. (2002) _Modern Applied Statistics
     with S._ Fourth edition. Springer. (Especially pp. 392-7.)

See Also:

     'spectrum', 'spec.taper', 'plot.spec', 'fft'

Examples:

     ## Examples from Venables & Ripley
     data(UKLungDeaths)
     spectrum(ldeaths)
     spectrum(ldeaths, spans = c(3,5))
     spectrum(ldeaths, spans = c(5,7))
     spectrum(mdeaths, spans = c(3,3))
     spectrum(fdeaths, spans = c(3,3))

     ## bivariate example
     mfdeaths.spc <- spec.pgram(ts.union(mdeaths, fdeaths), spans = c(3,3))
     # plots marginal spectra: now plot coherency and phase
     plot(mfdeaths.spc, plot.type = "coherency")
     plot(mfdeaths.spc, plot.type = "phase")

     ## now impose a lack of alignment
     mfdeaths.spc <- spec.pgram(ts.intersect(mdeaths, lag(fdeaths, 4)),
        spans = c(3,3), plot = FALSE)
     plot(mfdeaths.spc, plot.type = "coherency")
     plot(mfdeaths.spc, plot.type = "phase")

     data(EuStockMarkets)
     stocks.spc <- spectrum(EuStockMarkets, kernel("daniell", c(30,50)),
                            plot = FALSE)
     plot(stocks.spc, plot.type = "marginal") # the default type
     plot(stocks.spc, plot.type = "coherency")
     plot(stocks.spc, plot.type = "phase")

     data(BJsales)
     sales.spc <- spectrum(ts.union(BJsales, BJsales.lead),
                           kernel("modified.daniell", c(5,7)))
     plot(sales.spc, plot.type = "coherency")
     plot(sales.spc, plot.type = "phase")

