naginterfaces.library.tsa.multi_​gain_​bivar

naginterfaces.library.tsa.multi_gain_bivar(xg, yg, xyrg, xyig, stats)

For a bivariate time series, multi_gain_bivar calculates the gain and phase together with lower and upper bounds from the univariate and bivariate spectra.

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

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g13/g13cff.html

Parameters

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

The $\text{ng}$ univariate spectral estimates, $f_{xx}\left(\omega \right)$, for the $x$ series.

ygfloat, array-like, shape $\left(\text{ng}\right)$

The $\text{ng}$ univariate spectral estimates, $f_{yy}\left(\omega \right)$, for the $y$ series.

xyrgfloat, array-like, shape $\left(\text{ng}\right)$

The real parts, $cf\left(\omega \right)$, of the $\text{ng}$ bivariate spectral estimates for the $x$ and $y$ series. The $x$ series leads the $y$ series.

xyigfloat, array-like, shape $\left(\text{ng}\right)$

The imaginary parts, $qf\left(\omega \right)$, of the $\text{ng}$ bivariate spectral estimates for the $x$ and $y$ series. The $x$ series leads the $y$ series.

Note: the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing.

For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used.

For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same.

The spectral estimates and statistics must also be unlogged.

statsfloat, array-like, shape $\left(4\right)$

The four associated statistics for the univariate spectral estimates for the $x$ and $y$ series. $stats\left[0\right]$ contains the degrees of freedom, $stats\left[1\right]$ and $stats\left[2\right]$ contain the lower and upper bound multiplying factors respectively and $stats\left[3\right]$ holds the bandwidth.

Returns

gnfloat, ndarray, shape $\left(\text{ng}\right)$

The $\text{ng}$ gain estimates, $\hat{G}\left(\omega \right)$, at each frequency $\omega$.

gnlwfloat, ndarray, shape $\left(\text{ng}\right)$

The $\text{ng}$ lower bounds for the $\text{ng}$ gain estimates.

gnupfloat, ndarray, shape $\left(\text{ng}\right)$

The $\text{ng}$ upper bounds for the $\text{ng}$ gain estimates.

phfloat, ndarray, shape $\left(\text{ng}\right)$

The $\text{ng}$ phase estimates, $\hat{\varphi }\left(\omega \right)$, at each frequency $\omega$.

phlwfloat, ndarray, shape $\left(\text{ng}\right)$

The $\text{ng}$ lower bounds for the $\text{ng}$ phase estimates.

phupfloat, ndarray, shape $\left(\text{ng}\right)$

The $\text{ng}$ upper bounds for the $\text{ng}$ phase estimates.

Raises

NagValueError

(errno $1$)

On entry, $stats\left[0\right]=⟨value⟩$.

Constraint: $stats\left[0\right]\ge 3.0$.

(errno $1$)

On entry, $\text{ng}=⟨value⟩$.

Constraint: $\text{ng}\ge 1$.

Warns

NagAlgorithmicWarning

(errno $2$)

A bivariate spectral estimate is zero.

(errno $3$)

A univariate spectral estimate is negative.

(errno $4$)

A univariate spectral estimate is zero.

(errno $5$)

A calculated value of the squared coherency exceeds $1.0$.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Estimates of the gain $G\left(\omega \right)$ and phase $\varphi \left(\omega \right)$ of the dependency of series $y$ on series $x$ at frequency $\omega$ are given by

$$\begin{array}{c}\begin{array}{cc}\hat{G}\left(\omega \right)=\frac{A\left(\omega \right)}{f_{xx}\left(\omega \right)}& \\ & \\ \hat{\varphi }\left(\omega \right)=\arccos \left(\frac{cf\left(\omega \right)}{A\left(\omega \right)}\right)\text{,}& \text{if}qf\left(\omega \right)\ge 0\\ & \\ \hat{\varphi }\left(\omega \right)=2\pi -\arccos \left(\frac{cf\left(\omega \right)}{A\left(\omega \right)}\right)\text{,}& \text{if}qf\left(\omega \right)<0\text{.}\end{array}\end{array}$$

The quantities used in these definitions are obtained as in Notes for multi_spectrum_bivar.

Confidence limits are returned for both gain and phase, but should again be taken as very approximate when the coherency $W\left(\omega \right)$, as calculated by multi_spectrum_bivar(), is not significant. These are based on the assumption that both $\left(\hat{G}\left(\omega \right)/G\left(\omega \right)\right)-1$ and $\hat{\varphi }\left(\omega \right)$ are Normal with variance

$$\frac{1}{d}(\frac{1}{W\left(\omega \right)}-1)\text{.}$$

Although the estimate of $\varphi \left(\omega \right)$ is always given in the range $[0,2\pi )$, no attempt is made to restrict its confidence limits to this range.

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