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:
|
Filter object for FIR filters. |
|
Filter object for IIR filters. |
|
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)
, wherecshape
is the channel shape of theSignal
to be filtered.comment (str) – A comment. The default is
''
, which initializes an empty string.
- Returns:
The FIR filter object.
- Return type:
Attributes:
Get and set the coefficients of the filter.
Get comment.
The number of channels of the filter.
The order of the filter.
Sampling rate of the filter in Hz.
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 Overview of filters 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
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 isNone
, this option will have no effect. Useinit_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:
- 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='')[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)
, wherecshape
is the channel shape of theSignal
to be filtered.comment (str) – A comment. The default is
''
, which initializes an empty string.
- Returns:
The IIR filter object.
- Return type:
Attributes:
Get and set the coefficients of the filter.
Get comment.
The number of channels of the filter.
The order of the filter.
Sampling rate of the filter in Hz.
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 Overview of filters 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
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 isNone
, this option will have no effect. Useinit_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:
- 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='')[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)
, wherecshape
is the channel shape of theSignal
to be filtered.comment (str) – A comment. The default is
''
, which initializes an emptry string.
- Returns:
The SOS filter object.
- Return type:
Attributes:
Get and set the coefficients of the filter.
Get comment.
The number of channels of the filter.
The number of sections.
The order of the filter.
Sampling rate of the filter in Hz.
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 Overview of filters 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
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.
- 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 isNone
, this option will have no effect. Useinit_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:
- 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.