naginterfaces.library.tsa.uni_​spectrum_​lag¶

naginterfaces.library.tsa.uni_spectrum_lag(nx, mtx, px, iw, mw, ic, c, kc, l, lg, xg)[source]

uni_spectrum_lag calculates the smoothed sample spectrum of a univariate time series using one of four lag windows – rectangular, Bartlett, Tukey or Parzen window.

For full information please refer to the NAG Library document for g13ca

https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/g13/g13caf.html

Parameters
nxint

, the length of the time series.

mtxint

If covariances are to be calculated by the function (), must specify whether the data are to be initially mean or trend corrected.

For no correction.

For mean correction.

For trend correction.

pxfloat

If covariances are to be calculated by the function (), must specify the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper.

If covariances are supplied , must specify the proportion of data tapered before the supplied covariances were calculated and after any mean or trend correction. is required for the calculation of output statistics.

A value of implies no tapering.

iwint

The choice of lag window.

Rectangular.

Bartlett.

Tukey.

Parzen.

mwint

, the ‘cut-off’ point of the lag window. Windowed covariances at lag or greater are zero.

icint

Indicates whether covariances are to be calculated in the function or supplied in the call to the function.

Covariances are to be calculated.

Covariances are to be supplied.

cfloat, array-like, shape

If , must contain the covariances for lags from to , otherwise need not be set.

kcint

If , must specify the order of the fast Fourier transform (FFT) used to calculate the covariances.

If , that is covariances are supplied, is not used.

lint

, the frequency division of the spectral estimates as . Therefore, it is also the order of the FFT used to construct the sample spectrum from the covariances.

lgint

Indicates whether unlogged or logged spectral estimates and confidence limits are required.

Unlogged.

Logged.

xgfloat, array-like, shape

If the covariances are to be calculated, then must contain the data points. If covariances are supplied, may contain any values.

Returns
cfloat, ndarray, shape

If , will contain the calculated covariances.

If , the contents of will be unchanged.

xgfloat, ndarray, shape

Contains the spectral estimates, , for in to respectively (logged if ). The elements , for contain .

ngint

The number of spectral estimates, , in .

statsfloat, ndarray, shape

Four associated statistics. These are the degrees of freedom in , the lower and upper confidence limit factors in and respectively (logged if ), and the bandwidth in .

Raises
NagValueError
(errno )

On entry, and .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: , , or .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, and .

Constraint: if , .

(errno )

On entry, , and .

Constraint: if , .

(errno )

On entry, and : .

(errno )

On entry, and : .

(errno )

On entry, .

Constraint: .

(errno )

On entry, , and .

Constraint: if , .

(errno )

On entry, and .

Constraint: .

Warns
NagAlgorithmicWarning
(errno )

One or more spectral estimates are negative.

Unlogged spectral estimates are returned in , and the degrees of freedom, unloged confidence limit factors and bandwidth in .

(errno )

The calculation of confidence limit factors has failed.

Spectral estimates (logged if requested) are returned in , and degrees of freedom and bandwidth in .

Notes

The smoothed sample spectrum is defined as

where is the window width, and is calculated for frequency values

where denotes the integer part.

The autocovariances may be supplied by you, or constructed from a time series , as

the fast Fourier transform (FFT) being used to carry out the convolution in this formula.

The time series may be mean or trend corrected (by classical least squares), and tapered before calculation of the covariances, the tapering factors being those of the split cosine bell:

where and is the tapering proportion.

The smoothing window is defined by

which for the various windows is defined over by

rectangular:

Bartlett:

Tukey:

Parzen:

The sampling distribution of is approximately that of a scaled variate, whose degrees of freedom is provided by the function, together with multiplying limits , from which approximate confidence intervals for the true spectrum may be constructed as . Alternatively, log may be returned, with additive limits.

The bandwidth of the corresponding smoothing window in the frequency domain is also provided. Spectrum estimates separated by (angular) frequencies much greater than may be assumed to be independent.

References

Bloomfield, P, 1976, Fourier Analysis of Time Series: An Introduction, Wiley

Jenkins, G M and Watts, D G, 1968, Spectral Analysis and its Applications, Holden–Day