Add more information to eSSS in examples and docsstring

[skjerns]

fixes #13581

I've added some more information on eSSS and how to apply it. I'm far from an expert in SSS, so please let me know if my wording is correct.

Additional information

I think it might also be nice to have a full workflow in the example section that applys teSSS, together with head movement correction. Is there a dataset which would be used for that? Else we could record a small dataset for this purpose and upload it somewhere.

[larsoner]

Just a few minor commits, I'll push and then merge when green, thanks @skjerns !

[larsoner]

Oh I just saw draft and main comments, so I won't mark for merge

I think it might also be nice to have a full workflow in the example section that applys teSSS, together with head movement correction. Is there a dataset which would be used for that? Else we could record a small dataset for this purpose and upload it somewhere.

• One option would be just to link to https://github.com/ilabsbrainteam/2022-Best-Practices-Infant-MEG and https://onlinelibrary.wiley.com/doi/full/10.1002/hbm.25871 which does this
• There are tutorials/preprocessing/59_head_positions.py and tutorials/preprocessing/60_maxwell_filtering_sss.py. Neither of these are ideal but this would be next "least effort"
• Finally you could use https://osf.io/2xf4y/files/upj3h which we use in MNE-BIDS-Pipeline, but it's adults so the head movement is minimal and it takes a bit of work to add a dataset to MNE-Python (and there's CI overhead, etc.) so not sure it's worth it

[skjerns]

Oh I just saw draft and main comments, so I won't mark for merge

I think it might also be nice to have a full workflow in the example section that applys teSSS, together with head movement correction. Is there a dataset which would be used for that? Else we could record a small dataset for this purpose and upload it somewhere.

• One option would be just to link to https://github.com/ilabsbrainteam/2022-Best-Practices-Infant-MEG and https://onlinelibrary.wiley.com/doi/full/10.1002/hbm.25871 which does this
• There are tutorials/preprocessing/59_head_positions.py and tutorials/preprocessing/60_maxwell_filtering_sss.py. Neither of these are ideal but this would be next "least effort"
• Finally you could use https://osf.io/2xf4y/files/upj3h which we use in MNE-BIDS-Pipeline, but it's adults so the head movement is minimal and it takes a bit of work to add a dataset to MNE-Python (and there's CI overhead, etc.) so not sure it's worth it

Okay, given the complexity of adding a new dataset, I guess it's easiest to link the tutorial.

Generally it would be great to have an improved MaxFilter tutorial that shows all the variants that SSS can have (with/without movement correction, move to default head position, move to average head position of other participants, tSSS, eSSS, etc etc), as some of the functionality is slightly underdocumented currently. But generally the information is there, it's just in different examples/tutorials/docstrings

[skjerns]

Sorry, I don't know how to make the sphinx happy 😒 her riddles are to hard

/home/circleci/project/doc/auto_tutorials/preprocessing/60_maxwell_filtering_sss.rst:954: ERROR: Unexpected indentation. [docutils]
/home/circleci/project/doc/auto_tutorials/preprocessing/60_maxwell_filtering_sss.rst:955: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]

I guess its about these lines?

# Extended SSS (eSSS) is a variant of SSS that improves suppression of external
# interference especially, when the “ideal” external model is not perfect
# (e.g., because of small calibration/geometry errors). It does this by
# extending the *external* part of the SSS model with interference patterns
# learned from a separate empty-room recording :footcite:`HelleEtAl2021`.
#
# Practical notes:
# - Keep the number of added components small (the ~8 in the original paper);
#   adding too many can worsen numerical conditioning and increase noise.
# - Prefer empty-room data from the same session/environment.
# - eSSS can be combined with tSSS (“teSSS”, i.e. setting ``st_duration=X``).
# - You can get projections from an empty room recording via
#   :func:`mne.compute_proj_raw` like::
#
#       proj = mne.compute_proj_raw(
#           noise_raw, n_grad=3, n_mag=3, n_eeg=0, meg="combined",
#       )

[drammock]

Sorry, I don't know how to make the sphinx happy 😒 her riddles are to hard

Yeah, the line numbers are not informative because they refer to the .rst file that is compiled from the .py file by sphinx-gallery. It usually helps narrow it down to look at the rendered page: https://output.circle-artifacts.com/output/job/80da2061-c65f-42d6-afc6-a70f6e8ad372/artifacts/0/html/auto_tutorials/preprocessing/60_maxwell_filtering_sss.html#extended-sss-esss

First thing I notice is that the first bullet of your bullet list is misformatted as a blockquote; first thing I'd try is adding a blank line before the first bullet. The rest of it looks like it's rendering correctly so maybe that's all? (Of course, if you build the docs locally before pushing to GitHub, then the intermediate .rst files will be available locally, so then the line numbers are actually informative if you look at the intermediate files. They'll be in the same directory as the .py source of the tutorial)

[skjerns]

First thing I notice is that the first bullet of your bullet list is misformatted as a blockquote; first thing I'd try is adding a blank line before the first bullet. The rest of it looks like it's rendering correctly so maybe that's all? (Of course, if you build the docs locally before pushing to GitHub, then the intermediate .rst files will be available locally, so then the line numbers are actually informative if you look at the intermediate files. They'll be in the same directory as the .py source of the tutorial)

will try, thanks!

I've previously tried setting up building the docs locally but after trying quite a bit it still didn't work. Something doesn't seem to work on my local installation (maybe a Windows problem?), but I'll try again tomorrow

[skjerns]

that seems to have fixed it, thanks!

[drammock]

thanks @skjerns !