naginterfaces.library.tsa.multi_​spectrum_​lag

naginterfaces.library.tsa.multi_spectrum_lag(nxy, mtxy, pxy, iw, mw, ish, ic, cxy, cyx, kc, l, xg=None, yg=None)

multi_spectrum_lag calculates the smoothed sample cross spectrum of a bivariate time series using one of four lag windows: rectangular, Bartlett, Tukey or Parzen.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/g13/g13ccf.html

Parameters

nxyint

$n$, the length of the time series $x$ and $y$.

mtxyint

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

$mtxy=0$

For no correction.

$mtxy=1$

For mean correction.

$mtxy=2$

For trend correction.

If cross-covariances are supplied $(ic\ne 0)$, $mtxy$ is not used.

pxyfloat

If cross-covariances are to be calculated by the function ($ic=0$), $pxy$ must specify the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper. A value of $0.0$ implies no tapering.

If cross-covariances are supplied $(ic\ne 0)$, $pxy$ is not used.

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, relative to any alignment shift that has been applied. Windowed cross-covariances at lags $(-mw+ish)$ or less, and at lags $(mw+ish)$ or greater are zero.

ishint

$S$, the alignment shift between the $x$ and $y$ series. If $x$ leads $y$, the shift is positive.

icint

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

$ic=0$

Cross-covariances are to be calculated.

$ic\ne 0$

Cross-covariances are to be supplied.

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

If $ic\ne 0$, $cxy$ must contain the $\text{nc}$ cross-covariances between values in the $y$ series and earlier values in time in the $x$ series, for lags from $0$ to $(\text{nc}-1)$.

If $ic=0$, $cxy$ need not be set.

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

If $ic\ne 0$, $cyx$ must contain the $\text{nc}$ cross-covariances between values in the $y$ series and later values in time in the $x$ series, for lags from $0$ to $(\text{nc}-1)$.

If $ic=0$, $cyx$ need not be set.

kcint

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

If $ic\ne 0$, that is if 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 cross-covariances.

xgNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $ic=0$: $max(kc,l)$; otherwise: $l$.

If the cross-covariances are to be calculated, then $xg$ must contain the $nxy$ data points of the $x$ series. If covariances are supplied, $xg$ need not be set.

ygNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $ic=0$: $max(kc,l)$; otherwise: $l$.

If cross-covariances are to be calculated, $yg$ must contain the $nxy$ data points of the $y$ series. If covariances are supplied, $yg$ need not be set.

Returns

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

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

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

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

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

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

xgfloat, ndarray, shape $(:)$

Contains the real parts of the $ng$ complex spectral estimates in elements $xg\left[0\right]$ to $xg[ng-1]$, and $xg\left[ng\right]$ to $xg[\text{nxyg}-1]$ contain $0.0$. The $y$ series leads the $x$ series.

ygfloat, ndarray, shape $(:)$

Contains the imaginary parts of the $ng$ complex spectral estimates in elements $yg\left[0\right]$ to $yg[ng-1]$, and $yg\left[ng\right]$ to $yg[\text{nxyg}-1]$ contain $0.0$. The $y$ series leads the $x$ series.

ngint

The number, $\left[l/2\right]+1$, of complex spectral estimates, whose separate parts are held in $xg$ and $yg$.

Raises

NagValueError

(errno $1$)

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

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

(errno $1$)

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

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

(errno $1$)

On entry, $pxy=⟨value⟩$.

Constraint: if $ic=0$, $pxy\le 1.0$.

(errno $1$)

On entry, $pxy=⟨value⟩$.

Constraint: if $ic=0$, $pxy\ge 0.0$.

(errno $1$)

On entry, $mtxy=⟨value⟩$.

Constraint: if $ic=0$ then $mtxy\ne 0$, $1$ or $2$.

(errno $1$)

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

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

(errno $1$)

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

Constraint: $\text{nc}\ge mw+\left|ish\right|$.

(errno $1$)

On entry, $mw=⟨value⟩$, $ish=⟨value⟩$ and $nxy=⟨value⟩$.

Constraint: $mw+\left|ish\right|\le nxy$.

(errno $1$)

On entry, $mw=⟨value⟩$.

Constraint: $mw\ge 1$.

(errno $1$)

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

Constraint: $\left|ish\right|\le mw$.

(errno $1$)

On entry, $iw=⟨value⟩$.

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

(errno $1$)

On entry, $nxy=⟨value⟩$.

Constraint: $nxy\ge 1$.

(errno $2$)

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

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

(errno $3$)

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

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

Notes

The smoothed sample cross spectrum is a complex valued function of frequency $\omega$, $f_{xy}\left(\omega \right)=cf\left(\omega \right)+iqf\left(\omega \right)$, defined by its real part or co-spectrum

$$cf\left(\omega \right)=\frac{1}{2\pi }\sum _{k=-M+1}^{M-1}{w}_k{C}_{xy}(k+S)\cos \left(\omega k\right)$$

and imaginary part or quadrature spectrum

$$qf\left(\omega \right)=\frac{1}{2\pi }\sum _{k=-M+1}^{M-1}{w}_k{C}_{xy}(k+S)\sin \left(\omega k\right)$$

where $w_{\text{k}}=w_{-\text{k}}$, for $\text{k}=0,1,\dots ,M-1$, is the smoothing lag window as defined in the description of uni_spectrum_lag(). The alignment shift $S$ is recommended to be chosen as the lag $k$ at which the cross-covariances $c_{xy}\left(k\right)$ peak, so as to minimize bias.

The results are calculated for frequency values

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

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

The cross-covariances $c_{xy}\left(k\right)$ may be supplied by you, or constructed from supplied series $x_1,x_2,\dots ,x_n$; $y_1,y_2,\dots ,y_n$ as

$$c_{xy}\left(k\right)=\frac{{\sum }_{t=1}^{n-k}{x}_t{y}_{t+k}}{n}\text{,}k\ge 0$$

$$c_{xy}\left(k\right)=\frac{{\sum }_{t=1-k}^n{x}_t{y}_{t+k}}{n}=c_{yx}(-k)\text{,}k<0$$

this convolution being carried out using the finite Fourier transform.

The supplied series may be mean and trend corrected and tapered before calculation of the cross-covariances, in exactly the manner described in uni_spectrum_lag() for univariate spectrum estimation. The results are corrected for any bias due to tapering.

The bandwidth associated with the estimates is not returned. It will normally already have been calculated in previous calls of uni_spectrum_lag() for estimating the univariate spectra of $y_t$ and $x_t$.

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