API

cochlea

Innear ear models in Python.

cochlea.get_nearest_cf_holmberg2007(cf)

Return nearest valid frequency relative to cf.

cochlea.make_brian_group(trains)

Create Brian’s spike generator group from spike trains.

Parameters:

trains : spike_trains

Input spike trains

Returns:

brian.SpikeGeneratorGroup

Brian’s spike generator group.

cochlea.run_holmberg2007(sound, fs, anf_num, seed, cf=None, syn_mode='probability')

Run the inner ear model by [Holmberg2007]. It simulates the traveling wave on the basilar membrane, inner hair cell, synapses and generates auditory nerve spikes. The model takes sound signal as input and outputs auditory nerve spike trains.

Parameters:

sound : array_like

Input sound signal.

fs : float

Sampling frequency of the sound.

anf_num : tuple

Number of auditory nerve fibers per channel (HSR#, MSR#, LSR#).

seed : int

Random seed.

cf : float or array_like or None, optional

Characteristic frequencies. If None, then calculate all 100 predefined CFs. CFs must be a subset of real_freq_map.

syn_mode : {‘probability’, ‘quantal’}, optional

Output mode of the IHC synapse.

Returns:

spike_trains

Auditory nerve spike trains.

References

If you are using results of this or modified version of the model in your research, please cite [Holmberg2007].

[Holmberg2007]

Holmberg, M. (2007). Speech Encoding in the Human Auditory Periphery: Modeling and Quantitative Assessment by Means of Automatic Speech Recognition. PhD thesis, Technical University Darmstadt.

cochlea.run_holmberg2007_vesicles(sound, fs, anf_num, seed, cf=None)

Run the inner ear model by [Holmberg2007] in the quantal mode and return vesicles instead of spikes.

Parameters:

sound : array_like

Input sound signal.

fs : float

Sampling frequency of the sound.

anf_num : tuple

Number of auditory nerve fibers per channel (HSR#, MSR#, LSR#).

seed : int

Random seed.

cf : float or array_like or None, optional

Characteristic frequencies. If None, then calculate all 100 predefined CFs. CFs must be a subset of real_freq_map.

Returns:

pd.DataFrame with vesicle timings

Vesicles in the format of spike_trains.

References

If you are using results of this or modified version of the model in your research, please cite [Holmberg2007].

[Holmberg2007]

Holmberg, M. (2007). Speech Encoding in the Human Auditory Periphery: Modeling and Quantitative Assessment by Means of Automatic Speech Recognition. PhD thesis, Technical University Darmstadt.

cochlea.run_zilany2009(sound, fs, anf_num, cf, seed, cohc=1, cihc=1, powerlaw='approximate')

Run the inner ear model by [Zilany2009].

This model is based on the original implementation provided by the authors. The MEX specific code was replaced by Python code in C files. We also compared the outputs of both implementation (see the tests directory for unit tests).

Parameters:

sound : array_like

Input sound signal.

fs : float

Sampling frequency of the signal.

anf_num : tuple

The desired number of auditory nerve fibers per frequency channel (CF), (HSR#, MSR#, LSR#). For example, (100, 75, 25) means that we want 100 HSR fibers, 75 MSR fibers and 25 LSR fibers per CF.

cf : float or array_like or tuple

The center frequency(s) of the simulated auditory nerve fibers. If float, then defines a single frequency channel. If array_like (e.g. list or ndarray), then the frequencies are used. If tuple, then must have exactly 3 elements (min_cf, max_cf, num_cf) and the frequencies are calculated using the Greenwood function.

seed : int

Random seed.

cohc : flaot, optional

Outer hair cell impairment parameter, must be between <0; 1>.

cihc : flaot, optional

Inner hair cell impairment parameter, must be between <0; 1>.

powerlaw: {‘approximate’, ‘actual’}, optional

Type of the power-law implementation.

Returns:

spike_trains

Auditory nerve spike trains.

Notes

The fractorial Gausian noise from the oryginal implementation is disabled at the moment.

References

If you are using results of this or modified version of the model in your research, please cite [Zilany2009].

[Zilany2009]

(1, 2, 3) Zilany, M. S., Bruce, I. C., Nelson, P. C., & Carney, L. H. (2009). A phenomenological model of the synapse between the inner hair cell and auditory nerve: long-term adaptation with power-law dynamics. The Journal of the Acoustical Society of America, 126(5), 2390-2412.

cochlea.run_zilany2014(sound, fs, anf_num, cf, species, seed, cohc=1, cihc=1, powerlaw='approximate', ffGn=False)

Run the inner ear model by [Zilany2014].

This model is based on the original implementation provided by the authors. The MEX specific code was replaced by Python code in C files. We also compared the outputs of both implementation (see the tests directory for unit tests).

Parameters:

sound : array_like

The input sound in Pa.

fs : float

Sampling frequency of the sound in Hz.

anf_num : tuple

The desired number of auditory nerve fibers per frequency channel (CF), (HSR#, MSR#, LSR#). For example, (100, 75, 25) means that we want 100 HSR fibers, 75 MSR fibers and 25 LSR fibers per CF.

cf : float or array_like or tuple

The center frequency(s) of the simulated auditory nerve fibers. If float, then defines a single frequency channel. If array_like (e.g. list or ndarray), then the frequencies are used. If tuple, then must have exactly 3 elements (min_cf, max_cf, num_cf) and the frequencies are calculated using the Greenwood function.

species : {‘cat’, ‘human’, ‘human_glasberg1990’}

Species.

seed : int

Random seed for the spike generator.

cohc : float <0-1>, optional

Degredation of the outer hair cells.

cihc : float <0-1>, optional

Degredation of the inner hair cells.

powerlaw : {‘approximate’, ‘actual’}, optional

Defines which power law implementation should be used.

ffGn : bool

Enable/disable factorial Gaussian noise.

Returns:

spike_trains

Auditory nerve spike trains.

References

If you are using results of this or modified version of the model in your research, please cite [Zilany2014].

[Zilany2014]

Zilany, M. S., Bruce, I. C., & Carney, L. H. (2014). Updated parameters and expanded simulation options for a model of the auditory periphery. The Journal of the Acoustical Society of America, 135(1), 283-286.

cochlea.run_zilany2014_rate(sound, fs, anf_types, cf, species, cohc=1, cihc=1, powerlaw='approximate', ffGn=False)

Run the inner ear model by [Zilany2014]. Return mean firing rate of the auditory nerve fibers.

Notes

This implementation is was not used very much and may have some problems. Use with caution! (Like any implementation here, BTW)

References

[Zilany2014]

Zilany, M. S., Bruce, I. C., & Carney, L. H. (2014). Updated parameters and expanded simulation options for a model of the auditory periphery. The Journal of the Acoustical Society of America, 135(1), 283-286.

cochlea.set_dbspl(signal, dbspl)

Rescale the signal to a new level in dB SPL.

Parameters:

signal : array_like

Signal for scaling.

dbspl : float

Desired level of the output signal in dB SPL.

Returns:

array_like

Scaled version of the original signal.

cochlea.external

External models.

cochlea.external.run_matlab_auditory_periphery(sound, fs, anf_num, cf, seed, params_name='Normal', matlab_session=None)

Run Matlab Auditory Periphery [MAP] model by Ray Meddis. This function does not implement the model, but wraps the model implementation using matlab_wrapper. The model takes sound signal as input and outputs auditory nerve spike trains.

In order to run it, make sure that all necessary [MAP] model files are in MATLABPATH. You should be able to run MAP1_14 function in MATLAB first!

Requires MATLAB, matlab_wrapper, thorns and [MAP] in MATLABPATH.

Parameters:

sound : array_like

Input sound.

fs : float

Sampling frequency of the sound.

anf_num : tuple

Number of auditory nerve fibers per channel (HSR#, MSR#, LSR#).

cf : float or array_like or tuple

The center frequency(s) of the simulated auditory nerve fibers. If float, then defines a single frequency channel. If array_like (e.g. list or ndarray), then the frequencies are used. If tuple, then must have exactly 3 elements (min_cf, max_cf, num_cf) and the frequencies are calculated using the Greenwood function.

seed : int

Random seed.

params_name : str, optional Tail of the parameter filename

(parameterStore/MAPparams<params_name>.m). Refer to MAP documentation for the details.

matlab_session : MatlabSession or None, optional

MatlabSession object from matlab_wrapper module. If None, then new session is generated.

Returns:

spike_trains

Auditory nerve spike trains.

References

[MAP]

(1, 2, 3, 4) http://www.essexpsychology.macmate.me/HearingLab/modelling.html

cochlea.stats

cochlea.stats.calc_human_hearing_thresholds(freqs)

Calculate human hearing thresholds for given frequencies.

References

E. Terhardt, “Calculating virtual pitch”, Hearing Res., vol. 1, pp. 155–182, 1979.

http://www.diracdelta.co.uk/science/source/t/h/threshold%20of%20hearing/source.html

cochlea.stats.calc_modulation_gain(model, fms=None, cf=10000.0, model_pars=None, m=1, level_above_threshold=10, map_backend=None)

Calculate modulation gain of an inner ear model.

Parameters:

fms : array_like

List of modulation frequencies (Hz).

cf : scalar, optional

Characteristic frequency (Hz).

model_pars : dict, ooptional

Additional parameters to be passed to the model funtion.

m : float, optional

Modulation depth in the range of <0, 1>.

level_above_threshold : scalar, optional

Sound level which will be added to the threshold level to calculate modulation gain.

map_backend : str, optional

Map backend that will be used in the calculation. See thorns.util.map().

cochlea.stats.calc_rate_level(model, dbspls=None, cf=1000, model_pars=None, tone_duration=0.1)

Calculate rate-level characteristic of an auditory model.

Parameters:

dbspls : array_like, optional

An array of sound levels (dB SPL) for which to calculate rates.

cochlea.stats.calc_synchronization(model, cfs=None, dbspls=None, model_pars=None, map_backend=None)

Calculate vector strength of an inner ear model.

cochlea.stats.calc_thresholds_rate(model, cfs=None, model_pars=None, asr_filter=False, map_backend=None)

Calculate rate based hearing threshold of an inner ear model.

cochlea.stats.calc_tuning(model, cf, freqs=None, model_pars=None, map_backend=None)

Calculate runing of the cochlea at cf.