naginterfaces.library.tsa.multi_​varma_​diag

naginterfaces.library.tsa.multi_varma_diag(v, ip, iq, m, par, parhld, qq, ishow, io_manager=None)

multi_varma_diag is a diagnostic checking function suitable for use after fitting a vector ARMA model to a multivariate time series using multi_varma_estimate(). The residual cross-correlation matrices are returned along with an estimate of their asymptotic standard errors and correlations. Also, multi_varma_diag calculates the modified Li–McLeod portmanteau statistic and its significance level for testing model adequacy.

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

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

Parameters

vfloat, array-like, shape $(k,n)$

$v[\text{i}-1,\text{t}-1]$ must contain an estimate of the $\text{i}$th component of ${ϵ}_{\text{t}}$, for $\text{t}=1,2,\dots ,n$, for $\text{i}=1,2,\dots ,k$.

ipint

$p$, the number of AR parameter matrices.

iqint

$q$, the number of MA parameter matrices.

mint

The value of $m$, the number of residual cross-correlation matrices to be computed. See Further Comments for advice on the choice of $m$.

parfloat, array-like, shape $((ip+iq)\times k\times k)$

The parameter estimates read in row by row in the order ${\varphi }_1,{\varphi }_2,\dots ,{\varphi }_p$, ${\theta }_1,{\theta }_2,\dots ,{\theta }_q$.

Thus,

if $ip>0$, $par[(\text{l}-1)\times k\times k+(\text{i}-1)\times k+j-1]$ must be set equal to an estimate of the $(\text{i},j)$th element of ${\varphi }_{\text{l}}$, for $\text{i}=1,2,\dots ,k$, for $\text{l}=1,2,\dots ,p$;

if $iq\ge 0$, $par[p\times k\times k+(\text{l}-1)\times k\times k+(\text{i}-1)\times k+j-1]$ must be set equal to an estimate of the $(\text{i},j)$th element of ${\theta }_{\text{l}}$, for $\text{i}=1,2,\dots ,k$, for $\text{l}=1,2,\dots ,q$.

The first $p\times k\times k$ elements of $par$ must satisfy the stationarity condition and the next $q\times k\times k$ elements of $par$ must satisfy the invertibility condition.

parhldbool, array-like, shape $((ip+iq)\times k\times k)$

$parhld[\text{i}-1]$ must be set to $True$ if $par[\text{i}-1]$ has been held constant at a pre-specified value and $False$ if $par[\text{i}-1]$ is a free parameter, for $\text{i}=1,2,\dots ,(p+q)\times k\times k$.

qqfloat, array-like, shape $(k,k)$

$qq[i-1,j-1]$ is an efficient estimate of the $(i,j)$th element of $\Sigma$. The lower triangle only is needed.

ishowint

Must be nonzero if the residual cross-correlation matrices $\left\{{\hat{r}}_{ij}\left(l\right)\right\}$ and their standard errors $\left\{se\left({\hat{r}}_{ij}\left(l\right)\right)\right\}$, the modified portmanteau statistic with its significance and a summary table are to be printed. The summary table indicates which elements of the residual correlation matrices are significant at the $5\%$ level in either a positive or negative direction; i.e., if ${\hat{r}}_{ij}\left(l\right)>1.96\times se\left({\hat{r}}_{ij}\left(l\right)\right)$ then a ‘$+$’ is printed, if ${\hat{r}}_{ij}\left(l\right)<-1.96\times se\left({\hat{r}}_{ij}\left(l\right)\right)$ then a ‘$-$’ is printed, otherwise a fullstop (.) is printed. The summary table is only printed if $k\le 6$ on entry.

The residual cross-correlation matrices, their standard errors and the modified portmanteau statistic with its significance are available also as output variables in $r$, $rcm$, $chi$, $idf$ and $siglev$.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns

qqfloat, ndarray, shape $(k,k)$

If $errno$ != 1, then the upper triangle is set equal to the lower triangle.

r0float, ndarray, shape $(k,k)$

If $i\ne j$, then $r0[i-1,j-1]$ contains an estimate of the $(i,j)$th element of the residual cross-correlation matrix at lag zero, ${\hat{R}}_0$. When $i=j$, $r0[i-1,j-1]$ contains the standard deviation of the $i$th residual series. If $errno$ = 3 on exit then the first $\text{k}$ rows and columns of $r0$ are set to zero.

rfloat, ndarray, shape $(k,k,m)$

$r[\text{l}-1,\text{i}-1,\text{j}-1]$ is an estimate of the $(\text{i},\text{j})$th element of the residual cross-correlation matrix at lag $\text{l}$, for $\text{l}=1,2,\dots ,m$, for $\text{j}=1,2,\dots ,k$, for $\text{i}=1,2,\dots ,k$. If $errno$ = 3 on exit then all elements of $r$ are set to zero.

rcmfloat, ndarray, shape $(m\times k\times k,m\times k\times k)$

The estimated standard errors and correlations of the elements in the array $r$. The correlation between $r[l-1,i-1,j-1]$ and $r[l_2-1,i_2-1,j_2-1]$ is returned as $rcm[s,t]$ where $s=(l-1)\times k\times k+(j-1)\times k+i$ and $t=(l_2-1)\times k\times k+(j_2-1)\times k+i_2$ except that if $s=t$, then $rcm[s,t]$ contains the standard error of $r[l-1,i-1,j-1]$. If on exit, $errno$ >= 5, then all off-diagonal elements of $rcm$ are set to zero and all diagonal elements are set to $1/\sqrt{n}$.

chifloat

The value of the modified portmanteau statistic, $Q_{\left(m\right)}^{\ast }$. If $errno$ = 3 on exit then $chi$ is returned as zero.

idfint

The number of degrees of freedom of $chi$.

siglevfloat

The significance level of $chi$ based on $idf$ degrees of freedom. If $errno$ = 3 on exit, $siglev$ is returned as one.

Raises

NagValueError

(errno $1$)

On entry, $\text{ldrcm}=⟨value⟩$, $m=⟨value⟩$ and $k=⟨value⟩$.

Constraint: $\text{ldrcm}\ge m\times k\times k$.

(errno $1$)

On entry, $m=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $m<n$.

(errno $1$)

On entry, $m=⟨value⟩$, $ip=⟨value⟩$ and $iq=⟨value⟩$.

Constraint: $m>ip+iq$.

(errno $1$)

On entry, $ip=0$ and $iq=0$.

Constraint: $ip=iq=0$ must not hold.

(errno $1$)

On entry, $iq=⟨value⟩$.

Constraint: $iq\ge 0$.

(errno $1$)

On entry, $ip=⟨value⟩$.

Constraint: $ip\ge 0$.

(errno $1$)

On entry, $k=⟨value⟩$.

Constraint: $k\ge 1$.

(errno $2$)

On entry, the MA parameter matrices are outside the invertibility region.

(errno $2$)

On entry, the AR parameter matrices are outside the stationarity region.

(errno $2$)

On entry, the covariance matrix $qq$ is not positive definite.

(errno $4$)

Excessive iterations needed to find zeros of determinental polynomials.

(errno $5$)

On entry, the AR operator has a factor in common with the MA operator.

(errno $6$)

The matrix $rcm$ could not be computed because one of its diagonal elements was found to be non-positive.

Warns

NagAlgorithmicWarning

(errno $3$)

On entry, at least one of the residual series in the array $v$ has near-zero variance.

(errno $3$)

On entry, at least two of the residual series are identical.

Notes

Let $W_{\text{t}}={(w_{1\text{t}},w_{2\text{t}},\dots ,w_{\text{k}\text{t}})}^T$, for $\text{t}=1,2,\dots ,n$, denote a vector of $k$ time series which is assumed to follow a multivariate ARMA model of the form

$$\begin{array}{c}\begin{array}{cc}{W}_t-\mu =& {\varphi }_1(W_{t-1}-\mu )+{\varphi }_2(W_{t-2}-\mu )+\cdots +{\varphi }_p(W_{t-p}-\mu )\\ & +{ϵ}_t-{\theta }_1{ϵ}_{t-1}-{\theta }_2{ϵ}_{t-2}-\cdots -{\theta }_q{ϵ}_{t-q}\text{,}\end{array}\end{array}$$

where ${ϵ}_{\text{t}}={({ϵ}_{1\text{t}},{ϵ}_{2\text{t}},\dots ,{ϵ}_{k\text{t}})}^T$, for $\text{t}=1,2,\dots ,n$, is a vector of $k$ residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix $\Sigma$. The components of ${ϵ}_t$ are assumed to be uncorrelated at non-simultaneous lags. The ${\varphi }_i$ and ${\theta }_j$ are $k\times k$ matrices of parameters. $\left\{{\varphi }_{\text{i}}\right\}$, for $\text{i}=1,2,\dots ,p$, are called the autoregressive (AR) parameter matrices, and $\left\{{\theta }_{\text{i}}\right\}$, for $\text{i}=1,2,\dots ,q$, the moving average (MA) parameter matrices. The parameters in the model are thus the $p$ ($k\times k$) $\varphi$-matrices, the $q$ ($k\times k$) $\theta$-matrices, the mean vector $\mu$ and the residual error covariance matrix $\Sigma$. Let

$$\begin{array}{c}A\left(\varphi \right)={\left[\begin{array}{ccccccc}{\varphi }_1& I& 0& .& .& .& 0\\ {\varphi }_2& 0& I& 0& .& .& 0\\ .& & & .& & & \\ .& & & & .& & \\ .& & & & & .& \\ {\varphi }_{p-1}& 0& .& .& .& 0& I\\ {\varphi }_p& 0& .& .& .& 0& 0\end{array}\right]}_{pk\times pk}\text{and}B\left(\theta \right)={\left[\begin{array}{ccccccc}{\theta }_1& I& 0& .& .& .& 0\\ {\theta }_2& 0& I& 0& .& .& 0\\ .& & & .& & & \\ .& & & & .& & \\ .& & & & & .& \\ {\theta }_{q-1}& 0& .& .& .& & I\\ {\theta }_q& 0& .& .& .& .& 0\end{array}\right]}_{qk\times qk}\end{array}$$

where $I$ denotes the $k\times k$ identity matrix.

The ARMA model (1) is said to be stationary if the eigenvalues of $A\left(\varphi \right)$ lie inside the unit circle, and invertible if the eigenvalues of $B\left(\theta \right)$ lie inside the unit circle. The ARMA model is assumed to be both stationary and invertible. Note that some of the elements of the $\varphi$- and/or $\theta$-matrices may have been fixed at pre-specified values (for example by calling multi_varma_estimate()).

The estimated residual cross-correlation matrix at lag $l$ is defined to the $k\times k$ matrix ${\hat{R}}_l$ whose $(i,j)$th element is computed as

$${\hat{r}}_{ij}\left(l\right)=\frac{{\sum }_{t=l+1}^n({\widehat{ϵ}}_{it-l}-{\overline{ϵ}}_i)({\widehat{ϵ}}_{jt}-{\overline{ϵ}}_j)}{\sqrt{{\sum }_{t=1}^n{({\widehat{ϵ}}_{it}-{\overline{ϵ}}_i)}^2{\sum }_{t=1}^n{({\widehat{ϵ}}_{jt}-{\overline{ϵ}}_j)}^2}}\text{,}l=0,1,\dots ,i\text{and}j=1,2,\dots ,k\text{,}$$

where ${\widehat{ϵ}}_{it}$ denotes an estimate of the $t$th residual for the $i$th series ${ϵ}_{it}$ and ${\overline{ϵ}}_i={\sum }_{t=1}^n{\widehat{ϵ}}_{it}/n$. (Note that ${\hat{R}}_l$ is an estimate of $E\left({ϵ}_{t-l}{ϵ}_t^T\right)$, where $E$ is the expected value.)

A modified portmanteau statistic, $Q_{\left(m\right)}^{\ast }$, is calculated from the formula (see Li and McLeod (1981))

$$Q_{\left(m\right)}^{\ast }=\frac{k^{2}m(m+1)}{2n}+n\sum _{l=1}^m\hat{r}{\left(l\right)}^T({\hat{R}}_0^{-1}\otimes {\hat{R}}_0^{-1})\hat{r}\left(l\right)\text{,}$$

where $\otimes$ denotes Kronecker product, ${\hat{R}}_0$ is the estimated residual cross-correlation matrix at lag zero and $\hat{r}\left(l\right)=vec\left({\hat{R}}_l^T\right)$, where $\text{vec}$ of a $k\times k$ matrix is a vector with the $(i,j)$th element in position $(i-1)k+j$. $m$ denotes the number of residual cross-correlation matrices computed. (Advice on the choice of $m$ is given in Further Comments.) Let $l_C$ denote the total number of ‘free’ parameters in the ARMA model excluding the mean, $\mu$, and the residual error covariance matrix $\Sigma$. Then, under the hypothesis of model adequacy, $Q_{\left(m\right)}^{\ast }$, has an asymptotic ${\chi }^2$-distribution on $m{k}^2-l_C$ degrees of freedom.

Let $\underset{–}{\hat{r}}=(vec\left(R_1^T\right),vec\left(R_2^T\right),\dots ,vec\left(R_m^T\right))$ then the covariance matrix of $\underset{–}{\hat{r}}$ is given by

$$Var\left(\widehat{\underset{–}{r}}\right)=[Y-X{\left(X^{T}G{G}^{T}X\right)}^{-1}{X}^T]/n\text{,}$$

where $Y=I_m\otimes (\Delta \otimes \Delta )$ and $G=I_m\left(G{G}^T\right)$. $\Delta$ is the dispersion matrix $\Sigma$ in correlation form and $G$ a nonsingular $k\times k$ matrix such that $G{G}^T={\Delta }^{-1}$ and $G\Delta G^T=I_k$. The construction of the matrix $X$ is discussed in Li and McLeod (1981). (Note that the mean, $\mu$, plays no part in calculating $Var\left(\widehat{\underset{–}{r}}\right)$ and, therefore, is not required as input to multi_varma_diag.)

References

Li, W K and McLeod, A I, 1981, Distribution of the residual autocorrelations in multivariate ARMA time series models, J. Roy. Statist. Soc. Ser. B (43), 231–239