xcov

R2026b

Cross-covariance

Syntax

c = xcov(x,y)

c = xcov(x)

c = xcov(___,maxlag)

c = xcov(___,scaleopt)

c = xcov(___,LagSelection=range)

[c,lags] = xcov(___)

Description

c = xcov(x,y) returns the cross-covariance of two discrete-time sequences. Cross-covariance measures the similarity between a vector x and shifted (lagged) copies of a vector y as a function of the lag. If x and y have different lengths, the function appends zeros to the end of the shorter vector so it has the same length as the other.

c = xcov(x) returns the autocovariance sequence of x. If x is a matrix, then c is a matrix whose columns contain the autocovariance and cross-covariance sequences for all combinations of the columns of x.

c = xcov(___,maxlag) sets the lag range from -maxlag to maxlag for either of the previous syntaxes.

c = xcov(___,scaleopt) also specifies a normalization option for the cross-covariance or autocovariance. Any option other than "none" (the default) requires the inputs x and y to have the same length.

c = xcov(___,LagSelection=range) specifies whether to return the cross-covariance for only nonnegative lags, only nonpositive lags, or all lags. (since R2026b)

[c,lags] = xcov(___) also returns the lags at which the covariances are computed.

Examples

Cross-Covariance of Two Random Vectors

Create a vector of random numbers x and a vector y that is equal to x shifted by 3 elements to the right. Compute and plot the estimated cross-covariance of x and y. The largest spike occurs at the lag value when the elements of x and y match exactly (-3).

rng default
x = rand(20,1);
y = circshift(x,3);
[c,lags] = xcov(x,y);
stem(lags,c)

Autocovariance of Random Vector

Create a 20-by-1 random vector, then compute and plot the estimated autocovariance. The largest spike occurs at zero lag, where the vector is exactly equal to itself.

rng default
x = rand(20,1);
[c,lags] = xcov(x);
stem(lags,c)

Normalized Autocovariance of Noise

Compute and plot the estimated autocovariance of white Gaussian noise, $$c(m)$$, for $$-10\le m\le 10$$. Normalize the sequence so that it is unity at zero lag.

rng default
x = randn(1000,1);
maxlag = 10;
[c,lags] = xcov(x,maxlag,'normalized');
stem(lags,c)

Biased Cross-Covariance of Two Shifted Signals

Create a signal made up of two signals that are circularly shifted from each other by 50 samples.

rng default
shft = 50;
s1 = rand(150,1);
s2 = circshift(s1,[shft 0]);
x = [s1 s2];

Compute and plot biased estimates of the autocovariance and mutual cross-covariance sequences. The output matrix c is organized as four column vectors such that $$c=\left(\begin{array}{cccc}{c}_{s_1{s}_1}& c_{s_1{s}_2}& c_{s_2{s}_1}& c_{s_2{s}_2}\end{array}\right)$$. $c_{s_1{s}_2}$ has maxima at -50 and +100 and $c_{s_2{s}_1}$ has maxima at +50 and -100 as a result of the circular shift.

[c,lags] = xcov(x,'biased');
plot(lags,c)
legend('c_{s_1s_1}','c_{s_1s_2}','c_{s_2s_1}','c_{s_2s_2}')

Return Only Nonpositive Lags

Create two signals that each record an event at different times. The signals have different means, but cross-covariance removes the signal means, so it can detect the time delay between the events.

x = [11 10 10 10 10];
y = [2 2 2 3 2];

In the cross-covariance of x and y, a negative lag means y is delayed relative to x, and a positive lag means x is delayed relative to y.

If you know that the event in y occurs later than in x, the peak cross-covariance must be at a negative lag. Specify LagSelection="nonpositive" to return only the nonpositive lags.

[c,lags] = xcov(x,y,LagSelection="nonpositive")

c = 1×5

   -0.1600    0.6800   -0.2800   -0.2400   -0.2000

lags = 1×5

    -4    -3    -2    -1     0

Determine the delay between the events in x and y by finding the lag at the peak of the cross-covariance. The result indicates that the event in y occurs 3 samples after the event in x.

[~,idx] = max(c);
delay = lags(idx)

delay = 
-3

Input Arguments

x — Input array

vector | matrix | multidimensional array

Input array, specified as a vector, matrix, or multidimensional array. If x is a multidimensional array, then xcov operates column-wise across all dimensions and returns each autocovariance and cross-covariance as the columns of a matrix.

The input array x can be a sparse matrix or vector of type double or single. (since R2026b)

Data Types: double | single
Complex Number Support: Yes

y — Input array

vector

Input array, specified as a vector.

The input array y can be a sparse vector of type double or single. (since R2026b)

Data Types: double | single
Complex Number Support: Yes

maxlag — Maximum lag

integer scalar

Maximum lag, specified as an integer scalar. The maximum lag is the farthest number of samples that xcov shifts one input sequence relative to the other. If you specify maxlag, xcov computes the cross-covariance for lags from -maxlag to maxlag. If you do not specify maxlag, the default maximum lag is N - 1, where N is the greater of the lengths of x and y, and xcov computes the cross-covariance for lags from -(N - 1) to N - 1.

Data Types: single | double

scaleopt — Normalization option

"none" (default) | "biased" | "unbiased" | "normalized" | "coeff"

Normalization option, specified as one of the following.

• "none" — Raw, unscaled cross-covariance. "none" is the only valid option when inputs x and y have different lengths.

• "biased" — Biased estimate of the cross-covariance.

• "unbiased" — Unbiased estimate of the cross-covariance.

• "normalized" or "coeff" — Normalizes the sequence so that the autocovariances at zero lag equal 1.

range — Selection of lags to include in output

"all" (default) | "nonnegative" | "nonpositive"

Since R2026b

Selection of lags to include in the output, specified as one of these values:

• "all" — Return the cross-covariance for all lags from -maxlag to maxlag.

• "nonnegative" — Return the cross-covariance for nonnegative lags only, from 0 to maxlag.

• "nonpositive" — Return the cross-covariance for nonpositive lags only, from -maxlag to 0.

Output Arguments

c — Cross-covariance or autocovariance

vector | matrix

Cross-covariance or autocovariance, returned as a vector or matrix.

If x is an M × N matrix, then xcov(x) returns a (2M – 1) × N² matrix with the autocovariances and cross-covariances of the columns of x. If you specify a maximum lag maxlag, then the output c has size (2 × maxlag + 1) × N².

If you specify LagSelection as "nonnegative" or "nonpositive", then c has maxlag + 1 rows instead of 2 x maxlag + 1 rows.

For example, if S has three columns, $$\text{S}=\left(\begin{array}{ccc}{x}_1& x_2& x_3\end{array}\right)$$, then the result of C = xcov(S) is organized as

$$\text{c}=\left(\begin{array}{lllllllll}{c}_{x_1{x}_1}\hfill & c_{x_1{x}_2}\hfill & c_{x_1{x}_3}\hfill & c_{x_2{x}_1}\hfill & c_{x_2{x}_2}\hfill & c_{x_2{x}_3}\hfill & c_{x_3{x}_1}\hfill & c_{x_3{x}_2}\hfill & c_{x_3{x}_3}\hfill \end{array}\right).$$

lags — Lag indices

vector

Lag indices, returned as a vector.

More About

Cross-Covariance and Autocovariance

xcov computes the mean of its inputs, subtracts the mean, and then calls xcorr.

The result of xcov can be interpreted as an estimate of the covariance between two random sequences or as the deterministic covariance between two deterministic signals.

The true cross-covariance sequence of two jointly stationary random processes, x_n and y_n, is the cross-correlation of mean-removed sequences,

$${\varphi }_{xy}(m)=E\{(x_{n+m}-{\mu }_x){(y_n-{\mu }_y)}^{\ast })\},$$

where μ_x and μ_y are the mean values of the two stationary random processes, the asterisk denotes complex conjugation, and E is the expected value operator. xcov can only estimate the sequence because, in practice, only a finite segment of one realization of the infinite-length random process is available.

By default, xcov computes raw covariances with no normalization:

$$c_{xy}(m)=\{\begin{array}{ll}{\displaystyle \sum _{n=0}^{N-m-1}\left(x_{n+m}-\frac{1}{N}{\displaystyle \sum _{i=0}^{N-1}{x}_i}\right)\left(y_n^{\ast }-\frac{1}{N}{\displaystyle \sum _{i=0}^{N-1}{y}_i^{\ast }}\right),}\hfill & m\ge 0,\hfill \\ c_{yx}^{\ast }(-m),\hfill & m<0.\hfill \end{array}$$

The output vector c has elements given by

$$\text{c(m)}=c_{xy}(m-N),m=1,\dots ,2N-1.$$

The covariance function requires normalization to estimate the function properly. You can control the normalization of the correlation by using the input argument scaleopt.

References

[1] Orfanidis, Sophocles J. Optimum Signal Processing: An Introduction. 2nd Edition. New York: McGraw-Hill, 1996.

[2] Larsen, Jan. “Correlation Functions and Power Spectra.” November, 2009. https://www2.imm.dtu.dk/pubdb/edoc/imm4932.pdf

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The xcov function supports tall arrays with the following usage notes and limitations:

• The x input must be a tall column vector.

• The y input must be a non-tall vector.

• The syntax xcov(x) is not supported.

• The scaleopt option is not supported.

• If you specify maxlag, then it must satisfy maxlag <= max(numel(x),numel(y))-1.

• The lags output is returned as a tall column vector.

For more information, see Tall Arrays.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The xcov function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The xcov function supports GPU array input with these usage notes and limitations:

• Sparse gpuArray input is not supported.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2026b: Select nonnegative or nonpositive lags

Return the cross-covariance for only nonnegative or nonpositive lags by specifying the LagSelection name-value argument.

R2026b: Compute cross-covariance using sparse inputs

The xcov function now supports sparse inputs. You can compute cross-covariance using sparse inputs to significantly reduce memory usage and improve processing performance when the inputs contain many elements that are zero.

R2019a: Moved to MATLAB from Signal Processing Toolbox

Previously, xcov required Signal Processing Toolbox™.