clarity.evaluator.msbg package

Subpackages

• clarity.evaluator.msbg.msbg_hparams package
  • Module contents

Submodules

clarity.evaluator.msbg.cochlea module

Gammatone filterbank simulation of the Cochlea.

class clarity.evaluator.msbg.cochlea.Cochlea(audiogram: Audiogram, catch_up_level: float = 105.0, fs: float = 44100.0)

Bases: object

Simulate the cochlea.

Includes simulation of effects of bandwidth broadening (smearing) and recruitment. Implements 3 different degrees of impairment which affect the degree of smearing. Recruitment currently always with x2 broadening.

Degree of hearing impairment used to control the following filterbank variables: BROADEN, SPACING, NGAMMA, Fs, N_Chans, ERBn_CentFrq, GTn_CentFrq, GTnDelays, GTn_denoms, GTn_nums, Start2PoleHP, HP_FCorner, HP_denoms, HP_nums, HP_Delays, Recombination_dB

simulate(coch_sig: ndarray, equiv_0dB_file_SPL: float) → ndarray

Pass a signal through the cochlea.

Parameters:

• coch_sig (ndarray) – input signal

• equiv_0dB_file_SPL (float) – equivalent level in dB SPL of 0 dB Full Scale

Returns:

cochlear output signal

Return type:

ndarray

class clarity.evaluator.msbg.cochlea.FilterBank(nums: ndarray, denoms: ndarray)

Bases: object

Holds the numerators and denominators of an IIR filter bank.

denoms: ndarray

nums: ndarray

clarity.evaluator.msbg.cochlea.compute_envelope(coch_sig: ndarray, erbn_cf: ndarray, fs: float) → ndarray

Obtain signal envelope.

Envelope computed using full-wave rectification and low-pass filter

Parameters:

• coch_sig (ndarray) – input signal

• erbn_cf (ndarray) – ERB centre frequencies

• fs (float) – sampling frequency

Returns:

signal envelope

Return type:

ndarray

clarity.evaluator.msbg.cochlea.compute_recruitment_parameters(gtn_cf: ndarray, audiogram: Audiogram, catch_up: float) → tuple[ndarray, ndarray]

Compute parameters to be used in recruitment model.

Computes expansion ratios for each gammatone filterbank channel and the equal loudness catch up level per channel (currently this is a fixed value per channel)

Parameters:

• gtn_cf (ndarray) – gammatone filterbank centre frequencies

• audiogram (Audiogram) – the audiogram to employ

• catch_up (float) – level in dB at which catches up with NH

Returns:

expansion ratio for each gammatone filterbank channel

Return type:

ndarray

clarity.evaluator.msbg.cochlea.gammatone_filterbank(x: ndarray, ngamma: int, gtn_filters: FilterBank, gtn_delays: ndarray, start2poleHP: int, hp_filters: FilterBank) → ndarray

Pass signal through gammatone filterbank.

Parameters:

• x (ndarray) – input signal

• ngamma (int) – 4, gammatone order

• gtn_filters (FilterBank) – set of gammatone filters

• gtn_delays (ndarray) – gammatone filter delays

• start2poleHP (int) – parameter value from gtfbank_file

• hp_filter (FilterBarker) – set of highpass filters

Returns:

cochleagram with gtn_denoms.shape[0] channels of len(x)

Return type:

ndarray

clarity.evaluator.msbg.cochlea.recruitment(coch_sig: ndarray, envelope: ndarray, SPL_equiv_0dB: int | float, expansion_ratios: ndarray, eq_loud_db: ndarray) → ndarray

Simulate loudness recruitment.

Parameters:

• coch_sig (ndarray) – input signal

• envelope (ndarray) – signal envelope

• SPL_equiv_0dB (float) – equivalent level in dB SPL of 0 dB Full Scale

• expansion_ratios (ndarray) – expansion ratios for expanding channel signals

• eq_loud_db (ndarray) – loudness catch-up level in dB

Returns:

cochlear output signal

Return type:

ndarray

clarity.evaluator.msbg.msbg module

Implementation of the MSBG hearing loss model.

class clarity.evaluator.msbg.msbg.Ear(src_pos: str = 'ff', sample_rate: float = 44100.0, equiv_0db_spl: float = 100.0, ahr: float = 20.0)

Bases: object

Representation of a pairs of ears.

static get_src_correction(src_pos: str) → ndarray

Select relevant external field to eardrum correction.

Parameters:

src_pos (str) – Position of src. One of ff, df or ITU

make_calibration_signal(ref_rms_db: float, n_channels: int = 1) → tuple[ndarray, ndarray]

Add the calibration signal to the start of the signal.

Parameters:

ref_rms_db (float) – reference rms level in dB

Returns:

tuple[ndarray, ndarray] - pre and post calibration signals

process(signal: ndarray, add_calibration: bool = False) → list[ndarray]

Run the hearing loss simulation.

Parameters:

• signal (ndarray) – signal to process, shape either N, Nx1, Nx2

• add_calibration (bool) – prepend calibration tone and speech-shaped noise (default: False)

Returns:

the processed signal

Return type:

np.ndarray

set_audiogram(audiogram: Audiogram) → None

Set the audiogram to be used.

static src_to_cochlea_filt(input_signal: ndarray, src_correction: ndarray, sample_rate: float, backward: bool = False) → ndarray

Simulate middle and outer ear transfer functions.

Made more general, Mar2012, to include diffuse field as well as ITU reference points, that were included in DOS-versions of recruitment simulator, released ca 1999-2001, and on hearing group website, Mar2012 variable [src_pos] takes one of 3 values: ‘ff’, ‘df’ and ‘ITU’ free-field to cochlea filter forwards or backward direction, depends on ‘backward’ switch. NO LONGER via 2 steps. ff to eardrum and then via middle ear: use same length FIR 5-12-97.

Parameters:

• input_signal (ndarray) – signal to process

• src_correction (np.ndarray) – correction to make for src position as an array returned by get_src_correction(src_pos) where src_pos is one of ff, df or ITU

• sample_rate (int) – sampling frequency

• backward (bool, optional) – if true then cochlea to src (default: False)

Returns:

the processed signal

Return type:

np.ndarray

clarity.evaluator.msbg.msbg_utils module

Support for the MSBG hearing loss model.

class clarity.evaluator.msbg.msbg_utils.GTFParamDict

Bases: TypedDict

BROADEN: float

DateCreated: str

ERBn_CentFrq: list[float]

Fs: int

GTnDelays: list[int]

GTn_CentFrq: list[float]

GTn_denoms: list[list[float]]

GTn_nums: list[list[float]]

HP_Delays: list[int]

HP_FCorner: list[float]

HP_denoms: list[list[float]]

HP_nums: list[list[float]]

NChans: int

NGAMMA: int

Recombination_dB: float

SPACING: float

Start2PoleHP: int

clarity.evaluator.msbg.msbg_utils.fir2(filter_length: int, frequencies: list[float] | ndarray, filter_gains: list[float] | ndarray, window_shape: ndarray | None = None) → tuple[ndarray, int]

FIR arbitrary shape filter design using the frequency sampling method.

Partial implementation of MATLAB fir2.

Parameters:

• filter_length (int) – Order

• frequencies (ndarray) – The frequency sampling points (0 < frequencies < 1) where 1 is Nyquist rate. First and last elements must be 0 and 1 respectively.

• filter_gains (ndarray) – The filter gains at the frequency sampling points.

• window_shape (ndarray, optional) – window to apply. (default: hamming window)

Returns:

nn + 1 filter coefficients, 1

Return type:

np.ndarray

clarity.evaluator.msbg.msbg_utils.firwin2(n_taps: int, frequencies: list[float] | ndarray, filter_gains: list[float] | ndarray, window: tuple[str, int] | str | None = None, antisymmetric: bool | None = None) → ndarray

FIR filter design using the window method.

Partial implementation of scipy firwin2 but using our own MATLAB-derived fir2.

Parameters:

• n_taps (int) – The number of taps in the FIR filter.

• frequencies (ndarray) – The frequency sampling points. 0.0 to 1.0 with 1.0 being Nyquist.

• filter_gains (ndarray) – The filter gains at the frequency sampling points.

• window (string or (string, float), optional) – See scipy.firwin2. Default is None

• antisymmetric (bool, optional) – Unused but present to maintain compatibility with scipy firwin2.

Returns:

The filter coefficients of the FIR filter, as a 1-D array of length n.

Return type:

ndarray

clarity.evaluator.msbg.msbg_utils.gen_eh2008_speech_noise(duration: float, sample_rate: float = 44100.0, level: float | None = None, supplied_b: None = None) → ndarray

Generate speech shaped noise.

Start with white noise and re-shape to ideal SII, ie flat to 500 Hz, and sloping

-9db/oct beyond that.

Slightly different shape from SII stylised same as EarHEar 2008 paper, Moore et al.

Parameters:

• duration (float) – Duration of signal in seconds

• sample_rate (float) – Sampling rate

• level (float, optional) – Normalise to level dB if present

• supplied_b (ndarray, optional) – High-pass filter. Default uses built-in pre-emphasis filter

Returns:

Noise signal

Return type:

ndarray

clarity.evaluator.msbg.msbg_utils.gen_tone(freq: int, duration: float, sample_rate: float = 44100.0, level: float = 0.0) → ndarray

Generate a pure tone.

Parameters:

• freq (float) – Frequency of tone in Hz.

• duration (float) – Duration of tone in seconds.

• sample_rate (float, optional) – Sample rate of generated tone in Hz. Default is 44100.

• level (float, optional) – Level of tone in dB SPL. Default is 0.

Returns:

np.ndarray

clarity.evaluator.msbg.msbg_utils.generate_key_percent(signal: ndarray, threshold_db: float, window_length: int, percent_to_track: float | None = None) → tuple[ndarray, float]

Generate key percent. Locates frames above some energy threshold or tracks a certain percentage of frames. To track a certain percentage of frames in order to get measure of rms, adaptively sets threshold after looking at histogram of whole recording

Parameters:

• signal (ndarray) – The signal to analyse.

• threshold_db (float) – fixed energy threshold (dB).

• window_length (int) – length of window in samples.

• percent_to_track (float, optional) – Track a percentage of frames. Default is None

Raises:

ValueError – percent_to_track is set too high.

Returns:

containing - key (ndarray): The key array of indices of samples used in rms calculation. - used_threshold_db (float): Root Mean Squared threshold.

and the threshold used to get a more accurate rms calculation

Return type:

(tuple)

clarity.evaluator.msbg.msbg_utils.measure_rms(signal: ndarray, sample_rate: float, db_rel_rms: float, percent_to_track: float | None = None) → tuple[float, ndarray, float, float]

Measure Root Mean Square.

A sophisticated method of measuring RMS in a file. It splits the signal up into short windows, performs a histogram of levels, calculates an approximate RMS, and then uses that RMS to calculate a threshold level in the histogram and then re-measures the RMS only using those durations whose individual RMS exceed that threshold.

Parameters:

• signal (ndarray) – the signal of which to measure the Root Mean Square.

• sample_rate (float) – sampling frequency.

• db_rel_rms (float) – threshold for frames to track.

• percent_to_track (float, optional) – track percentage of frames, rather than threshold (default: {None})

Returns:

tuple containing - rms (float): overall calculated rms (linear) - key (ndarray): “key” array of indices of samples used in rms calculation - rel_db_thresh (float): fixed threshold value of -12 dB - active (float): proportion of values used in rms calculation

Return type:

(tuple)

clarity.evaluator.msbg.msbg_utils.pad(signal: ndarray, length: int) → ndarray

Zero pad signal to required length.

Assumes required length is not less than input length.

clarity.evaluator.msbg.msbg_utils.read_gtf_file(gtf_file: str) → GTFParamDict

Read a gammatone filterbank file.

List data is converted into numpy arrays.

clarity.evaluator.msbg.smearing module

Temporal smearing component of MSBG model.

class clarity.evaluator.msbg.smearing.Smearer(rl: float, ru: float, sample_rate: float)

Bases: object

Class to hold the re-usable smearing filter.

smear(input_signal: ndarray) → ndarray

Smear a given input signal.

clarity.evaluator.msbg.smearing.audfilt(rl: float, ru: float, sample_rate: float, asize: int = 256) → ndarray

Calculate an auditory filter array.

Parameters:

• rl (float) – broadening factor on the lower side

• ru (float) – broadening factor on the upper side

• sample_rate (float) – signal sampling frequency

• asize (int, optional) – number of taps in filter (default: {256})

Returns:

A bank of auditory filters stored as 2-d numpy array

Return type:

ndarray

clarity.evaluator.msbg.smearing.make_smear_mat3(rl: float, ru: float, sample_rate: float) → ndarray

Make the smearing filter matrix.

Parameters:

• rl (float) – filter broadening factor on the lower side

• ru (float) – filter broadening factor on the upper side

• sample_rate (float) – sampling frequency

Returns:

The FFT_SIZE/2 X FFT_SIZE/2 smearing filter matrix

Return type:

ndarray

clarity.evaluator.msbg.smearing.smear3(f_smear: ndarray, inbuffer: ndarray) → ndarray

Direct translation of smear3.m from MSBG hearing loss model.

Parameters:

• f_smear (ndarray) – The FFT_SIZE/2 X FFT_SIZE/2 smearing filter matrix

• inbuffer (ndarray) – signal with prepended tone and noise

Returns:

outbuffer

Return type:

ndarray

Module contents