crosscorr

Sample cross-correlation

Syntax

[xcf,lags] = crosscorr(y1,y2)

XCFTbl = crosscorr(Tbl)

[___,bounds] = crosscorr(___)

[___] = crosscorr(___,Name=Value)

crosscorr(___)

crosscorr(ax,___)

[___,h] = crosscorr(___)

Description

[xcf,lags] = crosscorr(y1,y2) returns the sample cross-correlation function (XCF) xcf and associated lags lags between the univariate time series y1 and y2.

XCFTbl = crosscorr(Tbl) returns the table XCFTbl containing variables for the sample XCF and associated lags of the last two variables in the input table or timetable Tbl. To select different variables in Tbl, for which to compute the XCF, use the DataVariables name-value argument.

[___,bounds] = crosscorr(___) uses any input-argument combination in the previous syntaxes, and returns the output-argument combination for the corresponding input arguments and the approximate upper and lower confidence bounds bounds on the XCF.

[___] = crosscorr(___,Name=Value) uses additional options specified by one or more name-value arguments. For example, crosscorr(Tbl,DataVariables=["RGDP" "CPI"],NumLags=10,NumSTD=1.96) returns the sample XCF for lags -10 through 10 of the table variables "RGDP" and "CPI" in Tbl and 95% confidence bounds.

crosscorr(___) plots the sample XCF between the input series with 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.

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

Examples

Compute XCF Between Vectors of Time Series Data

Compute the XCF between two univariate time series. Input the time series data as numeric vectors.

Load the equity index data Data_EquityIdx.mat. The variable Data is a 3028-by-2 matrix of daily closing prices from the NASDAQ and NYSE composite indices. Plot the two series.

load Data_EquityIdx

yyaxis left
dt = datetime(dates,ConvertFrom="datenum");
plot(dt,Data(:,1))
ylabel("NASDAQ")
yyaxis right
plot(dt,Data(:,2))
ylabel("NYSE")
title("Daily Closing Prices, 1990-2001")

The series exhibit exponential growth.

Compute the returns of each series.

Ret = price2ret(Data);

Ret is a 3027-by-2 series of returns; it has one less observation than Data.

Compute the XCF between the NASDAQ and NYSE returns, and return the associated lags.

rnasdaq = Ret(:,1);
rnyse = Ret(:,2);
[xcf,lags] = crosscorr(rnasdaq,rnyse);

xcf and lags are 41-by-1 vectors that describe the XCF.

Display several values of the XCF.

XCF = [xcf lags];
XCF([1:3 20:22 end-2:end],:)

ans = 9×2

   -0.0108  -20.0000
    0.0186  -19.0000
   -0.0002  -18.0000
    0.0345   -1.0000
    0.7080         0
    0.0651    1.0000
   -0.0461   18.0000
    0.0010   19.0000
    0.0015   20.0000

The correlation between the current NASDAQ return and the NYSE return from 20 days before is xcf(1) = -0.0108. The correlation between the NASDAQ and NYSE returns is xcf(21) = 0.7080. The correlation between the NASDAQ return from 20 days ago and the current NYSE return is xcf(41) = 0.0015.

Compute XCF of Table Variable

Compute the XCF between two univariate time series, which are two variables in a table.

Load the equity index data Data_EquityIdx.mat. The variable DataTable is a 3028-by-2 table of daily closing prices from the NYSE and NASDAQ composite indices, which are stored in the variables NYSE and NASDAQ.

load Data_EquityIdx
DataTable.Properties.VariableNames

ans = 1x2 cell
    {'NYSE'}    {'NASDAQ'}

Compute the returns of the series. Store the results in a new table.

RetTbl = price2ret(DataTable);
head(RetTbl)

    Tick    Interval       NYSE         NASDAQ  
    ____    ________    __________    __________

     2         1        -0.0010106     0.0034122
     3         1        -0.0076633    -0.0032816
     4         1        -0.0084415    -0.0025501
     5         1         0.0035387     0.0010688
     6         1         -0.010188    -0.0042382
     7         1        -0.0063818     -0.013378
     8         1         0.0034295    -0.0040909
     9         1         -0.023407     -0.020573

RetTbl is a 3027-by-4 table containing the returns of the indices, ticks (days by default), and time intervals between successive prices.

Compute the XCF between the NASDAQ and NYSE return series.

XCFTbl = crosscorr(RetTbl)

XCFTbl=41×2 table
    Lags        XCF    
    ____    ___________

    -20       -0.010809
    -19        0.018571
    -18     -0.00016185
    -17       -0.020271
    -16       -0.029353
    -15      0.00023188
    -14      -0.0080616
    -13        0.041498
    -12        0.078821
    -11       -0.013793
    -10       0.0076655
     -9         0.01763
     -8      -0.0011033
     -7       -0.011457
     -6       -0.016523
     -5       -0.046749
      ⋮

crosscorr returns the results in the table XCFTbl, where variables correspond to the XCF (XCF) and associated lags (Lags).

By default, crosscorr computes the XCF of the two variables in the table. To select variables from an input table, set the DataVariables option.

Return XCF Confidence Bounds

Consider the equity index series in Compute XCF of Table Variable.

Load the NYSE and NASDAQ closing price series in Data_EquityIdx.mat and preprocess the series. Compute the XCF and return the XCF confidence bounds.

load Data_EquityIdx
RetTbl = price2ret(DataTable);
[XCFTbl,bounds] = crosscorr(RetTbl)

XCFTbl=41×2 table
    Lags        XCF    
    ____    ___________

    -20       -0.010809
    -19        0.018571
    -18     -0.00016185
    -17       -0.020271
    -16       -0.029353
    -15      0.00023188
    -14      -0.0080616
    -13        0.041498
    -12        0.078821
    -11       -0.013793
    -10       0.0076655
     -9         0.01763
     -8      -0.0011033
     -7       -0.011457
     -6       -0.016523
     -5       -0.046749
      ⋮

bounds = 2×1

    0.0364
   -0.0364

Assuming the NYSE and NASDAQ return series are uncorrelated, an approximate 95.4% confidence interval on the XCF is (-0.0364, 0.0364).

Plot the XCF

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

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

Create a 4-period delayed version of x.

y = lagmatrix(x,4);

Plot the XCF between x and y. Because lagmatrix prepends lagged series with NaN values and crosscorr does not support NaN values, start the series at observation 5.

crosscorr(x(5:end),y(5:end))

The upper and lower confidence bounds are the horizontal lines in the XCF plot. By design, the XCF peaks at lag 4.

Select Table Variables for XCF Plot

Load the currency exchange rates data set Data_FXRates.mat. The table DataTable contains daily exchange rates of several countries, relative to the US dollar from 1980 through 1998 (with omissions).

load Data_FXRates.mat
dt = datetime(dates,ConvertFrom="datenum");

Plot the UK pound and French franc exchange rates.

yyaxis left
plot(dt,DataTable.GBP)
ylabel("UK Pound/$")
yyaxis right
plot(dt,DataTable.FRF)
ylabel("French Franc/$")

The series appear to be correlated.

Stabilize all series in the table by computing the first difference.

DiffDT = varfun(@diff,DataTable);
DiffDT.Properties.VariableNames = DataTable.Properties.VariableNames;

Determine whether lags of one series are associated with the other series by computing the XCF between the daily changes in the UK pound and French franc exchange rates.

figure
crosscorr(DiffDT,DataVariables=["GBP" "FRF"]);

The series have a high contemporaneous correlation, but all other cross-correlations are either insignificant or below 0.1.

Specify Additional XCF Lags

Specify the AR(1) model for the first series

$$y_{1t}=2+0.3y_{1t-1}+{\epsilon }_t,$$

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

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

MdlY1 is a fully specified arima object representing the AR(1) model.

Simulate data from the AR(1) model.

rng(3); % For reproducibility
T = 1000;
y1 = simulate(MdlY1,T);

Simulate standard Gaussian variates for the second series; induce correlation at lag 36.

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

Plot the XCF by using the default settings.

crosscorr(y1,y2)

All correlations in the plot are within the 2-standard-error confidence bounds. Therefore, none are significant.

Plot the XCF for 60 lags on both sides of lag 0. Specify 3 standard errors for the confidence bounds.

crosscorr(y1,y2,NumLags=60,NumSTD=3)

The plot shows significant correlations at and around lag 36.

Input Arguments

y1 — Univariate time series data

numeric vector

Univariate time series data, specified as a numeric vector of length T₁.

Data Types: double

y2 — Univariate time series data

numeric vector

Univariate time series data, specified as a numeric vector of length T₂.

Data Types: double

Tbl — Time series data

table | timetable

Time series data, specified as a table or timetable with T rows. Each row of Tbl contains contemporaneous observations of all variables.

Specify the two input series (variables) by using the DataVariables argument. The selected variables must be numeric.

ax — Axes on which to plot

Axes object

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

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

Note

Missing observations, specified by NaN entries in the input series, result in a NaN-valued XCF.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: crosscorr(Tbl,DataVariables=["RGDP" "CPI"],NumLags=10,NumSTD=1.96) returns the sample XCF for lags -10 through 10 of the table variables "RGDP" and "CPI" in Tbl and 95% confidence bounds.

NumLags — Number of lags

positive integer

Number of lags in the sample XCF, specified as a positive integer. crosscorr uses lags 0, ±1, ±2, …, ±NumLags to compute the sample XCF.

If you supply y1 and y2, the default is min(20, min(T₁,T₂) – 1)). If you supply Tbl, the default is min(20, T – 1).

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

Data Types: double

NumSTD — Number of standard errors in confidence bounds

2 (default) | nonnegative scalar

Number of standard errors in the confidence bounds, specified as a nonnegative scalar. The confidence bounds are 0 ± NumSTD*$$\widehat{\sigma }$$, where $$\widehat{\sigma }$$ is the estimated standard error of the sample cross-correlation between the input series assuming the series are uncorrelated.

The default yields approximate 95% confidence bounds.

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

Data Types: double

DataVariables — Two variables in Tbl

last two variables (default) | string vector | cell vector of character vectors | vector of integers | logical vector

Two variables in Tbl for which crosscorr computes the XCF, specified as a string vector or cell vector of character vectors containing two variable names in Tbl.Properties.VariableNames, or an integer or logical vector representing the indices of two names. The selected variables must be numeric.

Example: DataVariables=["GDP" "CPI"]

Example: DataVariables=[true true false false] or DataVariables=[1 2] selects the first and second table variables.

Data Types: double | logical | char | string

Output Arguments

xcf — Sample XCF

numeric vector

Sample XCF between the input time series, 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. crosscorr returns xcf only when you supply the inputs y1 and y2.

lags — XCF lags

numeric vector

XCF lags, returned as a numeric vector with elements (-NumLags):NumLags having the same orientation as y1. crosscorr returns lags only when you supply the inputs y1 and y2.

XCFTbl — Sample XCF

table

Sample XCF, returned as a table with variables for the outputs xcf and lags. crosscorr returns XCFTbl only when you supply the input Tbl.

bounds — Approximate upper and lower XCF confidence bounds

numeric vector

Approximate upper and lower XCF confidence bounds assuming the input series are uncorrelated, returned as a two-element numeric vector. The NumSTD option specifies the number of standard errors from 0 in the confidence bounds.

h — Handles to plotted graphics objects

graphics array

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.

More About

Cross-Correlation Function

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

Consider the time series y_1,t and y_2,t and lags k = 0, ±1, ±2, …. For data pairs (y_1,1,y_2,1), (y_1,2,y_2,2), …, (y_1,T,y_2,T), an estimate of the lag k cross-covariance is

$$c_{y_1{y}_2}(k)=\{\begin{array}{c}\frac{1}{T}{\displaystyle \sum }_{t=1}^{T-k}\left(y_{1,t}-{\overline{y}}_1\right)\left(y_{2,t+k}-{\overline{y}}_2\right);k=0,1,2,\dots \\ \frac{1}{T}{\displaystyle \sum }_{t=1}^{T+k}\left(y_{2,t}-{\overline{y}}_2\right)\left(y_{1,t-k}-{\overline{y}}_1\right);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}(0)},$$ where $$c_{y_1{y}_1}(0)=Var(y_1).$$

• $$s_{y_2}=\sqrt{c_{y_2{y}_2}(0)},$$ where $$c_{y_2{y}_2}(0)=Var(y_2).$$

An estimate of the cross-correlation is

$$r_{y_1{y}_2}(k)=\frac{c_{y_1{y}_2}(k)}{s_{y_1}{s}_{y_2}};k=0,\pm 1,\pm 2,\dots \text{.}$$

Algorithms

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

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

• NaN values in the input series result in NaN values in the output XCF. Unlike autocorr and parcorr, crosscorr does not treat NaN values as missing completely at random. Whereas autocorr and parcorr compute coefficients in the time domain, crosscorr uses fft and ifft to compute coefficients in the frequency domain. Therefore, missing data treatments follow fft and ifft defaults.

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

References

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

Version History

Introduced before R2006a