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) and associated lags between two input vectors of univariate time series data.

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

[___,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 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

Since R2022a

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

Since R2022a

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

Since R2022a

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

Since R2022a

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

Since R2022a

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

Since R2022a

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

R2024b: Optional positional inputs are removed and issue errors

When you use the optional positional inputs of crosscorr to specify the number of lags in the cross-correlation or number of standard errors in the confidence bounds, MATLAB^® issues an error stating that the syntaxes are removed. To avoid the error, replace the optional positional inputs by using the Name=Value argument syntax.

These syntaxes specify optional positional inputs and issue an error.

crosscorr(y1,y2,numLags)
crosscorr(y1,y2,numLags,numSTD)

This syntax is its replacement.

crosscorr(y1,y2,NumLags=numLags,NumSTD=numSTD)

R2024a: Optional positional inputs are being removed and issue warnings

When you use the optional positional inputs of crosscorr to specify the number of lags in the cross-correlation or number of standard errors in the confidence bounds, MATLAB issues a warning stating that the syntax will be removed. To avoid the warning, replace the optional positional inputs by using the Name=Value argument syntax.

These syntaxes specify optional positional inputs and issue a warning.

crosscorr(y1,y2,numLags)
crosscorr(y1,y2,numLags,numSTD)

This syntax is its replacement.

crosscorr(y1,y2,NumLags=numLags,NumSTD=numSTD)

R2023b: Optional positional inputs are being removed

The optional positional inputs of crosscorr that specify the number of lags in the cross-correlation or number of standard errors in the confidence bounds will be removed. To replace the optional positional inputs, use the Name=Value argument syntax.

These syntaxes specify optional positional inputs and are being removed.

crosscorr(y1,y2,numLags)
crosscorr(y1,y2,numLags,numSTD)

This syntax is its replacement.

crosscorr(y1,y2,NumLags=numLags,NumSTD=numSTD)

R2022a: crosscorr accepts input data in tables and timetables, and returns results in tables

In addition to accepting input data in numeric arrays, crosscorr accepts input data in tables and timetables. When you supply data in a table or timetable, the following conditions apply:

• crosscorr chooses default series on which to operate, but you can use the DataVariables name-value argument to select variables.

• crosscorr returns results in tables or timetables.

R2018a: Supply or return graphics object handles

crosscorr accepts a graphics handle in which to plot and returns handles to plotted graphics objects.

R2018a: crosscorr supports name-value argument syntax for all optional inputs

Instead of using the optional positional inputs of crosscorr that specify the number of lags in the cross-correlation or number of standard errors in the confidence bounds, use name-value argument syntax.

These syntaxes specify optional positional inputs before R2018a.

crosscorr(y1,y2,numLags)
crosscorr(y1,y2,numLags,numSTD)

This syntax is its recommended replacement for R2018a and later releases.

crosscorr(y1,y2,'NumLags',numLags,'NumSTD',numSTD)

There is no plan to remove the optional positional syntaxes.