Filter (FilterIIR, FilterFIR, FilterSOS)#

The following documents the pyfar filter classes. Examples for working with filter objects are part of the examples gallery. Available filters are shown in the filter types examples and documented in pyfar.dsp.filter.

Classes:

`FilterFIR`(coefficients, sampling_rate[, ...])	Filter object for FIR filters.
`FilterIIR`(coefficients, sampling_rate[, ...])	Filter object for IIR filters.
`FilterSOS`(coefficients, sampling_rate[, ...])	Filter object for IIR filters as second order sections (SOS).

class pyfar.classes.filter.FilterFIR(coefficients, sampling_rate, state=None, comment='')[source]#

Filter object for FIR filters.

Parameters:

coefficients (array, double) – The filter coefficients as an array with dimensions (number of channels, number of filter coefficients)
sampling_rate (number) – The sampling rate of the filter in Hz.
state (array, double, optional) – The state of the filter from prior information with dimensions (n_filter_chan, *cshape, order), where cshape is the channel shape of the Signal to be filtered.
comment (str) – A comment. The default is '', which initializes an empty string.

Returns:

The FIR filter object.

Return type:

FilterFIR

Attributes:

`coefficients`	Get and set the coefficients of the filter.
`comment`	Get comment.
`n_channels`	The number of channels of the filter.
`order`	The order of the filter.
`sampling_rate`	Sampling rate of the filter in Hz.
`state`	Get or set the filter state.

Methods:

`copy`()	Return a copy of the Filter object.
`impulse_response`([n_samples])	Compute the impulse response of the filter.
`init_state`(cshape[, state])	Initialize the buffer elements to pre-defined initial conditions.
`minimum_impulse_response_length`([unit, ...])	Get the minimum length of the filter impulse response.
`process`(signal[, reset])	Apply the filter to a signal.
`reset`()	Reset the filter state by filling it with zeros.

property coefficients#

Get and set the coefficients of the filter.

Refer to the Overview of filters for use cases.

property comment#: Get comment.

copy()#: Return a copy of the Filter object.

impulse_response(n_samples=None)[source]#

Compute the impulse response of the filter.

Parameters:: n_samples (int, optional) – Length in samples for which the impulse response is computed. The default is None in which case n_samples is computed as the maximum value across filter channels returned by minimum_impulse_response_length. A warning is returned if n_samples is shorter than the value returned by minimum_impulse_response_length.
Returns:: impulse_response – The impulse response of the filter of with a cshape = (n_channels, ), with the channel shape cshape and the number of filter channels n_channels.
Return type:: Signal

init_state(cshape, state='zeros')[source]#

Initialize the buffer elements to pre-defined initial conditions.

Parameters:

cshape (tuple, int) – The channel shape of the Signal which is to be filtered.
state (str, optional) – The desired state. This can either be 'zeros' which initializes an empty filter, or 'step' which constructs the initial conditions for step response steady-state. The default is ‘zeros’.

minimum_impulse_response_length(unit='samples', tolerance=None)[source]#

Get the minimum length of the filter impulse response.

The length is computed from the last non-zero coefficient per channel.

Parameters:

tolerance (float, optional) – Tolerance for estimating the minimum length of noisy FIR filters. The length is estimated by finding the last coefficient with an absolute value greater or equal to the absolute maximum of the filter coefficients per channel multiplied by tolerance. For example if tolerance = 0.001 trailing values below \(20 \log_{10}(0.001)=-60\) dB would be ignored in the length estimation. The default None uses the numerical precision 2 * numpy.finfo(float).resolution as a strict threshold.
unit (string, optional) – The unit in which the length is returned. Can be 'samples' or 's' (seconds). The default is 'samples'.

Returns:

minimum_impulse_response_length – An integer array of shape(n_channels, ) containing the length in samples with the number of filter channels n_channels.

Return type:

array

property n_channels#: The number of channels of the filter.

property order#: The order of the filter.

process(signal, reset=False)#

Apply the filter to a signal.

Parameters:

signal (Signal) – The data to be filtered as Signal object.
reset (bool, optional) – If set to True, the filter state will be reset to zeros before the filter is applied to the signal. Note that if the filter state is None, this option will have no effect. Use init_state to initialize a filter with no previously set state. The default is 'False'.

Returns:

filtered – A filtered copy of the input signal.

Return type:

Signal

reset()#: Reset the filter state by filling it with zeros.

property sampling_rate#: Sampling rate of the filter in Hz. The sampling rate is set upon initialization and cannot be changed after the object has been created.

property state#

Get or set the filter state.

The filter state sets the initial condition of the filter and can for example be used for block-wise filtering.

Note that the state can also be initialized with the init_state method.

Shape of the state must be (n_filter_channels, *cshape, order), with cshape being the channel shape of the Signal to be filtered.

class pyfar.classes.filter.FilterIIR(coefficients, sampling_rate, state=None, comment='')[source]#

Filter object for IIR filters.

For IIR filters with high orders, second order section IIR filters using FilterSOS should be considered.

Parameters:

coefficients (array, double) – The filter coefficients as an array, with shape (number of channels, 2, max(number of coefficients in the nominator, number of coefficients in the denominator))
sampling_rate (number) – The sampling rate of the filter in Hz.
state (array, double, optional) – The state of the filter from prior information with dimensions (n_filter_chan, *cshape, order), where cshape is the channel shape of the Signal to be filtered.
comment (str) – A comment. The default is '', which initializes an empty string.

Returns:

The IIR filter object.

Return type:

FilterIIR

Attributes:

`coefficients`	Get and set the coefficients of the filter.
`comment`	Get comment.
`n_channels`	The number of channels of the filter.
`order`	The order of the filter.
`sampling_rate`	Sampling rate of the filter in Hz.
`state`	Get or set the filter state.

Methods:

`copy`()	Return a copy of the Filter object.
`impulse_response`([n_samples])	Compute the impulse response of the filter.
`init_state`(cshape[, state])	Initialize the buffer elements to pre-defined initial conditions.
`minimum_impulse_response_length`([unit, ...])	Estimate the minimum length of the filter impulse response.
`process`(signal[, reset])	Apply the filter to a signal.
`reset`()	Reset the filter state by filling it with zeros.

property coefficients#

Get and set the coefficients of the filter.

Refer to the Overview of filters for use cases.

property comment#: Get comment.

copy()#: Return a copy of the Filter object.

impulse_response(n_samples=None)[source]#

Compute the impulse response of the filter.

Parameters:: n_samples (int, optional) – Length in samples for which the impulse response is computed. The default is None in which case n_samples is computed as the maximum value across filter channels returned by minimum_impulse_response_length. A warning is returned if n_samples is shorter than the value returned by minimum_impulse_response_length.
Returns:: impulse_response – The impulse response of the filter of with a cshape = (n_channels, ), with the channel shape cshape and the number of filter channels n_channels.
Return type:: Signal

init_state(cshape, state='zeros')[source]#

Initialize the buffer elements to pre-defined initial conditions.

Parameters:

cshape (tuple, int) – The channel shape of the Signal which is to be filtered.
state (str, optional) – The desired state. This can either be 'zeros' which initializes an empty filter, or 'step' which constructs the initial conditions for step response steady-state. The default is ‘zeros’.

minimum_impulse_response_length(unit='samples', tolerance=5e-05)[source]#

Estimate the minimum length of the filter impulse response.

The length is estimated from the positions of the poles of the filter. The closer the poles are to the unit circle, the longer the estimated length.

Parameters:

unit (string, optional) – The unit in which the length is returned. Can be 'samples' or 's' (seconds). The default is 'samples'.
tolerance (float, optional) – Tolerance for the accuracy. Smaller tolerances will result in larger impulse response lengths. The default is 5e-5.

Returns:

minimum_impulse_response_length – An integer array of shape(n_channels, ) containing the length in samples with the number of filter channels n_channels.

Return type:

array

property n_channels#: The number of channels of the filter.

property order#: The order of the filter.

process(signal, reset=False)#

Apply the filter to a signal.

Parameters:

signal (Signal) – The data to be filtered as Signal object.
reset (bool, optional) – If set to True, the filter state will be reset to zeros before the filter is applied to the signal. Note that if the filter state is None, this option will have no effect. Use init_state to initialize a filter with no previously set state. The default is 'False'.

Returns:

filtered – A filtered copy of the input signal.

Return type:

Signal

reset()#: Reset the filter state by filling it with zeros.

property sampling_rate#: Sampling rate of the filter in Hz. The sampling rate is set upon initialization and cannot be changed after the object has been created.

property state#

Get or set the filter state.

The filter state sets the initial condition of the filter and can for example be used for block-wise filtering.

Note that the state can also be initialized with the init_state method.

Shape of the state must be (n_filter_channels, *cshape, order), with cshape being the channel shape of the Signal to be filtered.

class pyfar.classes.filter.FilterSOS(coefficients, sampling_rate, state=None, comment='')[source]#

Filter object for IIR filters as second order sections (SOS).

Parameters:

coefficients (array, double) – The filter coefficients as an array with dimensions (n_filter_chan, n_sections, 6) The first three values of a section provide the numerator coefficients, the last three values the denominator coefficients, e.g, [[[ b[0], b[1], b[2], a[0], a[1], a[2] ]]] for a single channel SOS filter with one section.
sampling_rate (number) – The sampling rate of the filter in Hz.
state (array, double, optional) – The state of the filter from prior information with dimensions (n_filter_chan, *cshape, n_sections, 2), where cshape is the channel shape of the Signal to be filtered.
comment (str) – A comment. The default is '', which initializes an emptry string.

Returns:

The SOS filter object.

Return type:

FilterSOS

Attributes:

`coefficients`	Get and set the coefficients of the filter.
`comment`	Get comment.
`n_channels`	The number of channels of the filter.
`n_sections`	The number of sections.
`order`	The order of the filter.
`sampling_rate`	Sampling rate of the filter in Hz.
`state`	Get or set the filter state.

Methods:

`copy`()	Return a copy of the Filter object.
`impulse_response`([n_samples])	Approximate the infinite impulse response of the filter by a finite impulse response.
`init_state`(cshape[, state])	Initialize the buffer elements to pre-defined initial conditions.
`minimum_impulse_response_length`([unit, ...])	Estimate the minimum length of the filter impulse response.
`process`(signal[, reset])	Apply the filter to a signal.
`reset`()	Reset the filter state by filling it with zeros.

property coefficients#

Get and set the coefficients of the filter.

Refer to the Overview of filters for use cases.

property comment#: Get comment.

copy()#: Return a copy of the Filter object.

impulse_response(n_samples=None)[source]#

Approximate the infinite impulse response of the filter by a finite impulse response.

Note that the number of samples must be sufficiently long for impulse_response to be a good approximation of the theoretically infinitely long impulse response of the filter.

Parameters:: n_samples (int) – Length in samples for which the impulse response is computed. The default is None in which case n_samples is computed as the maximum value across filter channels returned by minimum_impulse_response_length. A warning is returned if n_samples is shorter than the value returned by minimum_impulse_response_length.
Returns:: impulse_response – The impulse response of the filter of with a cshape = (n_channels, ), with the channel shape cshape and the number of filter channels n_channels.
Return type:: Signal

init_state(cshape, state='zeros')[source]#

Initialize the buffer elements to pre-defined initial conditions.

Parameters:

cshape (tuple, int) – The channel shape of the Signal which is to be filtered.
state (str, optional) – The desired state. This can either be 'zeros' which initializes an empty filter, or 'step' which constructs the initial conditions for step response steady-state. The default is ‘zeros’.

minimum_impulse_response_length(unit='samples', tolerance=5e-05)[source]#

Estimate the minimum length of the filter impulse response.

The length is estimated separately per second order section using minimum_impulse_response_length. The final length is given by the length of the longest section.

Parameters:

unit (string, optional) – The unit in which the length is returned. Can be 'samples' or 's' (seconds). The default is 'samples'.
tolerance (float, optional) – Tolerance for the accuracy. Smaller tolerances will result in larger impulse response lengths. The default is 5e-5.

Returns:

minimum_impulse_response_length – An integer array of shape(n_channels, ) containing the length in samples with the number of filter channels n_channels.

Return type:

array

property n_channels#: The number of channels of the filter.

property n_sections#: The number of sections.

property order#: The order of the filter. This is always twice the number of sections.

process(signal, reset=False)#

Apply the filter to a signal.

Parameters:

signal (Signal) – The data to be filtered as Signal object.
reset (bool, optional) – If set to True, the filter state will be reset to zeros before the filter is applied to the signal. Note that if the filter state is None, this option will have no effect. Use init_state to initialize a filter with no previously set state. The default is 'False'.

Returns:

filtered – A filtered copy of the input signal.

Return type:

Signal

reset()#: Reset the filter state by filling it with zeros.

property sampling_rate#: Sampling rate of the filter in Hz. The sampling rate is set upon initialization and cannot be changed after the object has been created.

property state#

Get or set the filter state.

The filter state sets the initial condition of the filter and can for example be used for block-wise filtering.

Note that the state can also be initialized with the init_state method.

Shape of the state must be (n_filter_channels, *cshape, n_sections, 2)), with cshape being the channel shape of the Signal to be filtered.