pytimbre.spectral.time_histories.SpectralTimeHistory

class pytimbre.spectral.time_histories.SpectralTimeHistory

Bases: object

This class wraps the ability of the analysis to contain multiple spectrum objects and create a variation across time.

Remarks 2022-12-13 - FSM - added a function to collect the sound quality metrics from each of the spectra 2022-12-13 - FSM - added a function to collect the times past midnight from the spectra objects

__init__()

Constructor - this will build a class object for the TimeHistory and instantiate all properties and protected elements.

:param : :type : param a: This is the waveform object that we want to process into a TimeHistory object :param : Spectrum objects :type : param integration_time: float - the size of the independent waveforms that will be processed into a series of

Methods

__init__()	Constructor - this will build a class object for the TimeHistory and instantiate all properties and protected elements.
concatenate([b, inplace, normalize_time])	This function will concatenate the TimeHistory that is passed as an argument to the current element.
from_data(levels, frequencies, times[, ...])	This function constructs the Spectrogram object from information obtained from the users and sets up an object that can be compared with external data without concern for differences in the methods to calculate the spectrogram data.
from_digital_filters(wfm, fb[, ...])	This constructs the individual Spectrum objects with digital filters.
from_fourier_transform(wfm, fb[, fft_size])	This function creates a series of Spectrum objects using the FFT methods that exist within the Spectrum object.
load(filename)	This function loads the information from a file into the class object :param filename: the path to the file to be loaded :type filename: str :return: The contents of the file :rtype: SpectralTimeHistory
save(filename)
to_dataframe()	This function converts the information within the time history object into a Pandas.DataFrame :return: The data organized with the header as part of every row within a data frame :rtype: Pandas.DataFrame
to_fractional_octave_band([bandwidth, f0, f1])	This creates a new TimeHistory object where the spectral objects are representations of the fractional octave bandwidths rather than the narrowband.
trim([start_time, end_time, inplace])	This function creates a subset of the existing data that is between the start_time and end_time objects. If the start_time is None then no elements are eliminated from the beginning; if the end_time is None then no elements are eliminated from the end. :param start_time: The start time of the subset. This can be either represented as a datetime object or a float. If the value is None, then the start time of the system is used. :param end_time: The stop time of the subset. This can be either represented as a datetime object or a float. If the value is None, then the stop time of the system is used. :param inplace: This parameter determines whether the data will be stored in the current object, loosing any values that were excluded based on the start_time and end_time. If True the data is lost, otherwise the subset is returned as a new object.

Attributes

duration
fft_size
fractional_octave_bandwidth
frame_builder
frequencies
header
integration_time
is_fractional_octave_resolution
is_narrowband_resolution
signal
spectra
spectrogram_array_decibels
time_history_sample_rate	The number of samples per second of evey TimeHistory metric.
times
times_past_midnight
waveform
waveform_sample_rate
waveform_sample_size

concatenate(b=None, inplace: bool = False, normalize_time: bool = False)

This function will concatenate the TimeHistory that is passed as an argument to the current element. If the inplace argument is True, the data is concatenated to the current object, otherwise it is returned as a new object.

:param : This is the object to concatenate with the current object :type : param b: TimeHistory :param : Default = False - When False, this function will return a new TimeHistory Object, otherwise it returns a

new TimeHistory object

:type : param inplace: bool :param : Default = False - This will normalize the time to a zero for the first spectra. :type : param normalize_time: bool

static from_data(levels, frequencies, times, levels_as_pressure: bool = False)

This function constructs the Spectrogram object from information obtained from the users and sets up an object that can be compared with external data without concern for differences in the methods to calculate the spectrogram data.

Parameters:

• levels – array-like - the 2-D levels with shape = [len(times), len(frequencies)]

• frequencies – array-like - the collection of frequencies that define one dimension of the levels matrix

• times – array-like - the collection of times within the spectrogram that define the second dimension

• levels_as_pressure – boolean - if True the levels matrix is assumed to be a pressure matrix,

otherwise the levels are converted to a pressure matrix :returns: Spectrogram object

static from_digital_filters(wfm: Waveform, fb: FrameBuilder, frequency_resolution: int = 3, f0: float = 10.0, f1: float = 10000)

This constructs the individual Spectrum objects with digital filters. :param wfm: The audio data :type wfm: Waveform :param fb: the class that partitions the waveform for each frame :type fb: FrameBuilder :param frequency_resolution: The fractional octave frequency resolution :type frequency_resolution: int :param f0: The desired start frequency :type f0: float :param f1: The desired stop frequency :type f1: float :return: The spectral time history developed from fractional octave digital filters :rtype: SpectralTimeHistory

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

This function creates a series of Spectrum objects using the FFT methods that exist within the Spectrum object. The waveform for each frame are defined by the FrameBuilder object. :param wfm: The audio to process :type wfm: Waveform :param fft_size: The number of frequency bins :type fft_size: int :param fb: The class that partitions the waveform for each frame :type fb: FrameBuilder :return: The spectral time history object :rtype: SpectralTimeHistory

static load(filename: str)

This function loads the information from a file into the class object :param filename: the path to the file to be loaded :type filename: str :return: The contents of the file :rtype: SpectralTimeHistory

property time_history_sample_rate

The number of samples per second of evey TimeHistory metric.

to_dataframe()

This function converts the information within the time history object into a Pandas.DataFrame :return: The data organized with the header as part of every row within a data frame :rtype: Pandas.DataFrame

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

This creates a new TimeHistory object where the spectral objects are representations of the fractional octave bandwidths rather than the narrowband. This will check the contents of the current class and determine whether the conversion is appropriate (i.e. this is a narrowband spectral representation). If not a warning is thrown. :param bandwidth: The desired output fractional octave bandwidth :type bandwidth: int :param f0: the desired output lower limit frequency :type f0: float :param f1: the desired output upper limit frequency :type f1: float :return: The new fractional octave resolution time history object :rtype: SpectralTimeHistory

trim(start_time=None, end_time=None, inplace: bool = False)

This function creates a subset of the existing data that is between the start_time and end_time objects. If the start_time is None then no elements are eliminated from the beginning; if the end_time is None then no elements are eliminated from the end. :param start_time:

The start time of the subset. This can be either represented as a datetime object or a float. If the value is None, then the start time of the system is used.

Parameters:

• end_time – The stop time of the subset. This can be either represented as a datetime object or a float. If the value is None, then the stop time of the system is used.

• inplace – This parameter determines whether the data will be stored in the current object, loosing any values that were excluded based on the start_time and end_time. If True the data is lost, otherwise the subset is returned as a new object.