Filter (FilterIIR, FilterFIR, FilterSOS)¶

The following documents the pyfar filter classes. More background information is given in the filter concepts. Available filters are shown in filter types 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=None)[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 ~py:class:Signal to be filtered.
comment (str, optional) – A comment. The default is 'None'.

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`	The current state of the filter as an array with dimensions corresponding to the order of the filter and number of filter channels.

Methods:

`copy`()	Return a copy of the Filter object.
`init_state`(cshape[, state])	Initialize the buffer elements to pre-defined initial conditions.
`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 filter concepts for use cases.

property comment¶: Get comment.

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

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

Initialize the buffer elements to pre-defined initial conditions.

Parameters

cshape (tuple, int) – The channel shape of the ~py:class: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’.

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¶: The current state of the filter as an array with dimensions corresponding to the order of the filter and number of filter channels.

class pyfar.classes.filter.FilterIIR(coefficients, sampling_rate, state=None, comment=None)[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 ~py:class:Signal to be filtered.
comment (str, optional) – A comment. The default is 'None'.

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`	The current state of the filter as an array with dimensions corresponding to the order of the filter and number of filter channels.

Methods:

`copy`()	Return a copy of the Filter object.
`init_state`(cshape, state)	Initialize the buffer elements to pre-defined initial conditions.
`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 filter concepts for use cases.

property comment¶: Get comment.

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

init_state(cshape, state)[source]¶

Initialize the buffer elements to pre-defined initial conditions.

Parameters

cshape (tuple, int) – The channel shape of the ~py:class: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’.

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¶: The current state of the filter as an array with dimensions corresponding to the order of the filter and number of filter channels.

class pyfar.classes.filter.FilterSOS(coefficients, sampling_rate, state=None, comment=None)[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 ~py:class:Signal to be filtered.
comment (str, optional) – A comment. The default is 'None'.

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
`sampling_rate`	Sampling rate of the filter in Hz.
`state`	The current state of the filter as an array with dimensions corresponding to the order of the filter and number of filter channels.

Methods:

`copy`()	Return a copy of the Filter object.
`init_state`(cshape[, state])	Initialize the buffer elements to pre-defined initial conditions.
`order`()	The order of the filter.
`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 filter concepts for use cases.

property comment¶: Get comment.

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

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

Initialize the buffer elements to pre-defined initial conditions.

Parameters

cshape (tuple, int) – The channel shape of the ~py:class: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’.

property n_channels¶: The number of channels of the filter

property n_sections¶: The number of sections

order()[source]¶: The order of the filter. This is always 2 for SOS 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¶: The current state of the filter as an array with dimensions corresponding to the order of the filter and number of filter channels.