# NAG FL Interfaceg13dbf (multi_​autocorr_​part)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

g13dbf calculates the multivariate partial autocorrelation function of a multivariate time series.

## 2Specification

Fortran Interface
 Subroutine g13dbf ( c0, c, ldc0, ns, nl, nk, p, v0, v, d, db, w, wb, nvp, wa, iwa,
 Integer, Intent (In) :: ldc0, ns, nl, nk, iwa Integer, Intent (Inout) :: ifail Integer, Intent (Out) :: nvp Real (Kind=nag_wp), Intent (In) :: c0(ldc0,ns), c(ldc0,ldc0,nl) Real (Kind=nag_wp), Intent (Inout) :: d(ldc0,ldc0,nk), db(ldc0,ns), w(ldc0,ldc0,nk), wb(ldc0,ldc0,nk) Real (Kind=nag_wp), Intent (Out) :: p(nk), v0, v(nk), wa(iwa)
#include <nag.h>
 void g13dbf_ (const double c0[], const double c[], const Integer *ldc0, const Integer *ns, const Integer *nl, const Integer *nk, double p[], double *v0, double v[], double d[], double db[], double w[], double wb[], Integer *nvp, double wa[], const Integer *iwa, Integer *ifail)
The routine may be called by the names g13dbf or nagf_tsa_multi_autocorr_part.

## 3Description

The input is a set of lagged autocovariance matrices ${C}_{0},{C}_{1},{C}_{2},\dots ,{C}_{m}$. These will generally be sample values such as are obtained from a multivariate time series using g13dmf.
The main calculation is the recursive determination of the coefficients in the finite lag (forward) prediction equation
 $xt = Φl,1 xt-1 +⋯+ Φl,l xt-l + el,t$
and the associated backward prediction equation
 $xt-l- 1=Ψl,1xt-l+⋯+Ψl,lxt- 1+fl,t$
together with the covariance matrices ${D}_{l}$ of ${e}_{l,t}$ and ${G}_{l}$ of ${f}_{l,t}$.
The recursive cycle, by which the order of the prediction equation is extended from $l$ to $l+1$, is to calculate
 $Ml+1 = Cl+1T - Φ l,1 ClT -⋯- Φl,l C1T$ (1)
then ${\Phi }_{l+1,l+1}={M}_{l+1}{D}_{l}^{-1}$, $\text{ }{\Psi }_{l+1,l+1}={{M}^{\mathrm{T}}}_{l+1}{G}_{l}^{-1}$
from which
 $Φl+1,j=Φl,j-Φl+1,l+1Ψl,l+1-j, j=1,2,…,l$ (2)
and
 $Ψl+1,j=Ψl,j-Ψl+1,l+1Φl,l+1-j, j=1,2,…,l.$ (3)
Finally, ${D}_{l+1}={D}_{l}-{M}_{l+1}{{\Phi }^{\mathrm{T}}}_{l+1,l+1}$ and ${G}_{l+1}={G}_{l}-{{M}^{\mathrm{T}}}_{l+1}{{\Psi }^{\mathrm{T}}}_{l+1,l+1}$.
(Here $\mathrm{T}$ denotes the transpose of a matrix.)
The cycle is initialized by taking (for $l=0$)
 $D0=G0=C0.$
In the step from $l=0$ to $1$, the above equations contain redundant terms and simplify. Thus (1) becomes ${M}_{1}={{C}^{\mathrm{T}}}_{1}$ and neither (2) or (3) are needed.
Quantities useful in assessing the effectiveness of the prediction equation are generalized variance ratios
 $vl = det⁡Dl / det⁡C0 , l=1,2,…$
and multiple squared partial autocorrelations
 $pl2 = 1 - vl / v l-1 .$
Akaike H (1971) Autoregressive model fitting for control Ann. Inst. Statist. Math. 23 163–180
Whittle P (1963) On the fitting of multivariate autoregressions and the approximate canonical factorization of a spectral density matrix Biometrika 50 129–134

## 5Arguments

1: $\mathbf{c0}\left({\mathbf{ldc0}},{\mathbf{ns}}\right)$Real (Kind=nag_wp) array Input
On entry: contains the zero lag cross-covariances between the ns series as returned by g13dmf. (c0 is assumed to be symmetric, upper triangle only is used.)
2: $\mathbf{c}\left({\mathbf{ldc0}},{\mathbf{ldc0}},{\mathbf{nl}}\right)$Real (Kind=nag_wp) array Input
On entry: contains the cross-covariances at lags $1$ to nl. ${\mathbf{c}}\left(i,j,k\right)$ must contain the cross-covariance, ${c}_{ijk}$, of series $i$ and series $j$ at lag $k$. Series $j$ leads series $i$.
3: $\mathbf{ldc0}$Integer Input
On entry: the first dimension of the arrays c0, c, d, db, w and wb and the second dimension of the arrays c, d, w and wb as declared in the (sub)program from which g13dbf is called.
Constraint: ${\mathbf{ldc0}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ns}},1\right)$.
4: $\mathbf{ns}$Integer Input
On entry: $k$, the number of time series whose cross-covariances are supplied in c and c0.
Constraint: ${\mathbf{ns}}\ge 1$.
5: $\mathbf{nl}$Integer Input
On entry: $m$, the maximum lag for which cross-covariances are supplied in c.
Constraint: ${\mathbf{nl}}\ge 1$.
6: $\mathbf{nk}$Integer Input
On entry: the number of lags to which partial auto-correlations are to be calculated.
Constraint: $1\le {\mathbf{nk}}\le {\mathbf{nl}}$.
7: $\mathbf{p}\left({\mathbf{nk}}\right)$Real (Kind=nag_wp) array Output
On exit: the multiple squared partial autocorrelations from lags $1$ to nvp; that is, ${\mathbf{p}}\left(l\right)$ contains ${p}_{\mathit{l}}^{2}$, for $\mathit{l}=1,2,\dots ,{\mathbf{nvp}}$. For lags ${\mathbf{nvp}}+1$ to nk the elements of p are set to zero.
8: $\mathbf{v0}$Real (Kind=nag_wp) Output
On exit: the lag zero prediction error variance (equal to the determinant of c0).
9: $\mathbf{v}\left({\mathbf{nk}}\right)$Real (Kind=nag_wp) array Output
On exit: the prediction error variance ratios from lags $1$ to nvp; that is, ${\mathbf{v}}\left(\mathit{l}\right)$ contains ${v}_{\mathit{l}}$, for $\mathit{l}=1,2,\dots ,{\mathbf{nvp}}$. For lags ${\mathbf{nvp}}+1$ to nk the elements of v are set to zero.
10: $\mathbf{d}\left({\mathbf{ldc0}},{\mathbf{ldc0}},{\mathbf{nk}}\right)$Real (Kind=nag_wp) array Output
On exit: the prediction error variance matrices at lags $1$ to nvp.
Element $\left(i,j,\mathit{k}\right)$ of d contains the prediction error covariance of series $i$ and series $j$ at lag $\mathit{k}$, for $\mathit{k}=1,2,\dots ,{\mathbf{nvp}}$. Series $j$ leads series $i$; that is, the $\left(i,j\right)$th element of ${D}_{k}$. For lags ${\mathbf{nvp}}+1$ to nk the elements of d are set to zero.
11: $\mathbf{db}\left({\mathbf{ldc0}},{\mathbf{ns}}\right)$Real (Kind=nag_wp) array Output
On exit: the backward prediction error variance matrix at lag nvp.
${\mathbf{db}}\left(i,j\right)$ contains the backward prediction error covariance of series $i$ and series $j$; that is, the $\left(i,j\right)$th element of the ${G}_{k}$, where $k={\mathbf{nvp}}$.
12: $\mathbf{w}\left({\mathbf{ldc0}},{\mathbf{ldc0}},{\mathbf{nk}}\right)$Real (Kind=nag_wp) array Output
On exit: the prediction coefficient matrices at lags $1$ to nvp.
${\mathbf{w}}\left(i,j,\mathit{l}\right)$ contains the $j$th prediction coefficient of series $i$ at lag $\mathit{l}$; that is, the $\left(i,j\right)$th element of ${\Phi }_{k\mathit{l}}$, where $k={\mathbf{nvp}}$, for $\mathit{l}=1,2,\dots ,{\mathbf{nvp}}$. For lags ${\mathbf{nvp}}+1$ to nk the elements of w are set to zero.
13: $\mathbf{wb}\left({\mathbf{ldc0}},{\mathbf{ldc0}},{\mathbf{nk}}\right)$Real (Kind=nag_wp) array Output
On exit: the backward prediction coefficient matrices at lags $1$ to nvp.
${\mathbf{wb}}\left(i,j,\mathit{l}\right)$ contains the $j$th backward prediction coefficient of series $i$ at lag $\mathit{l}$; that is, the $\left(i,j\right)$th element of ${\Psi }_{k\mathit{l}}$, where $k={\mathbf{nvp}}$, for $\mathit{l}=1,2,\dots ,{\mathbf{nvp}}$. For lags ${\mathbf{nvp}}+1$ to nk the elements of wb are set to zero.
14: $\mathbf{nvp}$Integer Output
On exit: the maximum lag, $L$, for which calculation of p, v, d, db, w and wb was successful. If the routine completes successfully nvp will equal nk.
15: $\mathbf{wa}\left({\mathbf{iwa}}\right)$Real (Kind=nag_wp) array Workspace
16: $\mathbf{iwa}$Integer Input
On entry: the dimension of the array wa as declared in the (sub)program from which g13dbf is called.
Constraint: ${\mathbf{iwa}}\ge \left(2×{\mathbf{ns}}+1\right)×{\mathbf{ns}}$.
17: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ 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).

## 6Error 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{iwa}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{iwa}}\ge 1$.
On entry, ${\mathbf{iwa}}=⟨\mathit{\text{value}}⟩$ and the minimum size $\text{required}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{iwa}}\ge \left(2×{\mathbf{ns}}+1\right)×{\mathbf{ns}}$.
On entry, ${\mathbf{ldc0}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldc0}}\ge 1$.
On entry, ${\mathbf{nk}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nk}}\ge 1$.
On entry, ${\mathbf{nk}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{nl}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nk}}\le {\mathbf{nl}}$.
On entry, ${\mathbf{nl}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nl}}\ge 1$.
On entry, ${\mathbf{ns}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ns}}\ge 1$.
On entry, ${\mathbf{ns}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ldc0}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ns}}\le {\mathbf{ldc0}}$.
${\mathbf{ifail}}=2$
c0 is not positive definite. The arguments v0, v, p, d, db, w, wb and nvp are set to zero.
${\mathbf{ifail}}=3$
For ${\mathbf{nvp}}=⟨\mathit{\text{value}}⟩$, at lag $k={\mathbf{nvp}}+1$, ${D}_{k}$ was found not to be positive definite.
Up to lag $k-1$, arguments v0, v, p, d, w and wb contain the values calculated so far. From lag $k$ they contain zero. The argument db contains the backward prediction coefficients for lag $k-1$.
${\mathbf{ifail}}=-99$
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.

## 7Accuracy

The conditioning of the problem depends on the prediction error variance ratios. Very small values of these may indicate loss of accuracy in the computations.

## 8Parallelism and Performance

g13dbf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g13dbf 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 implementation-specific information.

The time taken by g13dbf is roughly proportional to ${{\mathbf{nk}}}^{2}×{{\mathbf{ns}}}^{3}$.
If sample autocorrelation matrices are used as input, then the output will be relevant to the original series scaled by their standard deviations. If these autocorrelation matrices are produced by g13dmf, you must replace the diagonal elements of ${C}_{0}$ (otherwise used to hold the series variances) by $1$.

## 10Example

This example reads the autocovariance matrices for four series from lag $0$ to $5$. It calls g13dbf to calculate the multivariate partial autocorrelation function and other related matrices of statistics up to lag $3$. It prints the results.

### 10.1Program Text

Program Text (g13dbfe.f90)

### 10.2Program Data

Program Data (g13dbfe.d)

### 10.3Program Results

Program Results (g13dbfe.r)