Option to plot locations of significant channels in expression_plots

[caiw]

This adds a new minimap: bool argument to expression_plot(). Pass True to plot the locations of the significant hexels.

This PR is for a simple case of plotting function-coloured dots for hexels which are above threshold.

Details

• Optional minimap_view: str argument which changes the view (see mne docs for allowed values).
• Optional minimap_surface: str argument to change the surface (see mne docs for allowed values).
• When run with the minimap=True plotting argument, it will download the fsaverage surfaces using mne (this only needs to be done once).
  • Unfortunately, because I'm using MNE's code, it downloads all the fsaverage surfaces, not just the requested one. But I think it's worth this minor inconvenience of extra files downloaded once, to keep the code nice and clean, and let MNE handle any changes to their data repository URLs.
• Plots on the fsaverage brain, and warns to let you know it's doing that.
• Fixes Add hexel location figure alongside expression plots #73
• Fixes Allow new brain plots to be easily used in notebooks #219

Example

config = load_config(str(Path(Path(__file__).parent.parent, "kymata", "config", "dataset3.yaml")))

expression_data = KymataMirror2023Q3Dataset().to_expressionset()

expression_plot(expression_data[
                    'vibration detection (RH-Th/P/M)',
                    'vibration detection (LH-Th/P/M)',
                    'vibration detection (LH-Ha/P/M)',
                    'vibration detection (RH-Ha/P/M)',
                    'CIECAM02 A',
                    'CIECAM02 a',
                    'CIELAB a*',
                    'CIELAB L',
                    'TVL loudness chan 1 (instantaneous)',
                    'TVL loudness chan 2 (instantaneous)',
                    'TVL loudness chan 3 (instantaneous)',
                    'TVL loudness chan 4 (instantaneous)',
                    'TVL loudness chan 5 (instantaneous)',
                    'TVL loudness chan 6 (instantaneous)',
                    'TVL loudness chan 7 (instantaneous)',
                    'TVL loudness chan 8 (instantaneous)',
                    'TVL loudness chan 9 (instantaneous)',
                ],
                show_only=[
                    'vibration detection (LH-Th/P/M)',
                    'CIECAM02 A',
                    'CIECAM02 a',
                    'TVL loudness chan 1 (instantaneous)',
                    'TVL loudness chan 2 (instantaneous)',
                    'TVL loudness chan 3 (instantaneous)',
                    'TVL loudness chan 4 (instantaneous)',
                    'TVL loudness chan 5 (instantaneous)',
                    'TVL loudness chan 6 (instantaneous)',
                    'TVL loudness chan 7 (instantaneous)',
                    'TVL loudness chan 8 (instantaneous)',
                    'TVL loudness chan 9 (instantaneous)',
                ],
                color=gradient_color_dict([
                    'TVL loudness chan 1 (instantaneous)',
                    'TVL loudness chan 2 (instantaneous)',
                    'TVL loudness chan 3 (instantaneous)',
                    'TVL loudness chan 4 (instantaneous)',
                    'TVL loudness chan 5 (instantaneous)',
                    'TVL loudness chan 6 (instantaneous)',
                    'TVL loudness chan 7 (instantaneous)',
                    'TVL loudness chan 8 (instantaneous)',
                    'TVL loudness chan 9 (instantaneous)',
                    ], start_color="blue", stop_color="purple"),
                minimap_config=config,
                minimap_view="lateral",
                minimap_surface="inflated",
                )

Notes

• Note that expression legends may get cut off (as in the above), but this bug exists on main prior to this PR: Expression plot legends can spill off the end of the image #215
• It flashes up a few images while the plot is being generated. I can't see a way around this.

[caiw]

@neukym I'm beginning by working on plotting hexel locations: sensor topomaps can come later.

I've got the general function written, I think, but I'm having a problem getting mne to actually plot the image.

My approach is to construct a fake stc object which has one timestep, and whose values are integers which reference the correct colour in a segmented colourmap (so that the dots on the brain have the same colours as the dots on the expression plot.

To do this I'm using

stc = SourceEstimate(...)
minimap_axis.imshow(stc.plot(hemi="split", colormap=colormap).to_image())

(see here)

However mne is giving me an error:

KeyError: 'Key "SUBJECTS_DIR" not found in the environment or in the the mne-python config file
(/Users/cai/.mne/mne-python.json). Try either os.environ["SUBJECTS_DIR"] = VALUE for a
temporary solution, or mne.utils.set_config("SUBJECTS_DIR", VALUE, set_env=True) for a
permanent one. You can also set the environment variable before running python.'

Does mne really need actual files on disk to plot data on a brain picture? If so, is there a different package we could use?

[neukym]

Ah, darn... Yes, mne assumes (for some of its functions involving meshes) that you have freesurfer installed and the SUBJECTS_DIR directory (where freesurfer outputs its meshes, including the fsaverage one) is set so it knows where to find these meshes.

perhaps we can set it with os.environ["SUBJECTS_DIR"] = config['dataset_directory_name'] / config['mri_structurals_directory']`?

[neukym]

I got the graph to show up (for a split second, before a runtime error). You can see that it is trying to give various interactive dialogue options which we don't need. But a good start...

[neukym]

I got the above plot by hard-coding the location for the structural data and the participant name - but my commit does a rough job of correcting for this and you might have to do some more changes before it will work for you.

[neukym]

No problem - I'll fix this separately over the weekend.

[neukym]

This looks good - can we chat about it next week though as I want to check some things with you.

[caiw]

Current bug in pycharm where when not plotting in tools window, the plot isn't created. When plotting in the tools window, it works.

[caiw]

Also works when stepping through

[caiw]

Works when debugging!!??

[caiw]

Fixed.
pyplot.show() is naturally blocking; we can individually close the 3d plots to unblock it.

[neukym]

Looks good. Merging.