References¶
Release: 1.0.1 Date: November 14, 2018
pyteuf.tf_transforms module¶
Direct and inverse shorttime 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 shorttime 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 highlevel description, or a lowlevel array:
 Highlevel 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 inwin_len
(leaving argumentwin_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 inltfatpy
. 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).  Lowlevel setting: window array: The user provides an arbitrary window
vector as an ndarray in
win_array
(leaving argumentswin_name
andwin_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
andn_bins
are kept unchanged, while the transform length is adjusted to the smallest multiple ofn_bins
by zeropadding the signal. This is appropriate whenhop
andn_bins
must not change while zeropadding 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 zeropadding the signal. This strategy limits the zeropadding of the signal by adjusting parametershop
andn_bins
. As a consequence, the input STFT parameters may not be exactly the same as the parameters used in the transform;'fix'
: parametershop
andn_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 withwin_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 shorttime 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 lowpass (i.e. frequency invariant) or ‘bp’ for bandpass (i.e. time invariant).

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 attributeswin_name
,win_len
, and so on. IfTrue
, compute the dual of this window.Returns: array_like

convention
¶ Type of convention ({‘lp’, ‘bp’}).
Type of convention : ‘lp’ for lowpass (i.e. frequency invariant) or ‘bp’ for bandpass (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 shorttime 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
, optionalWindow 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 lowpass (i.e. frequency invariant) or ‘bp’ for bandpass (i.e. time invariant).

apply
(X, signal_params=None)[source]¶ Apply inverse shorttime Fourier transform.
Parameters: X : array_like
Stft coefficients to be inversetransformed.
Returns:

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 lowpass (i.e. frequency invariant) or ‘bp’ for bandpass (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
Shorttime 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 lowpass (i.e. frequency invariant) or ‘bp’ for bandpass (i.e. time invariant).

apply
(x, fs=None)[source]¶ Compute ShortTime Fourier Transform of a signal.
Parameters: x : array_like
Input signal to be transformed.
Returns: TfData
Timefrequency matrix with related parameters. If input x is real, only coefficients for nonnegative 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_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 lowpass (i.e. frequency invariant) or ‘bp’ for bandpass (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 timefrequency data structure.

class
pyteuf.tf_data.
TfData
[source]¶ Bases:
madarrays.mad_array.MadArray
Subclass of
MadArray
to handle TimeFrequency representations of real signals.A TfData object is 2D
MadArray
, with either real or complex entries. It is initialized in the same way as aMadArray
object using binary or complex masks (see documentation ofMadArray
) It also two additional dictionaries tf_params and signal_params that contain respectively the parameters of the timefrequency 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 timefrequency transformation methods, and may be empty.Parameters: data : array of shape (n_frequencies, n_frames)
Timefrequency 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
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
Attributes
tf_params (dict) Timefrequency parameters (as described in the parameters section). signal_params (dict) Parameters of the original signal (as described in the parameters section). 
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()
orplotdgtreal()
.Other Parameters: **kwargs :
tfplot()
properties, optionalkwargs 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 attributesignal_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()
orplotdgtreal()
.Other Parameters: **kwargs :
tfplot()
properties, optionalkwargs 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 attributesignal_params
.

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 nonnegative 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 : 2tuple, optional
Range for the window length.
hop_divisor_lim : 2tuple, optional
Range for divisors of the window length in order to draw a hop size.
n_bins_factor_lim : 2tuple, 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 lowpass (i.e. frequency invariant) or ‘bp’ for bandpass (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'
.