mne-tools / mne-tools/mne-python
ENH: Support dockerized FreeSurfer installations
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 3.5k
- Forks
- 1.6k
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 100
Description
Describe the problem
The vast majority of scientists I work with use Windows computers. However, parts of MNE's source estimation stack rely on FreeSurfer, which is only available for Linux and macOS. This issue is preventing a number of my colleagues from switching to MNE-Python.
Describe your solution
Currently, FreeSurfer operations are carried out by concatenating a list of arguments and passing these to the respective FreeSurfer command line tool. This, obviously, will work only if FreeSurfer has been installed, so Windows is excluded per se.
To extend support to the Windows platform, I suggest to add support for containerized FreeSurfer installations, specifically for Docker images: Instead of invoking a FreeSurfer subprocess on the host machine, MNE-Python would execute the operation inside a Docker container. For example, instead of calling mri_watershed -T1 -useSRAS ... we'd call something along the lines of docker run -it -d mne/FreeSurfer mri_watershed -T1 -useSRAS ... Of course, we'd also need to map host directories to the appropriate places inside the container.
The user, then, would only need to acquire a FreeSurfer license file and install Docker; the rest could be done automatically. Incidentally, this would work on all platforms.
To allow switching between the local installation and the container, a kwarg freesurfer_backend could be added to the relevant Python function signatures: freesurfer_backend='native' (or 'local') uses the host installation, and freesurfer_backend='docker' uses the Docker container (and first pulls the image, if necessary). Might even be worthwhile to allow for different Docker images, e.g., docker_image='mne/FreeSurfer-extended:latest'
There is already a FreeSurfer image on Docker Hub which could serve as a base, and inspiration could be drawn from the FreeSurfer BIDS App.
Describe possible alternatives
The FreeSurfer BIDS App already dockerizes FreeSurfer for processing of BIDS-compliant data; however, currently it's a "stand-alone" thingy without integration into MNE-Python.
If the idea of a dockerized FreeSurfer is generally liked, it might be worthwhile to discuss whether adding a new, thin abstraction layer between MNE-Python and FreeSurfer could be of advantage in case we'd like to add support for additional FreeSurfer backends later on. For example, on Windows 10, Windows Subsystem for Linux (WSL) seems like an almost natural choice.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading mne/bem.py lines 1122-1150, where FreeSurfer arguments are assembled and passed to command-line tools. Review the FreeSurfer Docker image and BIDS App for relevant container behavior. Done means MNE-Python can support a selectable native or Docker FreeSurfer backend with host directories and licensing handled as described.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, python
- Domain
- devops, operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100