# mscohere

Magnitude-squared coherence

## Syntax

`Cxy = mscohere(x,y)Cxy = mscohere(x,y,window)Cxy = mscohere(x,y,window,noverlap)[Cxy,W] = mscohere(x,y,window,noverlap,nfft)[Cxy,F] = mscohere(x,y,window,noverlap,nfft,fs)[Cxy,F] = mscohere(x,y,window,noverlap,f,fs)[...] = mscohere(x,y,...,'twosided')mscohere(...)`

## Description

`Cxy = mscohere(x,y)` finds the magnitude-squared coherence estimate, `Cxy`, of the input signals, `x` and `y`, using Welch's averaged modified periodogram method.

The input signals may be either vectors or two-dimensional matrices. If both are vectors, they must have the same length. If both are matrices, they must have the same size, and `mscohere` operates columnwise: `Cxy(:,n) = mscohere(x(:,n),y(:,n))`. If one is a matrix and the other is a vector, then the vector is converted to a column vector and internally expanded so both inputs have the same number of columns.

For real `x` and `y`, `mscohere` returns a one-sided coherence estimate. For complex `x` or `y`, it returns a two-sided estimate.

`mscohere` uses the following default values:

ParameterDescriptionDefault Value

`nfft`

FFT length which determines the frequencies at which the coherence is estimated

For real `x` and `y`, the length of `Cxy` is (`nfft`/2 + 1) if `nfft` is even or (`nfft` + 1)/2 if `nfft` is odd. For complex `x` or `y`, the length of `Cxy` is `nfft`.

If `nfft` is greater than the signal length, the data is zero-padded. If `nfft` is less than the signal length, the data segment is wrapped so that the length is equal to `nfft`.

Maximum of 256 or the next power of 2 greater than the length of each section of `x` or `y`

`fs`

Sampling frequency

1

`window`

Windowing function and number of samples to use for each section

Periodic Hamming window of sufficient length to obtain eight equal sections of x and `y`

`noverlap`

Number of samples by which the sections overlap

Value to obtain 50% overlap

 Note   You can use the empty matrix, `[]`, to specify the default value for any input argument except `x` or `y`. For example, `Pxy = mscohere(x,y,[],[],128)` uses a Hamming window, default `noverlap` to obtain 50% overlap, and the specified 128 `nfft`.

`Cxy = mscohere(x,y,window)` specifies a windowing function, divides `x` and `y` into equal overlapping sections of the specified window length, and windows each section using the specified window function. If you supply a scalar for `window`, then `Cxy` uses a Hamming window of that length.

`Cxy = mscohere(x,y,window,noverlap)` overlaps the sections of `x` by `noverlap` samples. `noverlap` must be an integer smaller than the length of `window`.

`[Cxy,W] = mscohere(x,y,window,noverlap,nfft)` uses the specified FFT length `nfft` to calculate the coherence estimate. It also returns `W`, which is the vector of normalized frequencies (in rad/sample) at which the coherence is estimated. For real `x` and `y`, `Cxy` length is (`nfft`/2 + 1) if `nfft` is even; if `nfft` is odd, the length is (`nfft` + 1)/2. For complex `x` or `y`, the length of `Cxy` is `nfft`. For real signals, the range of `W` is [0, π] when `nfft` is even and [0, π) when `nfft` is odd. For complex signals, the range of `W` is [0, 2π).

`[Cxy,F] = mscohere(x,y,window,noverlap,nfft,fs)` returns `Cxy` as a function of frequency and a vector `F` of frequencies at which the coherence is estimated. `fs` is the sampling frequency in Hz. For real signals, the range of `F` is [0, `fs`/2] when `nfft` is even and [0, `fs`/2) when `nfft` is odd. For complex signals, the range of `F` is [0, `fs`).

`[Cxy,F] = mscohere(x,y,window,noverlap,f,fs)` computes the coherence estimate at the frequencies `f`. `f` is a vector containing two or more elements.

`[...] = mscohere(x,y,...,'twosided')` returns a coherence estimate with frequencies that range over the whole Nyquist interval. Specifying `'onesided'` uses half the Nyquist interval.

`mscohere(...)` plots the magnitude-squared coherence versus frequency in the current figure window.

 Note   If you estimate the magnitude-squared coherence with a single window, or section, the value is identically 1 for all frequencies [1]. You must use at least two sections.

## Examples

collapse all

### Coherence Estimate of Two Sequences

Compute and plot the coherence estimate between two colored noise sequences, `x` and `y`. Reset the random number generator for reproducible results. Use a Hann window to estimate the coherence.

```rng default r = randn(16384,1); h1 = ones(1,10)/sqrt(10); x = filter(h1,1,r); h = fir1(30,0.2,rectwin(31)); y = filter(h,1,x); mscohere(x,y,hanning(1024),512,1024) ```

### Modify `mscohere` Default Plot

Generate two sinusoidal signals sampled for 1 second each at 1 kHz. Each sinusoid has a frequency of 250 Hz. One of the signals lags the other in phase by π/3 radians. Embed both signals in white Gaussian noise of unit variance. Reset the random number generator for reproducible results.

```rng default fs = 1000; f = 250; t = 0:1/fs:1-1/fs; um = sin(2*pi*f*t)+rand(size(t)); un = sin(2*pi*f*t-pi/3)+rand(size(t)); ```

Use `mscohere` to compute and plot the magnitude-squared coherence of the signals.

```mscohere(um,un,[],[],[],fs) ```

Modify the title of the plot, the label of the x-axis, and the limits of the y-axis.

```title('Magnitude-Squared Coherence') xlabel('f (Hz)') ylim([0 1.1]) ```

Use `gca` to obtain a handle to the current axes. Change the locations of the tick marks. Remove the label of the y-axis.

```ax = gca; ax.XTick = 0:250:500; ax.YTick = 0:0.25:1; ax.YLabel.String = []; ```

Invoke the `Children` property of the handle to change the color and width of the plotted line.

```ln = ax.Children; ln.Color = [0.8 0 0]; ln.LineWidth = 1.5; ```

Alternatively, use `set` and `get` to modify the line properties.

```set(get(gca,'Children'),'Color',[0 0.4 0],'LineStyle','--','LineWidth',1) ```

collapse all

### Magnitude-Squared Coherence

The magnitude-squared coherence estimate is a function of frequency with values between 0 and 1 that indicates how well `x` corresponds to `y` at each frequency. The magnitude-squared coherence is a function of the power spectral densities, Pxx(f) and Pyy(f), of `x` and `y`, and the cross power spectral density, Pxy(f), of `x` and `y`:

`${C}_{xy}\left(f\right)=\frac{{|{P}_{xy}\left(f\right)|}^{2}}{{P}_{xx}\left(f\right){P}_{yy}\left(f\right)}.$`

### Algorithms

`mscohere` estimates the magnitude-squared coherence function [2] using Welch's overlapped averaged periodogram method (see references [3] and [4]).

## References

[1] Stoica, Petre, and Randolph Moses. Spectral Analysis of Signals. Upper Saddle River, NJ: Prentice Hall, 2005.

[2] Kay, Steven M. Modern Spectral Estimation. Englewood Cliffs, NJ: Prentice-Hall, 1988.

[3] Rabiner, Lawrence R., and Bernard Gold. Theory and Application of Digital Signal Processing. Englewood Cliffs, NJ: Prentice-Hall, 1975.

[4] Welch, Peter D. "The Use of Fast Fourier Transform for the Estimation of Power Spectra: A Method Based on Time Averaging Over Short, Modified Periodograms." IEEE® Transactions on Audio and Electroacoustics. Vol. AU-15, 1967, pp. 70–73.