SpectroData

SpectroData#

class osekit.core_api.spectro_data.SpectroData(items: list[SpectroItem] | None = None, audio_data: AudioData = None, begin: Timestamp | None = None, end: Timestamp | None = None, fft: ShortTimeFFT | None = None, db_ref: float | None = None, v_lim: tuple[float, float] | None = None, colormap: str | None = None)#

SpectroData represent Spectro data scattered through different SpectroFiles.

The SpectroData has a collection of SpectroItem. The data is accessed via a SpectroItem object per SpectroFile.

Initialize a SpectroData from a list of SpectroItems.

Parameters#

items: list[SpectroItem]

List of the SpectroItem constituting the SpectroData.

audio_data: AudioData

The audio data from which to compute the spectrogram.

begin: Timestamp | None

Only effective if items is None. Set the begin of the empty data.

end: Timestamp | None

Only effective if items is None. Set the end of the empty data.

fft: ShortTimeFFT

The short time FFT used for computing the spectrogram.

db_ref: float | None

Reference value for computing sx values in decibel.

v_lim: tuple[float,float]

Lower and upper limits (in dB) of the colormap used for plotting the spectrogram.

colormap: str

Colormap to use for plotting the spectrogram.

property db_ref: float#

Reference value for computing sx values in decibel.

If no reference is specified (self._db_ref is None), the sx db values will be given in dB FS.

property db_type: Literal['FS', 'SPL_instrument', 'SPL_parameter']#

Return whether the spectrogram dB values are in dB FS or dB SPL.

Returns#

Literal[“FS”, “SPL_instrument”, “SPL_parameter”]:

“FS”: The values are expressed in dB FS. “SPL_instrument”: The values are expressed in dB SPL relative to the

linked AudioData instrument P_REF property.

“SPL_parameter”: The values are expressed in dB SPL relative to the

self._db_ref field.

classmethod from_audio_data(data: AudioData, fft: ShortTimeFFT, v_lim: tuple[float, float] | None = None, colormap: str | None = None) → SpectroData#

Instantiate a SpectroData object from a AudioData object.

Parameters#

data: AudioData

Audio data from which the SpectroData should be computed.

fft: ShortTimeFFT

The ShortTimeFFT used to compute the spectrogram.

v_lim: tuple[float,float]

Lower and upper limits (in dB) of the colormap used for plotting the spectrogram.

colormap: str

Colormap to use for plotting the spectrogram.

Returns#

SpectroData:

The SpectroData object.

classmethod from_base_data(data: BaseData, fft: ShortTimeFFT, colormap: str | None = None) → SpectroData#

Return an SpectroData object from a BaseData object.

Parameters#

data: BaseData

BaseData object to convert to SpectroData.

fft: ShortTimeFFT

The ShortTimeFFT used to compute the spectrogram.

colormap: str

The colormap used to plot the spectrogram.

Returns#

SpectroData:

The SpectroData object.

classmethod from_dict(dictionary: dict, sft: ShortTimeFFT | None = None) → SpectroData#

Deserialize a SpectroData from a dictionary.

Parameters#

dictionary: dict

The serialized dictionary representing the AudioData.

sft: ShortTimeFFT | None

The ShortTimeFFT used to compute the spectrogram. If not provided, the SFT parameters must be included in the dictionary.

Returns#

SpectroData

The deserialized SpectroData.

classmethod from_files(files: list[SpectroFile], begin: Timestamp | None = None, end: Timestamp | None = None) → SpectroData#

Return a SpectroData object from a list of SpectroFiles.

Parameters#

files: list[SpectroFile]

List of SpectroFiles containing the data.

begin: Timestamp | None

Begin of the data object. Defaulted to the begin of the first file.

end: Timestamp | None

End of the data object. Defaulted to the end of the last file.

Returns#

SpectroData:

The SpectroData object.

static get_default_ax() → Axes#

Return a default-formatted Axes on a new figure.

The default osekit spectrograms are plotted on wide, borderless spectrograms. This method set the default figure and axes parameters.

Returns#

plt.Axes:

The default Axes on a new figure.

get_value() → ndarray#

Return the Sx matrix of the spectrogram.

The Sx matrix contains the absolute square of the STFT.

get_welch(nperseg: int | None = None, detrend: str | callable | False = 'constant', return_onesided: bool = True, scaling: Literal['density', 'spectrum'] = 'density', average: Literal['mean', 'median'] = 'mean') → np.ndarray#

Estimate power spectral density of the SpectroData using Welch’s method.

This method uses the scipy.signal.welch function. The window, sample rate, overlap and mfft are taken from the SpectroData.fft property.

Parameters#

nperseg: int|None

Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.

detrend: str | callable | False

Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.

return_onesided: bool

If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.

scaling: Literal[“density”, “spectrum”]

Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the squared magnitude spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’

average: Literal[“mean”, “median”]

Method to use when averaging periodograms. Defaults to ‘mean’.

Returns#

np.ndarray

Power spectral density or power spectrum of the SpectroData.

Link the SpectroData to a SpectroFile in the folder.

The given folder should contain a file named “str(self).npz”. Linking is intended for SpectroData objects that have already been written to disk. After linking, the SpectroData will have a single item with the same properties of the target SpectroFile.

Parameters#

folder: Path

Folder in which is located the SpectroFile to which the SpectroData instance should be linked.

Link the SpectroData to a given AudioData.

Parameters#

audio_data: AudioData

The AudioData to which this SpectroData will be linked.

property nb_bytes: int#

Total bytes consumed by the spectro values.

plot(ax: Axes | None = None, sx: ndarray | None = None, scale: Scale | None = None) → None#

Plot the spectrogram on a specific Axes.

Parameters#

ax: plt.axes | None

Axes on which the spectrogram should be plotted. Defaulted as the SpectroData.get_default_ax Axes.

sx: np.ndarray | None

Spectrogram sx values. Will be computed if not provided.

scale: osekit.core_api.frequecy_scale.Scale

Custom frequency scale to use for plotting the spectrogram.

save_spectrogram(folder: Path, ax: plt.Axes | None = None, sx: np.ndarray | None = None, scale: Scale | None = None) → None#

Export the spectrogram as a png image.

Parameters#

folder: Path

Folder in which the spectrogram should be saved.

ax: plt.Axes | None

Axes on which the spectrogram should be plotted. Defaulted as the SpectroData.get_default_ax Axes.

sx: np.ndarray | None

Spectrogram sx values. Will be computed if not provided.

scale: osekit.core_api.frequecy_scale.Scale

Custom frequency scale to use for plotting the spectrogram.

property shape: tuple[int, ...]#

Shape of the Spectro data.

split(nb_subdata: int = 2) → list[SpectroData]#

Split the spectro data object in the specified number of spectro subdata.

Parameters#

nb_subdata: int

Number of subdata in which to split the data.

Returns#

list[SpectroData]

The list of SpectroData subdata objects.

property sx_dtype: type[complex]#

Data type used to represent the sx values. Should either be float or complex.

If complex, the phase info will be included in the computed spectrum. If float, only the absolute value of the spectrum will be kept.

to_db(sx: ndarray) → ndarray#

Convert the sx values to dB.

If the linked audio data has an Instrument parameter, the values are converted to dB SPL (re Instrument.P_REF). Otherwise, the values are converted to dB FS.

Parameters#

sx: np.ndarray

Sx values of the spectrum.

Returns#

np.ndarray

Converted Sx values.

to_dict(embed_sft: bool = True) → dict#

Serialize a SpectroData to a dictionary.

Parameters#

embed_sft: bool

If True, the SFT parameters will be included in the dictionary. In a case where multiple SpectroData that share a same SFT are serialized, SFT parameters shouldn’t be included in the dictionary, as the window values might lead to large redundant data. Rather, the SFT parameters should be serialized in a SpectroDataset dictionary so that it can be only stored once for all SpectroData instances.

Returns#

dict:

The serialized dictionary representing the SpectroData.

property v_lim: tuple[float, float]#

Limits (in dB) of the colormap used for plotting the spectrogram.

write(folder: Path, sx: np.ndarray | None = None, link: bool = False) → None#

Write the Spectro data to file.

Parameters#

folder: pathlib.Path

Folder in which to write the Spectro file.

sx: np.ndarray | None

Spectrogram sx values. Will be computed if not provided.

link: bool

If True, the SpectroData will be bound to the written npz file. Its items will be replaced with a single item, which will match the whole new SpectroFile.

write_welch(folder: Path, px: np.ndarray | None = None, nperseg: int | None = None, detrend: str | callable | False = 'constant', return_onesided: bool = True, scaling: Literal['density', 'spectrum'] = 'density', average: Literal['mean', 'median'] = 'mean') → None#

Write the psd (welch) of the SpectroData to a npz file.

Parameters#

folder: pathlib.Path

Folder in which to write the Spectro file.

px: np.ndarray | None

Welch px values. Will be computed if not provided.

nperseg: int|None

Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.

detrend: str | callable | False

Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.

return_onesided: bool

If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.

scaling: Literal[“density”, “spectrum”]

Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the squared magnitude spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’

average: Literal[“mean”, “median”]

Method to use when averaging periodograms. Defaults to ‘mean’.

Contents