astsa (version 2.3)

mvspec: Univariate and Multivariate Spectral Estimation

Description

This is spec.pgram with a number changes and written so you can easily extract the estimate of the multivariate spectral matrix as fxx. The bandwidth calculation has been changed to the more practical definition given in the text and this can be used to replace spec.pgram.

Usage

mvspec(x, spans = NULL, kernel = NULL, taper = 0, pad = 0, fast = TRUE, 
        demean = FALSE, detrend = TRUE, lowess = FALSE, log = 'n', plot = TRUE, 
        gg = FALSE, type = NULL, na.action = na.fail, nxm = 2, nym = 1, 
        main = NULL, xlab = NULL, cex.main = NULL, ci = .95, ci.col = 4, plot.type, ...)

Value

All results are returned invisibly.

If plot is TRUE and smoothing is used, the bandwidth, degrees of freedom, and taper amount are printed.

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

fxx

spectral matrix estimates; an array of dimensions dim = c(p,p,nfreq).

freq

vector of frequencies at which the spectral density is estimated.

spec

vector (for univariate series) or matrix (for multivariate series) of estimates of the spectral density at frequencies corresponding to freq.

details

matrix with columns: frequency, period, spectral ordinate(s)

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.

Lh

Number of frequencies (approximate) used in the band.

n.used

Sample length used for the FFT

df

Degrees of freedom (may be approximate) associated with the spectral estimate.

bandwidth

Bandwidth (may be approximate) associated with the spectral estimate.

method

The method used to calculate the spectrum.

Arguments

x

univariate or multivariate time series (i.e., the p columns of x are 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

specifies the proportion of data to taper using a split cosine bell taper (.5 specifies a full taper)

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

if TRUE, series is demeaned first

detrend

if TRUE, series is detrended first (unless demean is TRUE)

lowess

if TRUE and detrend TRUE (and demean FALSE), series is detrended using lowess first

log

if log='y', spectra plotted on a log scale; otherwise a log scale is not used

plot

plot the estimated spectra

gg

if TRUE, will produce a gris-gris plot (gray graphic interior with white grid lines); the default is FALSE. The grammar of astsa is voodoo

type

type of plot to be drawn, defaults to lines (see par)

na.action

how to handle missing values

nxm, nym

the number of minor tick mark divisions on x-axis, y-axis; the default is one minor tick on the x-axis and none on the y-axis

main

title of the graphics; if NULL (default), a totally awesome title is generated dude, but if NA there will be no gnarly title and the top margin will be used for the plot

xlab

label for frequency axis; if NULL (default), a totally awesome label is generated for your viewing pleasure

cex.main

magnification for main title; default is 1.

ci

confidence level if one is drawn.

ci.col

color of the confidence interval if one is drawn.

plot.type

plot type for multivariate time series; leave blank or specify 'marginal' if a marginal plot of the spectra is desired, or set plot.type='coh' for coherency plot(s), or plot.type='phase' for phase plot(s). .

...

additional graphical arguments.

Details

This is built off of spec.pgram from the stats package with a few changes in the defaults and written so you can easily extract the estimate of the multivariate spectral matrix as fxx.

The default for the plot is NOT to plot on a log scale and the graphic will have a grid. Overall, the graphics have been improved.

The bandwidth calculation has been changed to the more practical definition given in the text, \((L_h/n.used)*frequency(x)\). Also, the bandwidth is not displayed in the graphic, but is returned.

Although initially meant to be used to easily obtain multivariate (mv) spectral (spec) estimates, this script can be used for univariate time series as a replacement for spec.pgram.

Note that the script does not taper by default (taper=0); this forces the user to do "conscious tapering".

In the multivariate case (more than 2 series), if "coherency" or "phase" plots are desired, the result is a grid of plots. There is a "scale" factor that can be set to prevent the labels from getting too small if there are many series. The default is scale=1, and to expand the labels by 10% for example, set scale=1.1. Also, if there are many series, having minor tick marks can make the graphic look crowded; in this case, set minor=FALSE. Finally, the plots include a type of legend that shows the axes with their corresponding labels (by default). To turn the legend off, include addLegend=FALSE in the call. Again, these considerations only work in the multivariate case (more than 2 series).

References

You can find demonstrations of astsa capabilities at FUN WITH ASTSA.

The most recent version of the package can be found at https://github.com/nickpoison/astsa/.

In addition, the News and ChangeLog files are at https://github.com/nickpoison/astsa/blob/master/NEWS.md.

The webpages for the texts and some help on using R for time series analysis can be found at https://nickpoison.github.io/.

Examples

# real raw periodogram
mvspec(soi)
mvspec(soi, log='y')  # on a log scale

# smooth and some details printed
mvspec(soi, spans=c(7,7), taper=.1)$details[1:45,]

# bivariate example
deth = cbind(mdeaths, fdeaths)    # two R data sets, male/female monthly deaths ...
tsplot(deth, type='b', col=c(4,6), spaghetti=TRUE, pch=c('M','F'), addLegend=TRUE)
dog = mvspec(deth, spans=c(3,3), taper=.1)
dog$fxx[,,1:5]  # look at a few spectral matrix estimates
dog$bandwidth   # bandwidth with time unit = year
dog$df          # degrees of freedom
mvspec(deth, spans=c(3,3), taper=.1, plot.type='coh')  # coherence

# multivariate example
mvspec(diff(log(econ5)), spans=c(5,5), col=5, lwd=2, ci=NA, gg=TRUE, minor=FALSE, 
         plot.type='coh')   

mvspec(diff(log(econ5)), spans=c(5,5), col=5, lwd=2, ci=NA, gg=TRUE, minor=FALSE, 
         plot.type='coh', addLegend=FALSE)