SpHr_Correlate [ flags ] srcWaveName [ , src2WaveName]
Cross-correlation computed using 'fast' DFT multiplication.
Parameters
srcWaveName Specification for single precision source wave.
srcWaveName(startX, endX) Specifies an x-range for the source wave.
srcWaveName[startP, endP] Specifies a point-range in the source wave.
src2WaveName Optional second source to correlate with srcWaveName
The SpHr_Correlate operation is designed for the following conditions:
(1) srcWaveName consists of exactly 2 layers, for which corresponding columns in each layer are correlated. This type of srcWaveName is typically generated using the SpHr_FilterBankBiquad operation as shown in the example below.
(2) srcWaveName consists of exactly 2 columns which are correlated. This type of srcWaveName is typically an unfiltered stereo/binaural sound.
(3) srcWaveName and src2WaveName are both passed, for which values along corresponding rows are correlated. Both sources must have the same dimensions (same number of row, columns, layers, and chunks). srcWaveName and src2WaveName may therefore reflect the left and right channels of a stereo/binaural sound. The waves may also reflect filter banks generated using the SpHr_FilterBankBiquad operation. The waves may also have more than one layer. For instance, filter banks may be generated for 2 different stereo/binaural sounds and correlated.
Flags
/Dest = correlationDestWaveName
correlationDestWaveName specifies where the results of correlation(s) are written.
/A = [ averageDestWaveName ]
averageDestWaveName specifies a wave to which average correlations are written. srcWaveName and src2WaveName must have identical dimensions or else srcWaveName must consists of exactly two layers. Unless more than one correlation is calculated, variables V_AvgMaxLag, V_AvgMax, V_AvgMinLag, and V_AvgMin are generated. To only generate these variables, the specification for averageDestWaveName may be omitted.
/Lim = {minLag [, maxLag] }
Re-dimension correlationDestWaveName and/or averageDestWaveName so that lag (x-scaling) values range between minLag and maxLag. If maxLag is omitted, values are scaled symmetrically between -minLag and minLag.
/E = { extremaDestWaveName [ , minX, maxX ] }
extremaDestWaveName specifies a wave to which correlation extrema are written. Maximum lag times, maxima, minimum lag times, and minima are written to columns 0-4. srcWaveName and src2WaveName must have identical dimensions or else srcWaveName must consists of exactly two layers. The main use of this flag is to obtain frequency-specific extrema.
minX is minimum x-scale for which extrema are found. minX can be omitted to search entire wave or set to -inf.
maxX is maximum x-scale for which extrema are found. maxX can be omitted to search entire wave or set to inf.
/AE = { averageExtremaDestWaveName [ , minX, maxX ] }
averageExtremaDestWaveName specifies a wave to which the maxima and minima of averaged correlations are written. This flag is sometimes useful when srcWaveName and src2WaveName both consist of multiple columns and layers (when srcWaveName and src2WaveName are 2-layered filter banks generated from stereo/binaural waves using the SpHr_FilterBankBiquad operation).
minX is minimum x-scale for which extrema are found. minX can be omitted to search entire wave or set to -inf.
maxX is maximum x-scale for which extrema are found. maxX can be omitted to search entire wave or set to inf.
/NoDC = nodc
Removes the mean from each source wave before computing the correlations. To allow DC offsets in the source waves, set nodc to 0.
Not sure why you would not want to remove DC but academic types seem to enjoy emphasizing the difference between cross-covariance from cross-correlation…
/NORM = norm
Normalizes the correlations to a maximum of 1. To return non-normalized values, set norm to 0.
Calculates: correlationDest /= (src1RMS * sqrt(src1Len) * src2RMS * sqrt(src2Len))
/Env = env
Correlation arguments are returned as envelopes computed using the Hilbert transformation. Extrema and averages are computed using these envelopes. env = 0 is the same as no flag. env = 1 is the same as the /Env flag alone.
/DF=dfRef
dfRef is an optional datafolder reference. Destination waves are written to this existing datafolder, overriding any datafolder specified by destWaveName. Waves are written to the current datafolder if not specified here or in destWaveName.
Example
Function SpHr_Correlate_Example()
// two channels of partially independent noise with
// 0.2 ms interaural time difference (ITD)
SpHr_SignalBinaural/ITD={0.2,1}/Ind=0.1/ms=20/dB=70/Buff=2/ramp=1 48000, NoiseBank
// generate filter bank
SpHr_FilterCenterFreqs/R/E=CFedges 50, 5000, 32, CFs
SpHr_FilterBankBiquadCoefs 48000, CFs, coefBank
SpHr_FilterBankBiquad CFs, coefBank, NoiseBank
killwaves/Z coefBank
// get correlations for the filter bank
SpHr_Correlate/Dest=Correlations/E=CorrelationExtrema/A=CorrelationsAvg NoiseBank
killwaves/Z NoiseBank
Display/K=1/W=(35,45,489,375) as "Correlation"
AppendImage Correlations vs {*,CFedges}
ModifyImage Correlations ctab= {*,*,RedWhiteBlue,1}
AppendToGraph/R CorrelationsAvg
ModifyGraph lsize=0.75,rgb=(0,0,0),lblMargin=3
AppendToGraph/Vert CorrelationExtrema vs CFs
ModifyGraph rgb=(0,0,0),mode(CorrelationExtrema)=3,marker(CorrelationExtrema)=8
ModifyGraph msize(CorrelationExtrema)=2,mrkThick(CorrelationExtrema)=1
ModifyGraph fSize=10,axThick=0.5,ZisZ=1,zapTZ=1,zapLZ=1,standoff=0,btLen=3
ModifyGraph btThick=0.5,stLen=1.5,stThick=0.5
Label left "frequency (\\U)"
Label bottom "lag (\\U)"
SetAxis bottom -0.002,0.002
Label right "across frequency average \\s(CorrelationsAvg)"
ModifyGraph lblMargin(right)=5
SetAxis right -1,1
ModifyGraph zero(bottom)=1,zeroThick(bottom)=0.5
TextBox/C/N=text0/F=0/H={15,0,5}/A=MT/E "\\s(CorrelationExtrema)maxima"
End