SpHr_CrossingEnvelopeCues [ Flags ] CFs, srcFilterBank
SpHr_CrossingEnvelopeCues [ Flags ] CFs, envelopeXs, envelopeYs, envelopeNs
Obtains spatial cues from envelopes. Envelopes are cues are both generated using zero-crossing.
Form 1 Parameters
CFs Bank of center frequencies (Hz). See SpHr_FilterCenterFreqs. Cues for individual bands may be excluded by setting values to NaN. Frequencies are used to determine the maximum number of crossings expected.
srcFilterBank Specifies the single precision 'filter bank' for which envelope cues are obtained. See SpHr_FilterBankBiquad. Left channel frequency bands are specified by columns in layer 0. Right channel frequency bands are specified by columns in layer 1. Destination values correspond to envelope peaks so that amplitude-based measures can be obtained at the same times.
srcFilterBank(startX, endX) Specifies an x-range in the source wave.
srcFilterBank[startP, endP] Specifies a point-range in the source wave.
Form 2 Parameters
CFs Bank of center frequencies (Hz). See SpHr_FilterCenterFreqs. Cues for individual bands may be excluded by setting values to NaN. Frequencies are used to determine the maximum number of crossings expected.
envelopeXs Envelope time (x) values obtained using the SpHr_CrossingEnvelope operation with the /X flag.
envelopeYs Envelope amplitude (Y) values obtained using the SpHr_CrossingEnvelope operation and the /Pa flag.
envelopeNs Number of, frequency specific, envelope time and amplitude values obtained using the operation SpHr_CrossingEnvelope and the /XN flag.
Flags
/F = minFreq Minimum center frequency (CFs value) for which carrier cues are found.
/F = {minFreq, maxFreq}
minimum and maximum center frequencies (CFs values) for which carrier cues are found.
/CPC = [ cpc ] Approximate number of ITDs and other corresponding cues registered per envelope-waveform cycle. Passed value must be between 1 and 3.
/CPC=1: (Default) One cue is obtained for each zero-crossing. There are 2 crossings per cycle and thus 2 cues registered per envelope-waveform cycle. ITD, IPD, and the timing of other cue values reflect only the shortest ITD found per zero-crossing.
/CPC=2: Two cues are obtained for each zero-crossing. There are 2 crossings per cycle and thus 4 cues registered per envelope-waveform cycle. ITD, IPD, and the timing of other cue values reflect the 1st and 2nd shortest ITDs found per zero-crossing.
/CPC=3: Same as no /CPC flag. Three cues are obtained for each zero-crossing. There are 2 crossings per cycle and thus 6 cues registered per envelope cycle. ITD, IPD, and the timing of other cue values reflect the 1st, 2nd, and 3rd shortest ITDs found per zero-crossing.
/X = [ destWaveName ]
Times when zero-crossings were found. If destWaveName is omitted, the destination wave uses the name of srcFilterBank or envelopeXs and appends '_EnvXs'. If the /N flag is used, nameStr is appended with the suffix '_Xs'. The wave single precision and always overwritten. To facilitate the plotting of left and right channel envelopes and envelope derivatives, identical values are written to two layers (layers 0 and 1).
/XN = [ destWaveName ]
Number of zero-crossings found in each frequency band. If destWaveName is omitted, the destination wave uses the name of srcFilterBank or envelopeXs and appends '_EnvNs'. If the /N flag is used, nameStr is appended with the suffix '_Ns'. The wave single precision and always overwritten.
/ITD = [ destWaveName ]
Interaural time differences (ITD) in seconds. If destWaveName is omitted, the destination wave uses the name of srcFilterBank or envelopeXs and appends '_EnvITDs'. If the /N flag is used, nameStr is appended with the suffix '_ITDs'. The wave single precision and always overwritten.
/IPD = [ destWaveName ]
Interaural phase differences (IPD) in cycles. If destWaveName is omitted, the destination wave uses the name of srcFilterBank or envelopeXs and appends '_EnvIPDs'. If the /N flag is used, nameStr is appended with the suffix '_IPDs'. The wave single precision and always overwritten.
/ILD = [ destWaveName ]
Interaural phase differences (ILD) in decibels. If destWaveName is omitted, the destination wave uses the name of srcFilterBank or envelopeXs and appends '_EnvILDs'. If the /N flag is used, nameStr is appended with the suffix '_ILDs'. The wave single precision and always overwritten. ILD = 20*log( Envelope[p][q][1] / Envelope[p][q][0]] )
/ABL = [ destWaveName ]
Interaural phase differences (ABL) in decibels. If destWaveName is omitted, the destination wave uses the name of srcFilterBank or envelopeXs and appends '_EnvABLs'. If the /N flag is used, nameStr is appended with the suffix '_ABLs'. The wave single precision and always overwritten. ABL = 20*log( ( Envelope[p][q][0] + Envelope[p][q][1]] ) /(0.00002*2) ).
/AWts = { amplitudeLimit, derivativeLimit, destWaveName }
Envelope weights, averaged across the left and right channels, are calculated and written to the wave specified by destWaveName. destWaveName is single precision and always overwritten. If amplitudeLimit and derivativeLimit and both > 0, weights generated for envelope amplitudes and their derivatives are averaged. The weights are comparable to those computed by the SpHr_CrossingEnvelopeWeights and SpHr_CrossingCarrierCues operations but are interpolated so that values correspond to the times of envelope cues obtained by the present operation.
amplitudeLimit Neural activity limit for envelope amplitude weights. Values do not contribute to destWaveName if amplitudeLimit < 0. Use the /dB flag or the dB parameter of the /En flag to compute the weights using decibels. Results are comparable to passing the results of the /Pa or /dB flags of the SpHr_CrossingEnvelope operation to the SpHr_CrossingEnvelopeWeights operation, and interpolating the returned weights at times of envelope cues found by the present operation.
derivativeLimit Neural activity limit for envelope derivative weights. Values do not contribute to destWaveName if derivativeLimit < 0. Use the /dtdB flag or the dB parameter of the /dtEn flag to compute the weights using decibels. Results are comparable to passing the results of the /dtPa or /dtdB flags of the SpHr_CrossingEnvelope operation to the SpHr_CrossingEnvelopeWeights operation, and interpolating the returned weights at times of envelope cues found by the present operation.
/dB = [ db ]
Envelopes are convert to decibels before computing weights. This flag does nothing without the /AWts flag or if amplitudeLimit is < 0.
/dB=0: Envelopes are linearly scaled in Pascals (Pa). Default.
/dB=1: Same as /dB alone. Decibels. 20*log(En)/20 µPa.
/dtdB = [ dtdb ]
Envelopes are convert to decibels before computing derivatives and their weights. This flag does nothing without the /AWts flag or if derivativeLimit is < 0.
/dtdB=0: Envelopes are linearly scaled in Pascals (Pa). Default.
/dtdB=1: Same as /dB alone. Decibels. 20*log(En)/20 µPa.
/TR = [ tr ]
Truncate the number of rows in destination waves to the number of crossings found. Otherwise, the number of rows remains equal to the maximum number of crossing expected.
/TR=0: Rows are not truncated.
/TR=1: Same as /TR alone or no /TR flag. (Default)
/Cues = bitMask
Bit mask used to determine which cues are generated. Set bit 0 for Xs, bit 1 for XNs, bit 2 for ITDs, bit 3 for IPDs, bit 4 for ILDs, bit 5 for ABLs.
/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.
/N = nameStr
optional string to take the place of srcWaveName if destWaveName is not specified.
/SPks = { pks [, pkXs ] }
pks 'Signed peaks' may be useful when evaluating the crossings algorithm.
pkXs Times corresponding to signed peaks.
If the /SPks flag is passed with no destination waves specified, waves are generated with the name of srcFilterBank as a prefix, or the string passed by the /N flag. The signed peaks wave is then appended with the suffix '_SignedPeaks' and the wave of corresponding times is appended with the suffix '_SignedPeak_Xs'.
Notes
Cues and envelopes are computed only for waveform peak values above a threshold of -20 dB re: 20 µPa. If lower values precede a sound of interest, Limits may not be reached and returned values may be poorly defined.
Example
Function SpHr_CrossingEnvelopeCues_Example()
// Generate binaural noise burst in independent background signal
variable fs = 48000
SpHr_SignalBinaural/ms=400/Ramp=20/dB=30/HP=50/Sp=1/Ind=1 fs, NoiseBurst
variable ITD = 0.2 // ms
SpHr_SignalBinaural/Sum/ms=200/Ramp=20/dB=70/HP=50/Buff={100,100}/Sp=1/Ind=0/ITD={ITD,1} fs, NoiseBurst
// Generate filter bank
SpHr_FilterCenterFreqs/R/Type=(2) 100, 500, 3, CFs // log
SpHr_FilterBankBiquadCoefs 48000, CFs, coefBank
SpHr_FilterBankBiquad /RMS/Dest=FilterBanks CFs, coefBank, NoiseBurst
killwaves/Z coefBank, NoiseBurst
SpHr_CrossingEnvelopeCues /X=Xs /ITD=ITDS CFs, FilterBanks
killwaves/Z FilterBanks
Display/K=1/W=(35,45,553,311) as "Envelope ITDs"
AppendToGraph ITDs[][0] /TN=Hz_100 vs Xs[][0]
AppendToGraph ITDs[][1] /TN=Hz_224 vs Xs[][1]
AppendToGraph ITDs[][2] /TN=Hz_500 vs Xs[][2]
ModifyGraph mode=3,marker=19,msize=1.5
ModifyGraph rgb(Hz_100)=(0,0,65535),rgb(Hz_224)=(2,39321,1)
SetAxis left -0.001,0.001
ModifyGraph zero(left)=1,zeroThick(left)=0.5
Label left "ITD (\\U)"
Label bottom "time (\\U)"
TextBox/C/N=text0/F=0/B=1/H={15,0,5}/A=MT/X=0.00/Y=0.00 "\\sb+06\\Z10CF (Hz)\r\\s(Hz_100) 100\r\\s(Hz_224) 224\r\\s(Hz_500) 500"
SetDrawEnv ycoord= left,dash= 2,linethick= 0.50
DrawLine 0,ITD/1000,1,ITD/1000
End