pytimbre.spectral.spectra.Spectrum

class pytimbre.spectral.spectra.Spectrum(a: Waveform = None, pressures=None, frequencies=None)

Bases: object

This is the base class that defines the structure of the spectrum object. It does not calculate the frequency spectrum from a waveform, but can be used to represent a single spectrum that was previously created.

Example

Make a simple Spectrum object, spec, with a spike at 2 Hz of 10 pascals

>>> from pytimbre.spectral.spectra import Spectrum

>>> f = np.arange(0, 5)
>>> p = np.zeros(len(f))
>>> p[f == 2] = 10

>>> spec = Spectrum()
>>> spec.frequencies = f
>>> spec.pressures_pascals = p

>>> print(spec.pressures_pascals)
[ 0.  0. 10.  0.  0.]

Remarks:

2022-12-13 - FSM - Added a function to calculate the sound quality metrics based on the frequency spectrum

__init__(a: Waveform = None, pressures=None, frequencies=None)

The default constructor that builds the information within the Spectrum class based on the contents of the object “a”.

:param : in processing :type : param a: Waveform - the acoustic samples that define the source of the time-domain information that we are interested

Methods

__init__([a, pressures, frequencies])	The default constructor that builds the information within the Spectrum class based on the contents of the object "a".
calculate_engineering_unit_scale_factor([...])	This will take the data within the class and build the spectral time history and then determine the value of the scale factor to get a specific sound pressure level at a certain frequency.
convert_nb_to_fob(frequencies_nb, ...[, ...])	This function converts the frequency and pressure arrays sampled in narrowband resolution to the fractional octave band resolution.
from_digital_filters(wfm[, ...])	This function processes the waveform using a sequence of digital filters defined for the highest octave filter band and sequentially moved down an octave through decimation of the input signal.
from_fourier_transform(wfm[, fft_size])	This function replaces the entire SpectrumByFFT class and inserts only the function for calculations of the spectral levels :param wfm: The audio to transform :type wfm: Waveform :param fft_size: the number of analysis frequency bins :type fft_size: int :return: the Spectral sound pressure levels :rtype: Spectrum
to_fractional_octave_band([bandwidth, f0, f1])	This function will convert the spectrum from a narrowband resolution to a factional octave band resolution by applying the shape functions to the narrowband spectral values and determining the weighted value within the fractional octave band.

Attributes

doublesided_frequency_array
duration
fft_size
fractional_octave_bandwidth
frequencies
frequency_increment
is_fractional_octave_resolution
is_narrowband_resolution
narrowband_frequency_count
power_spectral_density	Numpy array of single-sided real-values.
pressures_decibels	Sound pressure levels of the spectrum in units of dB re 20 microPa.
pressures_pascals
sample_rate
settle_samples	Based on requirements of Matlab filtering, you must have at least 3 times the number of coefficients to accurately filter data.
settle_time
signal
start_fractional_octave_frequency
stop_fractional_octave_frequency
time
time_past_midnight
waveform

calculate_engineering_unit_scale_factor(calibration_level: float = 94, calibration_frequency=1000)

This will take the data within the class and build the spectral time history and then determine the value of the scale factor to get a specific sound pressure level at a certain frequency.

Parameters:

• calibration_level (float) – The value of the acoustic level for the calibration

• calibration_frequency (float) – The value of the frequency that is supposed to be used for the calibration

Returns:

The engineering scale factor that can be directly applied to the acoustic data

Return type:

float

static convert_nb_to_fob(frequencies_nb, pressures_pascals_nb, fob_band_width: int = 3, f0: float = 10, f1: float = 10000)

This function converts the frequency and pressure arrays sampled in narrowband resolution to the fractional octave band resolution.

Parameters:

• frequencies_nb – nd_array - the collection of narrowband frequencies that we want to convert

• pressures_pascals_nb – nd_array - the collection of pressures in units of pascals for the frequencies

• fob_band_width – int, default = 3 - the fractional octave band resolution that we desire

• f0 – float, default = 10 - The start frequency of the output fractional octave frequencies

• f1 – float, default = 10000 - The end frequency of the output fractional octave frequencies

Returns:

frequencies_fob - nd_array - the collection of frequencies from f0 to f1 with the resolution of fob_band_width pressures_pascals_fob - nd_array - the fractional octave pressure in pascals at the associated frequencies

static from_digital_filters(wfm: Waveform, frequency_resolution: int = 3, start_frequency: float = 10.0, stop_frequency: float = 10000.0)

This function processes the waveform using a sequence of digital filters defined for the highest octave filter band and sequentially moved down an octave through decimation of the input signal. :param wfm: The audio to process :type wfm: Waveform :param frequency_resolution: the fractional octave frequency resolution :type frequency_resolution: int :param start_frequency: the lowest desired frequency within the spectrum :type start_frequency: float :param stop_frequency: the highest desired frequency within the spectrum :type stop_frequency: float :return: the audio spectrum organized with fractional octave center frequencies :rtype: Spectrum

static from_fourier_transform(wfm: Waveform, fft_size: int = None)

This function replaces the entire SpectrumByFFT class and inserts only the function for calculations of the spectral levels :param wfm: The audio to transform :type wfm: Waveform :param fft_size: the number of analysis frequency bins :type fft_size: int :return: the Spectral sound pressure levels :rtype: Spectrum

property power_spectral_density

Numpy array of single-sided real-values. Pressures scaled by frequency, in units of Pascals / sqrt(Hz).

property pressures_decibels

Sound pressure levels of the spectrum in units of dB re 20 microPa. Unweighted (i.e. Z-weighted) values required.

Examples:

Create Spectrum object and output sound pressure levels in dB

>>> import numpy as np
>>> from pytimbre.spectral.spectra import Spectrum
>>> spec = Spectrum()
>>> spec.frequencies = np.array([100., 125., 160.])
>>> spec.pressures_pascals = np.array([1., 10., 100.])
>>> spec.pressures_decibels
array([ 93.97940009, 113.97940009, 133.97940009])

Set the Spectrum pressures in dB and output pressures in Pa

>>> spec = Spectrum()
>>> spec.frequencies = [1000., 2000., 4000.]
>>> spec.pressures_decibels = np.array([114., 94., 114.])
>>> spec.pressures_pascals
array([10.02374467,  1.00237447, 10.02374467])

property settle_samples

Based on requirements of Matlab filtering, you must have at least 3 times the number of coefficients to accurately filter data. So this will start with that minimum, and then move through the full octave frequency band numbers to determine the minimum number of samples that are required for the filter to adequately settle.

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

This function will convert the spectrum from a narrowband resolution to a factional octave band resolution by applying the shape functions to the narrowband spectral values and determining the weighted value within the fractional octave band.

Parameters:

• bandwidth – float, default = 3 - the fractional octave resolution that we will sample the frequency spectrum

• f0 – float, default = 10 - the lowest frequency within the spectrum

• f1 – float, default = 10000 - the heighest frequency within the spectrum

Returns:

Spectrum - a spectrum object with the frequencies at the specified resolution and between the specified frequency values.