simplecochlea package¶

Subpackages¶

Submodules¶

simplecochlea.cochlea module¶

This file is part of simplecochlea.

simplecochlea is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

simplecochlea is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with simplecochlea. If not, see <https://www.gnu.org/licenses/>.

class simplecochlea.cochlea.BandPassFilterbank(order, wn, fs, ftype='butter')[source]¶

Bases: object

Band-pass Filterbank Class Defines a bank of band-pass filters. The Cochlea class uses it to model the inner hair cells.

Attributes:

fs : float Sampling frequency (Hz). Each BandPassFilterbank instance must be applied to signals with the same sampling frequency. order : int Filter order ftype : str Filter type. Must be in : ‘butter’ : Butterworth filters ‘bessel’ : Bessel filters ‘fir’ : FIR filters n_filters : int Number of band-pass filters a : array Filter coefficients - equal to 1 if FIR filters b : array Filter coefficients

Methods

filter_one_channel(input_sig, channel_pos[, …])	Filter input signal input_sig with channel specified by channel_pos
filter_signal(input_sig[, do_plot, zi_in])	Filter input signal input_sig.
plot_caracteristics([n_freqs])	Plot the frequency response of the differents band-pass filters

filter_one_channel(input_sig, channel_pos, zi_in=[])[source]¶

Filter input signal input_sig with channel specified by channel_pos

Parameters:	input_sig : array Input signal channel_pos : int Channel position zi_in : array Initial conditions for the filter delays - default : None
Returns:	output : array (1D) Output filtered signal zi_out : array Final filter delay values

filter_signal(input_sig, do_plot=0, zi_in=[])[source]¶

Filter input signal input_sig. Input signal is passed through all the band-pass filters.

Parameters:	input_sig : array Input signal do_plot : bool If True, plot the output filtered signals as an image. zi_in : array Initial conditions for the filter delays - default : None
Returns:	output : array (2D) Output filtered signals [n_filters * n_pnts] zi_out : array Final filter delay values

plot_caracteristics(n_freqs=1024)[source]¶

Plot the frequency response of the differents band-pass filters

Parameters:	n_freqs : int Number of frequencies used to compute the frequency response - Default : 1024
Returns:	ax : handle Pyplot axis handle

class simplecochlea.cochlea.Cochlea(n_channels, fs, fmin, fmax, freq_scale, order=2, fbank_type='butter', rect_type='full', rect_lowpass_freq=[], comp_factor=0.3333333333333333, comp_gain=1, lif_tau=0.01, lif_v_thresh=0.02, lif_v_spike=0.035, lif_t_refract=0.001, lif_v_reset=[], inhib_vect=[], tau_j=[], alpha_j=[], omega=[])[source]¶

Bases: object

Attributes:	cf compressionbank filterbank fmax fmin forder freq_scale fs lifbank n_channels rectifierbank

Methods

plot_channel_evolution(input_sig[, channel_pos])	Plot the processing of input_sig signal through the cochlea, for channels specified by channel_pos.
process_input(input_sig[, do_plot])	Process input signal through the Cochlea
process_one_channel(input_sig, channel_pos)	Process a signal with 1 channel of the cochlea
process_test_signal(signal_type[, …])	Run a test signal through the cochlea.
save(dirpath[, filename])	Save the cochlea.

cf¶

compressionbank¶

filterbank¶

fmax¶

fmin¶

forder¶

freq_scale¶

fs¶

lifbank¶

n_channels¶

plot_channel_evolution(input_sig, channel_pos=[])[source]¶

Plot the processing of input_sig signal through the cochlea, for channels specified by channel_pos. If channel_pos is not provided, 4 channels are selected ranging from low-frequency channel to high-frequency channel.

Parameters:	input_sig : array [1D] Input signal channel_pos : scalar | array | list | None Position of the channel(s) to plot. If multiples channels are selected, plot one figure per channel. If none, 4 channels are selected ranging from low-frequency channel to high-frequency channel.

process_input(input_sig, do_plot=False)[source]¶

Process input signal through the Cochlea

Parameters:	input_sig : array (1D) Input signal do_plot : bool If True, plot the differents steps of the cochlea
Returns:	spikelist : SpikeList Output spikelist (sig_filtered, sig_rectified, sig_comp, lif_out_sig) : tuple Contains the intermediary signals correponding to the different steps of the cochlea

process_one_channel(input_sig, channel_pos)[source]¶

Process a signal with 1 channel of the cochlea

Parameters:	input_sig : array [1D] Input signal channel_pos : scalar | array | list | None Position of the channel(s) to plot. If multiples channels are selected, plot one figure per channel. If none, 4 channels are selected ranging from low-frequency channel to high-frequency channel.
Returns:	sig_filtered : array [n_chan, n_pnts] Signals after the band pass filterbank sig_rectiry : array [n_chan, n_pnts] Signals after the rectifier bank sig_compressed : array [n_chan, n_pnts] Signals after the compression bank lif_out_sig : array [n_chan, n_pnts] Signals after the LIF bank (Membrane potential) t_spikes : array Spikes time (s)

process_test_signal(signal_type, channel_pos=[], do_plot=True, **kwargs)[source]¶

Run a test signal through the cochlea. Test signals can be a sinusoidal signal, a step or an impulse signal. Argument signal_type selects the wanted signal. If channel_pos is provided and do_plot is True, channel evolution is plot.

Parameters:	signal_type : str Test signal type. To choose between : ‘sin’ or ‘sinus’ : Sinusoidal signal ‘dirac’ or ‘impulse’: Impulse signal ‘step’ : Step signal channel_pos : int Channel position do_plot : bool If True, plot the results kwargs : Test signal parameters : ‘t_offset’, ‘t_max’, ‘amplitude’, ‘f_sin’ (for sinusoids only)
Returns:	spikelist : SpikeList Output spikelist

rectifierbank¶

save(dirpath, filename=[])[source]¶

Save the cochlea. The cochlea model is saved as a .p (pickle) file. The filename is appended with the current date and time.

Parameters:	dirpath : str Directory path filename : str Cochlea filename.

class simplecochlea.cochlea.CochleaEstimator(fs, n_filters, fmin, fmax, freq_scale=['linearscale', 'erbscale'], forder=[2], fbank_type=['butter', 'bessel'], comp_gain=array([0.8]), comp_factor=array([0.33333333, 0.25 , 0.2 ]), lif_tau_coeff=[0.5, 1, 3], lif_v_thresh_start=[0.3, 0.4, 0.5], lif_v_thresh_stop=[0.1, 0.15], lif_v_thresh_mid=[])[source]¶

Bases: object

Methods

grid_search
grid_search_atom
plot_param_scores
plot_results
print_cochlea_parameters
process_input

grid_search(input_sig, t_chunk_start, t_chunk_end, pattern_pos, input_sig_name='')[source]¶

grid_search_atom(param_i, input_sig, t_chunk_start, t_chunk_end, pattern_pos)[source]¶

plot_param_scores(global_score, vr_score, spkchanvar_score, channel_with_spikes_ratio, n_spikes_mean, param_key=[], inner='box')[source]¶

plot_results(global_score, vr_score, spkchanvar_score, channel_with_spikes_ratio, n_spikes_mean, param_grid, params_to_plot=['fmin', 'fmax', 'forder', 'freq_scale', 'fbank_type', 'comp_gain', 'comp_factor', 'lif_tau_coeff', 'lif_v_thresh_start', 'lif_v_thresh_stop', 'lif_v_thresh_mid'], order=[])[source]¶

print_cochlea_parameters(param_grid, grid_pos)[source]¶

process_input(cochlea, input_sig, t_chunk_start, t_chunk_end, pattern_pos, block_len_max=50000, w_vr=4, w_spkchanvar=1)[source]¶

class simplecochlea.cochlea.CompressionBank(n_channels, fs, comp_factor, comp_gain)[source]¶

Bases: object

CompressionBank Class Parralel association of compression units. Apply an amplitude compression using a logarithmic transform :

\(f(x) = comp_{gain} * x^{comp_{factor}}\)

Each channel can have a separate compression gain and compression factor. In the cochlea, the compression bank follows the rectifier bank and precede the LIF bank.

Attributes:	fs : float Sampling frequency (Hz). Each BandPassFilterbank instance must be applied to signals with the same sampling frequency. n_channels : int Number of channels comp_factor : float | array Compression factor - \(f(x) = comp_{gain} * x^{comp_{factor}}\) comp_gain : float | array Compression gain - \(f(x) = comp_{gain} * x^{comp_{factor}}\)

Methods

compress_one_channel(input_sig, channel_pos)	Apply the compression to input signal input_sig with channel specified by channel_pos
compress_signal(input_sig[, do_plot])	Compress input signal input_sig.

compress_one_channel(input_sig, channel_pos)[source]¶

Apply the compression to input signal input_sig with channel specified by channel_pos

Parameters:	input_sig : array (1D) Input signal channel_pos : int Channel position
Returns:	output_sig : array (1D) Output compressed signal

compress_signal(input_sig, do_plot=0)[source]¶

Compress input signal input_sig. Each channel of the input signal is compressed by its correponding compression unit.

Parameters:	input_sig : array (1D) Input signal do_plot : bool If True, plot the output rectified signals as an image.
Returns:	output_sig : array (2D) Output rectified signal [n_filters * n_pnts]

class simplecochlea.cochlea.LIFBank(n_channels, fs, tau, v_thresh=0.02, v_spike=0.035, t_refract=[], v_reset=[], inhib_vect=[], tau_j=[], alpha_j=[], omega=[])[source]¶

Bases: object

Leaky Integrate and Fire (LIF) Bank Parralel association of LIF neuron model. The LIF neuron is a simple spiking neuron model where the neuron is modeled as a leaky integrator of the input synaptic current I(t).

A refractiory period can be defined preventing the neuron to fire just after emitting a spike.

By default each LIF unit (i.e. channel) is independant from the others. To model more complex comportement, lateral inhibition can be added between units (channels). This lateral inhibition is inspired from [1].

Adaptive threshold is another option. Instead of using a fixed spiking threshold defined bt v_thresh, it is possible to model an adaptive threshold using the tau_j, alpha_j and omega attributes. These variables implements the adaptive threshold model described in [2].

References

[1]	Gershon G. Furman and Lawrence S. Frishkopf. Model of Neural Inhibition in the Mammalian Cochlea. The Journal of the Acoustical Society of America 1964 36:11, 2194-2201

[2]	Kobayashi Ryota, Tsubo Yasuhiro, Shinomoto Shigeru. Made-to-order spiking neuron model equipped with a multi-timescale adaptive threshold. Frontiers in Computational Neuroscience. 2009

Attributes:

fs : float Sampling frequency (Hz). Each LIFBank instance must be applied to signals with the same sampling frequency. n_channels : int Number of channels tau : float | array Time constant (s) v_thresh : float | array Spiking threshold - Default : 0.020 v_spike : float | array Spike potential - Default : 0.035 t_refract : float | array | None Refractory period (s). If none, no refractory period - Default : None v_reset : float | array | None Reset potential after a spike. Can act as a adaptable refractory period. inhib_vect : array | None - Default If defined, lateral inhibition is activated. If none, no lateral inhibition tau_j : array (1D) | None Time constants for the adaptive threshold. Usually no more than 3 time constants are needed. See [2]. alpha_j : array (1D) | None Coefficients for each time constant defined by tau_j. omega : float Threshold resting value (minimum threshold value).

Methods

filter_one_channel(input_sig, i[, v_init, …])	Filter one channel
filter_signal(input_sig[, v_init, t_start, …])	Parameters:
plot_caracteristics()	Plot the LIFBank characteristics

filter_one_channel(input_sig, i, v_init=[], t_start=0, t_last_spike=[])[source]¶

Filter one channel

Parameters:	input_sig : 1D array Input vector to be passed through the LIF i : int Channel position v_init : array Initial LIF potential t_start : float (default: 0) ??? t_last_spike : float | none (default: none) Time of the last spike
Returns:	v_out : array [n_pnts] LIF output potential t_spikes : array [n_spikes] Spikes time threshold : array [n_pnts] Threshold at each time point

filter_signal(input_sig, v_init=[], t_start=0, t_last_spike=[])[source]¶

Parameters:	input_sig : array [1D] Input signal v_init : array Initial LIF potential t_start : float (default: 0) ??? t_last_spike : float | none (default: none) Time of the last spike
Returns:	output_sig : array [n_chan, n_pnts] LIF output potential spikes : array [n_spikes, 2] First column contain the spikes time; the 2nd column contains the spike channel

plot_caracteristics()[source]¶

Plot the LIFBank characteristics

class simplecochlea.cochlea.RectifierBank(n_channels, fs, rtype='half', lowpass_freq=[], filtorder=1)[source]¶

Bases: object

RectifierBank Class Parralel association of rectifier units. Half and full rectification are possible :

• half-rectification : \(f(x) = x if x > 0, 0 otherwise\)
• full-rectification : \(f(x) = abs(x)\)

Rectification can include a low-pass filtering using a Butterworth filters. Each channel can have its own filtering cutoff frequency. The cochlea uses a rectifier bank just after the band-pass filtering step.

Attributes:

fs : float Sampling frequency (Hz). Each RectifierBank instance must be applied to signals with the same sampling frequency. n_channels : int Number of channels rtype : str Rectification type - to choose in : (Default : ‘half’) ‘half’ : \(f(x) = x if x > 0, 0 otherwise\) ‘full’ : \(f(x) = abs(x)\) lowpass_freq : flaot | array | None Low pass filter cutoff frequency. If scalar all channels are filtered in the same way. If it contains as much frequencies as there are channels, each channel is filtered with its own cutoff frequency. If None, no filtering. Default : None filtorder : int Order of the low-pass filter filttype : str Indicates the filtering scheme : ‘global’ : all channels are filtered with the same filter ‘channel’ : each channel has its own filtering parameters ‘none’ : no low-pass filtering a : array Low-pass filter coefficients b : array Low-pass filter coefficients

Methods

rectify_one_channel(input_sig, channel_pos)	Rectify input signal input_sig with channel specified by channel_pos
rectify_signal(input_sig[, do_plot])	Rectify input signal input_sig.

rectify_one_channel(input_sig, channel_pos)[source]¶

Rectify input signal input_sig with channel specified by channel_pos

Parameters:	input_sig : array (1D) Input signal channel_pos : int Channel position
Returns:	output_sig : array (1D) Output rectified signal

rectify_signal(input_sig, do_plot=0)[source]¶

Rectify input signal input_sig. Each channel of the input signal is rectified by its correponding rectifier.

Parameters:	input_sig : array (1D) Input signal do_plot : bool If True, plot the output rectified signals as an image.
Returns:	output_sig : array (2D) Output rectified signal [n_filters * n_pnts]

simplecochlea.cochlea.load_cochlea(dirpath, filename)[source]¶

Load the cochlea in pickle format (.p) defined by filename in dirpath

simplecochlea.cochlea.timethis(func)[source]¶

simplecochlea.generate_signals module¶

This file is part of simplecochlea.

simplecochlea is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

simplecochlea is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with simplecochlea. If not, see <https://www.gnu.org/licenses/>.

simplecochlea.generate_signals.delete_zero_signal(dirpath)[source]¶

There are some null signals (only zero amplitude) in the ABS directory. This function delete them. Delete also constant signals (only one single amplitude)

simplecochlea.generate_signals.generate_abs_stim(dirpath, chunk_duration, n_repeat_target, n_noise_iter=1)[source]¶

Generate a stimulus used for Audio Brain Spotting (ABS). The stimulus is composed of one repeating target sound, between n_noise_iter noise sound. It alternate between n_noise_iter noise sound (non-repeating one) and the target sound, starting with a noise sound.

Parameters:	dirpath : str Path of the directory containing the ABS stimuli chunk_duration : float Duration of each segment (s) n_repeat_target : int Number of times the target sound is repeated n_noise_iter : int Number of noise segments between 2 target repetition
Returns:	fs : float Sampling frequency (Hz) sound_merged : array Output ABS stimulus sound_order : array Pattern ID of each segment sound_names : array Pattern name of each segment sig_target_norm : array Target signal

simplecochlea.generate_signals.generate_dirac(fs, t_offset=0.2, t_max=1, amplitude=1)[source]¶

Generate a impulse signal (mathematically defined by the Dirac delta function)

Parameters:	fs : float Sampling frequency (Hz) t_offset : float Time offset of the impulse - Default : 0.2 t_max : float Duration of the output signal - Default : 1 amplitude : float Amplitude of the impulse - Default : 1
Returns:	sig_dirac : array Output impulse signal

simplecochlea.generate_signals.generate_sinus(fs, f_sin, t_offset=0, t_max=1, amplitude=1)[source]¶

Generate a signal containing one or more sinusoides. If multiples frequencies are defined by f_sin parameter, the output signal is the sum of the different sinusoides.

Parameters:	fs : float Sampling frequency (Hz) f_sin : float | array Frequency(ies) of the sinusoide(s). t_offset : float | array Time offset of the origin of the sinusoide(s) - Default : 0 t_max : float Duration of the signal (s) - Default : 1 amplitude : float | array Amplitude of the sinusoide(s) - Default : 1
Returns:	signal_out : array Output sinusoidal signal

simplecochlea.generate_signals.generate_step(fs, t_offset=0.2, t_max=1, amplitude=1)[source]¶

Generate a impulse signal (mathematically defined by the Dirac delta function)

Parameters:	fs : float Sampling frequency (Hz) t_offset : float Time offset of the impulse - Default : 1 t_max : float Duration of the output signal - Default : 1 amplitude : float Amplitude of the impulse - Default : 1
Returns:	sig_step : array Output step signal

simplecochlea.generate_signals.get_abs_stim_params(chunk_duration_s, n_repeat_target, n_noise_iter)[source]¶

For a sequence when a target segment is repeating n_repeat_target timesand interleaved by n_noise_iter noise segments, returns the pattern of each segments

Parameters:	chunk_duration_s : float Duration of each segment (s) n_repeat_target : int Number of repetition of the target n_noise_iter : int Number of noise segments between two target repetitions
Returns:	pattern_id : array Pattern ID of each segment pattern_name_dict : dict Dictionnary giving the label of each pattern ID chunk_start : array Starting time of each segment chunk_end : array Ending time of each segment

simplecochlea.generate_signals.merge_wav_sound_from_dir(dirpath, chunk_duration, n_sounds, n_repeat_per_sound=1, max_sound_repet=1)[source]¶

Parameters:	dirpath : str Path of the directory containing the ABS stimuli chunk_duration : float Duration of each segment (s) n_sounds : int Number of different sound in the sequence n_repeat_per_sound : int | array (default: 1) Number of repetition for each sound max_sound_repet : int Maximal number of times a sound can appears in a row
Returns:	fs : float Sampling rate(Hz) sound_merged : array Output sound sequence sound_order : array Number of the sound in the sequence sound_names : array Name of the sound in the sequence

simplecochlea.generate_signals.plot_signal(x, fs, ax=[])[source]¶

Plot signal x

simplecochlea.utils_freqanalysis module¶

Module contents¶

Simple-Cochlea Main Package