The following documents the pyfar filters. Visit the
Overview of filters
for an overview of the different filters and the
Filtering pyfar Signals
for more information on using pyfar filter objects.
Generate a forth order reconstructing Gammatone auditory filter bank
according to [1]. The center frequencies of the Gammatone filters
are calculated using the ERB scale (see erb_frequencies).
This is a Python port of the hohmann2002 filter bank
contained in the Auditory Modeling Toolbox [2]. The filter bank can
handle single and multi channel input and allows for an almost perfect
reconstruction of the input signal (see examples below).
Calling GFB=GammatoneBands() constructs the filter bank. Afterwards
the class methods GFB.process() and GFB.reconstruct() can be used
to filter and reconstruct signals. All relevant data such as the filter
coefficients can be obtained for example through GFB.coefficients. See
below for more documentation.
Parameters:
frequency_range (array_like) – The upper and lower frequency in Hz between which the filter bank is
constructed. Values must be larger than 0 and not exceed half the
sampling rate.
resolution (number) – The frequency resolution of the filter bands in equivalent rectangular
bandwidth (ERB) units. The bands of the filter bank are distributed
linearly on the ERB scale. The default value of 1 results in one
filter band per ERB. A value of 0.5 would result in two filter
bands per ERB.
reference_frequency (number) – The frequency relative to which the filter bands are distributed. The
default is 1000 Hz.
delay (number) – The delay in seconds that the filter bank will have, i.e., the delay
that is added to the input signal after being filtered and summed
again. The default is 0.004 seconds.
sampling_rate (number) – The sampling rate of the filter bank in Hz. The default is 44100
Hz.
freq_range (array_like) – The upper and lower frequency in Hz between which the filter bank is
constructed. Values must be larger than 0 and not exceed half the
sampling rate.
'freq_range' parameter will be deprecated in pyfar 0.8.0 in favor
of 'frequency_range'.
Examples
>>> importpyfaraspf>>> importnumpyasnp>>> importmatplotlib.pyplotasplt>>>>>> # generate the filter bank object>>> GFB=pf.dsp.filter.GammatoneBands([0,22050])>>>>>> # apply the filter bank to an impulse>>> x=pf.signals.impulse(2**13)>>> real,imag=GFB.process(x)>>> env=pf.Signal(np.abs(real.time+1j*imag.time),44100)>>>>>> # use pyfar plot style>>> pf.plot.use()>>>>>> # the output is complex:>>> # Real part gives band-limited Gammatone output>>> # Imaginary part gives the Hilbert Transform thereof>>> # Absolute value gives the Envelope>>> plt.figure()>>> ax=pf.plot.time(real[2],label='real part',unit='ms')>>> pf.plot.time(imag[2],label='imaginary part',unit='ms')>>> pf.plot.time(env[2],label='envelope',unit='ms')>>> plt.legend()>>>>>> # show the magnitude response of the filter bank>>> plt.figure()>>> ax=pf.plot.freq(real)>>> ax.set_ylim(-40,5)>>>>>> # reconstruct the filtered impulse>>> # the reconstruction error can be decreased>>> # using the filter bank parameter 'resolution'>>> y=GFB.reconstruct(real,imag)>>> plt.figure()>>> ax=pf.plot.time_freq(y,label="reconstructed impulse",unit='ms')>>> ax[0].set_xlim(0,20)>>> ax[1].set_ylim(-40,5)>>> ax[0].legend()>>>>>> # manipulate filter output before the reconstruction>>> # (manipulations must be applied to the real and imaginary output)>>> real.time[20:25]*=.5>>> imag.time[20:25]*=.5>>>>>> y=GFB.reconstruct(real,imag)>>> plt.figure()>>> ax=pf.plot.time_freq(... y,unit='ms',... label="manipulated and reconstructed and impulse")>>> ax[0].set_xlim(0,20)>>> ax[1].set_ylim(-40,5)>>> ax[0].legend()
The filter output is a complex valued time signal, whose real and
imaginary part are returned separately.
If the filter bank is used for analysis purposes only, the imaginary
part is not required for further processing.
If the filter bank is used for analysis and re-synthesis, any further
processing must be applied to the real and imaginary part. Any
complex-valued operations must be applied to the complex valued
output as a whole.
reset (bool, optional) – If true the internal state of the filter bank is reset before the
filters are applied. Not resetting the state can be useful for
blockwise processing. The default is True.
Returns:
real (Signal) – The real part of the complex output signal. This represents the
band-limited Gammatone filter output.
imag (Signal) – The imaginary part of the complex output signal. This approximates
the Hilbert transform of the band-limited Gammatone filter output.
Notes
sqrt(real.time**2+imag.time**2) gives the envelope of the
Gammatone filter output.
If the cshape of the output signals real.cshape and
imag.cshape generally is (self.n_bands,)+signal.cshape.
An exception to this occurs if signal.cshape is (1,), i.e.,
signal is a single channel signal. In this case the cshape of the
output signals is (self.n_bands) and not (self.n_bands,1).
Create and apply first or second order allpass filter.
Allpass filters have an almost constant group delay below their cut-off
frequency and are often used in analogue loudspeaker design.
The filter transfer function is based on Tietze et al. [3]:
\[A(s) = \frac{1-\frac{a_i}{\omega_c} s+\frac{b_i}
{\omega_c^2} s^2}{1+\frac{a_i}{\omega_c} s
+\frac{b_i}{\omega_c^2} s^2},\]
where \(\omega_c = 2 \pi f_c\) with the cut-off frequency \(f_c\)
and \(s=\mathrm{i} \omega\).
By definition the bi coefficient of a first order allpass is 0.
signal (Signal, None) – The signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Cutoff frequency of the allpass in Hz.
order (number) – Order of the allpass filter. Must be 1 or 2.
coefficients (number, list, optional) –
Filter characteristic coefficients bi and ai.
For 1st order allpass provide ai-coefficient as single value.n
The default is ai=0.6436.
For 2nd order allpass provide coefficients as list [bi,ai].n
The default is bi=0.8832, ai=1.6278.
Defaults are chosen according to Tietze et al. (Fig. 12.66)
for maximum flat group delay.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterIIR) – Filter object. Only returned if signal=None.
References
Examples
First and second order allpass filter with fc=1000 Hz.
importpyfaraspfimportmatplotlib.pyplotasplt# impulse to be filteredimpulse=pf.signals.impulse(256)orders=[1,2]labels=['First order','Second order']fig,(ax1,ax2)=plt.subplots(2,1,layout='constrained')for(order,label)inzip(orders,labels):# create and apply allpass filtersig_filt=pf.dsp.filter.allpass(impulse,1000,order)pf.plot.group_delay(sig_filt,unit='samples',label=label,ax=ax1)pf.plot.phase(sig_filt,label=label,ax=ax2,unwrap=True)ax1.set_title('1. and 2. order allpass filter with fc = 1000 Hz')ax2.legend()
signal (Signal, None) – The signal to be filtered. Pass None to create the filter without
applying it.
center_frequency (number) – Center frequency of the parametric equalizer in Hz
gain (number) – Gain of the parametric equalizer in dB
quality (number) – Quality of the parametric equalizer, i.e., the inverse of the
bandwidth
bell_type (str) –
Defines the bandwidth/quality. The default is 'II'.
'I'
not recommended. Also known as ‘constant Q’.
'II'
defines the bandwidth by the points 3 dB below the maximum if the
gain is positive and 3 dB above the minimum if the gain is
negative. Also known as ‘symmetric’.
'III'
defines the bandwidth by the points at gain/2. Also known as
‘half pad loss’.
quality_warp (str) – Sets the pre-warping for the quality ('cos', 'sin', or
'tan'). The default is 'cos'.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterIIR) – Filter object. Only returned if signal=None.
References
pyfar.dsp.filter.bessel(signal, N, frequency, btype='lowpass', norm='phase', sampling_rate=None)[source]#
Create and apply digital Bessel/Thomson IIR filter.
This is a wrapper for scipy.signal.bessel. Which creates digital
Bessel filter coefficients in second-order sections (SOS).
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
N (int) – The order of the Bessel/Thomson filter.
frequency (number, array like) – The cut off-frequency in Hz if btype is 'lowpass' or
'highpass'. An array
like containing the lower and upper cut-off frequencies in Hz if
btype is bandpass or bandstop.
btype (str) – One of the following 'lowpass', 'highpass', 'bandpass',
'bandstop'. The default is 'lowpass'.
norm (str) –
Critical frequency normalization:
'phase'
The filter is normalized such that the phase response reaches its
midpoint at angular (e.g. rad/s) frequency Wn. This happens for
both low-pass and high-pass filters, so this is the
“phase-matched” case.
The magnitude response asymptotes are the same as a Butterworth
filter of the same order with a cutoff of Wn.
This is the default, and matches MATLAB’s implementation.
'delay'
The filter is normalized such that the group delay in the passband
is 1/Wn (e.g., seconds). This is the “natural” type obtained by
solving Bessel polynomials.
'mag'
The filter is normalized such that the gain magnitude is -3 dB at
the angular frequency Wn.
The default is ‘phase’.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The default
is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterSOS) – SOS Filter object. Only returned if signal=None.
pyfar.dsp.filter.butterworth(signal, N, frequency, btype='lowpass', sampling_rate=None)[source]#
Create and apply a digital Butterworth IIR filter.
This is a wrapper for scipy.signal.butter. Which creates digital
Butterworth filter coefficients in second-order sections (SOS).
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
N (int) – The order of the Butterworth filter
frequency (number, array like) – The cut off-frequency in Hz if btype is lowpass or highpass. An array
like containing the lower and upper cut-off frequencies in Hz if
btype is bandpass or bandstop.
btype (str) – One of the following 'lowpass', 'highpass', 'bandpass',
'bandstop'. The default is 'lowpass'.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterSOS) – SOS Filter object. Only returned if signal=None.
pyfar.dsp.filter.chebyshev1(signal, N, ripple, frequency, btype='lowpass', sampling_rate=None)[source]#
Create and apply digital Chebyshev Type I IIR filter.
This is a wrapper for scipy.signal.cheby1. Which creates digital
Chebyshev Type I filter coefficients in second-order sections (SOS).
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
N (int) – The order of the Chebychev filter.
ripple (number) – The passband ripple in dB.
frequency (number, array like) – The cut off-frequency in Hz if btype is 'lowpass' or
'highpass'. An array like containing the lower and upper cut-off
frequencies in Hz if btype is 'bandpass' or 'bandstop'.
btype (str) – One of the following 'lowpass', 'highpass', 'bandpass',
'bandstop'. The default is 'lowpass'.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterSOS) – SOS Filter object. Only returned if signal=None.
pyfar.dsp.filter.chebyshev2(signal, N, attenuation, frequency, btype='lowpass', sampling_rate=None)[source]#
Create and apply digital Chebyshev Type II IIR filter.
This is a wrapper for scipy.signal.cheby2. Which creates digital
Chebyshev Type II filter coefficients in second-order sections (SOS).
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
N (int) – The order of the Chebychev filter.
attenuation (number) – The minimum stop band attenuation in dB.
frequency (number, array like) – The frequency in Hz where the attenuatoin is first reached if btype
is 'lowpass' or 'highpass'. An array like containing the lower
and upper frequencies in Hz if btype is 'bandpass' or
'bandstop'.
btype (str) – One of the following 'lowpass', 'highpass', 'bandpass',
'bandstop'. The default is 'lowpass'.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterSOS) – SOS Filter object. Only returned if signal=None.
pyfar.dsp.filter.crossover(signal, N, frequency, sampling_rate=None)[source]#
Create and apply Linkwitz-Riley crossover network.
Linkwitz-Riley crossover filters ([6], [7]) are designed by cascading
Butterworth filters of order N/2. where N must be even.
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
N (int) – The order of the Linkwitz-Riley crossover network, must be even.
frequency (number, array-like) – Characteristic frequencies of the crossover network. If a single number
is passed, the network consists of a single lowpass and highpass. If
M frequencies are passed, the network consists of 1 lowpass, M-1
bandpasses, and 1 highpass.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterSOS) – Filter object. Only returned if signal=None.
References
pyfar.dsp.filter.elliptic(signal, N, ripple, attenuation, frequency, btype='lowpass', sampling_rate=None)[source]#
Create and apply digital Elliptic (Cauer) IIR filter.
This is a wrapper for scipy.signal.ellip. Which creates digital
Elliptic (Cauer) filter coefficients in second-order sections (SOS).
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
N (int) – The order of the Elliptic filter.
ripple (number) – The passband ripple in dB.
attenuation (number) – The minimum stop band attenuation in dB.
frequency (number, array like) – The cut off-frequency in Hz if btype is 'lowpass' or
'highpass'. An array like containing the lower and upper cut-off
frequencies in Hz if btype is 'bandpass' or 'bandstop'.
btype (str) – One of the following 'lowpass', 'highpass', 'bandpass',
'bandstop'. The default is 'lowpass'.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterSOS) – SOS Filter object. Only returned if signal=None.
Get frequencies that are linearly spaced on the ERB frequency scale.
The human auditory system analyzes sound in auditory filters, whose band-
width is often given as a equivalent rectangular bandwidth (ERB). The ERB
denotes the bandwidth of a perfect rectangular band-pass that has the same
energy as the auditory filter. The ERB frequency scale is directly
constructed from this concept: One ERB unit is defined as the
frequency dependent ERB of the auditory filter at a given center frequency
(cf. [8], Section 3B).
The implementation follows Eq. (16) and (17) in [9] and was ported from
the auditory modeling toolbox [10].
Parameters:
frequency_range (array_like) – The upper and lower frequency limits in Hz between which the frequency
vector is computed.
resolution (number, optional) – The frequency resolution in ERB units. The default of 1 returns
frequencies that are spaced by 1 ERB unit, a value of 0.5 would
return frequencies that are spaced by 0.5 ERB units.
reference_frequency (number, optional) – The reference frequency in Hz relative to which the frequency vector
is constructed. The default is 1000.
freq_range (array_like) – The upper and lower frequency limits in Hz between which the frequency
vector is computed.
'freq_range' parameter will be deprecated in pyfar 0.8.0 in favor
of 'frequency_range'.
Returns:
frequencies – The frequencies in Hz that are linearly distributed on the ERB scale
with a spacing given by resolution ERB units.
Create and/or apply an energy preserving fractional octave filter bank.
The filters are designed using second order sections of Butterworth
band-pass filters. Note that if the upper cut-off frequency of a band lies
above the Nyquist frequency, a high-pass filter is applied instead. Due to
differences in the design of band-pass and high-pass filters, their slopes
differ, potentially introducing an error in the summed energy in the stop-
band region of the respective filters.
Note
This filter bank has -3 dB cut-off frequencies. For sufficiently large
values of 'order', the summed energy of the filter bank equals the
energy of input signal, i.e., the filter bank is energy preserving
(reconstructing). This is useful for analysis energetic properties of
the input signal such as the room acoustic property reverberation
time. For an amplitude preserving filter bank with -6 dB cut-off
frequencies see
reconstructing_fractional_octave_bands.
Parameters:
signal (Signal, None) – The signal to be filtered. Pass None to create the filter without
applying it.
num_fractions (int) – The number of bands an octave is divided into. Eg., 1 refers to
octave bands and 3 to third octave bands.
sampling_rate (None, int) – The sampling rate in Hz. Only required if signal is None. The
default is None.
frequency_range (array, tuple, optional) – The lower and upper frequency limits. The default is
frequency_range=(20,20e3).
order (int, optional) – Order of the Butterworth filter. The default is 14.
freq_range (array, tuple, optional) – The lower and upper frequency limits. The default is
frequency_range=(20,20e3).
'freq_range' parameter will be deprecated in pyfar 0.8.0 in favor
of 'frequency_range'.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterSOS) – Filter object. Only returned if signal=None.
Examples
Filter an impulse into octave bands. The summed energy of all bands equals
the energy of the input signal.
>>> importpyfaraspf>>> importnumpyasnp>>> importmatplotlib.pyplotasplt>>> # generate the data>>> x=pf.signals.impulse(2**17)>>> y=pf.dsp.filter.fractional_octave_bands(... x,1,frequency_range=(20,8e3))>>> # frequency domain plot>>> y_sum=pf.FrequencyData(... np.sum(np.abs(y.freq)**2,0),y.frequencies)>>> pf.plot.freq(y)>>> ax=pf.plot.freq(y_sum,color='k',log_prefix=10,linestyle='--')>>> ax.set_title(... "Filter bands and the sum of their squared magnitudes")
Return the octave center frequencies according to the IEC 61260:1:2014
standard.
For numbers of fractions other than 1 and 3, only the
exact center frequencies are returned, since nominal frequencies are not
specified by corresponding standards.
Parameters:
num_fractions (int, optional) – The number of bands an octave is divided into. Eg., 1 refers to
octave bands and 3 to third octave bands. The default is 1.
frequency_range (array, tuple) – The lower and upper frequency limits, the default is
frequency_range=(20,20e3).
return_cutoff (bool, optional) – If True, the lower and upper critical frequencies of the bandpass
filters for each band are returned. The default is False.
Returns:
nominal (array, float) – The nominal center frequencies are only defined for octave bands and
third octave bands in the range between 25 Hz and 20 kHz.
For all other cases, None is returned.
exact (array, float) – The exact center frequencies in Hz, resulting in a uniform distribution
of frequency bands over the frequency range.
cutoff_freq (tuple, array, float) – The lower and upper critical frequencies in Hz of the bandpass filters
for each band as a tuple corresponding to (f_lower,f_upper).
pyfar.dsp.filter.high_shelf(signal, frequency, gain, order, shelf_type='I', sampling_rate=None)[source]#
Create and/or apply first or second order high shelf filter.
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Characteristic frequency of the shelf in Hz.
gain (number) – Gain of the shelf in dB.
order (number) – The shelf order. Must be 1 or 2.
shelf_type (str) –
Defines the characteristic frequency. The default is 'I'.
'I'
Defines the characteristic frequency 3 dB below the gain value if
the gain is positive and 3 dB above the gain value if the
gain is negative.
'II'
Defines the characteristic frequency at 3 dB if the gain is
positive and at -3 dB if the gain is negative.
'III'
Defines the characteristic frequency at gain/2 dB.
For types I and II the absolute value of the gain must be
sufficiently large (> 9 dB) to set the characteristic
frequency according to the above rules with an error below 0.5 dB.
For smaller absolute gain values the gain at the characteristic
frequency becomes less accurate.
For type III the characteristic frequency is always set correctly.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterIIR) – Filter object. Only returned if signal=None.
Create and apply constant slope filter from cascaded 2nd order high
shelves.
The filters - also known as High-Schultz filters (cf. [12]) - are defined
by their characteristic frequency, gain, slope, and bandwidth. Two out of
the three parameter gain, slope, and bandwidth must be specified,
while the third parameter is calculated as
gain=bandwidth*slope
bandwidth=abs(gain/slope)
slope=gain/bandwidth
Note
The bandwidth must be at least 1 octave to obtain a good
approximation of the desired frequency response. Make sure to specify
the parameters gain, slope, and bandwidth accordingly.
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Characteristic frequency in Hz (see frequency_type)
frequency_type (string) –
Defines how frequency is used
'upper'
frequency gives the upper characteristic frequency. In this case
the lower characteristic frequency is given by
2**bandwidth/frequency
'lower'
frequency gives the lower characteristic frequency. In this case
the upper characteristic frequency is given by
2**bandwidth*frequency
gain (number) – The filter gain in dB. The default is None, which calculates the
gain from the slope and bandwidth (must be given if gain is
None).
slope (number) – Filter slope in dB per octave, with positive values denoting a rising
filter slope and negative values denoting a falling filter slope. The
default is None, which calculates the slope from the gain and
bandwidth (must be given if slope is None).
bandwidth (number) – The bandwidth of the filter in octaves. The default is None, which
calculates the bandwidth from gain and slope (must be given if
bandwidth is None).
N (int) – Number of shelf filters that are cascaded. The default is None,
which calculated the minimum N that is required to satisfy Eq. (11)
in Schultz et al. 2020, i.e., the minimum N that is required for
a good approximation of the ideal filter response.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal, FilterSOS) – The filtered signal (returned if sampling_rate=None) or the
Filter object (returned if signal=None).
N (int) – The number of shelf filters that were cascaded
ideal (FrequencyData) – The ideal, piece-wise magnitude response of the filter
References
Examples
Generate a filter with a bandwith of 4 octaves and a gain of -60 dB and
compare it to the piece-wise constant idealized magnitude response.
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Characteristic frequency of the shelf in Hz.
gain (number) – Gain of the shelf in dB.
order (number) – The shelf order. Must be 1 or 2.
shelve_type (str) –
Defines the characteristic frequency. The default is 'I'.
'I'
Defines the characteristic frequency 3 dB below the gain value if
the gain is positive and 3 dB above the gain value if the
gain is negative.
'II'
Defines the characteristic frequency at 3 dB if the gain is
positive and at -3 dB if the gain is negative.
'III'
Defines the characteristic frequency at gain/2 dB.
For types I and II the absolute value of the gain must be
sufficiently large (> 9 dB) to set the characteristic
frequency according to the above rules with an error below 0.5 dB.
For smaller absolute gain values the gain at the characteristic
frequency becomes less accurate.
For type III the characteristic frequency is always set correctly.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterIIR) – Filter object. Only returned if signal=None.
high_shelve_cascade will be deprecated in
pyfar 0.9.0 in favor of high_shelf_cascade.
Create and apply constant slope filter from cascaded 2nd order high
shelves.
The filters - also known as High-Schultz filters (cf. [14]) - are defined
by their characteristic frequency, gain, slope, and bandwidth. Two out of
the three parameter gain, slope, and bandwidth must be specified,
while the third parameter is calculated as
gain=bandwidth*slope
bandwidth=abs(gain/slope)
slope=gain/bandwidth
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Characteristic frequency in Hz (see frequency_type)
frequency_type (string) –
Defines how frequency is used
'upper'
frequency gives the upper characteristic frequency. In this case
the lower characteristic frequency is given by
2**bandwidth/frequency
'lower'
frequency gives the lower characteristic frequency. In this case
the upper characteristic frequency is given by
2**bandwidth*frequency
gain (number) – The filter gain in dB. The default is None, which calculates the
gain from the slope and bandwidth (must be given if gain is
None).
slope (number) – Filter slope in dB per octave, with positive values denoting a rising
filter slope and negative values denoting a falling filter slope. The
default is None, which calculates the slope from the gain and
bandwidth (must be given if slope is None).
bandwidth (number) – The bandwidth of the filter in octaves. The default is None, which
calculates the bandwidth from gain and slope (must be given if
bandwidth is None).
N (int) – Number of shelf filters that are cascaded. The default is None,
which calculated the minimum N that is required to satisfy Eq. (11)
in Schultz et al. 2020, i.e., the minimum N that is required for
a good approximation of the ideal filter response.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal, FilterSOS) – The filtered signal (returned if sampling_rate=None) or the
Filter object (returned if signal=None).
N (int) – The number of shelf filters that were cascaded
ideal (FrequencyData) – The ideal, piece-wise magnitude response of the filter
References
Examples
Generate a filter with a bandwith of 4 octaves and a gain of -60 dB and
compare it to the piece-wise constant idealized magnitude response.
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Characteristic frequency of the shelf in Hz.
gain (number) – Gain of the shelf in dB.
order (number) – The shelf order. Must be 1 or 2.
shelf_type (str) –
Defines the characteristic frequency. The default is 'I'.
'I'
Defines the characteristic frequency 3 dB below the gain value if
the gain is positive and 3 dB above the gain value if the
gain is negative.
'II'
Defines the characteristic frequency at 3 dB if the gain is
positive and at -3 dB if the gain is negative.
'III'
Defines the characteristic frequency at gain/2 dB.
For types I and II the absolute value of the gain must be
sufficiently large (> 9 dB) to set the characteristic
frequency according to the above rules with an error below 0.5 dB.
For smaller absolute gain values the gain at the characteristic
frequency becomes less accurate.
For type III the characteristic frequency is always set correctly.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterIIR) – Filter object. Only returned if signal=None.
Create and apply constant slope filter from cascaded 2nd order low shelves.
The filters - also known as Low-Schultz filters (cf. [16]) - are defined
by their characteristic frequency, gain, slope, and bandwidth. Two out of
the three parameter gain, slope, and bandwidth must be specified,
while the third parameter is calculated as
gain=-bandwidth*slope
bandwidth=abs(gain/slope)
slope=-gain/bandwidth
Note
The bandwidth must be at least 1 octave to obtain a good
approximation of the desired frequency response. Make sure to specify
the parameters gain, slope, and bandwidth accordingly.
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Characteristic frequency in Hz (see frequency_type)
frequency_type (string) –
Defines how frequency is used
'upper'
frequency gives the upper characteristic frequency. In this case
the lower characteristic frequency is given by
2**bandwidth/frequency
'lower'
frequency gives the lower characteristic frequency. In this case
the upper characteristic frequency is given by
2**bandwidth*frequency
gain (number) – The filter gain in dB. The default is None, which calculates the
gain from the slope and bandwidth (must be given if gain is
None).
slope (number) – Filter slope in dB per octave, with positive values denoting a rising
filter slope and negative values denoting a falling filter slope. The
default is None, which calculates the slope from the gain and
bandwidth (must be given if slope is None).
bandwidth (number) – The bandwidth of the filter in octaves. The default is None, which
calculates the bandwidth from gain and slope (must be given if
bandwidth is None).
N (int) – Number of shelf filters that are cascaded. The default is None,
which calculated the minimum N that is required to satisfy Eq. (11)
in Schultz et al. 2020, i.e., the minimum N that is required for
a good approximation of the ideal filter response.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal, FilterSOS) – The filtered signal (returned if sampling_rate=None) or the
Filter object (returned if signal=None).
N (int) – The number of shelf filters that were cascaded
ideal (FrequencyData) – The ideal, piece-wise magnitude response of the filter
References
Examples
Generate a filter with a bandwith of 4 octaves and a gain of -60 dB and
compare it to the piece-wise constant idealized magnitude response.
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Characteristic frequency of the shelf in Hz.
gain (number) – Gain of the shelf in dB.
order (number) – The shelf order. Must be 1 or 2.
shelve_type (str) –
Defines the characteristic frequency. The default is 'I'.
'I'
Defines the characteristic frequency 3 dB below the gain value if
the gain is positive and 3 dB above the gain value if the
gain is negative.
'II'
Defines the characteristic frequency at 3 dB if the gain is
positive and at -3 dB if the gain is negative.
'III'
Defines the characteristic frequency at gain/2 dB.
For types I and II the absolute value of the gain must be
sufficiently large (> 9 dB) to set the characteristic
frequency according to the above rules with an error below 0.5 dB.
For smaller absolute gain values the gain at the characteristic
frequency becomes less accurate.
For type III the characteristic frequency is always set correctly.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterIIR) – Filter object. Only returned if signal=None.
low_shelve_cascade will be deprecated in
pyfar 0.9.0 in favor of low_shelf_cascade.
Create and apply constant slope filter from cascaded 2nd order low shelves.
The filters - also known as Low-Schultz filters (cf. [18]) - are defined
by their characteristic frequency, gain, slope, and bandwidth. Two out of
the three parameter gain, slope, and bandwidth must be specified,
while the third parameter is calculated as
gain=-bandwidth*slope
bandwidth=abs(gain/slope)
slope=-gain/bandwidth
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
frequency (number) – Characteristic frequency in Hz (see frequency_type)
frequency_type (string) –
Defines how frequency is used
'upper'
frequency gives the upper characteristic frequency. In this case
the lower characteristic frequency is given by
2**bandwidth/frequency
'lower'
frequency gives the lower characteristic frequency. In this case
the upper characteristic frequency is given by
2**bandwidth*frequency
gain (number) – The filter gain in dB. The default is None, which calculates the
gain from the slope and bandwidth (must be given if gain is
None).
slope (number) – Filter slope in dB per octave, with positive values denoting a rising
filter slope and negative values denoting a falling filter slope. The
default is None, which calculates the slope from the gain and
bandwidth (must be given if slope is None).
bandwidth (number) – The bandwidth of the filter in octaves. The default is None, which
calculates the bandwidth from gain and slope (must be given if
bandwidth is None).
N (int) – Number of shelf filters that are cascaded. The default is None,
which calculated the minimum N that is required to satisfy Eq. (11)
in Schultz et al. 2020, i.e., the minimum N that is required for
a good approximation of the ideal filter response.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
signal (Signal, FilterSOS) – The filtered signal (returned if sampling_rate=None) or the
Filter object (returned if signal=None).
N (int) – The number of shelf filters that were cascaded
ideal (FrequencyData) – The ideal, piece-wise magnitude response of the filter
References
Examples
Generate a filter with a bandwith of 4 octaves and a gain of -60 dB and
compare it to the piece-wise constant idealized magnitude response.
Create and apply or return a second order IIR notch filter.
A notch filter is a band-stop filter with a narrow bandwidth
(high quality factor). It rejects a narrow frequency band around the
center frequency with a gain of 0 (\(-\infty\) dB) at the center
frequency and leaves the rest of the spectrum little changed
with gains close to 1 (0 dB) [19]. Wrapper for
scipy.signal.iirnotch.
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
center_frequency (number) – Frequency in Hz at which the magnitude response will be 0
(\(-\infty\) dB).
quality (number) – The quality characterizes notch filter -3 dB bandwidth relative to its
center frequency (both in Hz), i.e,
quality=center_frequency/bandwidth.
sampling_rate (None, number) – The sampling rate in Hz. Only required if signal is None. The
default is None.
Returns:
output – The function returns a filtered version of the input signal if
sampling_rate=None or the filter itself if signal=None.
Create and/or apply an amplitude preserving fractional octave filter bank.
Note
This filter bank has -6 dB cut-off frequencies. For sufficient lengths
of 'n_samples', the summed output of the filter bank equals the
input signal, i.e., the filter bank is amplitude preserving
(reconstructing). This is useful for analysis and synthesis
applications such as room acoustical simulations. For an energy
preserving filter bank with -3 dB cut-off frequencies see
fractional_octave_bands.
The filters have a linear phase with a delay of n_samples/2 and are
windowed with a Hanning window to suppress side lobes of the finite
filters. The magnitude response of the filters is designed similar to [20]
with two exceptions:
The magnitude response is designed using squared sine/cosine ramps to
obtain -6 dB at the cut-off frequencies.
The overlap between the filters is calculated between the center and
upper cut-off frequencies and not between the center and lower cut-off
frequencies. This enables smaller pass-bands with unity gain, which
might be advantageous for applications that apply analysis and
resynthesis.
Parameters:
signal (Signal, None) – The Signal to be filtered. Pass None to create the filter without
applying it.
num_fractions (int, optional) – Octave fraction, e.g., 3 for third-octave bands. The default is
1.
frequency_range (tuple, optional) – Frequency range for fractional octave in Hz. The default is
(63,16000)
overlap (float) – Band overlap of the filter slopes between 0 and 1. Smaller values yield
wider pass-bands and steeper filter slopes. The default is 1.
slope (int, optional) – Number > 0 that defines the width and steepness of the filter slopes.
Larger values yield wider pass-bands and steeper filter slopes. The
default is 0.
n_samples (int, optional) – Length of the filter in samples. Longer filters yield more exact
filters. The default is 2**12.
sampling_rate (int) – Sampling frequency in Hz. The default is None. Only required if
signal=None.
Returns:
signal (Signal) – The filtered signal. Only returned if sampling_rate=None.
filter (FilterFIR) – FIR Filter object. Only returned if signal=None.
frequencies (np.ndarray) – Center frequencies of the filters.
References
Examples
Filter and re-synthesize an impulse signal.
>>> importpyfaraspf>>> importnumpyasnp>>> importmatplotlib.pyplotasplt>>> # generate data>>> x=pf.signals.impulse(2**12)>>> y,f=pf.dsp.filter.reconstructing_fractional_octave_bands(x)>>> y_sum=pf.Signal(np.sum(y.time,0),y.sampling_rate)>>> # time domain plot>>> ax=pf.plot.time_freq(y_sum,color='k',unit='ms')>>> pf.plot.time(x,ax=ax[0],unit='ms')>>> ax[0].set_xlim(-20,250)>>> ax[0].set_title("Original (blue) and reconstructed pulse (black)")>>> # frequency domain plot>>> pf.plot.freq(y_sum,color='k',ax=ax[1])>>> pf.plot.freq(y,ax=ax[1])>>> ax[1].set_title(... "Reconstructed (black) and filtered impulse (colored)")