ltfatpy.sigproc package - Signal processing tools¶
General¶
normalize¶
Module of signal normalization
Ported from ltfat_2.1.0/sigproc/normalize.m
-
ltfatpy.sigproc.normalize.
normalize
(f, norm='2', dim=None)[source]¶ Normalize input signal by specified norm
Usage:
(f, fnorm) = normalize(f)
(f, fnorm) = normalize(f, 'area')
(f, fnorm) = normalize(f, dim=2)
…
Parameters: - f (numpy.ndarray) – Input signal
- norm (str) – Name of the norm to apply
- dim (int) – Dimension along which norm is applied (first non-singleton dimension as default)
- Output parameters:
Returns: (f, fnorm)
Return type: Variables: - f (numpy.ndarray) – normalized signal
- fnorm (numpy.ndarray) – norm of the signal
normalize(f,...)
will normalize the signal f by the specified norm.- The norm is specified as a string and may be one of:
'1'
Normalize the norm to be 1. 'area'
Normalize the area of the signal to be 1. This is exactly the same as '1'
.'2'
Normalize the norm to be 1. This is the default 'energy'
Normalize the energy of the signal to be 1. This is exactly the same as '2'
.'inf'
Normalize the norm to be 1. 'peak'
Normalize the peak value of the signal to be 1. This is exactly the same as 'inf'
.'rms'
Normalize the Root Mean Square (RMS) norm of the signal to be 1. 's0'
Normalize the S0-norm to be 1. 'wav'
Normalize to the norm to be 0.99 to avoid possible clipping introduced by the quantization procedure when saving as a wav file. This only works with floating point data types. 'null'
Do NOT normalize, output is identical to input.
rms¶
Module of Root Mean Square calculation
Ported from ltfat_2.1.0/sigproc/rms.m
-
ltfatpy.sigproc.rms.
rms
(f, ac=False, dim=None)[source]¶ RMS value of signal
Usage:
y = rms(f)
Input parameters:
Parameters: - f (numpy.ndarray) – Input signal
- ac (bool) –
True
if calculation should only consider the AC component of the signal (i.e. the mean is removed).False
by default. - dim (int) – Dimension along which norm is applied (first non-singleton dimension as default)
- Output parameters:
Returns: RMS value Return type: float rms(f)
computes the RMS (Root Mean Square) value of a finite sampled signal sampled at a uniform sampling rate. This is a vector norm equal to the averaged by the length of the signal.If the input is a matrix or ND-array, the RMS is computed along the first (non-singleton) dimension, and a vector of values is returned.
The RMS value of a signal
f
of lengthN
is computed by
Window functions¶
fir2long¶
Module that extends fir windows with zeros
Ported from ltfat_2.1.0/sigproc/fir2long.m
-
ltfatpy.sigproc.fir2long.
fir2long
(gin, Llong)[source]¶ Extend FIR window to LONG
Usage:
g= fir2long(g, Llong)
Input parameters:
Parameters: - g (numpy.ndarray) – input window
- Llong (int) – new length
- Ouput parameters:
Returns: extended window Return type: numpy.ndarray fir2long(g,Llong)
will extend the FIR window g to a length Llong window by inserting zeros. Note that this is a slightly different behaviour thanmiddlepad()
.fir2long
can also be used to extend a FIR window to a longer FIR window, for instance in order to satisfy the usual requirement that the window length should be divisible by the number of channels.See also
long2fir¶
Module that cuts long windows to fir
Ported from ltfat_2.1.0/sigproc/long2fir.m
-
ltfatpy.sigproc.long2fir.
long2fir
(g, L, centering='unsymmetric')[source]¶ Cut LONG window to FIR
Usage:
g = long2fir(g, L)
g = long2fir(g, L, 'hp')
Input parameters:
Parameters: - g (numpy.ndarray) – long window
- L (int) – length of the output FIR window
- centering (str) – ‘wp’ or ‘hp’ for whole point even or half point even input window. ‘unsymmetric’ makes no assumption on the symmetry of the input data. Default is ‘unsymmetric’
- Output parameters:
Returns: the FIR window Return type: numpy.ndarray long2fir(g, L)
will cut the LONG window g to a length L FIR window by cutting out the middle part. Note that this is a slightly different behaviour thanmiddlepad()
.long2fir(g, L, 'wp')
orlong2fir(g, L, 'hp')
does the same assuming the input window is a whole-point even or half-point even window, respectively.See also
firkaiser¶
Module of Kaiser-Bessel window calculation
Ported from ltfat_2.1.0/sigproc/firkaiser.m
-
ltfatpy.sigproc.firkaiser.
firkaiser
(L, beta, centering='wp', norm='null')[source]¶ Kaiser-Bessel window
Usage:
g = firkaiser(L, beta)
g = firkaiser(L, beta,...)
Input parameters:
Parameters: - L (int) – length of the window
- beta (int) – beta parameter of the Kaiser-Bessel window
- centering (str) – Flag specifying if the generated window g is
whole point even when
centering='wp'
or half point even whencentering='hp'
- norm (str) – Normalization flag for the output. Please see the
parameter norm in the help of
normalize()
for possible values.
- Output parameters:
Returns: Kaiser-Bessel window of length L
with parameterbeta
Return type: numpy.ndarray firkaiser(L, beta)
computes the Kaiser-Bessel window of length L with parameter beta. The smallest element of the window is set to zero when the window has an even length. This gives the window perfect whole-point even symmetry, and makes it possible to use the window for a Wilson basis.Note
This Python port only implements the
'normal'
option of the originalfirkaiser
function available in LTFAT for Octave.The
'derived'
option is not currently implemented in this port because the originalfirkaiser
function contains a reported bug.We are thus waiting for the correction of the original code to add the
'derived'
option to this port.See also
- References:
- [OS89]
firwin¶
Module of fir windows calculation
Ported from ltfat_2.1.0/sigproc/firwin.m
-
ltfatpy.sigproc.firwin.
firwin
(name, M=0, x=None, **kwargs)[source]¶ Returns a FIR window of length M of type name.
Usage:
(g, info) = firwin(name, M)
(g, info) = firwin(name, M,...)
(g, info) = firwin(name, x)
Input parameters:
Parameters: - name (str) – is the window.
- M (int) – is the length of the window
- x (numpy.ndarray) – is a points vector (default = None)
- Output parameters:
Returns: (g, info)
Return type: Variables: - g (numpy.ndarray) – window values array
- info (dict) – the information dictionary
All windows are symmetric and generate zero delay and zero phase filters. They can be used for the Wilson and WMDCT transform, except when noted otherwise.
firwin(name, x=numpy.array(...))
where x is a vector will sample the window definition as the specified points. The normal sampling interval for the windows is .In the following PSL means “Peak Sidelobe level”, and the main lobe width is measured in normalized frequencies.
If a window g forms a “partition of unity” (PU) it means specifically that
A PU can only be formed if the window length is even, but some windows may work for odd lengths anyway.
If a window is the square root of a window that forms a PU, the window will generate a tight Gabor frame / orthonormal Wilson/WMDCT basis if the number of channels is less than M.
The windows available are:
‘hann’ von Hann window. Forms a PU. The Hann window has a mainlobe with of 8/M, a PSL of -31.5 dB and decay rate of 18 dB/Octave. ‘sine’ Sine window. This is the square root of the Hanning window. The sine window has a mainlobe width of 8/M, a PSL of -22.3 dB and decay rate of 12 dB/Octave.
- Aliases: ‘cosine’, ‘sqrthann’
‘rect’ (Almost) rectangular window. The rectangular window has a mainlobe width of 4/M, a PSL of -13.3 dB and decay rate of 6 dB/Octave. Forms a PU if the order is odd.
- Alias: ‘square’
‘tria’ (Almost) triangular window. Forms a PU.
- Alias: ‘bartlett’
‘sqrttria’ Square root of the triangular window. ‘hamming’ Hamming window. Forms a PU that sums to 1.08 instead of 1.0 as usual. The Hamming window has a mainlobe width of 8/M, a PSL of -42.7 dB and decay rate of 6 dB/Octave. This window should not be used for a Wilson basis, as a reconstruction window cannot be found by wildual. ‘blackman’ Blackman window. The Blackman window has a mainlobe width of 12/M, a PSL of -58.1 dB and decay rate of 18 dB/Octave. ‘blackman2’ Alternate Blackman window. This window has a mainlobe width of 12/M, a PSL of -68.24 dB and decay rate of 6 dB/Octave. ‘itersine’ Iterated sine window. Generates an orthonormal Wilson/WMDCT basis. This window is described in Wesfreid and Wickerhauser (1993) and is used in the ogg sound codec.
- Alias: ‘ogg’
‘nuttall’ Nuttall window. The Nuttall window has a mainlobe width of 16/M, a PSL of -93.32 dB and decay rate of 18 dB/Octave. ‘nuttall10’ 2-term Nuttall window with 1 continuous derivative.
- Alias: ‘hann’, ‘hanning’.
‘nuttall01’ 2-term Nuttall window with 0 continuous derivatives. This is a slightly improved Hamming window. It has a mainlobe width of 8/M, a PSL of -43.19 dB and decay rate of 6 dB/Octave. ‘nuttall20’ 3-term Nuttall window with 3 continuous derivatives. The window has a mainlobe width of 12/M, a PSL of -46.74 dB and decay rate of 30 dB/Octave. ‘nuttall11’ 3-term Nuttall window with 1 continuous derivative. The window has a mainlobe width of 12/M, a PSL of -64.19 dB and decay rate of 18 dB/Octave. ‘nuttall02’ 3-term Nuttall window with 0 continuous derivatives. The window has a mainlobe width of 12/M, a PSL of -71.48 dB and decay rate of 6 dB/Octave. ‘nuttall30’ 4-term Nuttall window with 5 continuous derivatives. The window has a mainlobe width of 16/M, a PSL of -60.95 dB and decay rate of 42 dB/Octave. ‘nuttall21’ 4-term Nuttall window with 3 continuous derivatives. The window has a mainlobe width of 16/M, a PSL of -82.60 dB and decay rate of 30 dB/Octave. ‘nuttall12’ 4-term Nuttall window with 1 continuous derivatives.
- Alias: ‘nuttall’.
‘nuttall03’ 4-term Nuttall window with 0 continuous derivatives. The window has a mainlobe width of 16/M, a PSL of -98.17 dB and decay rate of 6 dB/Octave. Additional keywords arguments:
firwin
understands the following keyword arguments at the end of the list of input:- shift = s
Shift the window by samples. The value can be a fractional number.
- centering = ‘wp’ or ‘hp’
Point even output type : whole or half point even. Whole point even is the default. It corresponds to a shift of . Half point even is the convention of most Matlab filter routines. It corresponds to a shift of
- taper = t
Extend the window by a flat section in the middle. The argument t is the ratio of the rising and falling parts as compared to the total length of the window. The default value of 1 means no tapering. Accepted values lie in the range from 0 to 1.
Additionally,
firwin
accepts flags to normalize the output. Please see the help ofnormalize()
. Default is to use no normalization. For filtering in the time-domain, a normalization of ‘1’ or ‘area’ is preferable.See also
pgauss()
,pbspline()
,firkaiser()
,normalize()
Thresholding methods¶
thresh¶
Module of coefficient thresholding
Ported from ltfat_2.1.0/sigproc/thresh.m
-
ltfatpy.sigproc.thresh.
thresh
(xi, lamb, thresh_type='hard')[source]¶ Coefficient thresholding
Usage:
(xo, N) = thresh(xi, lamb)
(xo, N) = thresh(xi, lamb, thresh_type)
Input parameters:
Parameters: - xi (numpy.ndarray) – Input array
- lamb (float or numpy.ndarray) – Threshold
- thresh_type (str) – Optional flag specifying the type of thresholding (see possible values below)
- Output parameters:
Returns: (xo, N)
Return type: Variables: - xo (numpy.ndarray) – Array of the same shape as xi containing data from xi after thresholding
- N (int) – Number of coefficients kept
thresh(xi, lamb)
will perform hard thresholding on xi, i.e. all elements with absolute value less than scalar lamb will be set to zero.thresh(xi, lamb, 'soft')
will perform soft thresholding on xi, i.e. lamb will be substracted from the absolute value of every element of xi.The lamb parameter can also be a vector with number of elements equal to
xi.size
or it can be a numpy array of the same shape as xi. lamb is then applied element-wise and in a column major order if lamb is a vector.- The parameter thresh_type can take the following values:
'hard'
Perform hard thresholding. This is the default. 'wiener'
Perform empirical Wiener shrinkage. This is in between soft and hard thresholding. 'soft'
Perform soft thresholding.
The function
wthresh
in the Matlab Wavelet toolbox implements some of the same functionality.Example:
The following code produces a plot to demonstrate the difference between hard and soft thresholding for a simple linear input:
>>> import numpy as np >>> import matplotlib.pyplot as plt >>> from ltfatpy.sigproc.thresh import thresh >>> t = np.linspace(-4, 4, 100) >>> _ = plt.plot(t, thresh(t, 1., 'soft')[0], 'r', ... t, thresh(t, 1., 'hard')[0], '.b', ... t, thresh(t, 1., 'wiener')[0], '--g') >>> _ = plt.legend(('Soft thresh.', 'Hard thresh.', 'Wiener thresh.'), ... loc='upper left') >>> plt.show()
See also
groupthresh¶
Module of group thresholding
Ported from ltfat_2.1.0/sigproc/groupthresh.m
-
ltfatpy.sigproc.groupthresh.
groupthresh
(xi, lamb, dim=1, group_type='group', thresh_type='soft')[source]¶ Group thresholding
Usage:
xo = groupthresh(xi, lamb)
xo = groupthresh(xi, lamb, dim)
xo = groupthresh(xi, lamb, ...)
Input parameters:
Parameters: - xi (numpy.ndarray) – Input array.
xi
must be a two-dimensional array, with dimension0
labelling groups, and dimension1
labelling members. This means that the groups are the row vectors of the input (the vectors along the dimension1
). - lamb (float) – Threshold
- dim (int) – Dimension along which to choose the groups
(default
dim=1
) - group_type (str) – Optional flag specifying the grouping behaviour (see possible values below)
- thresh_type (str) – Optional flag specifying the type of thresholding
within each group (see the parameter
thresh_type
in the help ofthresh()
for possible values, defaultthresh_type=soft
)
- Output parameters:
Returns: Array of the same shape as xi containing data from xi after group thresholding Return type: numpy.ndarray groupthresh(xi, lamb)
performs group thresholding onxi
, with thresholdlamb
.groupthresh(xi, lamb, dim)
chooses groups along dimensiondim
.- The parameter group_type can take the following values:
'group'
Shrinks all coefficients within a given group according to the value of the norm of the group in comparison to the threshold lamb
. This is the default'elite'
Shrinks all coefficients within a given group according to the value of the norm of the group in comparison to the threshold value lamb
See also
- References:
- [KTorresani09][Kow09][YMB08]
largestn¶
Module of N largest coefficients extraction
Ported from ltfat_2.1.0/sigproc/largestn.m
-
ltfatpy.sigproc.largestn.
largestn
(xi, N, thresh_type='hard')[source]¶ Keep N largest coefficients
Usage:
(xo, Nout) = largestn(xi, N)
(xo, Nout) = largestn(xi, N, thresh_type)
Input parameters:
Parameters: - xi (numpy.ndarray) – Input array
- N (int) – Number of kept coefficients
- thresh_type (str) – Optional flag specifying the type of thresholding (see possible values below)
- Output parameters:
Returns: (xo, Nout)
Return type: Variables: - xo (numpy.ndarray) – Array of the same shape as xi keeping the N largest coefficients
- Nout (int) – Number of coefficients kept
- The parameter thresh_type can take the following values:
'hard'
Perform hard thresholding. This is the default. 'wiener'
Perform empirical Wiener shrinkage. This is in between soft and hard thresholding. 'soft'
Perform soft thresholding.
If the coefficients represents a signal expanded in an orthonormal basis then this will be the best N-term approximation.
Note
If soft- or Wiener thresholding is selected, only
N-1
coefficients will actually be returned. This is caused by the Nth coefficient being set to zero.See also
- References:
- [Mal98]
largestr¶
Module of fixed ratio of largest coefficients extraction
Ported from ltfat_2.1.0/sigproc/largestr.m
-
ltfatpy.sigproc.largestr.
largestr
(xi, p, thresh_type='hard')[source]¶ Keep fixed ratio of largest coefficients
Usage:
(xo, Nout) = largestr(xi, p)
(xo, Nout) = largestr(xi, p, thresh_type)
Input parameters:
Parameters: - xi (numpy.ndarray) – Input array
- p (float) – Ratio of kept coefficients
- thresh_type (str) – Optional flag specifying the type of thresholding (see possible values below)
- Output parameters:
Returns: (xo, Nout)
Return type: Variables: - xo (numpy.ndarray) – Array of the same shape as xi keeping the fraction p of the coefficients with the largest magnitude
- Nout (int) – Number of coefficients kept
Note
If the function is used on coefficients coming from a redundant transform or from a transform where the input signal was padded, the coefficient array will be larger than the original input signal. Therefore, the number of coefficients kept might be higher than expected.
- The parameter thresh_type can take the following values:
'hard'
Perform hard thresholding. This is the default. 'wiener'
Perform empirical Wiener shrinkage. This is in between soft and hard thresholding. 'soft'
Perform soft thresholding.
Note
If soft- or Wiener thresholding is selected, one less coefficient will actually be returned. This is caused by that coefficient being set to zero.
See also
- References:
- [Mal98]