naginterfaces.library.tsa.uni_​spectrum_​lag

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

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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/g13/g13caf.html

Parameters

nxint

$n$, the length of the time series.

mtxint

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

$mtx=0$

For no correction.

$mtx=1$

For mean correction.

$mtx=2$

For trend correction.

pxfloat

If covariances are to be calculated by the function ($ic=0$), $px$ 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 $(ic\ne 0)$, $px$ must specify the proportion of data tapered before the supplied covariances were calculated and after any mean or trend correction. $px$ is required for the calculation of output statistics.

A value of $0.0$ implies no tapering.

iwint

The choice of lag window.

$iw=1$

Rectangular.

$iw=2$

Bartlett.

$iw=3$

Tukey.

$iw=4$

Parzen.

mwint

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

icint

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

$ic=0$

Covariances are to be calculated.

$ic\ne 0$

Covariances are to be supplied.

cfloat, array-like, shape $\left(\text{nc}\right)$

If $ic\ne 0$, $c$ must contain the $\text{nc}$ covariances for lags from $0$ to $(\text{nc}-1)$, otherwise $c$ need not be set.

kcint

If $ic=0$, $kc$ must specify the order of the fast Fourier transform (FFT) used to calculate the covariances.

If $ic\ne 0$, that is covariances are supplied, $kc$ is not used.

lint

$L$, the frequency division of the spectral estimates as $\frac{2\pi }{L}$. 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.

$lg=0$

Unlogged.

$lg\ne 0$

Logged.

xgfloat, array-like, shape $\left(\text{nxg}\right)$

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

Returns

cfloat, ndarray, shape $\left(\text{nc}\right)$

If $ic=0$, $c$ will contain the $\text{nc}$ calculated covariances.

If $ic\ne 0$, the contents of $c$ will be unchanged.

xgfloat, ndarray, shape $\left(\text{nxg}\right)$

Contains the $ng$ spectral estimates, $\hat{f}\left({\omega }_{\text{i}}\right)$, for $\text{i}=0,1,\dots ,\left[L/2\right]$ in $xg\left[0\right]$ to $xg[ng-1]$ respectively (logged if $lg=1$). The elements $xg[\text{i}-1]$, for $\text{i}=ng+1,\dots ,\text{nxg}$ contain $0.0$.

ngint

The number of spectral estimates, $\left[L/2\right]+1$, in $xg$.

statsfloat, ndarray, shape $\left(4\right)$

Four associated statistics. These are the degrees of freedom in $stats\left[0\right]$, the lower and upper $95\%$ confidence limit factors in $stats\left[1\right]$ and $stats\left[2\right]$ respectively (logged if $lg=1$), and the bandwidth in $stats\left[3\right]$.

Raises

NagValueError

(errno $1$)

On entry, $\text{nc}=⟨value⟩$ and $nx=⟨value⟩$.

Constraint: $\text{nc}\le nx$.

(errno $1$)

On entry, $\text{nc}=⟨value⟩$ and $mw=⟨value⟩$.

Constraint: $\text{nc}\ge mw$.

(errno $1$)

On entry, $mw=⟨value⟩$ and $nx=⟨value⟩$.

Constraint: $mw\le nx$.

(errno $1$)

On entry, $mw=⟨value⟩$.

Constraint: $mw\ge 1$.

(errno $1$)

On entry, $iw=⟨value⟩$.

Constraint: $iw=1$, $2$, $3$ or $4$.

(errno $1$)

On entry, $px=⟨value⟩$.

Constraint: $px\le 1.0$.

(errno $1$)

On entry, $px=⟨value⟩$.

Constraint: $px\ge 0.0$.

(errno $1$)

On entry, $\text{nxg}=⟨value⟩$ and $l=⟨value⟩$.

Constraint: if $ic\ne 0$, $\text{nxg}\ge l$.

(errno $1$)

On entry, $\text{nxg}=⟨value⟩$, $kc=⟨value⟩$ and $l=⟨value⟩$.

Constraint: if $ic=0$, $\text{nxg}\ge max(kc,l)$.

(errno $1$)

On entry, $ic=0$ and $mtx>2$: $mtx=⟨value⟩$.

(errno $1$)

On entry, $ic=0$ and $mtx<0$: $mtx=⟨value⟩$.

(errno $1$)

On entry, $nx=⟨value⟩$.

Constraint: $nx\ge 1$.

(errno $2$)

On entry, $kc=⟨value⟩$, $nx=⟨value⟩$ and $\text{nc}=⟨value⟩$.

Constraint: if $ic=0$, $kc\ge (nx+\text{nc})$.

(errno $3$)

On entry, $l=⟨value⟩$ and $mw=⟨value⟩$.

Constraint: $l\ge 2\times mw-1$.

Warns

NagAlgorithmicWarning

(errno $4$)

One or more spectral estimates are negative.

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

(errno $5$)

The calculation of confidence limit factors has failed.

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

Notes

The smoothed sample spectrum is defined as

$$\hat{f}\left(\omega \right)=\frac{1}{2\pi }(C_0+2\sum _{k=1}^{M-1}{w}_k{C}_k\cos \left(\omega k\right))\text{,}$$

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

$${\omega }_i=\frac{2\pi i}{L}\text{,}i=0,1,\dots ,\left[L/2\right]\text{,}$$

where $\left[\right]$ denotes the integer part.

The autocovariances $C_k$ may be supplied by you, or constructed from a time series $x_1,x_2,\dots ,x_n$, as

$$C_k=\frac{1}{n}\sum _{t=1}^{n-k}{x}_t{x}_{t+k}\text{,}$$

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:

$$\begin{array}{c}\begin{array}{cc}\frac{1}{2}(1-\cos \left(\pi (t-\frac{1}{2})/T\right))\text{,}& 1\le t\le T\\ & \\ \frac{1}{2}(1-\cos \left(\pi (n-t+\frac{1}{2})/T\right))\text{,}& n+1-T\le t\le n\\ & \\ 1\text{,}& \text{otherwise,}\end{array}\end{array}$$

where $T=\left[\frac{np}{2}\right]$ and $p$ is the tapering proportion.

The smoothing window is defined by

$$w_k=W\left(\frac{k}{M}\right)\text{,}k\le M-1\text{,}$$

which for the various windows is defined over $0\le \alpha <1$ by

rectangular:

$$W\left(\alpha \right)=1$$

Bartlett:

$$W\left(\alpha \right)=1-\alpha$$

Tukey:

$$W\left(\alpha \right)=\frac{1}{2}(1+\cos \left(\pi \alpha \right))$$

Parzen:

$$\begin{array}{c}\begin{array}{cc}W\left(\alpha \right)=1-6{\alpha }^2+6{\alpha }^3\text{,}& 0\le \alpha \le \frac{1}{2}\\ & \\ W\left(\alpha \right)=2{(1-\alpha )}^3\text{,}& \frac{1}{2}<\alpha <1\text{.}\end{array}\end{array}$$

The sampling distribution of $\hat{f}\left(\omega \right)$ is approximately that of a scaled ${\chi }_d^2$ variate, whose degrees of freedom $d$ is provided by the function, together with multiplying limits $mu$, $ml$ from which approximate $95\%$ confidence intervals for the true spectrum $f\left(\omega \right)$ may be constructed as $[ml\times \hat{f}\left(\omega \right),mu\times \hat{f}\left(\omega \right)]$. Alternatively, log $\hat{f}\left(\omega \right)$ may be returned, with additive limits.

The bandwidth $b$ of the corresponding smoothing window in the frequency domain is also provided. Spectrum estimates separated by (angular) frequencies much greater than $b$ 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