ABR thresholds: fast, accurate, no human needed.
An algorithm for generating ABR thresholds by cross-correlation of resampled subaverages
This code algorithmically thresholds ABR data as described in Shaheen et al. 2024. Instead of averaged waveforms, the algorithm uses the single-trial data (i.e., the response to each presentation of the stimuli). Single-trial data can be collected using psiexperiment's CFTS module.
A full dataset of single-trial ABR waveforms used to test this algorithm is available on Zenodo.
Thresholds are generated by:
- Filtering the data twice, forward and backward each time using a first-order 300–3000 Hz Butterworth filter and the filtfilt function of Python’s SciPy module (for a total of 4 times). The first filtering occurs while loading the data (inside cftsdata.get_epochs_filtered). The second occurs inside the algorithm (XCsub.estimate_threshold)
- Randomly splitting the trials into two groups, each containing an equal number of responses to positive and negative polarity stimuli.
- Calculating the median waveform for each group.
- Calculating the normalized cross correlation between these median waveforms.
- This process (steps 2-4) is repeated 500 times to obtain a reshuffled cross-correlation distribution.
- The mean values of these distributions are computed for each level and fit with a sigmoid and a power law. The fit that provides the best mean squared error is then used, and threshold is defined as where that fit crossed a criterion (default 0.3).
This code must be installed using pip install. To install a version for
in-place modification (e.g., development), use pip install -e.
Full installation steps: (if you are using conda environments, you can create a new environment to install this code, otherwise you can just install directly into your main Python environment):
(if using conda environments) conda create -n ABRpresto python git
(if using conda environments) conda activate ABRpresto
(navigate to the folder containing ABRpresto)
python -m pip install -e ./ABRpresto
Example data is provided in both csv format (example_data) and psi format (example_data_psi).
The psi data is the original format and is unfiltered. It will be filtered once when loaded, and again inside the algorithm.
The csv data has been filtered once already. It isn't filted when loaded from csv, but will be filtered a second time inside the algorithm.
Two example scripts Example_fit_script.py and Example_fit_script_psi.py demonstrate how each of these datasets can be fit using ABRpresto.
Fit_all_examples.py illustrates how ABR.main.run_fit can be called from a script to fit a folder of data.
For CSV data, the algorithm requires data to be passed as a pandas dataframe with a multiindex containing polarity and level. Extra levels in the index will be ignored (e.g., t0 in the example datasets). Each row contains a single trial. Columns are the time relative to stimulus onsset in seconds. A dictionary of results and a figure are returned, which can be saved as json and png.
In the left column the figures show mean +/- SE of all trials in black, and median (or mean, depending on AVmode) for the two subsets. Waveforms are normalized (for each level all 3 lines are scaled by the peak-to-peak of the mean of all trials). The right hand side shows mean correlation coefficient vs stimulus level. Sigmoid and power law fits to this data are shown in green and purple. The threshold is shown by the pink dashed line.
Example_plot_performance.py illustrates how ABRpresto.utils.load_fits can be used to load the fitted thresholds (stored as individual .json files), and aggregate them into a single dataframe that can be saved to a .csv file. It also shows how to use ABRpresto.utils.compare_thresholds to create an interactive plot comparing the thresholds between two thresholders (in this case between manual (human) determined thresholds and those determined by ABRpresto).
A full dataset of single-trial ABR waveforms used to test this algorithm is available on Zenodo. To fit this data using the ABRpresto algorithm, extract the data to a folder and run ABRpresto on the command line:
ABRpresto <path to full dataset> -r
For example, if you extract the data to C:/Data/ABRpresto data run
ABRpresto "C:/Data/ABRpresto data" -r
You can also convert this data to csv format using the included functions, see Example_convert_psi_to_csv.py
The algorithm can be run on the command line to process one or more datasets.
To process a single psi dataset:
ABRpresto <path to dataset>
To process several psi datasets:
ABRpresto <path to dataset 1> <path to dataset2> <etc>
To recursively scan and process all datasets in a folder:
ABRpresto <path> -r
For example, to fit all example psi data, navigate to the ABRpresto directory, then run:
ABRpresto example_data_psi -r
To fit all example csv data, you just need to add the loader option to use the csv data loader. Navigate to the ABRpresto directory, then run:
ABRpresto example_data -r --loader csv
If you use this algorithm in you research, please cite: Shaheen, L. A., Buran, B. N., Suthakar, K., Koehler, S. D., & Chung, Y. (2024). ABRpresto: An algorithm for automatic thresholding of the Auditory Brainstem Response using resampled cross-correlation across subaverages. bioRxiv. https://doi.org/10.1101/2024.10.31.621303
The curve fitting decision tree used in this algorithm was inspired by Suthakar et al. If you use this algorithm please also cite their paper: Suthakar, K. & Liberman, M. C. A simple algorithm for objective threshold determination of auditory brainstem responses. Hear. Res. 381, 107782 (2019).
Please see LICENSE