Documentation

# crosscorr

Sample cross-correlation

## Description

example

crosscorr(y1,y2) plots the cross-correlation function (XCF) between the two univariate, stochastic time series y1 and y2 with confidence bounds.

example

crosscorr(y1,y2,Name,Value) uses additional options specified by one or more name-value pair arguments. For example, crosscorr(y1,y2,'NumLags',10,'NumSTD',2) plots the sample XCF of y1 and y2 for 10 lags and displays confidence bounds consisting of 2 standard errors.

example

xcf = crosscorr(___) returns the sample XCF of y1 and y2 using any of the input arguments in the previous syntaxes.

example

[xcf,lags,bounds] = crosscorr(___) additionally returns the lag numbers that MATLAB®uses to compute the XCF, and also returns the approximate upper and lower confidence bounds.

crosscorr(ax,___) plots on the axes specified by ax instead of the current axes (gca). ax can precede any of the input argument combinations in the previous syntaxes.

[xcf,lags,bounds,h] = crosscorr(___) plots the sample XCF of y1 and y2, and additionally returns handles to plotted graphics objects. Use elements of h to modify properties of the plot after you create it.

## Examples

collapse all

Generate 100 random deviates from a Gaussian distribution with mean 0 and variance 1.

rng(1); % For reproducibility
x = randn(100,1);

Create a 4-period delayed version of x.

y = lagmatrix(x,4);

Compute and plot the XCF.

y(isnan(y)) = 0; % crosscorr does not accept NaNs
[XCF,lags,bounds] = crosscorr(x,y);
bounds
bounds = 2×1

0.2000
-0.2000

crosscorr(x,y)

bounds displays the upper and lower confidence bounds, which are the horizontal lines in the XCF plot. As you should expect, XCF peaks at lag 4.

Specify the AR(1) model for the first series:

${y}_{1t}=2+0.3{y}_{1t-1}+{\epsilon }_{t},$

where ${\epsilon }_{t}$ is Gaussian with mean 0 and variance 1.

MdlY1 = arima('AR',0.3,'Constant',2,'Variance',1);

Simulate data from Mdl.

rng(1);
T = 1000;
y1 = simulate(MdlY1,T);

Simulate data for the second series by inducing correlation at lag 36.

y2 = [randn(36,1);y1(1:end-36)+randn(T-36,1)*0.1];

Plot the XCF using the default settings.

figure
crosscorr(y1,y2,'NumSTD',3)

The plot does not indicate significant cross-correlation between the two series.

Plot the XCF for 60 lags on either side of lag 0.

figure
crosscorr(y1,y2,'NumLags',60,'NumSTD',3)

The plot shows significant correlation at lag 36, as expected.

## Input Arguments

collapse all

First observed univariate time series for which MATLAB estimates or plots the XCF, specified as a numeric vector. The last element of y1 contains the latest observation.

Data Types: double

Second observed univariate time series for which MATLAB estimates or plots the XCF, specified as a numeric vector. The last element of y2 contains the latest observation.

Data Types: double

Axes on which to plot, specified as an Axes object.

By default, crosscorr plots to the current axes (gca).

### Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: crosscorr(y1,y2,'NumLags',10,'NumSTD',2) plots the sample cross correlation between y1 and y2 for the lags -10 to 10 and displays confidence bounds consisting of 2 standard errors.

Number of lags in the sample XCF, specified as the comma-separated pair consisting of 'NumLags' and a positive integer. crosscorr uses lags 0,±1,±2,…,±NumLags to estimate the XCF.

The default is min([20,min(T1,T2) – 1), where T1 and T2 are the effective sample sizes of y1 and y2.

Example: crosscorr(y,'NumLags',10) plots the sample XCF of y1 and y2 for lags – 10 through 10.

Data Types: double

Number of standard errors in the confidence bounds, specified as the comma-separated pair consisting of 'NumSTD' and a nonnegative scalar. The confidence bounds are 0 ±NumSTD*$\stackrel{^}{\sigma }$, where $\stackrel{^}{\sigma }$ is the estimated standard error of the sample cross-correlation between y1 and y2 assuming the series are uncorrelated.

The default yields approximate 95% confidence bounds.

Example: crosscorr(y,'NumSTD',1.5) plots the XCF of y1 and y2 with confidence bounds 1.5 standard errors away from 0.

Data Types: double

## Output Arguments

collapse all

Sample XCF between the univariate time series y1 and y2, returned as a numeric vector of length 2*NumLags + 1.

The elements of xcf correspond to the elements of lags. The center element is the lag 0 cross-correlation.

Lag numbers used for XCF estimation, returned as the numeric vector (-NumLags):NumLags having the same orientation as y1.

Approximate upper and lower cross-correlation confidence bounds assuming y1 and y2 are uncorrelated, returned as a two-element numeric vector.

Handles to plotted graphics objects, returned as a graphics array. h contains unique plot identifiers, which you can use to query or modify properties of the plot.

collapse all

### Cross-Correlation Function

The cross-correlation function measures the similarity between a time series and lagged versions of another time series as a function of the lag.

XCF starts with the estimation of the sample cross-covariance function. Consider the time series y1t and y2t and lags k = 0, ±1, ±2,…. For data pairs (y11,y21), (y12,y22),...,(y1T,y2T), an estimate of the lag k cross-covariance is

${c}_{{y}_{1}{y}_{2}}\left(k\right)=\left\{\begin{array}{c}\frac{1}{T}\sum _{t=1}^{T-k}\left({y}_{1t}-{\overline{y}}_{1}\right)\left({y}_{2,t+k}-{\overline{y}}_{2}\right);\text{\hspace{0.17em}}k=0,1,2,\dots \\ \frac{1}{T}\sum _{t=1}^{T+k}\left({y}_{2t}-{\overline{y}}_{2}\right)\left({y}_{1,t-k}-{\overline{y}}_{1}\right);\text{\hspace{0.17em}}k=0,-1,-2,\dots \end{array},$

where ${\overline{y}}_{1}$ and ${\overline{y}}_{2}$ are the sample means of the series.

The sample standard deviations of the series are:

• ${s}_{{y}_{1}}=\sqrt{{c}_{{y}_{1}{y}_{1}}\left(0\right)},$ where ${c}_{{y}_{1}{y}_{1}}\left(0\right)=Var\left({y}_{1}\right).$

• ${s}_{{y}_{2}}=\sqrt{{c}_{{y}_{2}{y}_{2}}\left(0\right)},$ where ${c}_{{y}_{2}{y}_{2}}\left(0\right)=Var\left({y}_{2}\right).$

An estimate of the cross-correlation is

${r}_{{y}_{1}{y}_{2}}\left(k\right)=\frac{{c}_{{y}_{1}{y}_{2}}\left(k\right)}{{s}_{{y}_{1}}{s}_{{y}_{2}}};\text{\hspace{0.17em}}k=0,±1,±2,\dots \text{.}$

## Algorithms

• If y1 and y2 have different lengths, then MATLAB appends enough zeros to the end of the shorter vector to make both vectors the same size.

• crosscorr uses a Fourier transform to compute the XCF in the frequency domain, then converts back to the time domain using an inverse Fourier transform.

• crosscorr plots the XCF when you do not request any output or when you request the fourth output.

## References

[1] Box, G. E. P., G. M. Jenkins, and G. C. Reinsel. Time Series Analysis: Forecasting and Control. 3rd ed. Englewood Cliffs, NJ: Prentice Hall, 1994.