LTASData

class osekit.core_api.ltas_data.LTASData(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, nb_time_bins: int = 1920)

LTASData is a special form of SpectroData.

The Sx values from a LTASData object are computed recursively. LTAS should be preferred in cases where the audio is really long. In that case, the corresponding number of time bins (scipy.ShortTimeFTT.p_nums) is too long for the whole Sx matrix to be computed once.

The LTAS are rather computed recursively. If the number of temporal bins is higher than a target p_num value, the audio is split in p_num parts. A separate sft is computed on each of these bits and averaged so that the end Sx presents p_num temporal windows.

This averaging is performed recursively: if the audio data is such that after a first split, the p_nums for each part still is higher than p_num, the parts are further split and each part is replaced with an average of the stft performed within it.

Initialize a LTASData from a list of SpectroItems.

Parameters

items: list[SpectroItem]

List of the SpectroItem constituting the LTASData.

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.

nb_time_bins: int

The maximum number of time bins of the LTAS. Given the audio data and the fft parameters, if the resulting spectrogram has a number of windows p_num <= nb_time_bins, the LTAS is computed like a classic spectrogram. Otherwise, the audio data is split in nb_time_bins equal-duration audio data, and each bin of the LTAS consist in an average of the fft values obtained on each of these bins. The audio is split recursively until p_num <= nb_time_bins.

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

Instantiate a SpectroData object from an 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.

nb_time_bins: int

The maximum number of windows over which the audio will be split to perform Defaulted to 1920.

Returns

LTASData:

The SpectroData object.

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

Deserialize a LTASData from a dictionary.

Parameters

dictionary: dict

The serialized dictionary representing the LTASData.

sft: ShortTimeFFT | None

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

Returns

LTASDataset

The deserialized LTASData.

classmethod from_spectro_data(spectro_data: SpectroData, nb_time_bins: int) → LTASData

Initialize a LTASData from a SpectroData.

Parameters

spectro_data: SpectroData

The spectrogram to turn in a LTAS.

nb_time_bins: int

The maximum number of windows over which the audio will be split to perform a LTAS.

Returns

LTASData:

The LTASData instance.

static get_ltas_fft(fft: ShortTimeFFT) → ShortTimeFFT

Return a ShortTimeFFT object optimized for computing LTAS.

The overlap of the fft is forced set to 0., as the value of consecutive windows will in the end be averaged.

Parameters

fft: ShortTimeFFT

The fft to optimize for LTAS computation.

Returns

ShortTimeFFT

The optimized fft.

get_value(depth: int = 0) → ndarray

Return the Sx matrix of the LTAS.

The Sx matrix contains the absolute square of the STFT.

static mean_value_part(sub_spectro: LTASData) → ndarray

Return the mean value of the LTAS part.

property shape: tuple[int, int]

Shape of the LTAS data.

to_dict(*, embed_sft: bool = True) → dict

Serialize a LTASData to a dictionary.

Parameters

embed_sft: bool

If True, the SFT parameters will be included in the dictionary. In a case where multiple LTASData 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 LTASDataset dictionary so that it can be only stored once for all LTASData instances.

Returns

dict:

The serialized dictionary representing the LTASData.