[ENH] Add Intracranial Electrode Contact Picking GUI (PyQt)

[alexrockhill]

The intracranial electrophysiology analysis pipeline could use a manual or semiautomated GUI to pick the locations of the electrode contacts based on a CT that has been aligned to the MR of that subject so that brain structures can be used to aid contact identification.

Basic Requirements:

• A CT and MR viewer that can scroll through slices like freeview
• A list selection to scroll through channel names from a raw object and associate them with a location on the CT in MR (surface RAS) space
• Ability to change the colormap to see color ranges within the CT more clearly as well as for the MR to make brain structures clearer
• An RAS locator to describe where you are in RAS space (helpful for use and this is also like freeview)

Advanced Requirements:

• A 3D viewer of the head with representations of "devices" or groups of contacts like an ECoG grid or sEEG electrode which more closely resembles surgical plans and so makes it easier to identify which device is which
• Speed of execution
• An automated algorithm to identify locations where electrode contacts are likely to be (likely using voxel_neighbors) to speed up location
• Contact coloring should be roughly orthogonal in ~24 dimensional space for sEEG patients with approximately that number of devices, also it looks nice if the device is colored the same

cc @larsoner

[alexrockhill]

Ok I think a reasonable first PR would be to load in the CT and the MR, resampling the CT to MR space if needed and taking in some channel names from a raw object and then allow the user to move around and mark electrodes and return the positions.

[larsoner]

Ok I think a reasonable first PR would be to load in the CT and the MR, resampling the CT to MR space if needed and taking in some channel names from a raw object and then allow the user to move around and mark electrodes and return the positions.

Let's not include resampling in the GUI. This is easily scripted and done once ahead of time. The GUI I think should load a T1 and the CT-resampled-to-T1-space.

Do you have an idea of the API? I'm thinking something like:

def electrode_location_gui(info, subject=None, ct='CT_aligned.mgz', mri='T1.mgz', subjects_dir=None)

thus the common use case would be to resample your CT and save it to SUBJECTS_DIR/SUBJECT/CT_aligned.mgz and then just do:

raw = mne.io.read_raw_fif(...)
mne.gui.electrode_location_gui(raw.info, 'whoever')

and under the hood if subject is provided, we use f'{subjects_dir}/{subject}/{ct}' and f'{subjects_dir}/{subject}/{t1}'.

[larsoner]

... and instead of returning the localized positions, it can just set info['chs']['loc'] directly. That way at the end if you do raw.save(...) that instance will have the correct locations.

People can always use raw.get_montage if they want to see the locations they set.

[agramfort]

what do you think about putting such a GUI while at it's infancy in a dedicated package where contributing guidelines are less strict. Should allow you to iterate faster and accept mistakes more easily?

[larsoner]

what do you think about putting such a GUI while at it's infancy in a dedicated package

The current state is actually already better than this -- it already lives in a dedicated package (img_pipe) that has been pretty well manually tested. So one important gain by / motivation for moving to MNE I think is following the full contributing guidelines (TDD included)

[alexrockhill]

Do you have an idea of the API? I'm thinking something like:

def electrode_location_gui(info, subject=None, ct='CT_aligned.mgz', mri='T1.mgz', subjects_dir=None)

Sounds good to me except where is subject coming from if it's None?

[larsoner]

subject=None is just provided in case people don't want to use FreeSurfer volumes at all. In other words, if people pass full paths to ct and mri then subject won't be used at all (so no need to provide it)

[larsoner]

... but I'm okay with not supporting that use case right away

[agramfort]

let's do a video call to discuss this ok?

[alexrockhill]

Hmmm, yeah for the elec_img PR I had it resample but then I thought it was leading down the wrong path with lots of coordinate transforms to do it in a coordinate frame other than surface RAS

[larsoner]

@agramfort sure, let us know your availability in the iEEG GSoC discord channel and we'll coordinate there