References

Release:1.0.1
Date: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.

See also tutorial on constraints on the transform length

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).

See also tutorial on boundary effects

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.
Returns:

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]

Bases: pyteuf.tf_transforms.BaseStft

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.
Returns:

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.
Returns:

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]

Bases: pyteuf.tf_transforms.BaseStft

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.
Returns:

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.
Returns:

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.
Returns:

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’}).

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’}).

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]

Bases: madarrays.mad_array.MadArray

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).

See also

madarrays.mad_array.MadArray

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:

mask_type : {‘any’, ‘all’, ‘magnitude’, ‘phase’, ‘magnitude only’, ‘phase only’}, optional

Type of mask to be displayed, with True values for unknown data.
Returns:

numpy.ndarray

The processed image data used in the plotting as returned by plotdgt() or plotdgtreal().
Other Parameters:
 

**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:

mask_type : {‘any’, ‘all’, ‘magnitude’, ‘phase’, ‘magnitude_only’, ‘phase_only’}, optional

Type of mask to be displayed as unknown data.
Returns:

numpy.ndarray

The processed image data used in the plotting as returned by plotdgt() or plotdgtreal().
Other Parameters:
 

**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).
Returns:

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'.