pytimbre.utilities.fractional_octave_band.FractionalOctaveBandTools

class pytimbre.utilities.fractional_octave_band.FractionalOctaveBandTools

Bases: object

Conversion and manipulation for fractional octave band center frequencies and band numbers.

__init__()

Methods

__init__()

ansi_band_limits([class_, fc, nth_oct])

This function will calculate the constant percentage bandwidth description of the accepted shape based on the ANSI S1.11 standard.

band_width(resolution, band)

Calculate the exact frequency band width of a corresponding band number for a specific fractional octave band interval.

center_frequency(resolution, band)

Calculate the exact center frequency of a corresponding band number for a specific fractional octave band interval.

center_frequency_to_erb(frequency)

This function converts the center frequency to the Equivalent Rectangular Band (ERB)

detect_peaks(array[, freq, cthr, ...])

Function detects the peaks in array, based from the mirpeaks algorithm.

erb_to_center_frequency(erb)

exact_band_number(resolution, frequency)

Determine the exact non-integer value of band number of a frequency for a specific fractional octave band interval.

filter_shape([bandwidth, center_frequency, ...])

This function defines the shape of the one-third octave band based on the narrowband frequencies that are provided.

filter_third_octaves_downsample(waveform[, ...])

Filters the audio file into third octave bands

frequencies(start_band, end_band, resolution)

Calculate the exact band center frequencies between a start and stop band number for a specific fractional octave band interval.

frequencies_ansi_preferred([f0, f1, bandwidth])

This function provides the list of accepted frequencies from the ANSI S1.6 definition of the shape of fractional octave bands.

get_frequency_array([band_width, f0, f1])

get_min_audible_fields()

Gather the minimum audible field values within the calculated frequencies from 10 Hz to 10 kHz

lower_frequency(resolution, band)

Calculate the exact lower frequency of a corresponding band number for a specific fractional octave band interval.

midbands(minimum_frequency, ...)

Divides the frequency range into third octave bands using filters

min_audible_field(frequency)

This function calculates a curve fit to the minimum audible field according to an equation provided by NASA in the AUDIB code.

tob_frequencies()

The exact frequencies from 10 Hz to 10 kHz using the center_frequency function at the one-third frequency resolution.

tob_frequencies_ansi()

The accepted frequencies for the one-third-octave bands from 10 Hz to 10 kHz

tob_to_erb(x, spl)

Convert the data form the one-third-octave bandwidth to the equivalent rectangular band bandwidth

upper_frequency(resolution, band)

Calculate the exact upper frequency of a corresponding band number for a specific fractional octave band interval.
static ansi_band_limits(class_: int = 0, fc: float = 1000, nth_oct: int = 3)

This function will calculate the constant percentage bandwidth description of the accepted shape based on the ANSI S1.11 standard.

Parameters:

  • class (int) – the class of the filter that we are trying to design

  • fc (float) – default: 1000 - the center frequency of the band that we are plotting

Returns:

  • frequency (float) – array-like - the collection of frequencies

  • shape_lo (float) – array-like - the levels of the lower limit of the filter design

  • shape_hi (float) – array-like - the levels of the upper limit of the filter design

static band_width(resolution, band)

Calculate the exact frequency band width of a corresponding band number for a specific fractional octave band interval.

Parameters:

  • resolution (int, float) – Used to specify the fractional octave band interval as 1/resolution. Intervals of 1, 1/3, 1/6, 1/12, and 1/24 are available. See ‘center_frequency’_ for band number/frequency pairs for common intervals.

  • band (int, float) – fractional octave band number

Returns:

frequency band width in Hz

Return type:

float

static center_frequency(resolution, band)

Calculate the exact center frequency of a corresponding band number for a specific fractional octave band interval.

Parameters:

  • resolution (int, float) – Used to specify the fractional octave band interval as 1/resolution. Intervals of 1, 1/3, 1/6, 1/12, and 1/24 are available. See ‘center_frequency’_ for band number/frequency pairs for common intervals.

  • band (int, float) – fractional octave band number

Returns:

band center frequency in Hz

Return type:

float

Note:

The band numbers that correspond to preferred band center frequencies include:

+-----------------+----+------+----+----+----+------+----+----+----+----+-----+-----+-----+-----+-----+
|                 | 10 | 12.5 | 16 | 20 | 25 | 31.5 | 40 | 50 | 63 | 80 | 100 | 125 | 160 | 200 | 250 |
+=================+====+======+====+====+====+======+====+====+====+====+=====+=====+=====+=====+=====+
| 1 Octave Band   |    |      | -6 |    |    | -5   |    |    | -4 |    |     | -3  |     |     | -2  |
+-----------------+----+------+----+----+----+------+----+----+----+----+-----+-----+-----+-----+-----+
| 1/3 Octave Band | 10 | 11   | 12 | 13 | 14 | 15   | 16 | 17 | 18 | 19 | 20  | 21  | 22  | 23  | 24  |
+-----------------+----+------+----+----+----+------+----+----+----+----+-----+-----+-----+-----+-----+

+-----------------+-----+-----+-----+-----+-----+------+------+------+------+------+------+------+
|                 | 315 | 400 | 500 | 630 | 800 | 1000 | 1250 | 1600 | 2000 | 2500 | 3150 | 4000 |
+=================+=====+=====+=====+=====+=====+======+======+======+======+======+======+======+
| 1 Octave Band   |     |     | -1  |     |     | 0    |      |      | 1    |      |      | 2    |
+-----------------+-----+-----+-----+-----+-----+------+------+------+------+------+------+------+
| 1/3 Octave Band | 25  | 26  | 27  | 28  | 29  | 30   | 31   | 32   | 33   | 34   | 35   | 36   |
+-----------------+-----+-----+-----+-----+-----+------+------+------+------+------+------+------+
static center_frequency_to_erb(frequency)

This function converts the center frequency to the Equivalent Rectangular Band (ERB)

Parameters:

frequency (double) – the center frequency of the one-third-octave band, Units: Hz

Return type:

double

Returns:

the bandwidth of the ERB at the selected center frequency

static detect_peaks(array, freq=0, cthr=0.2, unprocessed_array=False, fs=44100)

Function detects the peaks in array, based from the mirpeaks algorithm.

Parameters:

  • array – Array in which to detect peaks

  • freq – Scale representing the x axis (sample length as array)

  • cthr – Threshold for checking adjacent peaks

  • unprocessed_array – Array that in unprocessed (normalised), if False will default to the same as array.

  • fs – Sampe rate of the array

Returns:

index of peaks, values of peaks, peak value on freq.

Refactored intt PyTimbre by Dr. Frank Mobley, 2023

static exact_band_number(resolution, frequency)

Determine the exact non-integer value of band number of a frequency for a specific fractional octave band interval.

Parameters:

  • resolution (int) – Used to specify the fractional octave band interval as 1/resolution. Intervals of 1, 1/3, 1/6, 1/12, and 1/24 are available. See ‘center_frequency’_ for band number/frequency pairs for common intervals.

  • frequency (float) – The frequency in Hz

Returns:

The exact band number value

Return type:

float

Example:

>>> from pytimbre.spectral.fractional_octave_band import FractionalOctaveBandTools
>>> resolution = 1 # Select 1 Octave Band inberval
>>> FractionalOctaveBandTools.exact_band_number(resolution, frequency=1000.0)
0.0

>>> FractionalOctaveBandTools.exact_band_number(resolution, frequency=1111.0)
0.15185881672700494
static filter_shape(bandwidth: float = 3, center_frequency: float = 1000, narrowband_frequencies=None)

This function defines the shape of the one-third octave band based on the narrowband frequencies that are provided. This is based on the information from Matlab scripts provided by Brigham Young University researchers.

static filter_third_octaves_downsample(waveform, reference_level: float = 100.0, minimum_frequency: float = 25.0, maximum_frequency: float = 12500.0, filter_order: int = 4)

Filters the audio file into third octave bands

Parameters:

  • x – the waveform object

  • reference_level – the reference level for calculating decibels - does not allow for negative values; default: 100

  • minimum_frequency – the minimum frequency; default: 25

  • maximum_frequency – the maximum frequency (must be at least 2500 Hz); default: 12500

  • filter_order – the filter order; default: 4

Returns:

static frequencies(start_band, end_band, resolution) → list

Calculate the exact band center frequencies between a start and stop band number for a specific fractional octave band interval.

Parameters:

  • start_band (int, float) – starting fractional octave band number of the array

  • end_band (int, float) – ending fractional octave band number of the array

  • resolution (int, float) – Used to specify the fractional octave band interval as 1/resolution. Intervals of 1, 1/3, 1/6, 1/12, and 1/24 are available. See ‘center_frequency’_ for band number/frequency pairs for common intervals.

Return type:

float, array-like

Returns:

frequencies from the start to the stop bands in Hz

static frequencies_ansi_preferred(f0: float = 10, f1: float = 10000, bandwidth: int = 3)

This function provides the list of accepted frequencies from the ANSI S1.6 definition of the shape of fractional octave bands.

static get_min_audible_fields()

Gather the minimum audible field values within the calculated frequencies from 10 Hz to 10 kHz

Return type:

double, array-like

Returns:

the minimum audible field based on the NASA interpolation at the exact frequencies from 10 Hz to 10 kHz

static lower_frequency(resolution, band)

Calculate the exact lower frequency of a corresponding band number for a specific fractional octave band interval.

Parameters:

  • resolution (int, float) – Used to specify the fractional octave band interval as 1/resolution. Intervals of 1, 1/3, 1/6, 1/12, and 1/24 are available. See ‘center_frequency’_ for band number/frequency pairs for common intervals.

  • band (int, float) – fractional octave band number

Returns:

band lower frequency in Hz

Return type:

float

static midbands(minimum_frequency, maximum_frequency, sample_rate)

Divides the frequency range into third octave bands using filters

Parameters:

  • minimum_frequency – the minimum third octave band

  • maximum_frequency – the maximum third octave band

  • sample_rate – The number of samples per second

static min_audible_field(frequency)

This function calculates a curve fit to the minimum audible field according to an equation provided by NASA in the AUDIB code. Reference USAAMRDL-TR-74-102A.

@author: Gregory Bowers and Frank Mobley

Parameters:

frequency (double) – frequency to calculate the minimum audible field

Return type:

double

Returns:

minimum audible field at the selected frequency

static tob_frequencies()

The exact frequencies from 10 Hz to 10 kHz using the center_frequency function at the one-third frequency resolution.

static tob_frequencies_ansi()

The accepted frequencies for the one-third-octave bands from 10 Hz to 10 kHz

static tob_to_erb(x, spl)

Convert the data form the one-third-octave bandwidth to the equivalent rectangular band bandwidth

Parameters:

  • x (double/int) – the band frequency to convert (double) or the band index within the spectrum from 10 Hz t0 10 kHz (int)

  • spl (double) – the sound pressure level at the selected frequency

Return type:

double

Returns:

the sound pressure level adjusted for the difference between the TOB and ERB bandwidths

static upper_frequency(resolution, band)

Calculate the exact upper frequency of a corresponding band number for a specific fractional octave band interval.

Parameters:

  • resolution (int, float) – Used to specify the fractional octave band interval as 1/resolution. Intervals of 1, 1/3, 1/6, 1/12, and 1/24 are available. See ‘center_frequency’_ for band number/frequency pairs for common intervals.

  • band (int, float) – fractional octave band number

Returns:

band upper frequency in Hz

Return type:

float