astsa (version 2.4)

specenv: Spectral Envelope

Description

Computes the spectral envelope of categorical-valued or real-valued time series.

Usage

specenv(xdata, section = NULL, spans = NULL, kernel = NULL, taper = 0,
         significance = 1e-04, plot = TRUE, ylim = NULL, real = FALSE, ...)

Value

By default, will produce a graph of the spectral envelope and an approximate significance threshold. A matrix containing: frequency, spectral envelope ordinates, and (1) the scalings of the categories in the order of the categories in the alphabet or (2) the coefficients of the transformations, is returned invisibly.

Arguments

xdata

For categorical-valued sequences, a matrix with rows that are indicators of the categories represented by the columns, possibly a sequence converted using dna2vector. For real-valued sequences, a matrix with at least two columns that are various transformations of the data.

section

of the form start:end where start < end are positive integers; specifies the section used in the analysis - default is the entire sequence.

spans

specify smoothing used in mvspec.

kernel

specify kernel to be used in mvspec.

taper

specify amount of tapering to be used in mvspec.

significance

significance threshold exhibited in plot - default is .0001; set to NA to cancel

plot

if TRUE (default) a graphic of the spectral envelope is produced

ylim

limits of the spectral envelope axis; if NULL (default), a suitable range is calculated.

real

FALSE (default) for categorical-valued sequences and TRUE for real-valued sequences.

...

other graphical parameters.

Author

D.S. Stoffer

Details

Calculates the spectral envelope for categorical-valued series as discussed in
https://www.stat.pitt.edu/stoffer/dss_files/spenv.pdf
and summarized in
https://doi.org/10.1214/ss/1009212816.
Alternately, calculates the spectral envelope for real-valued series as discussed in
https://doi.org/10.1016/S0378-3758(96)00044-4.

These concepts are also presented (with examples) in Section 7.9 (Chapter 7) of Time Series Analysis and Its Applications: With R Examples: https://www.stat.pitt.edu/stoffer/tsa4/.

For categorical-valued series, the input xdata must be a matrix of indicators which is perhaps a sequence preprocessed using dna2vector.

For real-valued series, the input xdata should be a matrix whose columns are various transformations of the univariate series.

The script does not detrend the data prior to estimating spectra. If this is an issue, then detrend the data prior to using this script.

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/.

See Also

dna2vector

Examples

# a DNA sequence
data  = bnrf1ebv
xdata = dna2vector(data)
u = specenv(xdata, section=1:1000, spans=c(7,7))
head(u)  # scalings are for A, C, G, and last one T=0 always

# a real-valued series
x     = astsa::nyse
xdata = cbind(x, abs(x), x^2)
u     = specenv(xdata, real=TRUE, spans=c(3,3))
# plot optimal transform at freq = .001
beta  = u[2, 3:5]
( b   = beta/beta[2] )  # makes abs(x) coef=1
gopt  = function(z) { b[1]*z + b[2]*abs(z) + b[3]*z^2 }
gabs  = function(z) { abs(z) } 
z     = -20:20/100
tsplot(z, cbind(gopt(z), gabs(z)), spag=TRUE, col=5:6, addLegend=TRUE, lwd=2, 
        xlab='return', legend = c('optimal','absolute value' ), gg=TRUE)
title('transformations')