localizationerror
Compute psychoacoustic performance parameters from a sound localization experiment

Usage:

[accL, precL, accP, precP, querr] = localizationerror(m)
[res, meta, par] = localizationerror(m,errorflag)
[res, meta] = localizationerror(m,f,r,'perMacpherson2003');

Input parameters:

`m`	Item list from a localization experiment where each row is response from a trial and the columns are as follows: 1: Azimuth angle of the target (in degrees). 2: Elevation angle of the target (in degrees). 3: Azimuth angle of the response (in degrees). 4: Elevation angle of the response (in degrees). 5: Lateral angle of the target (in degrees). 6: Polar angle of the target (in degrees). 7: Lateral angle of the response (in degrees). 8: Polar angle of the response (in degrees). 9 to 11: Cartesian X, Y, and Z coordinates of the target. Required only for errorflags being `'rFBC'` or `'rF2B'`. 12 to 14: Cartesian X, Y, and Z coordinates of the response. Required only for errorflags being `'rFBC'` or `'rF2B'`.
`errorflag`	Error metric to be calculated.
`f`	Regression statistics for the frontal targets obtained from `[f,r] = localizationerror(m, 'sirp');`. Required only for the errorflag being `'perMacpherson2003'`.
`r`	Regression statistics for the rear targets obtained from `[f,r] = localizationerror(m, 'sirp');`. Required only for the errorflag being `'perMacpherson2003'`.

Output parameters:

`accL`	Accuracy bias (in degrees) in the lateral dimension.
`precL`	Precision error (in degrees) in the lateral dimension.
`accP`	Accuracy bias (in degrees) in the polar dimension.
`precP`	Precision error (in degrees) in the polar dimension.
`querr`	Quadrant error rate (in percentage).
`res`	Error metric as requested by errorflag.
`meta`	Additional metadata as requested by errorflag.
`par`	Additional calculation as requested by errorflag.

Description:

localizationerror(..) calculates various psychoacoustic performance parameters from responses of a sound-localization experiment.

[accL, precL, accP, precP, querr] = localizationerror(m) returns the metrics 'accL', 'precL', 'precP', and 'querr'.

[res, meta, par] = localizationerror(m, errorflag) returns in res the error metric requested by errorflag, with additional metadata and calculation results provided in meta and par, respectively.

The errorflag can be one of the following:

`'absaccE'`	Absolute elevation accuracy bias (in degrees), i.e., the absolute value of the circular average of elevation errors. See magnitude of elevation bias in Middlebrooks (1999).
`'absaccL'`	Absolute lateral accuracy bias (in degrees), i.e., the absolute value of the average of the (signed) errors in the lateral dimension. See magnitude of lateral bias in Middlebrooks (1999).
`'accabsL'`	Averaged absolute lateral erorr (in degrees), i.e., the average of the absolute (unsigned) lateral errors. Reference unclear. Note that the naming as accuracy is confusing.
`'accabsP'`	Averaged absolute polar error (in degrees), i.e., the circular average of the absolute (unsigned) polar errors. Reference unclear. Note that the naming as accuracy is confusing.
`'accE'`	Elevation accuracy bias (in degrees), i.e., the circular average of elevation errors. Reference unclear.
`'accL'`	Lateral acuracy bias (in degrees), i.e., the average of lateral errors. See lateral bias in Majdak et al. (2010).
`'accP'`	Polar accuracy bias (in degrees), i.e., the circular average of polar errors. Reference unclear.
`'accPnoquerr'`	As `'accP'` but with quadrant errors (see `'querr'`) removed. See local polar bias in Majdak et al. (2010).
`'corrcoefL'`	Lateral correlation coeffficient, i.e., the correlation coefficient between the response and target angles in the lateral dimension. meta provides the p-value of the correlation significance. See lateral target-response correlation coefficient in Majdak et al. (2011).
`'corrcoefP'`	Polar median-plane correlation coeffficient, i.e., the correlation coefficient between the response and target angles in the polar dimension, considering responses around the median plane only, i.e., within the lateral angles of \(\pm\) 30 \(^\circ\). meta provides the p-value of the correlation significance. See polar target-response correlation coefficient in Majdak et al. (2011).
`'gainL'`	Lateral gain. It uses `'gainLstats'`. Reference unclear.
`'gainLstats'`	Statistic details from the calculation of the lateral gain. See `regress` for a detailed description of the structure. Reference unclear.
`'gainP'`	Polar gain (between -1 and 1) as an average of `'gainPfront'` and `'gainPrear'`. See polar gain in Macpherson and Middlebrooks (2000).
`'gainPfront'`	Frontal polar gain (between -1 and 1), i.e., the of SIRP done for frontal targets. It uses `'sirp'`. See polar gain in Macpherson and Middlebrooks (2000).
`'gainPrear'`	Rear polar gain (between -1 and 1), i.e., the slope of SIRP done for rear targets. It uses `'sirp'`. See polar gain in Macpherson and Middlebrooks (2000).
`'perMacpherson2003'`	Polar error rate (in percentage) as the rate of deviations larger than \(45^\circ\) from the linear regression calculated by SIRP for polar angles. It requires the results from `'sirp'` provided as a separate inputs (see Usage above).
`'precE'`	Elevation precision error (in degrees) i.e., circular standard deviation of elevation errors. Reference unclear.
`'precL'`	Lateral precision error (in degrees), i.e., circular standard deviation of lateral errors. See lateral precision error in Majdak et al. (2010).
`'precLcentral'`	As `'precL'` but considering only responses \(\pm\) 30 \(^\circ\) in elevation around the horizontal meridian plane. Reference unclear.
`'precLregress'`	Lateral scatter (in degrees) around the lateral regression line, i.e., the RMS of the response deviation from the lateral regression line, considering only the quasi-veridical responses, i.e., deviations smaller then \(45^\circ\). It uses `'gainLstats'`. See lateral angle scatter in Macpherson and Middlebrooks (2000). Note that the naming as precision is confusing.
`'precP'`	Polar precision error (in degrees), i.e., circular standard deviation of polar errors. Reference unclear.
`'precPmedian'`	As `'precP'` but considering targets around the median plane, i.e., with lateral angles in the range of \(\pm\) 30 \(^\circ\), only. Reference unclear.
`'precPmedianlocal'`	As `'precpPmedian'` but with quadrant errors (see `'querrMiddlebrooks'`) removed. Similar but not the same as rms local polar error in Middlebrooks (1999).
`'precPnoquerr'`	As `'precP'` but with quadrant errors (see `'querr'`) removed. See local polar precision error in Majdak et al. (2010).
`'precPregressFront'`	Polar frontal scatter (in degrees) around the polar regression line, i.e., the RMS of the response deviation from the polar regression line calculated by SIRP considering only targets located in the front and only the quasi-veridical responses, i.e., deviations smaller then \(45^\circ\) and. It uses `'sirp'`. See polar angle scatter in Macpherson and Middlebrooks (2000). Note that the naming as precision is confusing.
`'precPregressRear'`	Polar rear scatter (in degrees). As `'precPregressFront'` but calculated considering only targets located in the rear. It uses `'sirp'`. See polar angle scatter in Macpherson and Middlebrooks (2000). Note that the naming as precision is confusing.
`'precPregress'`	Polar scatter (in degrees) as an average of `'precPregressFront'` and `'precPregressRear'`. See polar angle scatter in Macpherson and Middlebrooks (2000). Note that the naming as precision is confusing.
`'pVeridicalL'`	Proportion (in percentage) of lateral quasi-verdical responses. It uses `'gainLstats'`. Reference unclear.
`'pVeridicalPfront'`	Proportion (in percentage) of polar frontal quasi-verdical polar responses. See quasi-veridical responses in Macpherson and Middlebrooks (2000).
`'pVeridicalPrear'`	Proportion (in percentage) of polar rear quasi-verdical polar responses. See quasi-veridical responses in Macpherson and Middlebrooks (2000).
`'pVeridicalP'`	Proportion (in percentage) of polar quasi-verdical polar responses.See quasi-veridical responses in Macpherson and Middlebrooks (2000).
`'querr'`	Quadrant error rate (in percentage), i.e., the rate of responses with the weighted polar errors outside the quadrant defined by errors within \(\pm\) 45 \(^\circ\). The weighting is done as a function the lateral angle of the target. meta and par provide the information about the number of responses in the correct quadrants, the number of responses within the lateral range, and the chance rate to achieve the quadrant errors by chance. See quadrant errors in Majdak et al. (2010).
`'querrMiddlebrooks'`	Quadrant error rate (in percentage), i.e., the rate of responses with the unweighted polar errors outside the quadrant defined by absolute polar errors within \(\pm\) 90 \(^\circ\). meta and par provide the information about the number of confusions and the number of responses within the lateral range. See quadrant errors in Middlebrooks (1999).
`'rmsL'`	Lateral RMS error (in degrees), i.e., the root of the average of squared lateral errors. See rms lateral error in Middlebrooks (1999).
`'rmsPmedian'`	Polar median-plane RMS error (in degrees), i.e., the root of the average of squared polar errors considering only targets around the median plane, i.e., with lateral angles in the range of \(\pm\) 30 \(^\circ\), only. Reference unclear.
`'rmsPmedianlocal'`	As `'rmsPmedian'` but excluding responses with quadrant errors as in `'querrMiddlebrooks'`, i.e., absolute polar errors larger than 90 \(^\circ\). See rms local polar error in Middlebrooks (1999).
`'SCC'`	Spherical correlation coefficient. See SCC in Carlile et al. (1997).
`'sirp'`	Polar regression statistics by means of the selective iterative regression procedure (SIRP) to exclude outliers and reversals from the computation of the regression lines used to calculate gain-based metrics. The SIRP is run 100 times and the result including the most responses (in other words, excluding the least outliers) is selected. Only targets around the median plane are considered, i.e., within the lateral range of \(\pm\) 30 \(^\circ\). Outlier distance criterion is \(40^\circ\). The SIRP is run separately for targets located in the frontal and the rear hemisphere with the results stored in res and meta respectively (see `regress` for a detailed description of the structure). See p. 1873 in Macpherson and Middlebrooks (2000).
`'rFBC'`	Rate of front-back confusion (in percentage) in terms of being in the incorrect hemifield separated by the frontal plane. Responses on the interaural axis are not considered. Requires additional columns in the input. See front-back confusions in Carlile et al. (1997). Requires additional columns in the input.
`'rF2B'`	As `'rFBC'` but considering front-to-back confusions only. Requires additional columns in the input. See McLachlan et al. (2024).
`'rUDC'`	Rate of up-down confusion (in percentage) in terms of being in the incorrect hemifield separated by the horizontal meridian plane. Responses directly on that plane are not considered. Requires additional columns in the input. See up-down confusions in Carlile et al. (1997) and McLachlan et al. (2024).
`'slopePfront'`	Polar frontal slope angle (in degrees) calcalated from the slope of the regression line for the frontal targets. Uses `'gainPfront'`. Reference unclear.
`'slopePrear'`	Polar rear slope angle (in degrees) calcalated from the slope of the regression line for the rear targets. Uses `'gainPrear'`. Reference unclear.
`'slopeP'`	Polar slope angle (in degrees) calcalated from the slope of the regression line for all targets. Uses `'gainP'`. Reference unclear.

References:

G. McLachlan, P. Majdak, J. Reijniers, M. Mihocic, and H. Peremans. Insights into dynamic sound localisation: A direction-dependent comparison between human listeners and a Bayesian model, Apr. 2024. [ DOI ]

E. A. Macpherson and J. C. Middlebrooks. Localization of brief sounds: Effects of level and background noise. The Journal of the Acoustical Society of America, 108(1834), 2000. [ http ]

P. Majdak, M. J. Goupell, and B. Laback. Two-dimensional localization of virtual sound sources in cochlear-implant listeners. Ear Hear, 32:198--208, 2011. [ DOI ]

P. Majdak, M. J. Goupell, and B. Laback. 3-D localization of virtual sound sources: Effects of visual environment, pointing method and training. Atten Percept Psycho, 72:454--469, 2010.

J. C. Middlebrooks. Virtual localization improved by scaling nonindividualized external-ear transfer functions in frequency. The Journal of the Acoustical Society of America, 106:1493--1510, 1999.

E. A. Macpherson and J. C. Middlebrooks. Vertical-plane sound localization probed with ripple-spectrum noise. The Journal of the Acoustical Society of America, 114:430--445, 2003.

S. Carlile, P. Leong, and S. Hyams. The nature and distribution of errors in sound localization by human listeners. Hearing research, 114(1):179--196, 1997.