Deep source modeling (phase 1)

[payamsash]

Reference issue (if any)

First phase of #14097, also see #6784

What does this implement/fix?

adds setup_subcortical_source_space which should/will support both label (aseg) and surface (e.g coming from CBM).

Additional information

This is just a Proof-of-concept with sample subject.

[payamsash]

you can test it with this small code snippet:

import mne
from mne.datasets import sample

subjects_dir = sample.data_path() / "subjects"
subject = "sample"

# label
src_label = mne.setup_subcortical_source_space(
    subject, label=["Left-Hippocampus", "Left-Amygdala"], subjects_dir=subjects_dir
)
print(src_label.kind)

# surface (e.g for CBM)
surface = subjects_dir / subject / "surf" / "lh.white"
src_surface = mne.setup_subcortical_source_space(
    subject, surface=surface, subjects_dir=subjects_dir, keep_largest_component=False
)
print(src_surface.kind)

# cortex + subcortical
cortex_src = mne.setup_source_space(
    subject, spacing="oct4", add_dist=False, subjects_dir=subjects_dir, verbose=False
)
mixed = mne.SourceSpaces(list(cortex_src) + list(src_label))
print(mixed.kind)

# quick plot 
brain = mne.viz.Brain(
    subject,
    subjects_dir=subjects_dir,
    hemi="lh",
    surf="white",
    alpha=0.3,
    background="white",
    cortex="low_contrast",
)
brain.add_volume_labels(labels=["Left-Hippocampus", "Left-Amygdala"])

[ttaiv]

Thank you @payamsash! I ran you test code snippet using a cerebellar surface for sample from CMB and it worked well. I created a source space with cerebellum and cortex with mixed = src_surface + cortex_src and was able to plot it with mixed.plot().

[drammock]

additions to the FIFF standard need to go in https://github.com/mne-tools/fiff-constants. Presumably this would go here-ish:

https://github.com/mne-tools/fiff-constants/blob/9ccb09d69daa8332f2e7252638ba397b60ba2502/DictionaryTypes_MNE.txt#L89-L95

[payamsash]

Done, see this PR. I also added a temp one here: mne/_fiff/tests/test_constants.py

[payamsash]

ready to be reviewed @drammock . Thanks in advance

[ttaiv]

Any updates on this @larsoner @drammock? The CMB package would greatly benefit from subcortical surface source space support.

[larsoner]

I'm happy with this API / direction, it looks workable. We should wait for @drammock though

FYI we plan to cut 1.13 in the next few days, I think we should merge this PR soon after that lands so we have a release cycle to properly integrate the necessary features and work out issues

[drammock]

This approach is OK for me. Can you add some basic tests? I'm thinking: label input, mesh input, and I/O roundtrip

[drammock]

I'm 50/50 on whether this warning should go at the top of the docstring (just before Parameters section) rather than in the Notes section. Thoughts?

Suggested change

	This is a first, deliberately narrow proof of concept: it has been
	validated interactively on the ``sample`` subject. Known gaps, to be
	addressed in follow-up work: morphing (:class:`~mne.SourceMorph`) does
	not yet support these source spaces, and
	:func:`mne.extract_label_time_course` does not yet know how to select
	vertices within a subcortical-surface label.
	.. warning::
	This is **experimental** functionality. :class:`~mne.SourceSpaces` created by
	this function are not (yet) compatible with morphing (:class:`~mne.SourceMorph`)
	and :func:`mne.extract_label_time_course` does not yet know how to select
	vertices within a subcortical-surface label.

[ttaiv]

I think the warning could very well go at the top. Could also maybe add that plotting support for these source spaces is limited (at least plot() method of resulting MixedSourceEstimate currently throws error)?

[payamsash]

agree with both

[drammock]

@larsoner should this go in before 1.12 release, or just after? I'm OK with either, slightly lean toward after

[drammock]

IIUC, if the user passes a mesh (not a label) then the id is just the offset (SUBCORTICAL_ID_BASE), since we have no way of knowing what subcortical structure(s) the mesh represents. Are the seg_ids for volume labels always non-zero? In other words, if a source has id == 1000 then for certain we don't know what structure this is?

[payamsash]

yes, for label-based source spaces the seg_id is always the nonzero FS aseg label value, so they can never be 1000. and yes with only given surface we can't say which structure it represents.

[drammock]

also maybe worth asking @johnsam7 and @jasmainak for opinions here.

[jasmainak]

@payamsash and @ttaiv I would say try to run this branch to simplify CMB example script and then it will be trivial to merge this branch. Example script:

https://github.com/johnsam7/ceremegbellum/blob/main/examples/example_script.py

that way you'll discover what the API needs.

[ttaiv]

@jasmainak Regarding the CMB example script, I think the effect of this PR is that calling cmb.setup_full_source_space is replaced with a call to mne.setup_subcortical_source_space and the concatenation of cortical and subcortical source space. Then future PRs should address delegating plotting for MNE (currently the resulting MixedSourceEstimate cannot be plotted with MNE)

[drammock]

can remove this now; mne-tools/fiff-constants#47 is merged. You'll need to update the hash in mne/_fiff/tests/test_constants.py though (just below the imports at the top of the file)