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:

tuple

Variables:

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 l^1 norm to be 1.
'area' Normalize the area of the signal to be 1. This is exactly the same as '1'.
'2' Normalize the l^2 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 l^{\inf} 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 l^{\inf} 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.

See also

rms(), s0norm()

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 l^2 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 length N is computed by

rms(f) = \frac{1}{\sqrt N} \left( \sum_{n=1}^N |f(n)|^2
\right)^{\frac{1}{2}}

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:
  • 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 than middlepad().

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.

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 than middlepad().

long2fir(g, L, 'wp') or long2fir(g, L, 'hp') does the same assuming the input window is a whole-point even or half-point even window, respectively.

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 when centering='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 parameter beta
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 original firkaiser function available in LTFAT for Octave.

The 'derived' option is not currently implemented in this port because the original firkaiser function contains a reported bug.

We are thus waiting for the correction of the original code to add the 'derived' option to this port.

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:

tuple

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 -.5< x <.5.

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

g + \mbox{fftshift}(g) = \mathbf{1}_L

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 s 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 s=0. Half point even is the convention of most Matlab filter routines. It corresponds to a shift of s=-.5

    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 of normalize(). 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:

tuple

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()
    
thresh image

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 dimension 0 labelling groups, and dimension 1 labelling members. This means that the groups are the row vectors of the input (the vectors along the dimension 1).
  • 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 of thresh() for possible values, default thresh_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 on xi, with threshold lamb.

groupthresh(xi, lamb, dim) chooses groups along dimension dim.

The parameter group_type can take the following values:
'group' Shrinks all coefficients within a given group according to the value of the l^2 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 l^1 norm of the group in comparison to the threshold value lamb

See also

thresh()

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:

tuple

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

largestr()

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:

tuple

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

largestn()