Add filter comparison example

src/python_spectrometer/__init__.py

@@ -93,8 +93,11 @@ Finally, plot options can be changed dynamically at runtime::
     spect.plot_raw = True  # Updates the figure accordingly
     spect.plot_timetrace = False
 
+Examples
+--------
+
 Example from :func:`scipy.signal.welch`
----------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In this short demonstration, we reproduce the example from
 :func:`scipy:scipy.signal.welch`. To this end, we write a custom
 ``DAQ`` class that generates a noisy sine signal.
@@ -146,6 +149,46 @@ Finally, we can also plot data in dB relative to a given dataset.
 >>> float(data.max())  # Factor two in amplitude is approx 3 dB
 3.0284739712568682
 
+Analyzing filter behavior
+^^^^^^^^^^^^^^^^^^^^^^^^^
+:mod:`qutil:qutil.signal_processing.real_space` and
+:mod:`qutil:qutil.signal_processing.fourier_space` define filters that
+work in the time- and frequency-domain, respectively. We can visualize
+the filter properties using the spectrometer:
+
+>>> from tempfile import mkdtemp
+>>> import qutil.signal_processing as sp
+>>> from qutil.functools import partial
+>>> from python_spectrometer import daq, Spectrometer
+
+>>> def compare_filters(type: str, order: int):
+...     spect = Spectrometer(daq.QoptColoredNoise(), savepath=mkdtemp(),
+...                          plot_dB_scale=True, plot_density=False)
+...     spect.take('Baseline', n_seg=10, fs=1e4, df=0.1)
+...     spect.procfn = getattr(sp.real_space, f'{type}_filter')
+...     spect.take(f'Real space {order}. order {type} filter',
+...                n_seg=10, f_max=1e2, fs=1e4, df=0.1, order=order)
+...     spect.procfn = sp.real_space.Id
+...     spect.psd_estimator = partial(
+...         sp.real_space.welch,
+...         fourier_procfn=getattr(sp.fourier_space, f'{type}_filter')
+...     )
+...     spect.take(f'Fourier space {order}. order {type} filter',
+...                n_seg=10, f_max=1e2, fs=1e4, df=0.1, order=order)
+...     return spect
+
+RC and Butterworth first order filters are the same (up to real-space
+implementation):
+
+>>> compare_filters('RC', 1)
+>>> compare_filters('butter', 1)
+
+For higher orders, they differ:
+
+>>> compare_filters('RC', 5)
+>>> compare_filters('butter', 5)
+
+
 See the documentation of :class:`~core.Spectrometer` and its methods
 for more information.
 """