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.