File Exchange

image thumbnail

Precedence-based cross-correlograms

version 1.16.0.0 (715 KB) by Christopher Hummersone
Calculate cross-correlograms with a wide range of options

2 Downloads

Updated 05 May 2018

GitHub view license on GitHub

NOTE: this function is now available from the IoSR Matlab Toolbox as iosr.auditory.chXcorr.
-------------------------
Calculate cross-correlograms with a wide range of options.
ccg = ch_xcorr(hc_L,hc_R,fs)
ccg = ch_xcorr(hc_L,hc_R,fs,'parameter',value)
[ccg,ic] = ch_xcorr(...)

ccg = ch_xcorr(hc_L,hc_R,fs) cross-correlates the input
2-D matrices hc_L and hc_R over 10ms frame with a
maximum lag of 1ms. It is assumed that the number of
frequency channels is min(size(hc_L)) and hence hc_L and
hc_R can be in either orientation. The
cross-correlograms consist of cross-correlations for
every frame and frequency channel. ccg has dimensions
[lag,frequency,frame]. The function calculates running
cross-correlations for every sample and integrates these
cross-correlations over each frame. The number of
frames frame_count is calculated thus:

frame_count = ...
floor((max(size(hc_L))-maxlag-1)/frame_length);

The underlying cross-correlation algorithm is based on
that proposed by Faller & Merimaa [1]. In this
implmentation, the time constant of the backward
infinite exponential window is given by tau (in
samples).

ccg = ch_xcorr(hc_L,hc_R,fs,'parameter',value) allows a
number of options to be specified. The options are:

({} indicates the default value)

'frame_length' : {round(0.01*fs)} | scalar
The length of frames used to calculate for
integrating cross-correlations.
'noverlap' : {1} | scalar
The number of frames over which to integrate the
cross-correlations. Note that the frame count is
reduced accordingly.
'maxlag' : {round(0.001*fs)} | scalar
The maximum lag of the cross-correlation.
'tau' : {round(0.01*fs)} | scalar
The time constant of the exponential window used to
calculate running cross-correlations.
'inhib' : {[]} | array
Specificies an array with which to multiply the
cross-correlations before they are integrated. The
value defaults to an empty array, meaning that no
inhibition will be applied.
'ic_t' : {0} | scalar
Specifies the interaural coherence (IC) threshold.
Only samples for which the IC exceeds this threshold
will be used to integrate cross-correlations. The
algorithm calculates Interaural Coherence (IC)
according to [1]. The value should be in the range
[0,1];
'norm_flag' : {0} | scalar
Specifies whether the cross-correlograms are
calculated using normalised cross-correlations. A
non-zero value indicates that normalised
cross-correlations are used.
'inhib_mode' : {'subtract'} | 'multiply'
Specify how the inhibition is applied. The default
'subtract' will subtract inhib from the running
cross-correlations; 'multiply' will multiply inhib
with the running cross-correlations.

[ccg,ic] = ch_xcorr(...) returns the calculated IC to
the matrix IC. Although the matrix returned is the same
size as hc_L, IC is only calculated for samples
1:frame_count*frame_length, other values will be set to
0.

Algorithm

See the enclosed documentation for more details on the
workings of the algorithm and an important caveat.

References

[1] C. Faller and J. Merimaa, "Source localization in
complex listening situations: Selection of binaural cues
based on interaural coherence", The Journal of the
Acoustical Society of America, vol. 116, pp.3075-3089,
Nov. 2004.

Further Reading

C. Hummersone, R. Mason, and T. Brookes, "A comparison
of computational precedence models for source separation
in reverberant environments", in 128th Audio Engineering
Society Convention, London, May 2010, paper 7981.

Cite As

Christopher Hummersone (2020). Precedence-based cross-correlograms (https://github.com/IoSR-Surrey/MatlabToolbox), GitHub. Retrieved .

Updates

1.16.0.0

Corrected title.

1.16.0.0

Migrated to GitHub.

1.16.0.0

A few simplifications made to the C source code. Overhauled the interface: dramatically reduced the number of required arguments, and added other arguments as optional parameter/value pairs.

1.15.0.0

Made many simplifications to the C source code, and added error checks to m code.

1.14.0.0

Output IC now reflects specified threshold.

1.13.0.0

Some bug fixes.

1.12.0.0

Fixed a bug whereby output IC would not be the same size as the input data. Added check to ensure that they are the same size and transposition. Updated help to include dims of output CCG.

1.11.0.0

Added updated check_mex_compiled.m

1.10.0.0

Updated documentation, added verbose comments through source code

1.9.0.0

Updated check for inhib matrix size and shape

1.8.0.0

removed need to framecount parameter input, now calculated automatically.

1.7.0.0

Fixed a bug that gave negative numbers when using the 'subtract' option. Updated the documentation accordingly.

1.5.0.0

Created additional documentation explaining the algorithm.

1.4.0.0

Added additional 'NOVERLAP' parameter for integrating over several frames. Added note to documentation on limitations for normalised cross-correlation.

1.3.0.0

Whoops, fixed another silly mistake, thanks to Lars Bramsløw

1.2.0.0

Fixed an issue with an un-specified max function. Thanks to Lars Bramsløw for pointing it out.

1.1.0.0

Updated the mex function

MATLAB Release Compatibility
Created with R2014a
Compatible with any release
Platform Compatibility
Windows macOS Linux