spectrum {sarima}

Spectral Density

Description

Estimate the spectral density of a time series or compute the spectral density associated with a time series model.

Usage

spectrum(x, standardize = TRUE, ...)

## Default S3 method:
spectrum(x, standardize = TRUE, raw = TRUE, taper = 0.1, 
         demean = FALSE, detrend = TRUE, ...)

## S3 method for class 'genspec'
print(x, n.head = min(length(x$spec), 6), sort = TRUE, ...)

## S3 method for class 'Arima'
spectrum(x, standardize = TRUE, ...)

## S3 method for class 'ArmaModel'
spectrum(x, standardize = TRUE, ...)

## S3 method for class 'SarimaModel'
spectrum(x, standardize = TRUE, ...)

## S3 method for class 'function'
spectrum(x, standardize = TRUE, param = list(), ...)

Arguments

x

a model or a univariate or multivariate time series.

standardize

if TRUE, the default method standardises the time series before computing the periodogram, while the methods for models scale the spectral density so that it is a probability density function.

raw

if TRUE, the default, compute a completely raw periodogram, unless further arguments request otherwise, see section Details.

taper, demean, detrend

see spec.pgram and section ‘Details’.

...

further arguments for the default method. Currently not used by other methods.

n.head

how many rows to print?

sort

TRUE, FALSE or "max", see section ‘Details'’.

param

a named list, specying model parameters for the "function" method, see section ‘Details’.

Details

spectrum in package sarima is a generic function with a default method its namesake in package stats, see spectrum for a full description of its functionality.

Autoprinting of objects returned by spectrum prints concise information and plots the spectrum. This means that a plot is produced, for example, when the result of a call to spectrum() is not assigned to a variable or if a command containing just the name of the object is executed. If you don't want the graph, just assign the result to a variable. For more control over the printing (for example, number of digits) use print(object, ...) explicitly. In that case no plot is produced. If additional graphical parameters are desired, call plot, ....

All methods print some basic information about the object and a table giving the most influential frequencies and their contributions to the spectrum.

Methods for objects representing ARIMA and SARIMA models (fitted or theoretical) compute the corresponding spectral densities. For non-stationary models, the spectral density for the stationary part. These methods for spectrum return objects from class "Spectrum". If standardize = TRUE the spectral density is scaled, so that it integrates to one (and so is a probability density function). For fitted models confidence bands are not computed currently.

The method for class "function" can be used to create objects from class "Spectrum" using a user specified function. The first argument of that function needs to be a vector of frequencies for which to calculate the spectrum. It is conventionally called freq but this is not required. If there are parameters they should not be part of the signature of the function but need to be listed and given values as a named list via argument param, see the examples for class "Spectrum". This method is somewhat experimental but the restrictions might be relaxed in a future release.

The rest of this section describes the default method. For futher details on the other methods see "Spectrum".

The default method for spectrum

The default method is a wrapper for stats::spectrum().

The default method returns an object from class "genspec". It inherits from "spec", the class returned by stats::spectrum, and adds some additional components. The main difference though is that it has a print method, which plots the object as discussed above. raw = FALSE with no further arguments is equivalent to stats::spectrum(object) and computes a raw periodogram (for the standardised time series if standardize = TRUE). This still detrends and tapers the series though. raw = TRUE sets detrend to FALSE, taper to zero, and demean to TRUE, to compute a ‘completely raw’ periodogram. In both cases, further arguments are respected.

Argument sort of the print method for "genspec" controls the sorting order of the columns of the printed table. If FALSE, no sorting is done. If TRUE, the spectrum is sorted in decreasing order, so the first row contains the frequency with the highest value of the spectrum. If "max", the local maxima are found and sorted in decreasing order, followed by the rest, also sorted in decreasing order. Note that due to aliasing the local maxima may be shifted from the “true” frequency (e.g. not be exactly on the harmonics of the number of seasons). Tapering and smoothing parameters may help.

The plot method for class "genspec" is inherited from that for "spec", see ?plot.spec.

Value

for the default method, an object of class "genspec", which inherits from "spec", and contains the following additional components:

standardized

TRUE or FALSE,

nseasons

number of seasons,

freq.range

numeric(2), the frequency range - ⁠(-m/2, m/2]⁠, where m = floor(frequency(x));

for the remaining methods, an object of class "Spectrum".

Author(s)

Georgi N. Boshnakov

See Also

spectrum which is called by the default method to do the work.

class "Spectrum" for further details on the methods for objects returned by spectrum().

Examples

## spectral density of the stationary part of a fitted 'airline model'
fit0 <- arima(AirPassengers, order = c(0,1,1),
              seasonal = list(order = c(0,1,1), period = 12))
spectrum(fit0)

## spectral densities of some ARMA models models from Chan and Gray ().
##   (TODO: complete the reference)
spectrum(ArmaModel(ma = c(-1, 0.6), sigma2 = 1))
spectrum(ArmaModel(ar = 0.5, sigma2 = 1))
spectrum(ArmaModel(ar = 0.5, ma = -0.8, sigma2 = 1))
spectrum(new("SarimaModel", ar = 0.5, sar = 0.9, nseasons = 12, sigma2 = 1))

mo <- new("SarimaModel", ma = -0.4, sma = -0.9, nseasons = 12, sigma2 = 1)
sp1.mo <- spectrum(mo)
## this also plots the object.  (if you are reading the web version, generated
##     by pkgdown, it may not be showing some of the graphs,
##     I haven't figured out why.)
show(sp1.mo)  # equivalently, just sp1.mo

print(sp1.mo)
print(sp1.mo, digits = 4)
plot(sp1.mo)
plot(sp1.mo, standardize = FALSE)

## the object can be used as a function:
head(sp1.mo())
sp1.mo(seq(0, 0.5, length.out = 12))
sp1.mo(seq(0, 0.5, length.out = 12), standardize = FALSE)

sarima1b <- new("SarimaModel", ar = 0.9, ma = 0.1, sar = 0.5, sma = 0.9,
                nseasons = 12, sigma2 = 1)
spectrum(sarima1b)

## default method for spectrum()

## frequency range is c(-1/2, 1/2] since frequency(x) = 1
frequency(lh)
spectrum(lh)

## frequency range is c(-12/2, 12/2] since frequency(x) = 12
frequency(ldeaths)
( sp <- spectrum(ldeaths) )
print(sp) # equivalently: print(sp, sort = TRUE)
print(sp, sort = FALSE, n.head = 3)
print(sp, sort = "max")
plot(sp)
plot(sp, log = "dB")  # see ?plot.spec for further arguments