work on dipolefitui

Author: wmvanvliet

examples/inverse/multi_dipole_model.py

@@ -1,61 +1,38 @@
 """
 .. _ex-multi-dipole:
 
-=================================================================
-Computing source timecourses with an XFit-like multi-dipole model
-=================================================================
-
-MEGIN's XFit program offers a "guided ECD modeling" interface, where multiple
-dipoles can be fitted interactively. By manually selecting subsets of sensors
-and time ranges, dipoles can be fitted to specific signal components. Then,
-source timecourses can be computed using a multi-dipole model. The advantage of
-using a multi-dipole model over fitting each dipole in isolation, is that when
-multiple dipoles contribute to the same signal component, the model can make
-sure that activity assigned to one dipole is not also assigned to another. This
-example shows how to build a multi-dipole model for estimating source
-timecourses for evokeds or single epochs.
-
-The XFit program is the recommended approach for guided ECD modeling, because
-it offers a convenient graphical user interface for it. These dipoles can then
-be imported into MNE-Python by using the :func:`mne.read_dipole` function for
-building and applying the multi-dipole model. In addition, this example will
-also demonstrate how to perform guided ECD modeling using only MNE-Python
-functionality, which is less convenient than using XFit, but has the benefit of
-being reproducible.
+======================
+Guided dipole modeling
+======================
+
+Inspired by MEGIN's XFit program, MNE-Python offers a guided dipole modeling interface.
+Through this interface, you can fit dipoles at specific timings using selected subsets
+of sensors to gradually build up a multi dipole source estimate. This is the manual
+alternative to using automated algorithms such as TRAP-MUSIC and MxNE.
 """
 # Author: Marijn van Vliet <w.m.vanvliet@gmail.com>
 #
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
-###############################################################################
-# Importing everything and setting up the data paths for the MNE-Sample
-# dataset.
+########################################################################################
+# Read the MEG data from the audvis experiment. Make epochs for the left auditory
+# condition.
 import matplotlib.pyplot as plt
 import numpy as np
 
 import mne
-from mne.channels import read_vectorview_selection
 from mne.datasets import sample
-from mne.minimum_norm import apply_inverse, apply_inverse_epochs, make_inverse_operator
 
 data_path = sample.data_path()
 meg_path = data_path / "MEG" / "sample"
 raw_fname = meg_path / "sample_audvis_raw.fif"
-cov_fname = meg_path / "sample_audvis-shrunk-cov.fif"
-bem_dir = data_path / "subjects" / "sample" / "bem"
-bem_fname = bem_dir / "sample-5120-5120-5120-bem-sol.fif"
-
-###############################################################################
-# Read the MEG data from the audvis experiment. Make epochs and evokeds for the
-# left and right auditory conditions.
 raw = mne.io.read_raw_fif(raw_fname)
-raw = raw.pick(picks=["meg", "eog", "stim"])
 info = raw.info
 
 # Create epochs for auditory events
 events = mne.find_events(raw)
-event_id = dict(right=1, left=2)
+event_id = dict(left=2)
 epochs = mne.Epochs(
     raw,
     events,
@@ -67,18 +44,36 @@
 )
 
 # Create evokeds for left and right auditory stimulation
-evoked_left = epochs["left"].average()
-evoked_right = epochs["right"].average()
+evoked = epochs["left"].average()
+
+########################################################################################
+# Guided dipole modeling, meaning fitting dipoles to a manually selected subset of
+# sensors as a manually chosen time, can now be performed using the
+# :class:`mne.gui.DipoleFitting` GUI. By specifying only ``evokeds``, a default noise
+# covariance matrix and 1-layer spherical head model will be used.
+mne.gui.dipolefit(evoked)
 
 ###############################################################################
-# Guided dipole modeling, meaning fitting dipoles to a manually selected subset
-# of sensors as a manually chosen time, can now be performed in MEGINs XFit on
-# the evokeds we computed above. However, it is possible to do it completely
-# in MNE-Python.
+# The source modeling can be made more precise by using a noise covariance matrix and
+# MRI-based 3-layer BEM head model:
+cov_fname = meg_path / "sample_audvis-shrunk-cov.fif"
+subjects_dir = data_path / "subjects"
+bem_dir = subjects_dir / "sample" / "bem"
+bem_fname = bem_dir / "sample-5120-5120-5120-bem-sol.fif"
+trans_fname = meg_path / "sample_audvis_raw-trans.fif"
 
-# Setup conductor model
 cov = mne.read_cov(cov_fname)  # bad channels were already excluded here
 bem = mne.read_bem_solution(bem_fname)
+trans = mne.read_trans(trans_fname)
+
+mne.gui.dipolefit(
+    evoked,
+    cov=cov.as_diag(),
+    bem=bem,
+    trans=trans,
+    subject="sample",
+    subjects_dir=subjects_dir,
+)
 
 # Fit two dipoles at t=80ms. The first dipole is fitted using only the sensors
 # on the left side of the helmet. The second dipole is fitted using only the

mne/gui/__init__.pyi

@@ -1,3 +1,2 @@
-__all__ = ["_GUIScraper", "coregistration", "DipoleFitUI"]
-from ._gui import _GUIScraper, coregistration
-from ._xfit import DipoleFitUI
+__all__ = ["_GUIScraper", "coregistration", "dipolefit"]
+from ._gui import _GUIScraper, coregistration, dipolefit

mne/gui/_gui.py

@@ -165,6 +165,91 @@ def coregistration(
     )
 
 
+@verbose
+def dipolefit(
+    evoked,
+    cov=None,
+    bem=None,
+    initial_time=None,
+    trans=None,
+    stc=None,
+    subject=None,
+    subjects_dir=None,
+    rank="info",
+    show_density=True,
+    ch_type=None,
+    n_jobs=None,
+    show=True,
+    block=False,
+    verbose=None,
+):
+    """GUI for interactive dipole fitting, inspired by MEGIN's XFit program.
+
+    Parameters
+    ----------
+    evoked : instance of Evoked
+        Evoked data to show fieldmap of and fit dipoles to.
+    cov : instance of Covariance | "baseline" | None
+        Noise covariance matrix. If ``None``, an ad-hoc covariance matrix is used with
+        default values for the diagonal elements (see Notes). If ``"baseline"``, the
+        diagonal elements is estimated from the baseline period of the evoked data.
+    bem : instance of ConductorModel | None
+        Boundary element model to use in forward calculations. If ``None``, a spherical
+        model is used.
+    initial_time : float | None
+        Initial time point to show. If ``None``, the time point of the maximum field
+        strength is used.
+    trans : instance of Transform | None
+        The transformation from head coordinates to MRI coordinates. If ``None``,
+        the identity matrix is used and everything will be done in head coordinates.
+    stc : instance of SourceEstimate | None
+        An optional distributed source estimate to show alongside the fieldmap. The time
+        samples need to match those of the evoked data.
+    subject : str | None
+        The subject name. If ``None``, no MRI data is shown.
+    %(subjects_dir)s
+    %(rank)s
+    show_density : bool
+        Whether to show the density of the fieldmap.
+    ch_type : "meg" | "eeg" | None
+        Type of channels to use for the dipole fitting. By default (``None``) both MEG
+        and EEG channels will be used.
+    %(n_jobs)s
+    show : bool
+        Show the GUI if True.
+    block : bool
+        Whether to halt program execution until the figure is closed.
+    %(verbose)s
+
+    Notes
+    -----
+    When using ``cov=None`` the default noise values are 5 fT/cm, 20 fT, and 0.2 µV for
+    gradiometers, magnetometers, and EEG channels respectively.
+    """
+    from ..viz.backends.renderer import MNE_3D_BACKEND_TESTING
+    from ._xfit import DipoleFitUI
+
+    if MNE_3D_BACKEND_TESTING:
+        show = block = False
+    return DipoleFitUI(
+        evoked=evoked,
+        cov=cov,
+        bem=bem,
+        initial_time=initial_time,
+        trans=trans,
+        stc=stc,
+        subject=subject,
+        subjects_dir=subjects_dir,
+        rank=rank,
+        show_density=show_density,
+        ch_type=ch_type,
+        n_jobs=n_jobs,
+        show=show,
+        block=block,
+        verbose=verbose,
+    )
+
+
 class _GUIScraper:
     """Scrape GUI outputs."""
 

mne/gui/_xfit.py

@@ -25,69 +25,11 @@
 from ..utils import _check_option, fill_doc, logger, verbose
 from ..viz import EvokedField, create_3d_figure
 from ..viz._3d import _plot_head_surface, _plot_sensors_3d
+from ..viz.backends._utils import _qt_app_exec
 from ..viz.ui_events import link, subscribe
 from ..viz.utils import _get_color_list
 
 
-@fill_doc
-@verbose
-def dipolefit(
-    evoked,
-    cov=None,
-    bem=None,
-    initial_time=None,
-    trans=None,
-    rank=None,
-    show_density=True,
-    subject=None,
-    subjects_dir=None,
-    n_jobs=None,
-    verbose=None,
-):
-    """GUI for interactive dipole fitting, inspired by MEGIN's XFit program.
-
-    Parameters
-    ----------
-    evoked : instance of Evoked
-        Evoked data to show fieldmap of and fit dipoles to.
-    cov : instance of Covariance | None
-        Noise covariance matrix. If ``None``, an ad-hoc covariance matrix is used.
-    bem : instance of ConductorModel | None
-        Boundary element model to use in forward calculations. If ``None``, a spherical
-        model is used.
-    initial_time : float | None
-        Initial time point to show. If ``None``, the time point of the maximum field
-        strength is used.
-    trans : instance of Transform | None
-        The transformation from head coordinates to MRI coordinates. If ``None``, the
-        identity matrix is used.
-    stc : instance of SourceEstimate | None
-        An optional distributed source estimate to show alongside the fieldmap.
-    %(rank)s
-    show_density : bool
-        Whether to show the density of the fieldmap.
-    subject : str | None
-        The subject name. If ``None``, no MRI data is shown.
-    %(subjects_dir)s
-    %(n_jobs)s
-    %(verbose)s
-    """
-    return DipoleFitUI(
-        evoked=evoked,
-        cov=cov,
-        bem=bem,
-        initial_time=initial_time,
-        trans=trans,
-        stc=None,
-        rank=rank,
-        show_density=show_density,
-        subject=subject,
-        subjects_dir=subjects_dir,
-        n_jobs=n_jobs,
-        verbose=verbose,
-    )
-
-
 @fill_doc
 class DipoleFitUI:
     """GUI for interactive dipole fitting, inspired by MEGIN's XFit program.
@@ -144,6 +86,8 @@ def __init__(
         show_density=True,
         ch_type=None,
         n_jobs=None,
+        show=True,
+        block=False,
         verbose=None,
     ):
         if cov is None:
@@ -213,17 +157,23 @@ def __init__(
         self._verbose = verbose
 
         # Configure the GUI.
-        self._renderer = self._configure_main_display()
+        self._renderer = self._configure_main_display(show)
         self._configure_dock()
 
+        # must be done last
+        if show:
+            self._renderer.show()
+        if block and self._renderer._kind != "notebook":
+            _qt_app_exec(self._renderer.figure.store["app"])
+
     @property
     def dipoles(self):
         """A list of all the fitted dipoles that are enabled in the GUI."""
         return [d["dip"] for d in self._dipoles.values() if d["active"]]
 
-    def _configure_main_display(self):
+    def _configure_main_display(self, show=True):
         """Configure main 3D display of the GUI."""
-        fig = create_3d_figure((1500, 1020), bgcolor="white", show=True)
+        fig = create_3d_figure((1500, 1020), bgcolor="white", show=show)
 
         self._fig_stc = None
         if self._stc is not None: