Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_tsa_multi_xcorr (g13bc)

## Purpose

nag_tsa_multi_xcorr (g13bc) calculates cross-correlations between two time series.

## Syntax

[s, r0, r, stat, ifail] = g13bc(x, y, nl, 'nxy', nxy)
[s, r0, r, stat, ifail] = nag_tsa_multi_xcorr(x, y, nl, 'nxy', nxy)

## Description

Given two series ${x}_{1},{x}_{2},\dots ,{x}_{n}$ and ${y}_{1},{y}_{2},\dots ,{y}_{n}$ the function calculates the cross-correlations between ${x}_{t}$ and lagged values of ${y}_{t}$:
 $rxyl=∑t=1 n-lxt-x-yt+l-y- nsxsy , l=0,1,…,L$
where
 $x-=∑t= 1nxtn$
 $sx2=∑t=1n xt-x- 2n$
and similarly for $y$.
The ratio of standard deviations ${s}_{y}/{s}_{x}$ is also returned, and a portmanteau statistic is calculated:
 $stat=n∑l=1Lrxy l 2.$
Provided $n$ is large, $L$ much less than $n$, and both ${x}_{t},{y}_{t}$ are samples of series whose true autocorrelation functions are zero, then, under the null hypothesis that the true cross-correlations between the series are zero, stat has a ${\chi }^{2}$-distribution with $L$ degrees of freedom. Values of stat in the upper tail of this distribution provide evidence against the null hypothesis.

## References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}\left({\mathbf{nxy}}\right)$ – double array
The $n$ values of the $x$ series.
2:     $\mathrm{y}\left({\mathbf{nxy}}\right)$ – double array
The $n$ values of the $y$ series.
3:     $\mathrm{nl}$int64int32nag_int scalar
$L$, the maximum lag for calculating cross-correlations.
Constraint: $1\le {\mathbf{nl}}<{\mathbf{nxy}}$.

### Optional Input Parameters

1:     $\mathrm{nxy}$int64int32nag_int scalar
Default: the dimension of the arrays x, y. (An error is raised if these dimensions are not equal.)
$n$, the length of the time series.
Constraint: ${\mathbf{nxy}}\ge 2$.

### Output Parameters

1:     $\mathrm{s}$ – double scalar
The ratio of the standard deviation of the $y$ series to the standard deviation of the $x$ series, ${s}_{y}/{s}_{x}$.
2:     $\mathrm{r0}$ – double scalar
The cross-correlation between the $x$ and $y$ series at lag zero.
3:     $\mathrm{r}\left({\mathbf{nl}}\right)$ – double array
${\mathbf{r}}\left(\mathit{l}\right)$ contains the cross-correlations between the $x$ and $y$ series at lags $L$, ${r}_{xy}\left(\mathit{l}\right)$, for $\mathit{l}=1,2,\dots ,L$.
4:     $\mathrm{stat}$ – double scalar
The statistic for testing for absence of cross-correlation.
5:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{nxy}}\le 1$, or ${\mathbf{nl}}<1$, or ${\mathbf{nl}}\ge {\mathbf{nxy}}$.
${\mathbf{ifail}}=2$
One or both of the $x$ and $y$ series have zero variance and hence cross-correlations cannot be calculated.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

All computations are believed to be stable.

If $n<100$, or $L<10\mathrm{log}\left(n\right)$ then the autocorrelations are calculated directly and the time taken by nag_tsa_multi_xcorr (g13bc) is approximately proportional to $nL$, otherwise the autocorrelations are calculated by utilizing fast Fourier transforms (FFTs) and the time taken is approximately proportional to $n\mathrm{log}\left(n\right)$. If FFTs are used then nag_tsa_multi_xcorr (g13bc) internally allocates approximately $6n$ real elements.

## Example

This example reads two time series of length $20$. It calculates and prints the cross-correlations up to lag $15$ for the first series leading the second series and then for the second series leading the first series.
```function g13bc_example

fprintf('g13bc example results\n\n');

% Series
x = [0.02;  0.05;  0.08;  0.03; -0.05;  0.11; -0.01; -0.08; -0.08; -0.11;
-0.18; -0.19; -0.09;  0.03;  0.10;  0.15; -0.14;  0.07;  0.09;  0.16];
y = [3.18;  3.21;  3.26;  3.25;  3.08;  3.01;  3.06;  3.17;  3.12;  3.04;
3.26;  3.45;  3.33;  3.70;  3.31;  3.81;  3.33;  2.96;  3.28;  3.10];

% Number of lags
nl = int64(15);

% Cross correlations between x and y
[sxy, r0xy, rxy, statxy, ifail] = g13bc( ...
x, y, nl);
% Cross correlations between y and x
[syx, r0yx, ryx, statyx, ifail] = g13bc( ...
y, x, nl);

% Display results
fprintf('%34s%15s\n', 'Between', 'Between');
fprintf('%34s%15s\n', 'x and y', 'y and x');
fmt1 = '\n%24s%10.4f%15.4f\n';
fprintf(fmt1, 'Standard deviation ratio', sxy, syx);
fprintf('\nCross correlation at lag');
fprintf(fmt1, '0', r0xy, r0yx);
ivar = double([1:nl]');
fprintf('%24d%10.4f%15.4f\n', [ivar rxy ryx]')
fprintf(fmt1,'Test statistic          ', statxy, statyx);

```
```g13bc example results

Between        Between
x and y        y and x

Standard deviation ratio    2.0053         0.4987

Cross correlation at lag
0    0.0568         0.0568
1    0.0438        -0.0151
2   -0.3762         0.3955
3   -0.4864         0.3417
4   -0.6294         0.5486
5   -0.3871         0.2291
6   -0.1690         0.3190
7   -0.0678         0.1980
8    0.0962         0.0438
9    0.0788        -0.1428
10    0.2910        -0.1376
11    0.0950        -0.0387
12    0.0547        -0.0380
13    0.1855        -0.1551
14    0.0243        -0.1536
15    0.0034        -0.0696

Test statistic             22.1269        17.2917
```