xcorr {gsignal}

Cross-correlation

Description

Estimate the cross-correlation between two sequences or the autocorrelation of a single sequence

Usage

xcorr(
  x,
  y = NULL,
  maxlag = if (is.matrix(x)) nrow(x) - 1 else max(length(x), length(y)) - 1,
  scale = c("none", "biased", "unbiased", "coeff")
)

Arguments

x

Input, numeric or complex vector or matrix. Must not be missing.

y

Input, numeric or complex vector data. If x is a matrix (not a vector), y must be omitted. y may be omitted if x is a vector; in this case xcorr estimates the autocorrelation of x.

maxlag

Integer scalar. Maximum correlation lag. If omitted, the default value is N-1, where N is the greater of the lengths of x and y or, if x is a matrix, the number of rows in x.

scale

Character string. Specifies the type of scaling applied to the correlation vector (or matrix). matched to one of:

"none"

return the unscaled correlation, R

"biased"

return the biased average, R / N

"unbiased"

return the unbiased average, R(k) / (N - |k|)

"coeff"

return the correlation coefficient, R / (rms(x) . rms(y))

, where k is the lag, and N is the length of x If omitted, the default value is "none". If y is supplied but does not have the same length as x, scale must be "none".

Details

Estimate the cross correlation R_xy(k) of vector arguments x and y or, if y is omitted, estimate autocorrelation R_xx(k) of vector x, for a range of lags k specified by the argument maxlag. If x is a matrix, each column of x is correlated with itself and every other column.

The cross-correlation estimate between vectors x and y (of length N) for lag k is given by

            N
     Rxy = SUM x(i+k) . Conj(y(i))
           i=1

where data not provided (for example x[-1], y[N+1]) is zero. Note the definition of cross-correlation given above. To compute a cross-correlation consistent with the field of statistics, see xcov.

The cross-correlation estimate is calculated by a "spectral" method in which the FFT of the first vector is multiplied element-by-element with the FFT of second vector. The computational effort depends on the length N of the vectors and is independent of the number of lags requested. If you only need a few lags, the "direct sum" method may be faster.

Value

A list containing the following variables:

R

array of correlation estimates

lags

vector of correlation lags [-maxlag:maxlag]

The array of correlation estimates has one of the following forms:

1. Cross-correlation estimate if X and Y are vectors.

2. Autocorrelation estimate if is a vector and Y is omitted.

3. If x is a matrix, R is a matrix containing the cross-correlation estimate of each column with every other column. Lag varies with the first index so that R has 2 * maxlag + 1 rows and P^2 columns where P is the number of columns in x.

Author(s)

Paul Kienzle, [e-mail],
Asbjorn Sabo, [e-mail],
Peter Lanspeary. [e-mail].
Conversion to R by Geert van Boxtel, [e-mail].

See Also

xcov.

Examples

## Create a vector x and a vector y that is equal to x shifted by 5
## elements to the right. Compute and plot the estimated cross-correlation
## of x and y. The largest spike occurs at the lag value when the elements
## of x and y match exactly (-5).
n <- 0:15
x <- 0.84^n
y <- pracma::circshift(x, 5)
rl <- xcorr(x, y)
plot(rl$lag, rl$R, type="h")

## Compute and plot the estimated autocorrelation of a vector x.
## The largest spike occurs at zero lag, when x matches itself exactly.
n <- 0:15
x <- 0.84^n
rl <- xcorr(x)
plot(rl$lag, rl$R, type="h")

## Compute and plot the normalized cross-correlation of vectors
## x and y with unity peak, and specify a maximum lag of 10.
n <- 0:15
x <- 0.84^n
y <- pracma::circshift(x, 5)
rl <- xcorr(x, y, 10, 'coeff')
plot(rl$lag, rl$R, type="h")