:orphan:

Examples Gallery
================

This gallery contains examples demonstrating the usage of ``mne-denoise``.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

DSS Examples
============

Overview
--------

Examples demonstrating Denoising Source Separation (DSS) across evoked,
spectral, temporal, and blind-separation use cases.

Files
-----

- ``plot_01_dss_fundamentals.py``: Core DSS concepts with trial-average and bandpass biases.
- ``plot_02_artifact_correction.py``: Blink and heartbeat correction with DSS.
- ``plot_03_evoked_responses.py``: Evoked-response denoising and contrast-focused DSS.
- ``plot_04_spectral_dss.py``: Frequency-specific component extraction on synthetic and real data.
- ``plot_05_periodic_dss.py``: Periodic signal extraction for SSVEP and quasi-periodic structure.
- ``plot_06_temporal_dss.py``: Time-shift and smoothness biases for temporally structured signals.
- ``plot_07_spectrogram_dss.py``: Time-frequency masking with spectrogram-based DSS.
- ``plot_08_blind_source_separation.py``: Blind source separation and FastICA equivalence.
- ``plot_09_custom_bias.py``: Defining custom DSS biases.
- ``plot_10_benchmarking.py``: Efficiency benchmarking against PCA, ICA, and averaging.
- ``plot_11_wiener_masking.py``: Adaptive Wiener masking for bursty signals.
- ``plot_12_joint_dss.py``: Joint DSS for multi-dataset repeatability.

Data Requirements
-----------------

- Synthetic sections run directly with no external data.
- Examples using MNE datasets download and cache them through MNE when needed.

References
----------

- Särelä & Valpola (2005). Denoising Source Separation. J. Mach. Learn. Res.
- de Cheveigné & Simon (2008). Denoising based on spatial filtering. J. Neurosci. Methods.
- de Cheveigné & Parra (2014). Joint decorrelation. NeuroImage.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces Denoising Source Separation (DSS), a technique for extracting brain sources based on a specific criterion of &quot;interestingness&quot; (bias).">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_01_dss_fundamentals_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_01_dss_fundamentals`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fundamentals of DSS.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="DSS is a powerful tool for removing artifacts (ECG, EOG) from data. The core idea is: Artifacts are repetitive.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_02_artifact_correction_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_02_artifact_correction`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Artifact Correction with DSS.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use DSS to enhance evoked responses (ERPs/ERFs). It covers both standard average-bias denoising of the shared evoked response and a custom contrast bias that isolates the difference between two experimental conditions.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_03_evoked_responses_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_03_evoked_responses`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Denoising Evoked Responses.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use DSS to isolate oscillatory brain rhythms (e.g., Alpha, Beta) using spectral biases.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_04_spectral_dss_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_04_spectral_dss`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Denoising Rhythms (Spectral DSS).</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates periodic signal extraction with DSS. It combines PeakFilterBias, CombFilterBias, and QuasiPeriodicDenoiser with DSS and IterativeDSS to cover single-frequency extraction, SSVEP harmonics, and quasi-periodic structure such as ECG-like activity.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_05_periodic_dss_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_05_periodic_dss`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Periodic Signals (SSVEP and Quasi-Periodic).</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates DSS for extracting temporally structured signals: autocorrelated components, slow drifts, and smooth waveforms.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_06_temporal_dss_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_06_temporal_dss`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Temporal DSS: Time-Shift Regression & Smoothness.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates DSS for extracting transient oscillatory bursts using time-frequency (TF) domain constraints via spectrogram masking.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_07_spectrogram_dss_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_07_spectrogram_dss`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Time-Frequency DSS: Spectrogram Masking.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how Nonlinear DSS can perform Blind Source Separation (BSS), effectively recovering independent sources from mixed signals. It explicitly shows the equivalence between DSS with specific nonlinearities and ICA.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_08_blind_source_separation_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_08_blind_source_separation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Blind Source Separation and ICA Equivalence.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to extend DSS by defining custom bias criteria. This is useful when you have domain-specific knowledge about the target source (e.g., &quot;it has sharp gradients&quot;, &quot;it occurs after a specific trigger&quot;, etc.).">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_09_custom_bias_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_09_custom_bias`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Custom DSS: Defining Your Own Bias.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the superior efficiency of DSS in recovering evoked responses compared to standard methods.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_10_benchmarking_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_10_benchmarking`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Efficiency Benchmark: DSS vs PCA, ICA, and Averaging.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the WienerMaskDenoiser, a nonlinear function that adapts to the local variance (envelope) of the signal.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_11_wiener_masking_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_11_wiener_masking`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Adaptive Wiener Masking for Bursty Signals.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates Joint Denoising Source Separation (JDSS), a method for extracting components that are reproducible across multiple datasets.">

.. only:: html

  .. image:: /auto_examples/dss/images/thumb/sphx_glr_plot_12_joint_dss_thumb.png
    :alt:

  :doc:`/auto_examples/dss/plot_12_joint_dss`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Joint DSS (Multi-Dataset Repeatability).</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

ZapLine Examples
================

Overview
--------

Examples demonstrating ZapLine and ZapLine-plus for removing power-line
artifacts from synthetic, epoched, continuous, and adaptive-cleaning scenarios.

Files
-----

- ``plot_01_basic_usage.py``: Basic ZapLine usage on synthetic line-noise data.
- ``plot_02_parameter_tuning.py``: Parameter tuning and real NoiseTools MEG data.
- ``plot_03_epoched_data.py``: Epoched ZapLine workflows and high-channel MEG data.
- ``plot_04_adaptive_mode.py``: ZapLine-plus style adaptive cleaning on non-stationary data.
- ``plot_05_adaptive_advanced.py``: Advanced harmonic and chunk-level adaptive outputs.

Data Requirements
-----------------

- Synthetic sections run directly with no external data.
- Examples using MNE datasets download and cache them through MNE when needed.
- NoiseTools-backed examples download and cache the required `.mat` files into
  ``examples/zapline/data`` the first time they are run.

References
----------

- de Cheveigné (2020). ZapLine: A simple and effective method to remove power line artifacts. NeuroImage.
- Klug & Kloosterman (2022). Zapline-plus: A Zapline extension for automatic and adaptive removal of frequency-specific noise artifacts in M/EEG. Human Brain Mapping.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example introduces ZapLine on a controlled synthetic dataset. The goal is to show the basic workflow first on a simple 50 Hz contamination problem, then extend it to harmonics and more realistic multi-channel structure.">

.. only:: html

  .. image:: /auto_examples/zapline/images/thumb/sphx_glr_plot_01_basic_usage_thumb.png
    :alt:

  :doc:`/auto_examples/zapline/plot_01_basic_usage`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">ZapLine: Line Noise Removal Fundamentals.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how the main ZapLine tuning parameters change the cleaning behavior on synthetic data, then applies the same workflow to a real NoiseTools MEG recording.">

.. only:: html

  .. image:: /auto_examples/zapline/images/thumb/sphx_glr_plot_02_parameter_tuning_thumb.png
    :alt:

  :doc:`/auto_examples/zapline/plot_02_parameter_tuning`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">ZapLine: Parameter Tuning and Real Data.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how ZapLine can be applied when the data are naturally epoched, then extends the same workflow to larger real MEG arrays from the NoiseTools examples.">

.. only:: html

  .. image:: /auto_examples/zapline/images/thumb/sphx_glr_plot_03_epoched_data_thumb.png
    :alt:

  :doc:`/auto_examples/zapline/plot_03_epoched_data`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">ZapLine: Epoched Data and Real Data Examples.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example follows the main steps of ZapLine-plus on a synthetic recording whose line noise changes in frequency, topography, and strength over time. The goal is to make the adaptive logic visible: frequency detection, segmentation, and chunk-wise cleaning.">

.. only:: html

  .. image:: /auto_examples/zapline/images/thumb/sphx_glr_plot_04_adaptive_mode_thumb.png
    :alt:

  :doc:`/auto_examples/zapline/plot_04_adaptive_mode`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">ZapLine-plus: Adaptive Cleaning on Non-Stationary Noise.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example focuses on the extra adaptive features around the core ZapLine step: harmonic handling, chunk metadata, and the hybrid fallback path when a plain component projection is not enough.">

.. only:: html

  .. image:: /auto_examples/zapline/images/thumb/sphx_glr_plot_05_adaptive_advanced_thumb.png
    :alt:

  :doc:`/auto_examples/zapline/plot_05_adaptive_advanced`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">ZapLine-plus: Advanced Settings and Features.</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/dss/index.rst
   /auto_examples/zapline/index.rst