# References¶

Release: 1.0.1 November 14, 2018

## pyteuf.tf_transforms module¶

Direct and inverse short-time Fourier transforms.

Implementation of the STFT and its inverse computed using ltfatpy. Module pyteuf provides a class Stft and a class Istft, which are an interface to ltfatpy in order to facilitate the use of direct and inverse short-time Fourier transforms, especially for applied signal processing and engineering purposes. In particular, it includes some intuitive and ergonomic ways to choose either an analysis or a synthesis window, to control transform parameters and boundary effects.

Choosing a window: the window contents can be described using a high-level description, or a low-level array:

• High-level setting: window name and length: The user provides the window name as a string in win_name, and the characteristic length of the window as an integer in win_len (leaving argument win_array to the default None value). In this case, the window is built internally when needed. The available windows are the FIR and Gaussian windows available in ltfatpy. The characteristic length of a window is its actual length in the case of a FIR window, and the standard deviation for a Gaussian window (its actual length equals the signal length).
• Low-level setting: window array: The user provides an arbitrary window vector as an nd-array in win_array (leaving arguments win_name and win_len to the default None value). The window length is automatically set to the length of the array.

Analysis and synthesis windows: depending on the user’s motivations, one may prefer to chooser either the analysis window or the synthesis window and to obtain the other window automatically. In order to implement this both in Stft and Istft, the user can set parameter win_type to analysis or synthesis so that the specified parameters (win_name, win_len, win_array) are used to build either the analysis or the synthesis window; the other related window is then automatically computed as the canonical dual window.

Rules on parameter settings: the ltfatpy implementation requires constraints on the parameters of the STFT: the transform length must be a multiple of both the hop size hop and the number of frequency bins n_bins. This implementation offers three strategies to enforce this constraint, that can be selected through the parameter param_constraint that can have three different values:

• 'pad': hop and n_bins are kept unchanged, while the transform length is adjusted to the smallest multiple of n_bins by zero-padding the signal. This is appropriate when hop and n_bins must not change while zero-padding is allowed, but the transform length may be very large;
• 'pow2': hop is rounded to the closest power of two, n_bins is rounded to the smallest higher power of two and the transform length is adjusted to the smallest multiple of n_bins by zero-padding the signal. This strategy limits the zero-padding of the signal by adjusting parameters hop and n_bins. As a consequence, the input STFT parameters may not be exactly the same as the parameters used in the transform;
• 'fix': parameters hop and n_bins should satisfy the constraint that the transform length is a common multiple of them, otherwise, an error is generated. This option is suited to users that want to control parameters by themselves without any rounding.

Boundary effects: various usages of the STFT have been observed regarding the way the first and last signal samples are windowed:

• adding zeros before the first samples and after the last samples such that these samples are windowed by several frames;
• getting STFT coefficients coming only from full signal frames, even if the reconstruction is not possible or inaccurate at the boundaries of the signal;
• considering the signal being circular, such that frames at the boundary of the signal include both samples from the beginning and samples from the end of the sound.

By default, the implementation uses the last stategy. It is controlled using zero_pad_full_sig to the appropriate value and process the STFT data carefully:

• if zero_pad_full_sig is set to False, a circular transform is obtained.
• If zero_pad_full_sig is set to True, the signal is padded with win_len zeros such that frames can include either first samples or last samples, but not both. The circular implementation is nonetheless used, First and last frames should then be considered with caution).

class pyteuf.tf_transforms.BaseStft(hop, n_bins, win_type='analysis', win_name=None, win_len=None, win_array=None, is_tight=False, convention='lp')[source]

Bases: abc.ABC

Base class for direct and inverse short-time Fourier transforms.

Parameters: hop : int Desired hop size in samples. Subject to rounding (see Rules on parameter settings). n_bins : int Desired number of frequency bins in samples. Subject to rounding (see Rules on parameter settings). win_type : {‘analysis’, ‘synthesis’}, optional Type of the window (see Analysis and synthesis windows). win_name : None or str, optional Window type among ‘gauss’ or one of the FIR windows listed in firwin() (see Choosing a window). win_len : None or int, optional If win_name is set, FIR window length or Gaussian window width, in samples (see Choosing a window). win_array : None or array_like, optional Window array, as an alternative to win_name and win_len (see Choosing a window). is_tight : bool, optional If True, the window is adapted to obtain a tight frame (see gabtight()). If both is_dual=’synthesis’ and is_tight=True are set, the tight synthesis window is first computed and the related analysis window is then computed. convention : {‘lp’, ‘bp’} Type of convention : ‘lp’ for low-pass (i.e. frequency invariant) or ‘bp’ for band-pass (i.e. time invariant).
get_params()[source]

Returns the parameters of the transform.

get_win_array(sig_len=None, compute_dual=False)[source]

Window array.

Parameters: sig_len : int Length of the signal. Needed for a Gaussian window, otherwise, this parameter has no effect. compute_dual : bool If False, compute the window specified by the attributes win_name, win_len, and so on. If True, compute the dual of this window. array_like
convention

Type of convention ({‘lp’, ‘bp’}).

Type of convention : ‘lp’ for low-pass (i.e. frequency invariant) or ‘bp’ for band-pass (i.e. time invariant).

hop

Actual hop size (int).

If parameter param_constraint is set to ‘pow2’, the actual value is automatically computed from the desired hop size (see Rules on parameter settings).

is_tight

Tight frame flag (bool).

n_bins

Actual number of frequency bins (int).

If parameter param_constraint is set to ‘pow2’, the actual value is automatically computed from the desired number of bins (see rules on parameter settings).

raw_win_array

Window array (None or array_like).

Window array if parameter win_array has been specified at object creation. If is_tight is True, attribute raw_win_array may differ from parameter win_array.

win_len

Window length (None or int).

None if window is defined by win_array.

win_name

Window name (None or str).

None if window is defined by win_array.

win_type

Window type ({‘analysis’, ‘synthesis’}).

class pyteuf.tf_transforms.Istft(hop, n_bins, win_name=None, win_len=None, win_array=None, win_type='synthesis', is_tight=False, convention='lp')[source]

Inverse short-time Fourier transform for STFT representations.

Parameters: hop : int Hop size in samples. n_bins : int Number of frequency bins. win_name : None or str, optional Window name (None if window is defined by win_array). win_len : None or int, optional Window length (None if window is defined by win_array). win_array : None or ndarray, optional Window array, as an alternative to win_name and win_len (see Choosing a window). win_type : {‘synthesis’, ‘analysis’}, optional Type of the window. If 'synthesis', the canonical dual window is computed as the analysis window (see Analysis and synthesis windows). is_tight : bool, optional If True, the window is adapted to obtain a tight frame (see gabtight()). If both is_dual=’analysis’ and is_tight=True are set, the tight analysis window is first computed and the related synthesis window is then computed. convention : {‘lp’, ‘bp’} Type of convention : ‘lp’ for low-pass (i.e. frequency invariant) or ‘bp’ for band-pass (i.e. time invariant).
apply(X, signal_params=None)[source]

Apply inverse short-time Fourier transform.

Parameters: X : array_like Stft coefficients to be inverse-transformed. Waveform
get_params()

Returns the parameters of the transform.

get_win_array(sig_len=None)[source]

Synthesis window array.

Parameters: sig_len : int Length of the signal. Needed for a Gaussian window, otherwise, this parameter has no effect. array
convention

Type of convention ({‘lp’, ‘bp’}).

Type of convention : ‘lp’ for low-pass (i.e. frequency invariant) or ‘bp’ for band-pass (i.e. time invariant).

hop

Actual hop size (int).

If parameter param_constraint is set to ‘pow2’, the actual value is automatically computed from the desired hop size (see Rules on parameter settings).

is_tight

Tight frame flag (bool).

n_bins

Actual number of frequency bins (int).

If parameter param_constraint is set to ‘pow2’, the actual value is automatically computed from the desired number of bins (see rules on parameter settings).

raw_win_array

Window array (None or array_like).

Window array if parameter win_array has been specified at object creation. If is_tight is True, attribute raw_win_array may differ from parameter win_array.

win_len

Window length (None or int).

None if window is defined by win_array.

win_name

Window name (None or str).

None if window is defined by win_array.

win_type

Window type ({‘analysis’, ‘synthesis’}).

class pyteuf.tf_transforms.Stft(hop, n_bins, win_type='analysis', win_name=None, win_len=None, win_array=None, is_tight=False, param_constraint='fix', zero_pad_full_sig=True, convention='lp')[source]

Short-time Fourier transform object for 1D signals.

Parameters: hop : int Desired hop size in samples. Subject to rounding (see Rules on parameter settings). n_bins : int Desired number of frequency bins in samples. Subject to rounding (see Rules on parameter settings). win_type : {‘analysis’, ‘synthesis’}, optional Type of the window. If ‘synthesis’, the canonical dual window is computed as the analysis window (see Analysis and synthesis windows). win_name : None or str, optional Window type among ‘gauss’ or one of the FIR windows listed in firwin() (see Choosing a window). win_len : None or int, optional If win_name is set, FIR window length or Gaussian window width, in samples (see Choosing a window). win_array : None or array_like, optional Window array, as an alternative to win_name and win_len (see Choosing a window). is_tight : bool, optional If True, the window is adapted to obtain a tight frame (see gabtight()). If both is_dual=’synthesis’ and is_tight=True are set, the tight synthesis window is first computed and the related analysis window is then computed. param_constraint : {‘fix’, ‘pad’, ‘pow2’}, optional Strategy to adjust parameters hop and n_bins (see Rules on parameter settings). zero_pad_full_sig : bool, optional If True, the full signal is padded with win_len zeros to avoid a circular transform (see Boundary effects). convention : {‘lp’, ‘bp’} Type of convention : ‘lp’ for low-pass (i.e. frequency invariant) or ‘bp’ for band-pass (i.e. time invariant).
apply(x, fs=None)[source]

Compute Short-Time Fourier Transform of a signal.

Parameters: x : array_like Input signal to be transformed. TfData Time-frequency matrix with related parameters. If input x is real, only coefficients for non-negative frequencies are returned.
apply_adjoint(x)[source]

Apply the adjoint operator of the current STFT.

Parameters: x : TfData Adjoint operator. array_like
get_istft()[source]

Return the inverse STFT (canonical dual) with the same parameters.

Returns: Istft
get_params()[source]

Returns the parameters of the Stft.

get_win_array(sig_len=None)[source]

Analysis window array.

Parameters: sig_len : int Length of the signal. Needed for a Gaussian window, otherwise, this parameter has no effect. array_like
convention

Type of convention ({‘lp’, ‘bp’}).

Type of convention : ‘lp’ for low-pass (i.e. frequency invariant) or ‘bp’ for band-pass (i.e. time invariant).

hop

Actual hop size (int).

If parameter param_constraint is set to ‘pow2’, the actual value is automatically computed from the desired hop size (see Rules on parameter settings).

is_tight

Tight frame flag (bool).

n_bins

Actual number of frequency bins (int).

If parameter param_constraint is set to ‘pow2’, the actual value is automatically computed from the desired number of bins (see rules on parameter settings).

param_constraint

Strategy to adjust hop and n_bins ({‘fix’, ‘pad’, ‘pow2’}).

raw_win_array

Window array (None or array_like).

Window array if parameter win_array has been specified at object creation. If is_tight is True, attribute raw_win_array may differ from parameter win_array.

win_len

Window length (None or int).

None if window is defined by win_array.

win_name

Window name (None or str).

None if window is defined by win_array.

win_type

Window type ({‘analysis’, ‘synthesis’}).

zero_pad_full_sig

Zero padding flag (bool).

If True, the full signal is padded with win_len zeros to avoid a circular transform (see Boundary effects).

## pyteuf.tf_data module¶

Definition of a time-frequency data structure.

class pyteuf.tf_data.TfData[source]

Subclass of MadArray to handle Time-Frequency representations of real signals.

A TfData object is 2D MadArray, with either real or complex entries. It is initialized in the same way as a MadArray object using binary or complex masks (see documentation of MadArray) It also two additional dictionaries tf_params and signal_params that contain respectively the parameters of the time-frequency transformation, such as the hop size or the window, as well as the parameters needed to reconstruct the signals, such as the sampling frequency or the length. These two dictionaries can be used by any time-frequency transformation methods, and may be empty.

Parameters: data : array of shape (n_frequencies, n_frames) Time-frequency data matrix. mask : boolean array_like, optional See parameter mask in MadArray mask_magnitude : boolean array_like or None, optional See parameter mask_magnitude in MadArray mask_phase : boolean array_like or None, optional See parameter mask_phase in MadArray masked_indexing : bool or None, optional See parameter masked_indexing in MadArray tf_params : dict Time-frequency parameters. The dictionary keys should be parameters for the constructor of a Stft object so that Stft(**tf_params) returns an STFT similar to the one used to generate the current TfData object. signal_params : dict Parameters of the original signal. The dictionary keys should be the sampling frequency fs and the length sig_len of the original signal (useful to reconstruct a signal of the exact same length as the original one).

Attributes

 tf_params (dict) Time-frequency parameters (as described in the parameters section). signal_params (dict) Parameters of the original signal (as described in the parameters section).
copy()[source]

Copy the object.

Returns: TfData
plot_mask(mask_type='any', **kwargs)[source]

Display the mask as an image, with several possible mask types

Parameters: Returns: mask_type : {‘any’, ‘all’, ‘magnitude’, ‘phase’, ‘magnitude only’, ‘phase only’}, optional Type of mask to be displayed, with True values for unknown data. numpy.ndarray The processed image data used in the plotting as returned by plotdgt() or plotdgtreal(). **kwargs : tfplot() properties, optional kwargs are used to specify properties like the dynamic range, colormap, and so on. See documentation of tfplot(). Note that the sampling frequency may not be included in kwargs since it is read from attribute signal_params.
plot_spectrogram(mask_type='any', **kwargs)[source]

Display the spectrogram of the STFT.

Parameters: Returns: mask_type : {‘any’, ‘all’, ‘magnitude’, ‘phase’, ‘magnitude_only’, ‘phase_only’}, optional Type of mask to be displayed as unknown data. numpy.ndarray The processed image data used in the plotting as returned by plotdgt() or plotdgtreal(). **kwargs : tfplot() properties, optional kwargs are used to specify properties like the dynamic range, colormap, and so on. See documentation of tfplot(). Note that the sampling frequency may not be included in kwargs since it is read from attribute signal_params.
signal_is_complex()[source]

Indicate if the TF representation includes negative frequencies.

end_times

Ending times of all the frames (array of shape (n_frames,)).

End times are computed by considering that the first frame is centered at time 0 and returned as an array of floats values with ending times in seconds.

energy_spectrogram

Power spectrogram (TfData).

frequencies

Array of Fourier frequencies (array of shape (n_frequencies,))

magnitude_spectrogram

Magnitude spectrogram (TfData).

mid_times

Middle times of all the frames (array of shape (n_frames,)).

Middle times are computed by considering that the first frame is centered at time 0 and returned as an array of floats values with middle times in seconds.

n_frames

Number of frames (int).

n_frequencies

Number of Fourier frequencies (int).

If the original signal is real, the number of frequencies correspond to non-negative Fourier frequencies and negative frequencies are discarded due to Hermitian symmetry, while the number of bins specified in the transform correspond to all (positive and negative) frequencies.

phase

Phase (TfData).

start_times

Starting times of all the frames (array of shape (n_frames,)).

Starting times are computed by considering that the first frame is centered at time 0 and returned as an array of floats values with starting times in seconds.

## pyteuf.utils module¶

Utils functions and classes for testing.

pyteuf.utils.make_random_stft_parameters(win_name_set=None, win_len_lim=(8, 256), hop_divisor_lim=(6, 4), n_bins_factor_lim=(2, 5), with_array=False, param_constraint='fix', zero_pad_full_sig=True, is_tight=False, win_type='analysis', convention='lp')[source]

Draw parameters for Stft objects at random from ranges of values.

Parameters: win_name_set : set, optional Set of possible window names. If None, the name is chosen among the set of available FIR windows and a Gaussian window. win_len_lim : 2-tuple, optional Range for the window length. hop_divisor_lim : 2-tuple, optional Range for divisors of the window length in order to draw a hop size. n_bins_factor_lim : 2-tuple, optional Range for powers of 2 to be multiplied by the window length to draw the number of bins. with_array : bool, optional If True, a window with random coefficients (uniformly drawn in [0, 1]) is returned, and parameter win_name_set is ignored. param_constraint : {‘fix’, ‘pad’, ‘pow2’}, optional Fixed choice for param_constraint. zero_pad_full_sig : bool, optional Fixed choice for zero_pad_full_sig. is_tight : bool, optional Fixed choice for is_tight. win_type : {‘analysis’, ‘synthesis’}, optional Fixed choice for win_type. convention : {‘lp’, ‘bp’}, optional Convention to use: ‘lp’ for low-pass (i.e. frequency invariant) or ‘bp’ for band-pass (a.k.a. time invariant). dict If parameter with_array is True, the dictionary contains values for the keys 'win_array', 'hop', 'n_bins', 'param_constraint', 'zero_pad_full_sig', 'is_tight', 'win_type' and 'convention'. Otherwise, value with key 'win_array' is replaced by values with keys 'win_name' and 'win_len'.