API
spatialaudiometrics.load_data module
spatialaudiometrics.localisation_metrics module
localisation_metrics.py. Functions that calculate perceptual metrics for localisation experiments
- spatialaudiometrics.localisation_metrics.calculate_localisation_error(df: DataFrame, *grouping_vars: str)
Calculates localisation precision and accuracy (lat and pol) like in AMT toolbox (currently only in the interaural domain for now) and the middle brooks quadrant error and confusion classification percentages
- Parameters:
df – data frame thats been preprocessed by load_behav_data.preprocess_localisation_data
grouping_vars – columns that you want to group the table when calculating the mean (e.g. ‘subjectID’,’HRTFidx’)
- spatialaudiometrics.localisation_metrics.calculate_quadrant_error(df: DataFrame)
Calculates the middlebrooks quadrant error like that in the AMT toolbox
- Parameters:
df – Pandas data frame with the columns: lat_target, lat_response, pol_target, pol_response which has the polar and lateral coordinates for behavioural responses and auditory targets
- spatialaudiometrics.localisation_metrics.classify_confusion(row, cone_size_degrees=45)
Classifys perceptual confusions as per Poirier-Quinot et al. (2022): 10.5772/intechopen.104931
Classifies whether the response is a:- Precision error (within 45 degrees around target as default)- Front-back error (within 45 degrees as default of the opposite hemifield of the target)- In-cone error (errors made within the lateral cone, i.e. responses that failed at elevation judgements but were good in azimuth judgements)- Off-cone error (errors that failed in azimuth judgements, outside of the cone)- Parameters:
row – One row of a pandas dataframe with the columns ‘azi_target, ele_target, azi_response, ele_response, lat_response, lat_target, pol_response and pol_target
- spatialaudiometrics.localisation_metrics.polar_error_weight(df: DataFrame)
Calculates the weight for the polar error such that lateral targets that are at -90 and 90 degrees have a low weight due to polar compression
- Parameters:
df – Pandas dataframe with the column lat_target (lateral target)
spatialaudiometrics.signal_processing module
signal_processing.py. Generic signal processing functions
- spatialaudiometrics.signal_processing.calculate_spectrum(x: array, fs, db_flag=1)
Converts a time domain signal (such as an impulse reponse) to the frequency domain (such as a transfer function). The default is to return the output in dB
- Parameters:
x – 1D numpy array
fs – sample rate of the signal (e.g. 48000)
db_flag – if you want the spectra in dB rather than magnitude
- Returns spec:
spectrum (e.g. transfer function)
- Returns freqs:
the frequencies for each value in the spectrum
- Returns phase:
phase
- spatialaudiometrics.signal_processing.create_wavelet(frequency, fs, oscillations_per_side=7)
Creates a morlet wavelet (for wavelet decomposition) :param frequency: frequency of the wavelet :param fs: sample rate :param oscillations_per_side: how wide the wavelet is in number of oscillations :return: return the real and imaginary part of the wavelet
- spatialaudiometrics.signal_processing.db2mag(x)
Convert values from dB to magnitude
- Parameters:
x – float value (dB)
- Returns y:
float value
- spatialaudiometrics.signal_processing.mag2db(x)
Convert values from magnitude to dB using 20log10
- Parameters:
x – float value
- Returns y:
float value (dB)
- spatialaudiometrics.signal_processing.rms(x)
- spatialaudiometrics.signal_processing.wavelet_decomposition(sig, fs, freq_steps=1, freq_min=0.5, freq_max=20000)
Runs wavelet decomposition on the signal Try and use FWHM to deinfe the number of cycles
https://www.sciencedirect.com/science/article/pii/S1053811919304409 :param sig: signal you want to decompose :param fs: sample rate :param freq_steps: the step size of frequencies to be decomposed (i.e. 1 is every 1hz step) :param freq_min: the minimum frequency you want :param freq_max: the maximum frequency you want :returns: mag. phase and frequencies of the decomposition
spatialaudiometrics.angular_metrics module
spherical_metrics.py. Functions to calculate spherical metrics
- spatialaudiometrics.angular_metrics.great_circle_error(az1: float, el1: float, az2: float, el2: float)
Calculate the great circle arror between two azimuth and elevation locations
- Parameters:
az1 – First azimuth coordinate
el1 – First elevation coordinate
az2 – Second azimuth coordinate
el2 – Second elevation coordinate
- spatialaudiometrics.angular_metrics.polar2cartesian(az: float, el: float, dist: float)
Converts polar coordinates (azimuth and elevation) to cartesian
- Parameters:
az – Azimuth coordinate
el – Elevation coordinate
dist – Distance coordinate
- spatialaudiometrics.angular_metrics.spherical2interaural(az: float, el: float)
Converts spherical (azimuth and elevation) to interaural cordinates (lateral and polar)
lat lateral angle in deg, [-90 deg, +90 deg]pol polar angle in deg, [-90 deg, 270 deg]Currently doesn’t take array (would need to fix the ifs statements to work with np.where but would also need to get it to work with single numbers)Modified by Katarina C. Poole from the AMT toolbox sph2horpolar.m (23/01/2024)Original author: Peter L. Sondergaard- Parameters:
az – Azimuth coordinate
el – Elevation coordiate
spatialaudiometrics.hrtf_metrics module
spatialaudiometrics.statistics module
Functions to do some general statistics
- spatialaudiometrics.statistics.repeated_measures_anova(df: DataFrame, dep_col: str, subject_col: str, ind_col: list, bonferroni_correction=1)
Runs a repeated measures ANOVA
- Parameters:
df – Pandas dataframe that contains the data to run the stats on
dep_col – dependent column name (e.g. the response variable such as polar error)
subject_col – name of the column containing subject ID
ind_col – list of independent column name/s (e.g. the variable you are grouping with such as hrtf type)
- spatialaudiometrics.statistics.run_friedman_test(df: DataFrame, dep_col: str, subject_col: str, ind_col: list, bonferroni_correction=1)
Compare the mean between three or more groups if the distributions are non normal using Friedman test and Wilcoxon for post hoc pairwise
- Parameters:
df – Pandas dataframe that contains the data to run the stats on
dep_col – dependent column name (e.g. the response variable such as polar error)
subject_col – name of the column containing subject ID
ind_col – list of independent column name/s (e.g. the variable you are grouping with such as hrtf type)
- spatialaudiometrics.statistics.test_normality(df: DataFrame, dep_col: str, subject_col: str, ind_col: list)
Uses the shapiro test to test if normal
- Parameters:
df – Pandas dataframe that contains the data to run the stats on
dep_col – dependent column name (e.g. the response variable such as polar error)
subject_col – name of the column containing subject ID
ind_col – list of independent column name/s (e.g. the variable you are grouping with such as hrtf type)
- Returns bool:
Returns whether the data is normal (True) or not (False)
- spatialaudiometrics.statistics.tukey_hsd(df: DataFrame, dep_col: str, ind_col: list)
Creates a pariwise comparison table using the Tukey test (for normal data)
- Parameters:
df – data frame you want to run the test on (already aggregated)
dep_col – dependent column name (e.g. the response variable such as polar error)
ind_col – list of independent column name/s (e.g. the variable you are grouping with such as hrtf type)