naginterfaces.library.rand.times_​mv_​varma

naginterfaces.library.rand.times_mv_varma(mode, n, xmean, ip, phi, iq, theta, var, comm, statecomm)

times_mv_varma generates a realization of a multivariate time series from a vector autoregressive moving average (VARMA) model. The realization may be continued or a new realization generated at subsequent calls to times_mv_varma.

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

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g05/g05pjf.html

Parameters

modeint

A code for selecting the operation to be performed by the function.

$mode=0$

Set up reference vector and compute a realization of the recent history.

$mode=1$

Generate terms in the time series using reference vector set up in a prior call to times_mv_varma.

$mode=2$

Combine the operations of $mode=0$ or $1$.

$mode=3$

A new realization of the recent history is computed using information stored in the reference vector, and the following sequence of time series values are generated.

If $mode=1$ or $3$, you must ensure that the reference vector $comm$[‘r’] and the values of $\text{k}$, $ip$, $iq$, $xmean$, $phi$, $theta$, $var$ and $\text{ldvar}$ have not been changed between calls to times_mv_varma.

nint

$n$, the number of observations to be generated.

xmeanfloat, array-like, shape $\left(k\right)$

$\mu$, the vector of means of the multivariate time series.

ipint

$p$, the number of autoregressive parameter matrices.

phifloat, array-like, shape $(k\times k\times ip)$

Must contain the elements of the $ip\times k\times k$ autoregressive parameter matrices of the model, ${\varphi }_1,{\varphi }_2,\dots ,{\varphi }_p$. If $phi$ is considered as a three-dimensional array, dimensioned as $phi[k-1,k-1,ip-1]$, the $(i,j)$th element of ${\varphi }_{\text{l}}$ would be stored in $phi[i-1,j-1,\text{l}-1]$; that is, $phi[(\text{l}-1)\times k\times k+(j-1)\times k+i-1]$ must be set equal to the $(i,j)$th element of ${\varphi }_{\text{l}}$, for $\text{l}=1,2,\dots ,p$, $i=1,2,\dots ,k$ and $j=1,2,\dots ,k$.

iqint

$q$, the number of moving average parameter matrices.

thetafloat, array-like, shape $(k\times k\times iq)$

Must contain the elements of the $iq\times k\times k$ moving average parameter matrices of the model, ${\theta }_1,{\theta }_2,\dots ,{\theta }_q$. If $theta$ is considered as a three-dimensional array, dimensioned as $theta$($\text{k}$,$\text{k}$,$iq$), the $(i,j)$th element of ${\theta }_{\text{l}}$ would be stored in $theta[\text{i}-1,\text{j}-1,\text{l}-1]$; that is, $theta[(\text{l}-1)\times k\times k+(\text{j}-1)\times k+\text{i}-1]$ must be set equal to the $(\text{i},\text{j})$th element of ${\theta }_{\text{l}}$, for $\text{j}=1,2,\dots ,k$, for $\text{i}=1,2,\dots ,k$, for $\text{l}=1,2,\dots ,q$.

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

$var[\text{i}-1,\text{j}-1]$ must contain the ($\text{i},\text{j}$)th element of $\Sigma$, for $\text{j}=1,2,\dots ,k$, for $\text{i}=1,2,\dots ,k$. Only the lower triangle is required.

commdict, communication object, modified in place

Communication structure for the reference vector.

If $mode=1$ or $3$, this argument must have been initialized by a prior call to times_mv_varma.

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to init_repeat() or init_nonrepeat().

Returns

xfloat, ndarray, shape $(k,n)$

$x[\text{i}-1,\text{t}-1]$ will contain a realization of the $\text{i}$th component of $X_{\text{t}}$, for $\text{t}=1,2,\dots ,n$, for $\text{i}=1,2,\dots ,k$.

Raises

NagValueError

(errno $1$)

On entry, $mode=⟨value⟩$.

Constraint: $mode=0$, $1$, $2$ or $3$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $3$)

On entry, $k=⟨value⟩$.

Constraint: $k\ge 1$.

(errno $5$)

On entry, $ip=⟨value⟩$.

Constraint: $ip\ge 0$.

(errno $6$)

On entry, the AR parameters are outside the stationarity region.

(errno $7$)

On entry, $iq=⟨value⟩$.

Constraint: $iq\ge 0$.

(errno $8$)

On entry, the moving average parameter matrices are such that the model is non-invertible.

(errno $9$)

On entry, the covariance matrix $var$ is not positive semidefinite to machine precision.

(errno $11$)

$\text{k}$ is not the same as when $comm$[‘r’] was set up in a previous call.

Previous value of $k=⟨value⟩$ and $k=⟨value⟩$.

(errno $13$)

On entry, $statecomm$[‘state’] vector has been corrupted or not initialized.

(errno $20$)

An excessive number of iterations were required by the NAG function used to evaluate the eigenvalues of the matrices used to test for stationarity or invertibility.

(errno $21$)

The reference vector cannot be computed because the AR parameters are too close to the boundary of the stationarity region.

(errno $22$)

An excessive number of iterations were required by the NAG function used to evaluate the eigenvalues of the covariance matrix.

Warns

NagAlgorithmicWarning

(errno $23$)

An excessive number of iterations were required by the NAG function used to evaluate the eigenvalues stored in the reference vector.

Notes

Let the vector $X_t={(x_{1t},x_{2t},\dots ,x_{kt})}^T$, denote a $k$-dimensional time series which is assumed to follow a vector autoregressive moving average (VARMA) model of the form:

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

where ${ϵ}_t={({ϵ}_{1t},{ϵ}_{2t},\dots ,{ϵ}_{kt})}^T$, is a vector of $k$ residual series assumed to be Normally distributed with zero mean and covariance matrix $\Sigma$. The components of ${ϵ}_t$ are assumed to be uncorrelated at non-simultaneous lags. The ${\varphi }_i$’s and ${\theta }_j$’s are $k\times k$ matrices of parameters. $\left\{{\varphi }_i\right\}$, for $\text{i}=1,2,\dots ,p$, are called the autoregressive (AR) parameter matrices, and $\left\{{\theta }_j\right\}$, for $\text{j}=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& .& .& .& 0& I\\ {\theta }_q& 0& .& .& .& 0& 0\end{array}\right]}_{qk\times qk}\end{array}$$

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

The model (1) must be both stationary and invertible. The model 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.

For $k\ge 6$ the VARMA model (1) is recast into state space form and a realization of the state vector at time zero computed. For all other cases the function computes a realization of the pre-observed vectors $X_0,X_{-1},\dots ,X_{1-p}$, ${ϵ}_0,{ϵ}_{-1},\dots ,{ϵ}_{1-q}$, from (1), see Shea (1988). This realization is then used to generate a sequence of successive time series observations. Note that special action is taken for pure MA models, that is for $p=0$.

At your request a new realization of the time series may be generated more efficiently using the information in a reference vector created during a previous call to times_mv_varma. See the description of the argument $mode$ in Parameters for details.

The function returns a realization of $X_1,X_2,\dots ,X_n$. On a successful exit, the recent history is updated and saved in the array $comm$[‘r’] so that times_mv_varma may be called again to generate a realization of $X_{n+1},X_{n+2},\dots$, etc. See the description of the argument $mode$ in Parameters for details.

Further computational details are given in Shea (1988). Note, however, that times_mv_varma uses a spectral decomposition rather than a Cholesky factorization to generate the multivariate Normals. Although this method involves more multiplications than the Cholesky factorization method and is thus slightly slower it is more stable when faced with ill-conditioned covariance matrices. A method of assigning the AR and MA coefficient matrices so that the stationarity and invertibility conditions are satisfied is described in Barone (1987).

One of the initialization functions init_repeat() (for a repeatable sequence if computed sequentially) or init_nonrepeat() (for a non-repeatable sequence) must be called prior to the first call to times_mv_varma.

References

Barone, P, 1987, A method for generating independent realisations of a multivariate normal stationary and invertible ARMA $(p,q)$ process, J. Time Ser. Anal. (8), 125–130

Shea, B L, 1988, A note on the generation of independent realisations of a vector autoregressive moving average process, J. Time Ser. Anal. (9), 403–410