apply diataxis to tutorials/inverse/80_brainstorm_phantom_elekta.py by CarinaFo · Pull Request #13584 · mne-tools/mne-python

CarinaFo · 2026-01-10T05:03:13Z

apply diataxis framework to tutorials/inverse/80_brainstorm_phantom_elekta.py

Bumps [davidslusser/actions_python_bandit](https://github.com/davidslusser/actions_python_bandit) from 1.0.0 to 1.0.1. - [Release notes](https://github.com/davidslusser/actions_python_bandit/releases) - [Commits](davidslusser/actions_python_bandit@v1.0.0...v1.0.1) --- updated-dependencies: - dependency-name: davidslusser/actions_python_bandit dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com>

…usser/actions_python_bandit-1.0.1 Bump davidslusser/actions_python_bandit from 1.0.0 to 1.0.1

CarinaFo · 2026-01-25T01:41:31Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

 raw.plot(events=events)

+# We can see that the simulated dipoles produce sinusoidal bursts at 20 Hz
+#  (can we really see that in the plot?)


Here I wonder if we can get rid of one of the screenshots of the dipole events and maybe zoom into one event to show the 20Hz burst

Yes that sounds good, you should be able to see it clearly at least in the average, and depending on the dipole amplitude you can sometimes see it in the raw / epoched data

I plotted fewer channels, I think now it's a bit easier to see

CarinaFo · 2026-01-25T01:43:02Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

 cov = mne.compute_covariance(epochs, tmax=bmax)
 mne.viz.plot_evoked_white(epochs["1"].average(), cov)

+# Not sure what we see here TBH


Here we should explain why we plot the whitened data and what the user is expected to see vs. what we actually see in this plot.

Or can we just link to the whitening / covariance tutorials? It is explained there I think

I would add one sentence on whitening plus link to the whitening tutorial for further referenc (this is in line with diataxis)

CarinaFo · 2026-01-25T01:44:00Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

-# Now we can compare to the actual locations, taking the difference in mm:
-
+# Finally, we compare the estimated to the true dipole locations
+# To do this, we calculate the difference by .....


I think we should explain how we compute the difference and why, this seems to be crucial info for a tutorial on comparing estimated vs. true dipoles.

Makes sense to me

CarinaFo · 2026-01-25T01:45:43Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

 ax3.set_ylabel("Amplitude error (nAm)")

+# We can see that the error magnitude depends on the position of the estimate dipole
+# however, the location error is never greater than 5 mm which is good?


again I am not sure if we can interpret the error magnitude (or should). I think it would be very useful for a user to get some guidance on what to do with those results but maybe this goes too far for the current tutorial.

I think we can, we can say something about the potential localization accuracy of MEG. Like if we can get ~2-5mm error localizing these dipoles we can say MEG can localize point sources with that accuracy (given proper coreg etc.), which helps justify claims of "sub-centimeter" accuracy

larsoner

Didn't read through all changes but wanted to give input on questions!

larsoner · 2026-01-26T14:05:08Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

 raw.plot(events=events)

+# We can see that the simulated dipoles produce sinusoidal bursts at 20 Hz
+#  (can we really see that in the plot?)


Yes that sounds good, you should be able to see it clearly at least in the average, and depending on the dipole amplitude you can sometimes see it in the raw / epoched data

larsoner · 2026-01-26T14:05:45Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

 cov = mne.compute_covariance(epochs, tmax=bmax)
 mne.viz.plot_evoked_white(epochs["1"].average(), cov)

+# Not sure what we see here TBH


Or can we just link to the whitening / covariance tutorials? It is explained there I think

larsoner · 2026-01-26T14:06:33Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

-# Now we can compare to the actual locations, taking the difference in mm:
-
+# Finally, we compare the estimated to the true dipole locations
+# To do this, we calculate the difference by .....


Makes sense to me

larsoner · 2026-01-26T14:08:46Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

 ax3.set_ylabel("Amplitude error (nAm)")

+# We can see that the error magnitude depends on the position of the estimate dipole
+# however, the location error is never greater than 5 mm which is good?


I think we can, we can say something about the potential localization accuracy of MEG. Like if we can get ~2-5mm error localizing these dipoles we can say MEG can localize point sources with that accuracy (given proper coreg etc.), which helps justify claims of "sub-centimeter" accuracy

drammock

The tutorials go .py -> .rst -> .html.
if you build the docs locally, you should be able to view the intermediate rST files, which means the line number in the error message (line 663) will tell you exactly where the problem is. (You might need to tweak the build command, it might delete the generated rST files by default)

https://app.circleci.com/pipelines/github/mne-tools/mne-python/30229/workflows/0e25b414-b050-40d7-8e10-fa5c75b00a1a/jobs/79087?invite=true#step-143-0_171

drammock · 2026-02-17T15:27:19Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

 # .. _plt_brainstorm_phantom_elekta_eeg_sphere_geometry:
+# We averaged over 640 simulated events for the first dipole.


between these two, this might be where you need a blank line?

tutorials/inverse/80_brainstorm_phantom_elekta.py

drammock · 2026-02-17T15:30:34Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

+#
 # .. footbibliography::
+#
+#


remove the extra empty lines you added here. It's possible that is what causes the cryptic sphinx build error.

CarinaFo · 2026-02-21T06:05:41Z

The tutorials go .py -> .rst -> .html. if you build the docs locally, you should be able to view the intermediate rST files, which means the line number in the error message (line 663) will tell you exactly where the problem is. (You might need to tweak the build command, it might delete the generated rST files by default)

https://app.circleci.com/pipelines/github/mne-tools/mne-python/30229/workflows/0e25b414-b050-40d7-8e10-fa5c75b00a1a/jobs/79087?invite=true#step-143-0_171

I ran into issues building docs locally (Windows 11 Pro, python 3.11), currently trying to document where it breaks and what are possible solutions.

Update: local docs are finally working

CarinaFo · 2026-03-21T06:04:11Z

@drammock ready for review

drammock · 2026-03-18T21:53:06Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

+For comparison, see :footcite:`TadelEtAl2011` and
+`the original Brainstorm tutorial with an explanation of phantom recordings


maybe worthwhile to add 1 sentence at start of this paragraph, explaining what a phantom is? Something like "Phantoms are devices that fit inside a MEG measurement volume, and can generate electric dipoles with known current amplitudes and locations."

I added a sentence after mentioning phantom recordings the first time

drammock · 2026-03-18T21:56:08Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

+# Next, let's look at the events in the phantom data for one stimulus channel.
 events = find_events(raw, "STI201")
-raw.plot(events=events)
 raw.info["bads"] = ["MEG1933", "MEG2421"]  # known bad channels


seems like this should come earlier (right after read_raw_fif I think); it's known a priori (not inferred from the raw.info output or the find_events call)

drammock · 2026-03-18T21:59:41Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

-# The first peak appears around 3 ms. Because we low-passed at 40 Hz,
-# we can also decimate our data to save memory.
-
+# The simulated dipoles produce sinusoidal bursts at 20 Hz.


In this data the phantom was programmed to produce 20 Hz sinusoidal bursts of current.

(i.e., make it clear that this was user-determined, 20 Hz is not intrinsic to the device)

drammock · 2026-03-18T22:00:53Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

-
+# The simulated dipoles produce sinusoidal bursts at 20 Hz.
+#
+# Next, we epoch the the data based on the dipoles events (1:32).


Suggested change

# Next, we epoch the the data based on the dipoles events (1:32).

# Next, we epoch the the data based on the dipole events (1:32).

drammock · 2026-03-18T22:03:06Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

+# Next, we epoch the the data based on the dipoles events (1:32).
+#
+# We select 100 ms before and after the event trigger
+# and baseline correct the epochs from -100 ms to -0.05 ms before stimulus onset.


Suggested change

# and baseline correct the epochs from -100 ms to -0.05 ms before stimulus onset.

# and baseline correct the epochs using a baseline period from -100 ms to -50 ms (before stimulus onset).

drammock · 2026-03-24T22:37:45Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

-# but in general "shrunk" is usually better
+# We can see that our head model aligns with the phantom head model.
+#
+# Let's do some dipole fits.


This is a critical part of the process, and deserves more emphasis (and hand-holding). Consider making this a titled subsection, or at least spelling out the step a bit more clearly. For example: "Our next step is to use the epoched data to fit dipoles, then compare them to the known dipole locations built into the phantom"

drammock · 2026-03-24T22:39:21Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

-mne.viz.plot_evoked_white(epochs["1"].average(), cov)

+# The plot shows the evoked signal divided by the estimated noise standard deviation.
+mne.viz.plot_evoked_white(epochs["1"].average(), cov)


not sure this is strictly necessary for the tutorial's stated goal

drammock · 2026-03-24T22:41:54Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

+# We have seen in the evoked plot that this is around 3 ms after dipole onset.
 data = []
 t_peak = 0.036  # true for Elekta phantom


text says 3 ms, but t_peak is 36 ms. 3 ms is when the first wave starts right, not the peak location?

Also: might be worth going through the process of computing the peak exactly here, instead of just saying "true for Elekta phantom"

Agreed, I include the peak determination

drammock · 2026-03-24T22:44:09Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

+# Let's visualize the explained variance.
+# To do this, we need to make sure that the
+# data and the residuals are on the same scale
+# (here the "time points" are the 32 dipole peak values that we fit).


to me this is a confusing visualization. Surely there's a better way to summarize explained variance?

We can plot goodness of fit for each dipole. Currently trying to figure out what values that actually is.

drammock · 2026-03-24T22:47:55Z

tutorials/inverse/80_brainstorm_phantom_elekta.py

    evoked = epochs[str(ii)][1:-1].average().crop(t_peak, t_peak)
    data.append(evoked.data[:, 0])
 evoked = mne.EvokedArray(np.array(data).T, evoked.info, tmin=0.0)


this approach of cramming a single (peak) timepoint from each of 32 separate evokeds into a single EvokedArray is very confusing. We should probably do this a more straightforward way, or at least add a lot more explanation of this code block.

fit_dipoles() expects an Evoked Object, we can store every dipole as a separate evoked, that migh be less confusing.

CarinaFo · 2026-04-12T06:42:23Z

CI failure seems unrelated to this PR (PyVista/VTK on Python 3.13).

dependabot bot and others added 11 commits March 11, 2024 03:30

Merge pull request #4 from CarinaFo/dependabot/github_actions/davidsl…

8aa3e7a

…usser/actions_python_bandit-1.0.1 Bump davidslusser/actions_python_bandit from 1.0.0 to 1.0.1

Merge branch 'mne-tools:main' into main

81e73c8

Merge branch 'mne-tools:main' into main

1cb10a1

Merge branch 'mne-tools:main' into main

92cdef1

diataxis

25e3990

first draft using diataxis framework

9624517

added changelog

174d36d

changelog update

aa4ca19

wrong PR

37ef2ad

deleted changelog with wrong PR

e31c386

CarinaFo commented Jan 25, 2026

View reviewed changes

larsoner reviewed Jan 26, 2026

View reviewed changes

CarinaFo added 8 commits February 14, 2026 13:32

Merge branch 'main' into diataxis

efb2765

added explanations

ab6f3c5

formatting for docs

c398ec7

more formatting

0be4f48

final formatting

c5e8c3f

add blank lines around directives

9ccff3f

add blank line at file end

9fc7c4a

fix sphinx error log

e8299e2

CarinaFo marked this pull request as ready for review February 17, 2026 00:31

CarinaFo requested review from agramfort and drammock as code owners February 17, 2026 00:31

drammock reviewed Feb 17, 2026

View reviewed changes

fix sphinx formatting error

35949f4

Merge branch 'main' into diataxis

7ea90a6

CarinaFo mentioned this pull request Mar 1, 2026

Possible improvements to structuring of Decoding (MVPA) documentation #13707

Open

CarinaFo changed the title ~~apply diataxis framework to tutorials~~ apply diataxis to tutorials/inverse/80_brainstorm_phantom_elekta.py Mar 21, 2026

drammock reviewed Mar 24, 2026

View reviewed changes

CarinaFo added 2 commits March 29, 2026 14:51

address dan's review

139d273

fix t_peak

bd52896

CarinaFo marked this pull request as draft March 29, 2026 05:08

CarinaFo added 13 commits March 29, 2026 19:40

fixed peak amplitude estimation

d39b6e5

prettified GOF plot

bd754f8

single evokeds instead of evoked with dipoles as timepoints

fa6976a

add TODO

f2a079b

add formatting TODO

4e2cdc6

removed plotting label

5046a47

fix 3D plotting (very slow, discuss with Dan)

93be3a6

second dipole object instead of heavy loop

722692e

final formatting (ask Dan regarding ouputs)

01aa3f0

quick formatting

e22e205

removed sphere model reference

b175b50

sphinx error

2b1b4a3

fix doc build sphinx error

e27ac56

CarinaFo marked this pull request as ready for review April 6, 2026 09:05

CarinaFo added 2 commits April 11, 2026 15:02

final formatting

111066e

fix docs fail

b66d7f0

		# .. _plt_brainstorm_phantom_elekta_eeg_sphere_geometry:
		# We averaged over 640 simulated events for the first dipole.

		For comparison, see :footcite:`TadelEtAl2011` and
		`the original Brainstorm tutorial with an explanation of phantom recordings

	# Next, we epoch the the data based on the dipoles events (1:32).
	# Next, we epoch the the data based on the dipole events (1:32).

	# and baseline correct the epochs from -100 ms to -0.05 ms before stimulus onset.
	# and baseline correct the epochs using a baseline period from -100 ms to -50 ms (before stimulus onset).

Uh oh!

Conversation

CarinaFo commented Jan 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

drammock left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CarinaFo commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CarinaFo commented Mar 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

drammock Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CarinaFo Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CarinaFo commented Feb 21, 2026 •

edited

Loading

drammock Mar 18, 2026 •

edited

Loading

CarinaFo Mar 29, 2026 •

edited

Loading