XFit-style dipole fitting GUI

doc/api/inverse.rst

@@ -85,6 +85,7 @@ Inverse Solutions
    Dipole
    DipoleFixed
    fit_dipole
+   gui.dipolefit
 
 :py:mod:`mne.dipole`:
 

doc/changes/dev/13074.newfeature.rst

@@ -0,0 +1 @@
+Add a GUI for interactive guided dipole fitting (:func:`mne.gui.dipolefit`), by `Marijn van Vliet`_

doc/conf.py

@@ -424,6 +424,7 @@
     "default",
     # unlinkable
     "CoregistrationUI",
+    "DipoleFitUI",
     "mne_qt_browser.figure.MNEQtBrowser",
     # pooch, since its website is unreliable and users will rarely need the links
     "pooch.Unzip",

mne/commands/mne_dipolefit.py

@@ -0,0 +1,169 @@
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+"""Open the dipole fitting GUI on the given evoked file ("-ave.fif").
+
+Examples
+--------
+.. code-block:: console
+
+    $ mne dipolefit
+
+"""
+
+import os.path as op
+import sys
+
+import mne
+
+
+def run():
+    """Run command."""
+    from mne.commands.utils import _add_verbose_flag, get_optparser
+
+    parser = get_optparser(__file__, usage="mne dipolefit EVOKED_FILE")
+
+    parser.add_option(
+        "--condition",
+        default=0,
+        help="The condition to use.",
+    )
+    parser.add_option(
+        "--baseline",
+        default=None,
+        metavar="BASELINE",  # docutils doesn't like commas in rendered metavar
+        help=(
+            "The time period to use as baseline, written as two numbers (in seconds, "
+            "relative to the stimulus onset) separated by a comma. "
+            "For example: --baseline=-0.2,0.1"
+        ),
+    )
+    parser.add_option(
+        "-c",
+        "--cov",
+        default=None,
+        metavar="COV_FILE",
+        help='The noise covariance ("-cov.fif") to use.',
+    )
+    parser.add_option(
+        "-b",
+        "--bem",
+        default=None,
+        metavar="BEM_FILE",
+        help=(
+            'The BEM model ("-bem-sol.fif") to use. When omitted, a basic sphere '
+            "model will be used."
+        ),
+    )
+    parser.add_option(
+        "-t",
+        "--initial-time",
+        default=None,
+        type=float,
+        metavar="TIME",
+        help="The initial time to show",
+    )
+    parser.add_option(
+        "--trans",
+        default=None,
+        metavar="TRANS_FILE",
+        help='Head<->MRI transform FIF file ("-trans.fif")',
+    )
+    parser.add_option(
+        "--stc",
+        default=None,
+        metavar="STC_FILE",
+        help="An optional distributed source estimate to show during dipole fitting.",
+    )
+    parser.add_option(
+        "-s", "--subject", dest="subject", default=None, help="Subject name"
+    )
+    parser.add_option(
+        "-d",
+        "--subjects-dir",
+        default=None,
+        help="Subjects directory",
+    )
+    parser.add_option(
+        "--hide-density",
+        action="store_true",
+        default=False,
+        help="Prevent showing the magnetic field density as blobs of color.",
+    )
+    parser.add_option(
+        "--channel-type",
+        default=None,
+        help=(
+            'Restrict channel types to either "meg" or "eeg". By default both are used '
+            "if present."
+        ),
+    )
+    parser.add_option(
+        "-j", "--n-jobs", default=-1, type=int, help="Number of CPUs to use."
+    )
+    _add_verbose_flag(parser)
+
+    options, args = parser.parse_args()
+    if len(args) != 1:
+        parser.print_help()
+        sys.exit(1)
+
+    # expanduser allows ~ for paths
+    subjects_dir = options.subjects_dir
+    if subjects_dir is not None:
+        subjects_dir = op.expanduser(subjects_dir)
+    bem = options.bem
+    if bem is not None:
+        bem = op.expanduser(bem)
+    trans = options.trans
+    if trans is not None:
+        trans = op.expanduser(trans)
+    stc = options.stc
+    if stc is not None:
+        stc = op.expanduser(stc)
+
+    # Condition can be specified as integer index or string comment.
+    if options.condition is not None:
+        try:
+            condition = int(options.condition)
+        except ValueError:
+            condition = options.condition
+    else:
+        condition = None
+    evoked = mne.read_evokeds(args[0], condition=condition)
+
+    # Parse the baseline time period
+    baseline = None
+    if options.baseline:
+        try:
+            baseline = [float(x) for x in options.baseline.split(",")]
+            if len(baseline) != 2:
+                raise ValueError()
+        except ValueError:
+            raise ValueError(
+                "The 'baseline' parameter should be written as two numbers (in seconds,"
+                " relative to the stimulus onset) separated by a comma. "
+                "For example: --baseline=-0.2,0.1"
+            )
+
+    mne.gui.dipolefit(
+        evoked=evoked,
+        baseline=baseline,
+        cov=options.cov,
+        bem=bem,
+        subject=options.subject,
+        subjects_dir=subjects_dir,
+        stc=stc,
+        ch_type=options.channel_type,
+        initial_time=options.initial_time,
+        trans=trans,
+        n_jobs=options.n_jobs,
+        show_density=not options.hide_density,
+        show=True,
+        block=True,
+        verbose=options.verbose,
+    )
+
+
+mne.utils.run_command_if_main()

mne/commands/tests/test_commands.py

@@ -31,6 +31,7 @@
     mne_compute_proj_ecg,
     mne_compute_proj_eog,
     mne_coreg,
+    mne_dipolefit,
     mne_flash_bem,
     mne_kit2fiff,
     mne_make_scalp_surfaces,
@@ -59,9 +60,9 @@
 raw_fname = op.join(base_dir, "test_raw.fif")
 
 testing_path = testing.data_path(download=False)
-subjects_dir = op.join(testing_path, "subjects")
-bem_model_fname = op.join(
-    testing_path, "subjects", "sample", "bem", "sample-320-320-320-bem.fif"
+subjects_dir = testing_path / "subjects"
+bem_model_fname = (
+    testing_path / "subjects" / "sample" / "bem" / "sample-320-320-320-bem.fif"
 )
 
 
@@ -617,3 +618,8 @@ def test_anonymize(tmp_path):
     info = read_info(out_fname)
     assert op.exists(out_fname)
     assert info["meas_date"] == _stamp_to_dt((946684800, 0))
+
+
+def test_dipolefit():
+    """Test mne dipolefit."""
+    check_usage(mne_dipolefit)

mne/dipole.py

@@ -911,7 +911,7 @@ def _write_dipole_bdip(fname, dip):
             fid.write(np.array(has_errors, ">i4").tobytes())  # has_errors
             fid.write(np.zeros(1, ">f4").tobytes())  # noise level
             for key in _BDIP_ERROR_KEYS:
-                val = dip.conf[key][ti] if key in dip.conf else 0.0
+                val = dip.conf[key][ti] if key in dip.conf else np.array(0.0)
                 assert val.shape == ()
                 fid.write(np.array(val, ">f4").tobytes())
             fid.write(np.zeros(25, ">f4").tobytes())

mne/gui/__init__.pyi

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