SpHr_ActivityAtTime [ flags ] [ keywords ] CFs=CFs, XsNs = { Xs, Ns }, IPD = { IPDs, IPDneurons, IPDneuronLabels }, ILD = { ILDs, ILDneurons, ILDneuronLabels }
Generates neural activities patterns representive of auditory space, across frequency bands, and at the time of the last IPD and/or ILD value(s) passed to the operation. Activities patterns may also be averaged over time.
Required Keyword Parameters
CFs = CFs
CFs is the reference to a wave of filter bank center frequencies. The CFs wave is typically generated using the SpHr_FilterCenterFreqs operation.
XsNs = { Xs, Ns }
Xs is the reference to a wave of frequency-specific time (X-axis) values.
Ns is the reference to a wave indicating the number of frequency-specific Xs and other values obtained.
Waves Xs and Ns are typically generated using the SpHr_CrossingCarrierCues and/or SpHr_CrossingEnvelopeCues operations.
IPD = { IPDs, IPDneurons, IPDneuronLabels }
IPDs is the reference to a wave of frequency-specific interaural phase differences (IPD) values. The IPDs wave is typically generated using the SpHr_CrossingCarrierCues and/or SpHr_CrossingEnvelopeCues operations.
IPDneurons is the reference to a 'look-up' wave (table) of modeled neurons and activities evoked by interaural phase differences (IPD).
IPDneuronLabels is the reference to a 'look-up' wave (table) of half-maximal neuron 'labels' (column 0) and maximal neuron 'labels' (column 1).
Waves IPDneurons and IPDneuronLabels are typically generated using the SpHr_NeuronsIPD operation.
and/or
ILD = { ILDs, ILDneurons, ILDneuronLabels [, ScaleILDtoITD] }
ILDs is the reference to a wave of frequency-specific interaural level differences (ILD) values. The ILDs wave is typically generated using the SpHr_CrossingCarrierCues and/or SpHr_CrossingEnvelopeCues operations.
ILDneurons is the reference to a 'look-up' wave (table) of modeled neurons and activities evoked by interaural level differences (ILD).
ILDneuronLabels is the reference to a 'look-up' wave (table) of neuron 'labels'. Waves ILDneurons and ILDneuronLabels are typically generated using the SpHr_NeuronsILD operation.
ScaleILDtoITD is an optional variable to determine if ILD labels scale with ITD (= 1, Default) or scale directly with IPD labels (= 0). When labels scale with ITD, values in the wave ILDs are multiplied with a scaling value calculated as: frequency/((ILDlabelSpread/IPDlabelSpread); where frequency is center frequency, ILDlabelSpread is the average spread of ILD labels away from 0 dB and IPDlabelSpread is the average spread of IPD labels away from 0 seconds (average spread = (maximum label - minimum label) / 2)).
Note: If keywords IPD and ILD are both used, activity outputs are unit-less, reflecting a combination of IPD (cycles) or ITD (seconds, with /ITD flag) and ILD (dB).
Optional Keyword Parameters
Env = { filterImpulseEnvelopeWidths [, neuronWidth ] }
The Env keyword should be used when envelope IPDs and/or ILDs were obtained using the SpHr_CrossingEnvelopeCues operation. The SpHr_CrossingCarrierCues operation should not be used with the Env keyword.
filterImpulseEnvelopeWidths is a wave of filter bank impulse envelope widths. This wave is generated using the /W flag of the SpHr_FilterBankBiquadCoefs operation.
neuronWidth is the width of IPD neurons at the half-maximal activity level. See the variable V_NeuronWidth set by the SpHr_NeuronsIPD operation. If neuronWidth is omitted, the default value of 0.4284 is used (log-normal 2 width parameters).
Wts = { Wts [, lastWeightsDest ] }
Wts is the reference to a wave of weights corresponding to IPDs and/or ILDs that have been pre-averaged across the left and right channels. Such weights are typically obtained using the /AWts flag of the SpHr_CrossingCarrierCues operation.
lastWeightsDest is the optional specification for a wave of frequency-specific weights used at the time of the last IPD and/or ILD value(s) passed to the operation. Values are meaningless if activities are averaged over time (/Avg = 1 or /Stats = 1).
Flags
/Lim = limit [ , limitTimes ]
When modeled activities exceed the value set by limit, prior activities are diminished by the excess difference. If the /Lim flag is omitted, a default value of 20 is used. Prior activities diminish faster as the value of limit is reduced (i.e., activities accrue faster). Conversely, prior activities diminish more slowly as the value of limit is increased. Smaller limit values thus result in faster apparent 'adaptation' over time whereas larger values result in slower apparent 'adaptation' over time. Because IPDs and/or ILDs coincide with carrier or envelope cycles, prior activities diminish faster as center frequency increases. Two IPD and/or ILD values are assumed per cycle and the actual limit used internally therefore equals limit * 2. Upon completion, the internal limit used is set to the variable V_FreqAvgLimit.
limitTimes is an optional specification for a wave of times (s) when the specified limit is first reached for each center frequency. Modeled activities obtained before the specified limit is reached should be ignored. Upon completion, the time at which limit is first reached is set to the variable V_FreqMaxLimitTime.
/ITD [ = { numITDs, maxITD } ]
Outputs specified by the /HM and /M flags are interpolated using a cubic spline operation so that activities reflect interaural time differences (ITD) as opposed to interaural phase differences (IPD).
numITDs determines the number of rows in waves specified by the /HM and /M output flags. If numITDs is less than 1.0, numITDs is treated as a delta value and the number of rows is calculated as (maxITD*2)/numITDs. If numITDs is omitted, a default value of 501 is used. Passing a negative number or 0 for numITDs is the same as omitting the /ITD flag.
maxITD is the maximum X-scale value, in seconds, of waves specified by the /HM and /M output flags. Wave offsets are set to -maxITD. Values should be between 1e-7 and 10. If omitted, a default value of 0.0012 seconds is used.
/Stat = [ stats ]
Activities are averaged from the time when each frequency-specific Limit is reached (see /Lim flag) to the time of the last passed IPD and/or ILD value (see 'IPD=' and 'ILD=' keywords).
stats = 0, Same as omitting the /Stats flag.
stats = 1, Activities are averaged over time. Same as /Stat flag alone.
stats = 2, Activities are averaged and standard deviations are written to the second layers of waves specified by the /HM and/or /M activity output flags.
stats = 3, Activities are averaged and waves specified by the /M and /HM activity output flags are generated with 2 layers. This may be helpful if standard deviation layers are always displayed but not always generated.
/Avg = [ avg ]
Same as the /Stat flag. Overrides the /Stat flag if both flags are used.
/IHC = { limitIndex [, halvingIndex ] }
Inter-hemispheric coordination. When limitIndex = 1 (Default), prior activities are diminished in both hemispheres whenever activities in either hemisphere exceed Limit ((See /Lim flag). When limitIndex = 0, prior activities are diminished independently in each hemisphere.
When halvingIndex = 1 (Default), maximal activities in both hemispheres are used to determine the level at which activities are reflected downward so that half-maximal activities may be viewed as 'peaks' (see /HMOP flag). When halvingIndex = 0, activities are reflected independently in each hemisphere. If halvingIndex is omitted, it is set to the same value as limitIndex.
/T = { startTime, endTime }
Activities are obtained only when times passed by the Xs wave via the 'XsNs=' keyword are greater than startTime and less than endTime.
Abbreviated form:
/T = endTime
/F = { lowFreq , highFreq }
Activities are obtained only when center frequencies passed by the CFs wave via the 'CFs=' keyword are greater than lowFreq and less than highFreq.
Abbreviated forms:
/F = highFreq If the 'Env=' keyword is omitted.
/F = lowFreq If the 'Env=' keyword is used.
/Q [ = quiet ] Silences uncritical warnings. quiet = 1 is the same as the /Q flag alone.
/DF = dfRef dfRef is an optional datafolder reference. Destination waves are written to this existing datafolder, overriding individual wave specifications. Waves are written to the current datafolder if dfRef is omitted and no other datafolder is specified.
Activity output flags
/HM [ = { HalfmaximalActivity_Left, HalfmaximalActivity_Right } ]
Activity patterns where half-maximal or 'edge' activities indicate the greatest contributions to auditory spatial perception. Activities for each center frequency are written across columns.
HalfmaximalActivity_Left is the specification for a wave reflecting left-hemisphere activities. If wave specifications are omitted, a wave named HalfmaximalActivity_Left is created or a wave named EnvelopeHalfmaximalActivity_Left, if the 'Env=' keyword was also used. Whatever name used is written to the string S_HMflagLeft.
HalfmaximalActivity_Right is the specification for a wave reflecting right-hemisphere activities. If omitted, a wave named HalfmaximalActivity_Right is created or a wave named EnvelopeHalfmaximalActivity_Right, if the 'Env=' keyword was also used. Whatever name used is written to the string S_HMflagRight.
/HMOP = { useMaximalLabels [, reflectAtHalfmaximum] }
Output options for the /HM flag.
If useMaximalLabels is set to 1, maximal labels are used instead of halfmaximal labels. Halfmaximal labels are used if useMaximalLabels is set to 0 (Default).
If reflectAtHalfmaximum is omitted or set to 1(Default), activities above limit/2 (see /L=limit flag) are reflected downward so that half-maximal activities may be viewed as 'peaks'.
/M [ = { MaximalActivity_Left, MaximalActivity_Right } ]
Activity patterns where maximal activities indicate the greatest contributions to auditory spatial perception. Activities for each center frequency are written across columns. MaximalActivity_Left is the specification for a wave reflecting left-hemisphere activities. If omitted, a wave named MaximalActivity_Left is created or a wave named EnvelopeMaximalActivity_Left, if the 'Env=' keyword was also used. Whatever name used is written to the string S_MflagLeft.
MaximalActivity_Right is the specification for a wave reflecting right-hemisphere activities. If omitted, a wave named MaximalActivity_Right is created or a wave named EnvelopeMaximalActivity_Right, if the 'Env=' keyword was also used. Whatever name used is written to the string S_MflagRight.
/MOP = { useHalfmaximalLabels }
Output options for the /M flag.
If useHalfmaximalLabels is set to 1, half-maximal labels are used instead of maximal labels. Maximal labels are used if useHalfmaximalLabels is set to 0 (Default).
/P [ = { HalfmaximalActivityPoints, MaximalActivityPoints } ]
HalfmaximalActivityPoints is the specification for a wave to which frequency-specific half-maximal activity levels and corresponding 'labels' are written.
Frequency-specific values are written across rows.
'Labels' for the left and right hemispheres are written to columns 0 and 1, respectively, of the first layer (layer 0).
Activity levels for the left and right hemispheres are written to columns 0 and 1, respectively, of the second layer (layer 1). Note that activity levels should remain close to V_FreqAvgLimit (see /L=limit flag) once this value is reached and that all outputs should be ignored if this level has not yet been reached.
If the keywords IPD and ILD are both used, ‘labels’ are unit-less, reflecting IPD (cycles) and ILD (dB) or ITD (seconds, with /ITD flag) and ILD (dB). If the wave specification HalfmaximalActivityPoints is omitted, a wave named HalfmaximalActivityPoints is created. The name used is always written to the string S_PflagHM.
MaximalActivityPoints is the specification for a wave to which frequency-specific maximal activity levels and corresponding 'labels' are written. If the wave specification MaximalActivityPoints is omitted, a wave named MaximalActivityPoints is created. The name used is always written to the string S_PflagM.
The formatting of MaximalActivityPoints is otherwise similar to that of HalfmaximalActivityPoints.
/POP = { setPointsAtLimitsToNaN }
Output options for the /P flag.
If setPointsAtLimitsToNaN is set to 1 (Default), then values in waves HalfmaximalActivityPoints and MaximalActivityPoints (see /P flag) are set to NaN if points are found to correspond to the first or last 'labels' passed using the 'IPD=' and/or 'ILD=' keywords. As an example, values are set to NaN if half-maximal 'labels' in IPDneuronLabels range from -0.2 to 0.2 (cycles) and a half-maximal 'peak' was found corresponding to 0.2 cycles.
/ACC [ = ActivityAccrual ]
ActivityAccrual is the specification for a wave indicating how prior activities were diminished prior to the time of the last IPD and/or ILD value. If the ActivityAccrual specification is omitted, a wave named Accruals is created or a wave named EnvelopeAccruals if the 'Env=' keyword was also used. The name used is written to the string S_ACCflagRight.
Example
Function SpHr_ActivityAtTime_Example()
variable useEnvelopeCues = 0 // carrier=0, envelope=1
DFREF saveDFR = GetDataFolderDFR()
NewDataFolder/O/S ActivityAtTime
// Test Signal, ITD= 0.1 ms, ILD= 3 dB, independence index= 0.1
SpHr_SignalBinaural/sec=1/Ramp=1/dB=70/HP=50/Sp=1/Ind=0.1/ITD={0.1}/ILD={3} 48000, NoiseBurst
// Filter bank
variable lowHz = 100, highHz = 8000, carrierHighHz = 2000
SpHr_FilterCenterFreqs/R/Type=(2)/E=CFEdges lowHz, highHz, 32, CFs
SpHr_FilterBankBiquadCoefs/W=FilterWidths 48000, CFs, coefBank
SpHr_FilterBankBiquad /RMS/Dest=FilterBanks CFs, coefBank, NoiseBurst
KillWaves/Z coefBank, NoiseBurst
// IPD, ILDs, Xs, and XNs
if(useEnvelopeCues)
SpHr_CrossingEnvelopeCues/IPD=IPDs/ILD=ILDs/ABL=ABLs/X=Xs/XN=Ns CFs, FilterBanks
else
SpHr_CrossingCarrierCues/F={carrierHighHz}/IPD=IPDs/ILD=ILDs/ABL=ABLs/X=Xs/XN=Ns/AWts={20,20,EnvWts} CFs, FilterBanks
endif
KillWaves/Z FilterBanks
// Model left hemisphere IPD and ILD Neurons
variable numNeurons = 1001, numNeuronBins = 1001
SpHr_NeuronsIPD/R=1.2/L=0.2/N={numNeurons,numNeuronBins} IPDLabels, MaxLabels, IPDNeurons; killwaves/Z MaxLabels
SpHr_NeuronsILD/R=(50)/W=6/S/L=24/N={numNeurons,numNeuronBins}/SL=(V_IPDLabelShift) ILDLabels, ILDNeurons
// SpHr_ActivityAtTime - default output wave names
variable LimitSet = 20 // Activity limit
if(useEnvelopeCues) // include Env={FilterWidths,V_NeuronWidth}
SpHr_ActivityAtTime/Q/F=(lowHz)/Lim=(LimitSet)/ITD/HM/P Env={FilterWidths,V_NeuronWidth},CFs=CFs,XsNs={Xs,Ns},IPD={IPDs,IPDNeurons,IPDLabels},ILD={ILDs,ILDNeurons,ILDLabels,1}
else
SpHr_ActivityAtTime/Q/F=(carrierHighHz)/Lim=(LimitSet)/ITD/HM/P CFs=CFs,XsNs={Xs,Ns},Wts={EnvWts},IPD={IPDs,IPDNeurons,IPDLabels},ILD={ILDs,ILDNeurons,ILDLabels,1}
endif
wave HM_L = $S_HMflagLeft; wave HM_R = $S_HMflagRight; wave HM_Points = $S_PflagHM // default wave names
Variable LimitUsed = V_FreqAvgLimit
// Display Activities re: Half-maximum
SpHr_ColorTable/P=(0.5)/Dest=ColorTable "Turbo" // /P=(0.5) so half-maximum is hot color
KillWindow/Z LeftHemisphereAT; KillWindow/Z RightHemisphereAT
// Left Hemisphere
Display/W=(455,54,822,290)/N=LeftHemisphereAT/K=1/VERT HM_Points[*][0][0] vs CFs as "Left Hemisphere"
ModifyGraph margin(right)=54
AppendImage/G=1 HM_L vs {*,CFEdges}
ModifyImage $NameOfWave(HM_L) ctab={0,LimitUsed,ColorTable,0}
ModifyGraph mode=3,marker=19,rgb=(48059,48059,48059),msize=1.5
ModifyGraph log(left)=1,zero(bottom)=2, mirror=0
SetAxis/A/E=2 bottom
Label left "frequency (\\U)"
Label bottom "Combination of ILD and ITD \\U"
ColorScale/C/N=text0/F=0/B=1/A=RC/X=-20.00/Y=0.00
ColorScale/C/N=text0 image=$NameOfWave(HM_L),side=1,frame=0
ColorScale/C/N=text0 height=120, width=6,tickThick=0.5,tickLen=2,nticks=3,lblMargin=-2
// Right Hemisphere
Display/W=(455,315,822,551)/N=RightHemisphereAT/K=1/VERT HM_Points[*][1][0] vs CFs as "Right Hemisphere"
ModifyGraph margin(right)=54
AppendImage/G=1 HM_R vs {*,CFEdges}
ModifyImage $NameOfWave(HM_R) ctab={0,LimitUsed,ColorTable,0}
ModifyGraph mode=3,marker=19,rgb=(48059,48059,48059),msize=1.5
ModifyGraph log(left)=1,zero(bottom)=2, mirror=0
SetAxis/A/E=2 bottom
Label left "frequency (\\U)"
Label bottom "Combination of ILD and ITD \\U"
ColorScale/C/N=text0/F=0/B=1/A=RC/X=-20.00/Y=0.00
ColorScale/C/N=text0 image=$NameOfWave(HM_R),side=1,frame=0
ColorScale/C/N=text0 height=120, width=6,tickThick=0.5,tickLen=2,nticks=3,lblMargin=-2
SetDataFolder saveDFR
End