More information on eSSS for MaxFilter algorithm

[skjerns]

Proposed documentation enhancement

In mne.preprocessing.maxwell_filter it is mentioned that mne implements Extended external basis (eSSS). When trying to find more information about what this exactly is and if and how I should use it, the only information I could find was this GitHub issue of the PR that added it. Additionally, the paper of course, but it's very technical.

It would be great if more information on eSSS and scenarios in which it is useful would be added to the official documentation!

This could include / questions I had:

• example that uses eSSS
• when should I use eSSS
• when should you NOT use eSSS
• is eSSS compatible with tSSS (according to the paper it should be?)
• what is a extended_proj and how to obtain it
• disadvantage of using an empty room recording not obtained during the same session

[larsoner]

Yes it would be good to improve the docs! @skjerns would you be up for fixing the docs at least by adding eSSS to some example probably (this one) and add a citation to the paper, which should answer most of these questions? The short version is that you can use any projector you want really, but the idea is that it should typically capture something about your empty-room data that isn't captured by the ext_order=3, like some higher order room vibration, etc. By adding it to the extended basis it should help suppress the artifact

[skjerns]

I'd be up for that, however, I'm myself not entirely sure how to apply it. I'm not even sure if I understand projections enough to get how eSSS works. ChatGPT suggested something like this, but I have no idea if this is correct.

raw = mne.io.read_raw('recording.fif')
raw_er = mne.io.read_raw('empty_room.fif')
raw_er_prep = mne.preprocessing.maxwell_filter_prepare_emptyroom(raw_er, raw=raw)
extended_proj = mne.compute_proj_raw(
                    raw_er_prep.pick('meg'),
                    n_grad=3,
                    n_mag=3,
                    meg="separate",
                )
raw_etsss = mne.preprocessing.maxwell_filter(
            raw,
            calibration=fine_cal_file,
            cross_talk=crosstalk_file,
            st_duration=10.0,          # tSSS
            head_pos=headpos[task],
            extended_proj=extended_proj,
            destination=dest,          # rotate to main mean head position
            coord_frame="head",
            verbose=True,
        )

[larsoner]

I think meg="combined" makes more sense here since it'll end up being used similarly to an SSS basis vector. And you don't need the raw_er_prep step most likely. But otherwise yes just compute_proj_raw on whatever has an artifact of interest then pass the resulting proj to extended_proj...