NAG FL Interface
g13dnf (multi_corrmat_partlag)
1
Purpose
g13dnf calculates the sample partial lag correlation matrices of a multivariate time series. A set of
${\chi}^{2}$statistics and their significance levels are also returned. A call to
g13dmf is usually made prior to calling this routine in order to calculate the sample crosscorrelation matrices.
2
Specification
Fortran Interface
Subroutine g13dnf ( 
k, n, m, kmax, r0, r, maxlag, parlag, x, pvalue, work, lwork, ifail) 
Integer, Intent (In) 
:: 
k, n, m, kmax, lwork 
Integer, Intent (Inout) 
:: 
ifail 
Integer, Intent (Out) 
:: 
maxlag 
Real (Kind=nag_wp), Intent (In) 
:: 
r0(kmax,k), r(kmax,kmax,m) 
Real (Kind=nag_wp), Intent (Inout) 
:: 
parlag(kmax,kmax,m) 
Real (Kind=nag_wp), Intent (Out) 
:: 
x(m), pvalue(m), work(lwork) 

C Header Interface
#include <nag.h>
void 
g13dnf_ (const Integer *k, const Integer *n, const Integer *m, const Integer *kmax, const double r0[], const double r[], Integer *maxlag, double parlag[], double x[], double pvalue[], double work[], const Integer *lwork, Integer *ifail) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
g13dnf_ (const Integer &k, const Integer &n, const Integer &m, const Integer &kmax, const double r0[], const double r[], Integer &maxlag, double parlag[], double x[], double pvalue[], double work[], const Integer &lwork, Integer &ifail) 
}

The routine may be called by the names g13dnf or nagf_tsa_multi_corrmat_partlag.
3
Description
Let
${W}_{\mathit{t}}={\left({w}_{1\mathit{t}},{w}_{2\mathit{t}},\dots ,{w}_{\mathit{k}\mathit{t}}\right)}^{\mathrm{T}}$, for
$\mathit{t}=1,2,\dots ,n$, denote
$n$ observations of a vector of
$k$ time series. The partial lag correlation matrix at lag
$l$,
$P\left(l\right)$, is defined to be the correlation matrix between
${W}_{t}$ and
${W}_{t+l}$, after removing the linear dependence on each of the intervening vectors
${W}_{t+1},{W}_{t+2},\dots ,{W}_{t+l1}$. It is the correlation matrix between the residual vectors resulting from the regression of
${W}_{t+l}$ on the carriers
${W}_{t+l1},\dots ,{W}_{t+1}$ and the regression of
${W}_{t}$ on the same set of carriers; see
Heyse and Wei (1985).
$P\left(l\right)$ has the following properties.

(i)If ${W}_{t}$ follows a vector autoregressive model of order $p$, then $P\left(l\right)=0$ for $l>p$;

(ii)When $k=1$, $P\left(l\right)$ reduces to the univariate partial autocorrelation at lag $l$;

(iii)Each element of $P\left(l\right)$ is a properly normalized correlation coefficient;

(iv)When $l=1$, $P\left(l\right)$ is equal to the crosscorrelation matrix at lag $1$ (a natural property which also holds for the univariate partial autocorrelation function).
Sample estimates of the partial lag correlation matrices may be obtained using the recursive algorithm described in
Wei (1990). They are calculated up to lag
$m$, which is usually taken to be at most
$n/4$. Only the sample crosscorrelation matrices (
$\hat{R}\left(\mathit{l}\right)$, for
$\mathit{l}=0,1,\dots ,m$) and the standard deviations of the series are required as input to
g13dnf. These may be computed by
g13dmf. Under the hypothesis that
${W}_{t}$ follows an autoregressive model of order
$s1$, the elements of the sample partial lag matrix
$\hat{P}\left(s\right)$, denoted by
${\hat{P}}_{ij}\left(s\right)$, are asymptotically Normally distributed with mean zero and variance
$1/n$. In addition the statistic
has an asymptotic
${\chi}^{2}$distribution with
${k}^{2}$ degrees of freedom. These quantities,
$X\left(l\right)$, are useful as a diagnostic aid for determining whether the series follows an autoregressive model and, if so, of what order.
4
References
Heyse J F and Wei W W S (1985) The partial lag autocorrelation function Technical Report No. 32 Department of Statistics, Temple University, Philadelphia
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley
5
Arguments

1:
$\mathbf{k}$ – Integer
Input

On entry: $k$, the dimension of the multivariate time series.
Constraint:
${\mathbf{k}}\ge 1$.

2:
$\mathbf{n}$ – Integer
Input

On entry: $n$, the number of observations in each series.
Constraint:
${\mathbf{n}}\ge 2$.

3:
$\mathbf{m}$ – Integer
Input

On entry:
$m$, the number of partial lag correlation matrices to be computed. Note this also specifies the number of sample crosscorrelation matrices that must be contained in the array
r.
Constraint:
$1\le {\mathbf{m}}<{\mathbf{n}}$.

4:
$\mathbf{kmax}$ – Integer
Input

On entry: the first dimension of the arrays
r0,
r and
parlag and the second dimension of the arrays
r and
parlag as declared in the (sub)program from which
g13dnf is called.
Constraint:
${\mathbf{kmax}}\ge {\mathbf{k}}$.

5:
$\mathbf{r0}\left({\mathbf{kmax}},{\mathbf{k}}\right)$ – Real (Kind=nag_wp) array
Input

On entry: if $i\ne j$, then ${\mathbf{r0}}\left(i,j\right)$ must contain the $\left(i,j\right)$th element of the sample crosscorrelation matrix at lag zero, ${\hat{R}}_{ij}\left(0\right)$. If $i=j$, then ${\mathbf{r0}}\left(i,i\right)$ must contain the standard deviation of the $i$th series.

6:
$\mathbf{r}\left({\mathbf{kmax}},{\mathbf{kmax}},{\mathbf{m}}\right)$ – Real (Kind=nag_wp) array
Input

On entry:
${\mathbf{r}}\left(i,j,l\right)$ must contain the
$\left(i,j\right)$th element of the sample crosscorrelation at lag
$l$,
${\hat{R}}_{\mathit{i}\mathit{j}}\left(\mathit{l}\right)$, for
$\mathit{l}=1,2,\dots ,m$,
$\mathit{i}=1,2,\dots ,k$ and
$\mathit{j}=1,2,\dots ,k$, where series
$\mathit{j}$ leads series
$\mathit{i}$ (see
Section 9).

7:
$\mathbf{maxlag}$ – Integer
Output

On exit: the maximum lag up to which partial lag correlation matrices (along with
${\chi}^{2}$statistics and their significance levels) have been successfully computed. On a successful exit
maxlag will equal
m. If
${\mathbf{ifail}}={\mathbf{2}}$ on exit,
maxlag will be less than
m.

8:
$\mathbf{parlag}\left({\mathbf{kmax}},{\mathbf{kmax}},{\mathbf{m}}\right)$ – Real (Kind=nag_wp) array
Output

On exit: ${\mathbf{parlag}}\left(i,j,l\right)$ contains the $\left(i,j\right)$th element of the sample partial lag correlation matrix at lag $l$,
${\hat{P}}_{\mathit{i}\mathit{j}}\left(\mathit{l}\right)$, for $\mathit{l}=1,2,\dots ,{\mathbf{maxlag}}$, $\mathit{i}=1,2,\dots ,k$ and $\mathit{j}=1,2,\dots ,k$.

9:
$\mathbf{x}\left({\mathbf{m}}\right)$ – Real (Kind=nag_wp) array
Output

On exit: ${\mathbf{x}}\left(\mathit{l}\right)$ contains the ${\chi}^{2}$statistic at lag $\mathit{l}$, for $\mathit{l}=1,2,\dots ,{\mathbf{maxlag}}$.

10:
$\mathbf{pvalue}\left({\mathbf{m}}\right)$ – Real (Kind=nag_wp) array
Output

On exit:
${\mathbf{pvalue}}\left(\mathit{l}\right)$ contains the significance level of the corresponding
${\chi}^{2}$statistic in
x, for
$\mathit{l}=1,2,\dots ,{\mathbf{maxlag}}$.

11:
$\mathbf{work}\left({\mathbf{lwork}}\right)$ – Real (Kind=nag_wp) array
Workspace

12:
$\mathbf{lwork}$ – Integer
Input

On entry: the dimension of the array
work as declared in the (sub)program from which
g13dnf is called.
Constraint:
${\mathbf{lwork}}\ge \left(5{\mathbf{m}}+6\right){{\mathbf{k}}}^{2}+{\mathbf{k}}$.

13:
$\mathbf{ifail}$ – Integer
Input/Output

On entry:
ifail must be set to
$0$,
$1\text{or}1$. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{or}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{k}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{k}}\ge 1$.
On entry, ${\mathbf{kmax}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{k}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{kmax}}\ge {\mathbf{k}}$.
On entry, ${\mathbf{lwork}}=\u2329\mathit{\text{value}}\u232a$ and the minimum size $\text{required}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{lwork}}\ge \left(5\times {\mathbf{m}}+6\right)\times {{\mathbf{k}}}^{2}+{\mathbf{k}}$.
On entry, ${\mathbf{m}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{m}}\ge 1$.
On entry, ${\mathbf{m}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{m}}<{\mathbf{n}}$.
On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}\ge 2$.
 ${\mathbf{ifail}}=2$

The recursive equations used to compute the partial lag correlation matrices are illconditioned (they have been computed up to lag
$\u2329\mathit{\text{value}}\u232a$). All output quantities in the arrays
parlag,
x and
pvalue up to and including lag
maxlag will be correct.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
The accuracy will depend upon the accuracy of the sample crosscorrelations.
8
Parallelism and Performance
g13dnf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g13dnf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
The time taken is roughly proportional to ${m}^{2}{k}^{3}$.
If you have calculated the sample crosscorrelation matrices in the arrays
r0 and
r, without calling
g13dmf, then care must be taken to ensure they are supplied as described in
Section 5. In particular, for
$l\ge 1$,
${\hat{R}}_{ij}\left(l\right)$ must contain the sample crosscorrelation coefficient between
${w}_{i\left(tl\right)}$ and
${w}_{jt}$.
The routine
g13dbf computes squared partial autocorrelations for a specified number of lags. It may also be used to estimate a sequence of partial autoregression matrices at lags
$1,2,\dots \text{}$ by making repeated calls to the routine with the argument
nk set to
$1,2,\dots \text{}$. The
$\left(i,j\right)$th element of the sample partial autoregression matrix at lag
$l$ is given by
$W\left(i,j,l\right)$ when
nk is set equal to
$l$ on entry to
g13dbf. Note that this is the ‘Yule–Walker’ estimate. Unlike the partial lag correlation matrices computed by
g13dnf, when
${W}_{t}$ follows an autoregressive model of order
$s1$, the elements of the sample partial autoregressive matrix at lag
$s$ do not have variance
$1/n$, making it very difficult to spot a possible cutoff point. The differences between these matrices are discussed further by
Wei (1990).
Note that
g13dbf takes the sample crosscovariance matrices as input whereas this routine requires the sample crosscorrelation matrices to be input.
10
Example
This example computes the sample partial lag correlation matrices of two time series of length $48$, up to lag $10$. The matrices, their ${\chi}^{2}$statistics and significance levels and a plot of symbols indicating which elements of the sample partial lag correlation matrices are significant are printed. Three * represent significance at the $0.5$% level, two * represent significance at the 1% level and a single * represents significance at the 5% level. The * are plotted above or below the central line depending on whether the elements are significant in a positive or negative direction.
10.1
Program Text
10.2
Program Data
10.3
Program Results