R: Compute and plot multitaper spectrum estimates

spec.mtm {multitaper} | R Documentation

## Compute and plot multitaper spectrum estimates

### Description

Computes and plots adaptive or nonadaptive multitaper spectrum estimates from contiguous time series objects.

### Usage

    spec.mtm(timeSeries, nw=4.0, k=7, nFFT="default", taper=c("dpss"),
             centre=c("Slepian"), dpssIN=NULL, returnZeroFreq=TRUE,
             Ftest=FALSE, jackknife=FALSE, jkCIProb=.95, adaptiveWeighting=TRUE,
             maxAdaptiveIterations=100, plot=TRUE, na.action=na.fail,
             returnInternals=FALSE, sineAdaptive=FALSE, sineSmoothFact=0.2,
             dtUnits=c("default"), deltat=NULL, ...)

### Arguments

`timeSeries` | A time series of equally spaced data, this can be created by the ts() function where deltat is specified.
`nw` | nw a positive double precision number, the time-bandwidth parameter.
`k` | k a positive integer, the number of tapers, often 2*nw.
`nFFT` | This function pads the data before computing the fft. nFFT indicates the total length of the data after padding.
`taper` | Choose between dpss-based multitaper (the default,'dpss') or sine taper method. In the case of the sine taper, parameter nw is useless, and both Ftest and jackknife are forced to FALSE. The sine taper also has two specific parameters below.
`centre` | The time series is centred using one of three methods: expansion onto discrete prolate spheroidal sequences ('Slepian'), arithmetic mean ('arithMean'), trimmed mean ('trimMean'), or not at all ('none').
`dpssIN` | Allows the user to enter a dpss object which has already been created. This can save computation time when Slepians with the same bandwidth parameter and same number of tapers are used repeatedly.
`returnZeroFreq` | Boolean variable indicating if the zeroth frequency (DC component) should be returned for all applicable arrays.
`Ftest` | Boolean variable indicating if the Ftest result should be computed and returned.
`jackknife` | Boolean variable indicating if jackknifed confidence intervals should be computed and returned.
`jkCIProb` | Decimal value indicating the jackknife probability for calculating jackknife confidence intervals. The default returns a 95% confidence interval.
`adaptiveWeighting` | Boolean flag for enabling/disabling adaptively weighted spectrum estimates. Defaults to `TRUE`. The `FALSE` case gives complex Fourier transforms equivalent to direct estimates with Slepian sequences as tapers.
`maxAdaptiveIterations` | Maximum number of iterations in the adaptive multitaper calculation. Generally convergence is quick, and should require less than 100 iterations.
`plot` | Boolean variable indicating if the spectrum should be plotted.
`na.action` | Action to take if NAs exist in the data, the default is to fail.
`returnInternals` | Return the weighted eigencoefficients, complex mean values, and so on. These are necessary for extensions to the multitaper, including magnitude-squared coherence (function mtm.coh in this package). Note: The internal ($mtm) variables eigenCoefs and eigenCoefWt correspond to the multitaper eigencoefficients. The eigencoefficients correspond to equation (3.4) and weights correspond to |d_k(f)|^2 from equation (5.4) in Thomson's 1982 paper. The values sqrt(eigenCoefWt) * eigenCoefs are most commonly used in additional calculations. The values returned in mtm$cmv correspond to the the estimate of the coefficients hat(mu)(f) in equation (13.5) in Thomson (1982), or to the estimate of hat(C)_1 at frequency 1 in equation (499) form Percival and Walden (1993)
`sineAdaptive` | In the case of using the sine taper method, choose between non-adaptive and adaptive taper choice.
`sineSmoothFact` | The sine taper option has an inherent smoothing parameter that can be set between 0.01 and 0.5. Lower values indicate smaller amounts of smoothing.
`dtUnits` | Allows indication of the units of delta-t for accurate frequency axis labels.
`deltat` | Time step for observations. If not in seconds, dtUnits should be set to indicate the proper units for plot labels.
`...` | Additional parameters, such as xaxs="i" which are passed to the plotting function. Not all parameters are supported.

### Details

The value log can be set to “yes” (default), “no”, or “dB” as in the function plot.spec.

### References

Thomson, D.J (1982) Spectrum estimation and harmonic analysis. Proceedings of the IEEE Volume 70, Number 9, pp. 1055–1096.

Percival, D.B. and Walden, A.T. (1993) Spectral analysis for physical applications Cambridge University Press.

Riedel, K.S. and Sidorenko, A. (1995) Minimum bias multiple taper spectral estimation. IEEE Transactions on Signal Processing Volume 43, Number 1, pp. 188–195.

### See Also

`plot.mtm` and `plot.spec`

### Examples

    ## default behaviour, dpss tapers; deltat and dtUnits set to ensure axis accuracy
    data(willamette)
    spec.mtm(willamette, nw=4.0, k=8, deltat=1/12, dtUnits="month")
    spec.mtm(willamette, nw=4.0, k=8, nFFT=2048, deltat=1/12, dtUnits="month")

    ## if you have a ts object, you can skip the deltat and dtUnits parameters
    will.ts <- ts(data=willamette, start=1950.75, freq=12)
    spec.mtm(will.ts, nw=4.0, k=8)

    ## using Sine Tapers
    spec.mtm(will.ts, k=10, taper="sine", sineAdaptive=FALSE)
    spec.mtm(will.ts, k=10, taper="sine", sineAdaptive=TRUE,
             maxAdaptiveIterations=100, sineSmoothFact=0.05)

[Package multitaper version 1.0-13 Index]