Adaptfilt
=========
Adaptfilt is an adaptive filtering module for Python. It includes simple, procedural implementations of the following filtering algorithms:
* **Least-mean-squares (LMS)** - including traditional and leaky filtering
* **Normalized least-mean-squares (NLMS)** - including traditional and leaky filtering with recursively updated input energy
* **Affine projection (AP)** - including traditional and leaky filtering
* **Recursive least squares (RLS)**
The algorithms are implemented using Numpy for computational efficiency. Further optimization have also been done, but this is very limited and only on the most computationally intensive parts of the source code.
| **Authors**: Jesper Wramberg & Mathias Tausen
| **Version**: 0.3
| **PyPI**: https://pypi.python.org/pypi/adaptfilt
| **GitHub**: https://github.com/Wramberg/adaptfilt
| **License**: MIT
Installation
------------
To install from PyPI using pip simply run::
sudo pip install adaptfilt
Alternatively, the module can also be downloaded at https://pypi.python.org/pypi/adaptfilt or
https://github.com/Wramberg/adaptfilt. The latter is also used for issue tracking. Note that adaptfilt requires Numpy to run (tested using version 1.9.0).
Usage
-----
Once installed, the module should be available for import by calling::
import adaptfilt
Following the reference sections, examples are provided to show the modules functionality. Please do not hesitate to star us on GitHub if you found the module useful.
Function Reference
------------------
In this section, the functions provided by adaptfilt are described. The descriptions correspond with excerpts from the function docstrings and are only included here for your convenience.
**y, e, w = lms(u, d, M, step, leak=0., initCoeffs=None, N=None, returnCoeffs=False)**
Perform least-mean-squares (LMS) adaptive filtering on u to minimize error
given by e=d-y, where y is the output of the adaptive filter.
Parameters
u : array-like
One-dimensional filter input.
d : array-like
One-dimensional desired signal, i.e., the output of the unknown FIR
system which the adaptive filter should identify. Must have length >=
len(u), or N+M-1 if number of iterations are limited (via the N
parameter).
M : int
Desired number of filter taps (desired filter order + 1), must be
non-negative.
step : float
Step size of the algorithm, must be non-negative.
Optional Parameters
leak : float
Leakage factor, must be equal to or greater than zero and smaller than
one. When greater than zero a leaky LMS filter is used. Defaults to 0,
i.e., no leakage.
initCoeffs : array-like
Initial filter coefficients to use. Should match desired number of
filter taps, defaults to zeros.
N : int
Number of iterations, must be less than or equal to len(u)-M+1
(default).
returnCoeffs : boolean
If true, will return all filter coefficients for every iteration in an
N x M matrix. Does not include the initial coefficients. If false, only
the latest coefficients in a vector of length M is returned. Defaults
to false.
Returns
y : numpy.array
Output values of LMS filter, array of length N.
e : numpy.array
Error signal, i.e, d-y. Array of length N.
w : numpy.array
Final filter coefficients in array of length M if returnCoeffs is
False. NxM array containing all filter coefficients for all iterations
otherwise.
Raises
TypeError
If number of filter taps M is not type integer, number of iterations N
is not type integer, or leakage leak is not type float/int.
ValueError
If number of iterations N is greater than len(u)-M, number of filter
taps M is negative, or if step-size or leakage is outside specified
range.
**y, e, w = nlmsru(u, d, M, step, eps=0.001, leak=0, initCoeffs=None, N=None, returnCoeffs=False)**
Same as nlms but updates input energy recursively for faster computation. Note that this can cause instability due to rounding errors.
**y, e, w = nlms(u, d, M, step, eps=0.001, leak=0, initCoeffs=None, N=None, returnCoeffs=False)**
Perform normalized least-mean-squares (NLMS) adaptive filtering on u to
minimize error given by e=d-y, where y is the output of the adaptive
filter.
Parameters
u : array-like
One-dimensional filter input.
d : array-like
One-dimensional desired signal, i.e., the output of the unknown FIR
system which the adaptive filter should identify. Must have length >=
len(u), or N+M-1 if number of iterations are limited (via the N
parameter).
M : int
Desired number of filter taps (desired filter order + 1), must be
non-negative.
step : float
Step size of the algorithm, must be non-negative.
Optional Parameters
eps : float
Regularization factor to avoid numerical issues when power of input
is close to zero. Defaults to 0.001. Must be non-negative.
leak : float
Leakage factor, must be equal to or greater than zero and smaller than
one. When greater than zero a leaky LMS filter is used. Defaults to 0,
i.e., no leakage.
initCoeffs : array-like
Initial filter coefficients to use. Should match desired number of
filter taps, defaults to zeros.
N : int
Number of iterations to run. Must be less than or equal to len(u)-M+1.
Defaults to len(u)-M+1.
returnCoeffs : boolean
If true, will return all filter coefficients for every iteration in an
N x M matrix. Does not include the initial coefficients. If false, only
the latest coefficients in a vector of length M is returned. Defaults
to false.
Returns
y : numpy.array
Output values of LMS filter, array of length N.
e : numpy.array
Error signal, i.e, d-y. Array of length N.
w : numpy.array
Final filter coefficients in array of length M if returnCoeffs is
False. NxM array containing all filter coefficients for all iterations
otherwise.
Raises
TypeError
If number of filter taps M is not type integer, number of iterations N
is not type integer, or leakage leak is not type float/int.
ValueError
If number of iterations N is greater than len(u)-M, number of filter
taps M is negative, or if step-size or leakage is outside specified
range.
**y, e, w = ap(u, d, M, step, K, eps=0.001, leak=0, initCoeffs=None, N=None, returnCoeffs=False)**
Perform affine projection (AP) adaptive filtering on u to minimize error
given by e=d-y, where y is the output of the adaptive filter.
Parameters
u : array-like
One-dimensional filter input.
d : array-like
One-dimensional desired signal, i.e., the output of the unknown FIR
system which the adaptive filter should identify. Must have length >=
len(u), or N+M-1 if number of iterations are limited (via the N
parameter).
M : int
Desired number of filter taps (desired filter order + 1), must be
non-negative.
step : float
Step size of the algorithm, must be non-negative.
K : int
Projection order, must be integer larger than zero.
Optional Parameters
eps : float
Regularization factor to avoid numerical issues when power of input
is close to zero. Defaults to 0.001. Must be non-negative.
leak : float
Leakage factor, must be equal to or greater than zero and smaller than
one. When greater than zero a leaky LMS filter is used. Defaults to 0,
i.e., no leakage.
initCoeffs : array-like
Initial filter coefficients to use. Should match desired number of
filter taps, defaults to zeros.
N : int
Number of iterations to run. Must be less than or equal to len(u)-M+1.
Defaults to len(u)-M+1.
returnCoeffs : boolean
If true, will return all filter coefficients for every iteration in an
N x M matrix. Does not include the initial coefficients. If false, only
the latest coefficients in a vector of length M is returned. Defaults
to false.
Returns
y : numpy.array
Output values of LMS filter, array of length N.
e : numpy.array
Error signal, i.e, d-y. Array of length N.
w : numpy.array
Final filter coefficients in array of length M if returnCoeffs is
False. NxM array containing all filter coefficients for all iterations
otherwise.
Raises
TypeError
If number of filter taps M is not type integer, number of iterations N
is not type integer, or leakage leak is not type float/int.
ValueError
If number of iterations N is greater than len(u)-M, number of filter
taps M is negative, or if step-size or leakage is outside specified
range.
Helper Function Reference
-------------------------
**mswe = mswe(w, v)**
Calculate mean squared weight error between estimated and true filter
coefficients, in respect to iterations.
Parameters
v : array-like
True coefficients used to generate desired signal, must be a
one-dimensional array.
w : array-like
Estimated coefficients from adaptive filtering algorithm. Must be an
N x M matrix where N is the number of iterations, and M is the number
of filter coefficients.
Returns
mswe : numpy.array
One-dimensional array containing the mean-squared weight error for
every iteration.
Raises
TypeError
If inputs have wrong dimensions
Note
To use this function with the adaptive filter functions set the optional
parameter returnCoeffs to True. This will return a coefficient matrix w
corresponding with the input-parameter w.
Examples
--------
The following examples illustrate the use of the adaptfilt module. Note that the matplotlib.pyplot module is required to run them.
Acoustic echo cancellation
++++++++++++++++++++++++++
::
"""
Acoustic echo cancellation in white background noise with NLMS.
Consider a scenario where two individuals, John and Emily, are talking over the
Internet. John is using his loudspeakers, which means Emily can hear herself
through John's microphone. The speech signal that Emily hears, is a distorted
version of her own. This is caused by the acoustic path from John's
loudspeakers to his microphone. This path includes attenuated echoes, etc.
Now for the problem!
Emily wishes to cancel the echo she hears from John's microphone. Emily only
knows the speech signal she sends to him, call that u(n), and the speech signal
she receives from him, call that d(n). To successfully remove her own echo
from d(n), she must approximate the acoustic path from John's loudspeakers to
his microphone. This path can be approximated by a FIR filter, which means an
adaptive NLMS FIR filter can be used to identify it. The model which Emily uses
to design this filter looks like this:
u(n) ------->->------+----------->->-----------
| |
+-----------------+ +------------------+
+->-| Adaptive filter | | John's Room |
| +-----------------+ +------------------+
| | -y(n) |
| | d(n) |
e(n) ---+---<-<------+-----------<-<----------+----<-<---- v(n)
As seen, the signal that is sent to John is also used as input to the adaptive
NLMS filter. The output of the filter, y(n), is subtracted from the signal
received from John, which results in an error signal e(n) = d(n)-y(n). By
feeding the error signal back to the adaptive filter, it can minimize the error
by approximating the impulse response (that is the FIR filter coefficients) of
John's room. Note that so far John's speech signal v(n) has not been taken into
account. If John speaks, the error should equal his speech, that is, e(n)
should equal v(n). For this simple example, however, we assume John is quiet
and v(n) is equal to white Gaussian background noise with zero-mean.
In the following example we keep the impulse response of John's room constant.
This is not required, however, since the advantage of adaptive filters, is that
they can be used to track changes in the impulse response.
A short speech sample is included in speech.npy, available on github or pypi in
the examples folder. The sample is single-channel and is in floating-point
format to keep the example simple. The original recording is sampled at 44.1
kHz, and has been downsampled by a factor of 4. To listen to any of the audio
signals of the example, they can be normalized and stored as wav files with
scipy:
from scipy.io.wavfile import write
write("d.wav", 44100/4, d/np.max(d))
"""
import numpy as np
import matplotlib.pyplot as plt
import adaptfilt as adf
# Get u(n) - this is available on github or pypi in the examples folder
u = np.load('speech.npy')
# Generate received signal d(n) using randomly chosen coefficients
coeffs = np.concatenate(([0.8], np.zeros(8), [-0.7], np.zeros(9),
[0.5], np.zeros(11), [-0.3], np.zeros(3),
[0.1], np.zeros(20), [-0.05]))
d = np.convolve(u, coeffs)
# Add background noise
v = np.random.randn(len(d)) * np.sqrt(5000)
d += v
# Apply adaptive filter
M = 100 # Number of filter taps in adaptive filter
step = 0.1 # Step size
y, e, w = adf.nlms(u, d, M, step, returnCoeffs=True)
# Calculate mean square weight error
mswe = adf.mswe(w, coeffs)
# Plot speech signals
plt.figure()
plt.title("Speech signals")
plt.plot(u, label="Emily's speech signal, u(n)")
plt.plot(d, label="Speech signal from John, d(n)")
plt.grid()
plt.legend()
plt.xlabel('Samples')
# Plot error signal - note how the measurement noise affects the error
plt.figure()
plt.title('Error signal e(n)')
plt.plot(e)
plt.grid()
plt.xlabel('Samples')
# Plot mean squared weight error - note that the measurement noise causes the
# error the increase at some points when Emily isn't speaking
plt.figure()
plt.title('Mean squared weight error')
plt.plot(mswe)
plt.grid()
plt.xlabel('Samples')
# Plot final coefficients versus real coefficients
plt.figure()
plt.title('Real coefficients vs. estimated coefficients')
plt.plot(w[-1], 'g', label='Estimated coefficients')
plt.plot(coeffs, 'b--', label='Real coefficients')
plt.grid()
plt.legend()
plt.xlabel('Samples')
plt.show()
.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/echocancel-input.png
.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/echocancel-error.png
.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/echocancel-mswe.png
.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/echocancel-coeffs.png
Convergence comparison
++++++++++++++++++++++
::
"""
Convergence comparison of different adaptive filtering algorithms (with
different step sizes) in white Gaussian noise.
"""
import numpy as np
import matplotlib.pyplot as plt
import adaptfilt as adf
# Generating input and desired signal
N = 3000
coeffs = np.concatenate(([-4, 3.2], np.zeros(20), [0.7], np.zeros(33), [-0.1]))
u = np.random.randn(N)
d = np.convolve(u, coeffs)
# Perform filtering
M = 60 # No. of taps to estimate
mu1 = 0.0008 # Step size 1 in LMS
mu2 = 0.0004 # Step size 1 in LMS
beta1 = 0.08 # Step size 2 in NLMS and AP
beta2 = 0.04 # Step size 2 in NLMS and AP
K = 3 # Projection order 1 in AP
# LMS
y_lms1, e_lms1, w_lms1 = adf.lms(u, d, M, mu1, returnCoeffs=True)
y_lms2, e_lms2, w_lms2 = adf.lms(u, d, M, mu2, returnCoeffs=True)
mswe_lms1 = adf.mswe(w_lms1, coeffs)
mswe_lms2 = adf.mswe(w_lms2, coeffs)
# NLMS
y_nlms1, e_nlms1, w_nlms1 = adf.nlms(u, d, M, beta1, returnCoeffs=True)
y_nlms2, e_nlms2, w_nlms2 = adf.nlms(u, d, M, beta2, returnCoeffs=True)
mswe_nlms1 = adf.mswe(w_nlms1, coeffs)
mswe_nlms2 = adf.mswe(w_nlms2, coeffs)
# AP
y_ap1, e_ap1, w_ap1 = adf.ap(u, d, M, beta1, K, returnCoeffs=True)
y_ap2, e_ap2, w_ap2 = adf.ap(u, d, M, beta2, K, returnCoeffs=True)
mswe_ap1 = adf.mswe(w_ap1, coeffs)
mswe_ap2 = adf.mswe(w_ap2, coeffs)
# Plot results
plt.figure()
plt.title('Convergence comparison of different adaptive filtering algorithms')
plt.plot(mswe_lms1, 'b', label='LMS with stepsize=%.4f' % mu1)
plt.plot(mswe_lms2, 'b--', label='LMS with stepsize=%.4f' % mu2)
plt.plot(mswe_nlms1, 'g', label='NLMS with stepsize=%.2f' % beta1)
plt.plot(mswe_nlms2, 'g--', label='NLMS with stepsize=%.2f' % beta2)
plt.plot(mswe_ap1, 'r', label='AP with stepsize=%.2f' % beta1)
plt.plot(mswe_ap2, 'r--', label='AP with stepsize=%.2f' % beta2)
plt.legend()
plt.grid()
plt.xlabel('Iterations')
plt.ylabel('Mean-squared weight error')
plt.show()
.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/convergence-result.png
Release History
---------------
0.3
+++
| Included RLS filtering function.
| Added support for complex signals.
| Support Python 3
0.2
+++
| Included NLMS filtering function with recursive updates of input energy.
| Included acoustic echo cancellation example.
0.1
+++
| Initial module with LMS, NLMS and AP filtering functions.
Raw data
{
"_id": null,
"home_page": "https://github.com/Wramberg/adaptfilt",
"name": "adaptfilt",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "adaptive filter, adaptive filtering, signal processing, lms, apa, nlms, rls",
"author": "Jesper Wramberg & Mathias Tausen",
"author_email": "jesper.wramberg@gmail.com & mathias.tausen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/15/cc/7c9730e3a80eb3b05007f72b25a60c7c17252d569a86a9aa9e0e98ed28da/adaptfilt-0.3.tar.gz",
"platform": null,
"description": "Adaptfilt\n=========\n\nAdaptfilt is an adaptive filtering module for Python. It includes simple, procedural implementations of the following filtering algorithms:\n\n* **Least-mean-squares (LMS)** - including traditional and leaky filtering\n* **Normalized least-mean-squares (NLMS)** - including traditional and leaky filtering with recursively updated input energy\n* **Affine projection (AP)** - including traditional and leaky filtering\n* **Recursive least squares (RLS)**\n\nThe algorithms are implemented using Numpy for computational efficiency. Further optimization have also been done, but this is very limited and only on the most computationally intensive parts of the source code.\n\n| **Authors**: Jesper Wramberg & Mathias Tausen\n| **Version**: 0.3\n| **PyPI**: https://pypi.python.org/pypi/adaptfilt\n| **GitHub**: https://github.com/Wramberg/adaptfilt\n| **License**: MIT\n\nInstallation\n------------\nTo install from PyPI using pip simply run::\n\n sudo pip install adaptfilt\n\nAlternatively, the module can also be downloaded at https://pypi.python.org/pypi/adaptfilt or \nhttps://github.com/Wramberg/adaptfilt. The latter is also used for issue tracking. Note that adaptfilt requires Numpy to run (tested using version 1.9.0).\n\nUsage\n-----\nOnce installed, the module should be available for import by calling::\n\n import adaptfilt\n\nFollowing the reference sections, examples are provided to show the modules functionality. Please do not hesitate to star us on GitHub if you found the module useful.\n\nFunction Reference\n------------------\nIn this section, the functions provided by adaptfilt are described. The descriptions correspond with excerpts from the function docstrings and are only included here for your convenience.\n\n**y, e, w = lms(u, d, M, step, leak=0., initCoeffs=None, N=None, returnCoeffs=False)**\n\n Perform least-mean-squares (LMS) adaptive filtering on u to minimize error\n given by e=d-y, where y is the output of the adaptive filter.\n\n Parameters\n u : array-like\n One-dimensional filter input.\n d : array-like\n One-dimensional desired signal, i.e., the output of the unknown FIR\n system which the adaptive filter should identify. Must have length >=\n len(u), or N+M-1 if number of iterations are limited (via the N\n parameter).\n M : int\n Desired number of filter taps (desired filter order + 1), must be\n non-negative.\n step : float\n Step size of the algorithm, must be non-negative.\n\n Optional Parameters\n leak : float\n Leakage factor, must be equal to or greater than zero and smaller than\n one. When greater than zero a leaky LMS filter is used. Defaults to 0,\n i.e., no leakage.\n initCoeffs : array-like\n Initial filter coefficients to use. Should match desired number of\n filter taps, defaults to zeros.\n N : int\n Number of iterations, must be less than or equal to len(u)-M+1\n (default).\n returnCoeffs : boolean\n If true, will return all filter coefficients for every iteration in an\n N x M matrix. Does not include the initial coefficients. If false, only\n the latest coefficients in a vector of length M is returned. Defaults\n to false.\n\n Returns\n y : numpy.array\n Output values of LMS filter, array of length N.\n e : numpy.array\n Error signal, i.e, d-y. Array of length N.\n w : numpy.array\n Final filter coefficients in array of length M if returnCoeffs is\n False. NxM array containing all filter coefficients for all iterations\n otherwise.\n\n Raises\n TypeError\n If number of filter taps M is not type integer, number of iterations N\n is not type integer, or leakage leak is not type float/int.\n ValueError\n If number of iterations N is greater than len(u)-M, number of filter\n taps M is negative, or if step-size or leakage is outside specified\n range.\n\n**y, e, w = nlmsru(u, d, M, step, eps=0.001, leak=0, initCoeffs=None, N=None, returnCoeffs=False)**\n\n Same as nlms but updates input energy recursively for faster computation. Note that this can cause instability due to rounding errors.\n\n**y, e, w = nlms(u, d, M, step, eps=0.001, leak=0, initCoeffs=None, N=None, returnCoeffs=False)**\n\n Perform normalized least-mean-squares (NLMS) adaptive filtering on u to\n minimize error given by e=d-y, where y is the output of the adaptive\n filter.\n\n Parameters\n u : array-like\n One-dimensional filter input.\n d : array-like\n One-dimensional desired signal, i.e., the output of the unknown FIR\n system which the adaptive filter should identify. Must have length >=\n len(u), or N+M-1 if number of iterations are limited (via the N\n parameter).\n M : int\n Desired number of filter taps (desired filter order + 1), must be\n non-negative.\n step : float\n Step size of the algorithm, must be non-negative.\n\n Optional Parameters\n eps : float\n Regularization factor to avoid numerical issues when power of input\n is close to zero. Defaults to 0.001. Must be non-negative.\n leak : float\n Leakage factor, must be equal to or greater than zero and smaller than\n one. When greater than zero a leaky LMS filter is used. Defaults to 0,\n i.e., no leakage.\n initCoeffs : array-like\n Initial filter coefficients to use. Should match desired number of\n filter taps, defaults to zeros.\n N : int\n Number of iterations to run. Must be less than or equal to len(u)-M+1.\n Defaults to len(u)-M+1.\n returnCoeffs : boolean\n If true, will return all filter coefficients for every iteration in an\n N x M matrix. Does not include the initial coefficients. If false, only\n the latest coefficients in a vector of length M is returned. Defaults\n to false.\n\n Returns\n y : numpy.array\n Output values of LMS filter, array of length N.\n e : numpy.array\n Error signal, i.e, d-y. Array of length N.\n w : numpy.array\n Final filter coefficients in array of length M if returnCoeffs is\n False. NxM array containing all filter coefficients for all iterations\n otherwise.\n\n Raises\n TypeError\n If number of filter taps M is not type integer, number of iterations N\n is not type integer, or leakage leak is not type float/int.\n ValueError\n If number of iterations N is greater than len(u)-M, number of filter\n taps M is negative, or if step-size or leakage is outside specified\n range.\n\n\n**y, e, w = ap(u, d, M, step, K, eps=0.001, leak=0, initCoeffs=None, N=None, returnCoeffs=False)**\n\n Perform affine projection (AP) adaptive filtering on u to minimize error\n given by e=d-y, where y is the output of the adaptive filter.\n\n Parameters\n u : array-like\n One-dimensional filter input.\n d : array-like\n One-dimensional desired signal, i.e., the output of the unknown FIR\n system which the adaptive filter should identify. Must have length >=\n len(u), or N+M-1 if number of iterations are limited (via the N\n parameter).\n M : int\n Desired number of filter taps (desired filter order + 1), must be\n non-negative.\n step : float\n Step size of the algorithm, must be non-negative.\n K : int\n Projection order, must be integer larger than zero.\n\n Optional Parameters\n eps : float\n Regularization factor to avoid numerical issues when power of input\n is close to zero. Defaults to 0.001. Must be non-negative.\n leak : float\n Leakage factor, must be equal to or greater than zero and smaller than\n one. When greater than zero a leaky LMS filter is used. Defaults to 0,\n i.e., no leakage.\n initCoeffs : array-like\n Initial filter coefficients to use. Should match desired number of\n filter taps, defaults to zeros.\n N : int\n Number of iterations to run. Must be less than or equal to len(u)-M+1.\n Defaults to len(u)-M+1.\n returnCoeffs : boolean\n If true, will return all filter coefficients for every iteration in an\n N x M matrix. Does not include the initial coefficients. If false, only\n the latest coefficients in a vector of length M is returned. Defaults\n to false.\n\n Returns\n y : numpy.array\n Output values of LMS filter, array of length N.\n e : numpy.array\n Error signal, i.e, d-y. Array of length N.\n w : numpy.array\n Final filter coefficients in array of length M if returnCoeffs is\n False. NxM array containing all filter coefficients for all iterations\n otherwise.\n\n Raises\n TypeError\n If number of filter taps M is not type integer, number of iterations N\n is not type integer, or leakage leak is not type float/int.\n ValueError\n If number of iterations N is greater than len(u)-M, number of filter\n taps M is negative, or if step-size or leakage is outside specified\n range.\n\n\nHelper Function Reference\n-------------------------\n**mswe = mswe(w, v)**\n\n Calculate mean squared weight error between estimated and true filter\n coefficients, in respect to iterations.\n\n Parameters\n v : array-like\n True coefficients used to generate desired signal, must be a\n one-dimensional array.\n w : array-like\n Estimated coefficients from adaptive filtering algorithm. Must be an\n N x M matrix where N is the number of iterations, and M is the number\n of filter coefficients.\n\n Returns\n mswe : numpy.array\n One-dimensional array containing the mean-squared weight error for\n every iteration.\n\n Raises\n TypeError\n If inputs have wrong dimensions\n\n Note\n To use this function with the adaptive filter functions set the optional\n parameter returnCoeffs to True. This will return a coefficient matrix w\n corresponding with the input-parameter w.\n\n\nExamples\n--------\nThe following examples illustrate the use of the adaptfilt module. Note that the matplotlib.pyplot module is required to run them. \n\nAcoustic echo cancellation\n++++++++++++++++++++++++++\n::\n\n \"\"\"\n Acoustic echo cancellation in white background noise with NLMS.\n\n Consider a scenario where two individuals, John and Emily, are talking over the\n Internet. John is using his loudspeakers, which means Emily can hear herself\n through John's microphone. The speech signal that Emily hears, is a distorted\n version of her own. This is caused by the acoustic path from John's\n loudspeakers to his microphone. This path includes attenuated echoes, etc.\n\n Now for the problem!\n\n Emily wishes to cancel the echo she hears from John's microphone. Emily only\n knows the speech signal she sends to him, call that u(n), and the speech signal\n she receives from him, call that d(n). To successfully remove her own echo\n from d(n), she must approximate the acoustic path from John's loudspeakers to\n his microphone. This path can be approximated by a FIR filter, which means an\n adaptive NLMS FIR filter can be used to identify it. The model which Emily uses\n to design this filter looks like this:\n\n u(n) ------->->------+----------->->-----------\n | |\n +-----------------+ +------------------+\n +->-| Adaptive filter | | John's Room |\n | +-----------------+ +------------------+\n | | -y(n) |\n | | d(n) |\n e(n) ---+---<-<------+-----------<-<----------+----<-<---- v(n)\n\n As seen, the signal that is sent to John is also used as input to the adaptive\n NLMS filter. The output of the filter, y(n), is subtracted from the signal\n received from John, which results in an error signal e(n) = d(n)-y(n). By\n feeding the error signal back to the adaptive filter, it can minimize the error\n by approximating the impulse response (that is the FIR filter coefficients) of\n John's room. Note that so far John's speech signal v(n) has not been taken into\n account. If John speaks, the error should equal his speech, that is, e(n)\n should equal v(n). For this simple example, however, we assume John is quiet\n and v(n) is equal to white Gaussian background noise with zero-mean.\n\n In the following example we keep the impulse response of John's room constant.\n This is not required, however, since the advantage of adaptive filters, is that\n they can be used to track changes in the impulse response.\n\n A short speech sample is included in speech.npy, available on github or pypi in\n the examples folder. The sample is single-channel and is in floating-point\n format to keep the example simple. The original recording is sampled at 44.1\n kHz, and has been downsampled by a factor of 4. To listen to any of the audio\n signals of the example, they can be normalized and stored as wav files with\n scipy:\n\n from scipy.io.wavfile import write\n write(\"d.wav\", 44100/4, d/np.max(d))\n \"\"\"\n\n import numpy as np\n import matplotlib.pyplot as plt\n import adaptfilt as adf\n\n # Get u(n) - this is available on github or pypi in the examples folder\n u = np.load('speech.npy')\n\n # Generate received signal d(n) using randomly chosen coefficients\n coeffs = np.concatenate(([0.8], np.zeros(8), [-0.7], np.zeros(9),\n [0.5], np.zeros(11), [-0.3], np.zeros(3),\n [0.1], np.zeros(20), [-0.05]))\n\n d = np.convolve(u, coeffs)\n\n # Add background noise\n v = np.random.randn(len(d)) * np.sqrt(5000)\n d += v\n\n # Apply adaptive filter\n M = 100 # Number of filter taps in adaptive filter\n step = 0.1 # Step size\n y, e, w = adf.nlms(u, d, M, step, returnCoeffs=True)\n\n # Calculate mean square weight error\n mswe = adf.mswe(w, coeffs)\n\n # Plot speech signals\n plt.figure()\n plt.title(\"Speech signals\")\n plt.plot(u, label=\"Emily's speech signal, u(n)\")\n plt.plot(d, label=\"Speech signal from John, d(n)\")\n plt.grid()\n plt.legend()\n plt.xlabel('Samples')\n\n # Plot error signal - note how the measurement noise affects the error\n plt.figure()\n plt.title('Error signal e(n)')\n plt.plot(e)\n plt.grid()\n plt.xlabel('Samples')\n\n # Plot mean squared weight error - note that the measurement noise causes the\n # error the increase at some points when Emily isn't speaking\n plt.figure()\n plt.title('Mean squared weight error')\n plt.plot(mswe)\n plt.grid()\n plt.xlabel('Samples')\n\n # Plot final coefficients versus real coefficients\n plt.figure()\n plt.title('Real coefficients vs. estimated coefficients')\n plt.plot(w[-1], 'g', label='Estimated coefficients')\n plt.plot(coeffs, 'b--', label='Real coefficients')\n plt.grid()\n plt.legend()\n plt.xlabel('Samples')\n\n plt.show()\n\n.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/echocancel-input.png\n.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/echocancel-error.png\n.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/echocancel-mswe.png\n.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/echocancel-coeffs.png\n\n\nConvergence comparison\n++++++++++++++++++++++\n::\n\n \"\"\"\n Convergence comparison of different adaptive filtering algorithms (with\n different step sizes) in white Gaussian noise.\n \"\"\"\n \n import numpy as np\n import matplotlib.pyplot as plt\n import adaptfilt as adf\n \n # Generating input and desired signal\n N = 3000\n coeffs = np.concatenate(([-4, 3.2], np.zeros(20), [0.7], np.zeros(33), [-0.1]))\n u = np.random.randn(N)\n d = np.convolve(u, coeffs)\n \n # Perform filtering\n M = 60 # No. of taps to estimate\n mu1 = 0.0008 # Step size 1 in LMS\n mu2 = 0.0004 # Step size 1 in LMS\n beta1 = 0.08 # Step size 2 in NLMS and AP\n beta2 = 0.04 # Step size 2 in NLMS and AP\n K = 3 # Projection order 1 in AP\n \n # LMS\n y_lms1, e_lms1, w_lms1 = adf.lms(u, d, M, mu1, returnCoeffs=True)\n y_lms2, e_lms2, w_lms2 = adf.lms(u, d, M, mu2, returnCoeffs=True)\n mswe_lms1 = adf.mswe(w_lms1, coeffs)\n mswe_lms2 = adf.mswe(w_lms2, coeffs)\n \n # NLMS\n y_nlms1, e_nlms1, w_nlms1 = adf.nlms(u, d, M, beta1, returnCoeffs=True)\n y_nlms2, e_nlms2, w_nlms2 = adf.nlms(u, d, M, beta2, returnCoeffs=True)\n mswe_nlms1 = adf.mswe(w_nlms1, coeffs)\n mswe_nlms2 = adf.mswe(w_nlms2, coeffs)\n \n # AP\n y_ap1, e_ap1, w_ap1 = adf.ap(u, d, M, beta1, K, returnCoeffs=True)\n y_ap2, e_ap2, w_ap2 = adf.ap(u, d, M, beta2, K, returnCoeffs=True)\n mswe_ap1 = adf.mswe(w_ap1, coeffs)\n mswe_ap2 = adf.mswe(w_ap2, coeffs)\n \n # Plot results\n plt.figure()\n plt.title('Convergence comparison of different adaptive filtering algorithms')\n plt.plot(mswe_lms1, 'b', label='LMS with stepsize=%.4f' % mu1)\n plt.plot(mswe_lms2, 'b--', label='LMS with stepsize=%.4f' % mu2)\n plt.plot(mswe_nlms1, 'g', label='NLMS with stepsize=%.2f' % beta1)\n plt.plot(mswe_nlms2, 'g--', label='NLMS with stepsize=%.2f' % beta2)\n plt.plot(mswe_ap1, 'r', label='AP with stepsize=%.2f' % beta1)\n plt.plot(mswe_ap2, 'r--', label='AP with stepsize=%.2f' % beta2)\n plt.legend()\n plt.grid()\n plt.xlabel('Iterations')\n plt.ylabel('Mean-squared weight error')\n plt.show()\n\n.. image:: https://raw.githubusercontent.com/Wramberg/adaptfilt/master/examples/convergence-result.png\n\nRelease History\n---------------\n0.3\n+++\n| Included RLS filtering function.\n| Added support for complex signals.\n| Support Python 3\n\n0.2\n+++\n| Included NLMS filtering function with recursive updates of input energy.\n| Included acoustic echo cancellation example.\n\n0.1\n+++\n| Initial module with LMS, NLMS and AP filtering functions.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Adaptive filtering module for Python",
"version": "0.3",
"project_urls": {
"Homepage": "https://github.com/Wramberg/adaptfilt"
},
"split_keywords": [
"adaptive filter",
" adaptive filtering",
" signal processing",
" lms",
" apa",
" nlms",
" rls"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d4c6328a268d558e39e88f41df967c78153880aa9cfe4152eb93d3e99e883a0",
"md5": "14c5a9bd93fe0e44b9d1d174f038a5fe",
"sha256": "4dc04b60b56c5df374c8eec749073326e7dacc3dd6b691cbb30638f9386a0780"
},
"downloads": -1,
"filename": "adaptfilt-0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "14c5a9bd93fe0e44b9d1d174f038a5fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19155,
"upload_time": "2024-07-14T15:40:30",
"upload_time_iso_8601": "2024-07-14T15:40:30.942552Z",
"url": "https://files.pythonhosted.org/packages/0d/4c/6328a268d558e39e88f41df967c78153880aa9cfe4152eb93d3e99e883a0/adaptfilt-0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "15cc7c9730e3a80eb3b05007f72b25a60c7c17252d569a86a9aa9e0e98ed28da",
"md5": "c7f0685892338ccd948355792eb74f5c",
"sha256": "1b49e0020918cd988505b813bc6fd9adc7b2a541ec1818f50832c118797d2094"
},
"downloads": -1,
"filename": "adaptfilt-0.3.tar.gz",
"has_sig": false,
"md5_digest": "c7f0685892338ccd948355792eb74f5c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1013931,
"upload_time": "2024-07-14T15:40:33",
"upload_time_iso_8601": "2024-07-14T15:40:33.339690Z",
"url": "https://files.pythonhosted.org/packages/15/cc/7c9730e3a80eb3b05007f72b25a60c7c17252d569a86a9aa9e0e98ed28da/adaptfilt-0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-14 15:40:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Wramberg",
"github_project": "adaptfilt",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "adaptfilt"
}
JSON
