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_uni_autocorr (g13ab)

## Purpose

nag_tsa_uni_autocorr (g13ab) computes the sample autocorrelation function of a time series. It also computes the sample mean, the sample variance and a statistic which may be used to test the hypothesis that the true autocorrelation function is zero.

## Syntax

[xm, xv, r, stat, ifail] = g13ab(x, nk, 'nx', nx)
[xm, xv, r, stat, ifail] = nag_tsa_uni_autocorr(x, nk, 'nx', nx)

## Description

The data consists of n$n$ observations xi${x}_{i}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$ from a time series.
The quantities calculated are
(a) The sample mean
 x = ( ∑ i = 1nxi)/n. $x-=∑i=1nxin.$
(b) The sample variance (for n2$n\ge 2$)
 s2 = ( ∑ i = 1n(xi − x)2)/((n − 1)). $s2=∑i=1n (xi-x-) 2 (n-1) .$
(c) The sample autocorrelation coefficients of lags k = 1,2,,K$k=1,2,\dots ,K$, where K$K$ is a user-specified maximum lag, and K < n$K, n > 1$n>1$.
The coefficient of lag k$k$ is defined as
 rk = ( ∑ i = 1n − k(xi − x)(xi + k − x))/( ∑ i = 1n(xi − x)2). $rk=∑i=1 n-k(xi-x-)(xi+k-x-) ∑i=1n (xi-x-) 2 .$
See page 496 of Box and Jenkins (1976) for further details.
(d) A test statistic defined as
 K stat = n ∑ rk2, k = 1
$stat=n∑k= 1Krk2,$
which can be used to test the hypothesis that the true autocorrelation function is identically zero.
If n$n$ is large and K$K$ is much smaller than n$n$, stat has a χK2${\chi }_{K}^{2}$ distribution under the hypothesis of a zero autocorrelation function. Values of stat in the upper tail of the distribution provide evidence against the hypothesis; nag_stat_prob_chisq (g01ec) can be used to compute the tail probability.
Section 8.2.2 of Box and Jenkins (1976) provides further details of the use of stat.

## 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:     x(nx) – double array
nx, the dimension of the array, must satisfy the constraint nx > 1${\mathbf{nx}}>1$.
The time series, xi${x}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$.
2:     nk – int64int32nag_int scalar
K$K$, the number of lags for which the autocorrelations are required. The lags range from 1$1$ to K$K$ and do not include zero.
Constraint: 0 < nk < nx$0<{\mathbf{nk}}<{\mathbf{nx}}$.

### Optional Input Parameters

1:     nx – int64int32nag_int scalar
Default: The dimension of the array x.
n$n$, the number of values in the time series.
Constraint: nx > 1${\mathbf{nx}}>1$.

None.

### Output Parameters

1:     xm – double scalar
The sample mean of the input time series.
2:     xv – double scalar
The sample variance of the input time series.
3:     r(nk) – double array
The sample autocorrelation coefficient relating to lag k$\mathit{k}$, for k = 1,2,,K$\mathit{k}=1,2,\dots ,K$.
4:     stat – double scalar
The statistic used to test the hypothesis that the true autocorrelation function of the time series is identically zero.
5:     ifail – int64int32nag_int scalar
${\mathrm{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:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
 On entry, nx ≤ nk${\mathbf{nx}}\le {\mathbf{nk}}$, or nx ≤ 1${\mathbf{nx}}\le 1$, or nk ≤ 0${\mathbf{nk}}\le 0$.
W ifail = 2${\mathbf{ifail}}=2$
On entry, all values of x are practically identical, giving zero variance. In this case r and stat are undefined on exit.

## Accuracy

The computations are believed to be stable.

If n < 100$n<100$, or K < 10log(n)$K<10\mathrm{log}\left(n\right)$ then the autocorrelations are calculated directly and the time taken by nag_tsa_uni_autocorr (g13ab) is approximately proportional to nK$nK$, otherwise the autocorrelations are calculated by utilizing fast fourier transforms (FFTs) and the time taken is approximately proportional to nlog(n)$n\mathrm{log}\left(n\right)$. If FFTs are used then nag_tsa_uni_autocorr (g13ab) internally allocates approximately 4n$4n$ real elements.
If the input series for nag_tsa_uni_autocorr (g13ab) was generated by differencing using nag_tsa_uni_diff (g13aa), ensure that only the differenced values are input to nag_tsa_uni_autocorr (g13ab), and not the reconstituting information.

## Example

```function nag_tsa_uni_autocorr_example
x = [5;
11;
16;
23;
36;
58;
29;
20;
10;
8;
3;
0;
0;
2;
11;
27;
47;
63;
60;
39;
28;
26;
22;
11;
21;
40;
78;
122;
103;
73;
47;
35;
11;
5;
16;
34;
70;
81;
111;
101;
73;
40;
20;
16;
5;
11;
22;
40;
60;
80.9];
nk = int64(10);
[xm, xv, r, stat, ifail] = nag_tsa_uni_autocorr(x, nk)
```
```

xm =

37.4180

xv =

1.0020e+03

r =

0.8004
0.4355
0.0328
-0.2835
-0.4505
-0.4242
-0.2419
0.0550
0.3783
0.5857

stat =

92.1231

ifail =

0

```
```function g13ab_example
x = [5;
11;
16;
23;
36;
58;
29;
20;
10;
8;
3;
0;
0;
2;
11;
27;
47;
63;
60;
39;
28;
26;
22;
11;
21;
40;
78;
122;
103;
73;
47;
35;
11;
5;
16;
34;
70;
81;
111;
101;
73;
40;
20;
16;
5;
11;
22;
40;
60;
80.9];
nk = int64(10);
[xm, xv, r, stat, ifail] = g13ab(x, nk)
```
```

xm =

37.4180

xv =

1.0020e+03

r =

0.8004
0.4355
0.0328
-0.2835
-0.4505
-0.4242
-0.2419
0.0550
0.3783
0.5857

stat =

92.1231

ifail =

0

```