New in version 0.1.

Changed in version 0.7.

An adaptive filter is a system that changes its adaptive parameteres - adaptive weights $$\textbf{w}(k)$$ - according to an optimization algorithm.

The an adaptive filter can be described as

$$y(k) = w_1 \cdot x_{1}(k) + ... + w_n \cdot x_{n}(k)$$,

or in a vector form

$$y(k) = \textbf{x}^T(k) \textbf{w}(k)$$.

The adaptation of adaptive parameters (weights) can be done with various algorithms.

## Usage instructions¶

The parameters of all implemented adaptive filters can be initially set:

• manually and passed to a filter as an array
• w="random" - set to random - this will produce a vector of random values (zero mean, 0.5 standard deviation)
• w="zeros" - set to zeros

Input data

The adaptive filters need two inputs

• input matrix x where rows represent the samples. Every row (sample) should contain multiple values (features).
• desired value (target) d

If you have only one signal and the historical values of this signal should be input of the filter (data reconstruction/prediction task) you can use helper function Input Matrix Construction to build input matrix from the historical values.

If you want to create adaptive filter (for example NLMS), with size n=4, learning rate mu=0.1 and random initial parameters (weights), than use following code

f = pa.filters.AdaptiveFilter(model="NLMS", n=4, mu=0.1, w="random")


where returned f is the instance of class FilterNLMS with given parameters.

Data filtering

If you already created an instance of adaptive filter (f in previous example) you can use it for filtering of data x with desired value d as simple as follows

y, e, w = f.run(d, x)


where y is output, e is the error and w is set of parameters at the end of the simulation.

In case you want to just simply filter the data without creating and storing filter instance manually, use the following function

y, e, w = pa.filters.filter_data(d, x, model="NLMS", mu=0.9, w="random")


Search for optimal learning rate

The search for optimal filter setup (especially learning rate) is a task of critical importance. Therefor an helper function for this task is implemented in the Padasip. To use this function you need to specify

• number of epochs (for training)
• part of data used in training epochs - ntrain (0.5 stands for 50% of given data)
• start and end of learning rate range you want to test (and number of steps in this range) - mu_start, mu_end, steps
• testing criteria (MSE, RMSE, MAE)

Example for mu in range of 100 values from [0.01, ..., 1] follows. In example is used 50% of data for training and leftoever data for testing with MSE criteria. Returned arrays are list of errors and list of corresponding learning rates, so it is easy to plot and analyze the error as a function of learning rate.

errors_e, mu_range = f.explore_learning(d, x,
mu_start=0.01,
mu_end=1.,
steps=100, ntrain=0.5, epochs=1,
criteria="MSE")


Note: optimal learning rate depends on purpose and usage of filter (ammount of training, data characteristics, etc.).

## Full Working Example¶

Bellow is full working example with visualisation of results - the NLMS adaptive filter used for channel identification.

import numpy as np
import matplotlib.pylab as plt

# creation of data
N = 500
x = np.random.normal(0, 1, (N, 4)) # input matrix
v = np.random.normal(0, 0.1, N) # noise
d = 2*x[:,0] + 0.1*x[:,1] - 4*x[:,2] + 0.5*x[:,3] + v # target

# identification
f = pa.filters.AdaptiveFilter(model="NLMS", n=4, mu=0.1, w="random")
y, e, w = f.run(d, x)

## show results
plt.figure(figsize=(15,9))
plt.plot(d,"b", label="d - target")
plt.plot(y,"g", label="y - output");plt.legend()
plt.subplot(212);plt.title("Filter error");plt.xlabel("samples - k")
plt.plot(10*np.log10(e**2),"r", label="e - error [dB]");plt.legend()
plt.tight_layout()
plt.show()


## Code explanation¶

padasip.filters.AdaptiveFilter(model='lms', **kwargs)[source]

Function that filter data with selected adaptive filter.

Args:

• d : desired value (1 dimensional array)
• x : input matrix (2-dimensional array). Rows are samples, columns are input arrays.

Kwargs:

• Any key argument that can be accepted with selected filter model. For more information see documentation of desired adaptive filter.
• It should be at least filter size n.

Returns:

• y : output value (1 dimensional array). The size corresponds with the desired value.
• e : filter error for every sample (1 dimensional array). The size corresponds with the desired value.
• w : history of all weights (2 dimensional array). Every row is set of the weights for given sample.
padasip.filters.filter_data(d, x, model='lms', **kwargs)[source]

Function that filter data with selected adaptive filter.

Args:

• d : desired value (1 dimensional array)
• x : input matrix (2-dimensional array). Rows are samples, columns are input arrays.

Kwargs:

• Any key argument that can be accepted with selected filter model. For more information see documentation of desired adaptive filter.

Returns:

• y : output value (1 dimensional array). The size corresponds with the desired value.
• e : filter error for every sample (1 dimensional array). The size corresponds with the desired value.
• w : history of all weights (2 dimensional array). Every row is set of the weights for given sample.