fmriprep-docker ---------- ---------- fmriprep-docker is a light weight python wrapper for the BIDS app, fmriprep, allowing fmriprep to be run from within a Docker environment. It requires Docker and python to be installed, as well as an active internet connection. Additionally, as fmriprep is a BIDS app, the input image files must have BIDS-format filenames and be stored in a BIDS-format directory that passes the BIDS validator. @[toc] ## General Installation Instructions 1. Follow the instructions [here][1] for installing Docker on your system. 2. Ensure that you have python (python 3.7 preferred) installed on your system. If not, probably easiest to install the python 3.7 [Anaconda Distribution][3]. 3. You will need a Freesurfer license file, even if you are planning on running the fmriprep pipeline without Freesurfer. A Freesurfer license can be obtained by registering for free at the following website: https://surfer.nmr.mgh.harvard.edu/registration.html **N.B.**: If Freesurfer does not include a license.txt file as an attachment to the email with your Freesurfer license information, copy the four lines beginning with your email address into an empty Matlab .m file and save out as a .txt file. Do NOT use any other text editor to save out these four lines. ---------- ### Mac OS 1. Launch Docker. (It may take a few minutes for it to start up.) 2. Open the Preferences menu for Docker and make sure that all of the needed parent directories are listed under the File Sharing tab. If not, add the needed parent directories. Click Apply and Restart to adopt the changes.  3. From the Disk tab, you can change the amount of storage allocated to the Docker Engine.  4. Still in the Preferences menu, use the Advanced tab to set the parameters for the Docker Engine. Again click on Apply and Restart to adopt the changes.**N.B.: The Docker Engine is configured to access 2GM RAM by default. It is recommended to assign at least 8GB of RAM to the Docker Engine.**  5. Open a Terminal window and follow the fmriprep [documentation][4] for installing the fmriprep-docker function. From your home directory, type the following at the Terminal command prompt: ``` pip install --user --upgrade fmriprep-docker ``` 6. Make note of the directory in which fmriprep-docker is installed. For the above command with ```--user``` specified, the location should be: ``` /Users/<username>/.local/bin ``` 7. Make sure that the fmriprep-docker directory is in your PATH. In your .bashrc file (```~/.bashrc```), add the following lines to add the fmriprep-docker path to PATH and create an alias for the fmriprep-docker command: ``` export PATH=$PATH:/Users/<username>/.local/bin alias fmriprep-docker='/Users/<username>/.local/bin/fmriprep-docker' ``` 8. Save out the changes to .bashrc, and from the Terminal command prompt type the following from your home directory (```~/```) to have the new changes take effect. **N.B.: When launching Docker and Terminal each time, you may need to re-execute this command for Docker to find fmriprep-docker again.** ``` source .bashrc ``` 9. With Docker running, from a Terminal command prompt, type: ``` fmriprep-docker -h ``` to check the installation and get the usage statement. If prompted to install the latest fmriprep image, accept. **N.B.: Once an image of fmriprep has been installed, users should refrain (if prompted) from installing the latest version to ensure that all data are being run through the same version of the fmriprep pipeline.** 10. At this point fmriprep-docker should be ready to use. ---------- ### Windows 1. Launch Docker. 2. If you get the following pop-up error message when launching Docker, you most likely do not have [Hyper-V][5] or virtualization enabled on your system.  3. You can check whether virtualization is enabled from the Performance tab of the Task Manager menu.  4. First follow the Visualization section on the [Docker for Windows troubleshooting guide][6] for enabling (or installing if necessary) Hyper-V. During this process, make sure that the following Windows Features are enabled: Containers, Hyper-V, and Virtualization.  5. In order to enable virtualization, access PC BIOS. The following [website][7] outlines several ways of accessing the PC BIOS menu depending on Windows version and PC brand. (Scroll down part way to: *2. How can I enable virtualization, if available but disabled on my PC?*) Users located in BMI/WIRB should contact Haitao Yang (htyang AT uwo DOT ca) if they have any questions about and/or experience any difficulties enabling virtualization. 6. Once Hyper-V and Virtualization have been enabled, the Docker Desktop for Windows menu can be opened by right-clicking on the Docker icon in the Notifications area or System tray.  7. Select Settings to access the settings for the Docker Engine. 8. Under Shared Drives, it is vital that you make sure that all relevant local drives are shared with Docker. **N.B.: Per the Docker for Windows [website][8], shared drives are tied to specific Windows user credentials. So a user logged into another account on the same computer will also need to complete this step.**  9. Under Advanced, set at least 8GB RAM (Memory) for the Docker Engine (See note above in Step 4 of Mac OS instructions).  10. With Docker running, open a Anaconda Prompt window and type the following to install fmriprep-docker: ``` pip install --user --upgrade fmriprep-docker ``` 11. Once fmriprep-docker is succesfully installed, make note of the installation directory (listed in the yellow text following the installation log). It will most likely be: ``` C:\Users\<username>\AppData\Roaming\Python\Python37\Scripts ```  12. In order to be able to run fmriprep-docker, its location needs to be added to the Windows Environmental Path variable. The following [website][9] includes instructions for editing the Windows Environmental Path variable. In this case, you will want to replace the anaconda path location with the path location of fmriprep-docker. (Scroll down to: *Add Anaconda to Path (Optional)*.) 13. **For older versions of Windows:** Open the Windows Environmental Variables menu, select Path from the User variables, and click Edit. From there, append the existing list of paths with the location of ```fmriprep-docker.exe```, using a semi-colon (```;```) to separate the fmriprep-docker path from the previous path in the list. Quit and restart Anaconda Prompt.  **For newer versions of Windows:** Open the Windows Environmental Variables menu, select Path from the User variables, and click Edit. Click 'New' to create a new entry to the Path variable and enter the fmriprep-docker path in the blank. Quit and restart Anaconda Prompt.  14. Back in the Anaconda Prompt window, you can test whether ```fmriprep-docker.exe``` has been successfully added to your Path variable by typing the following command to get the usage statement: ``` fmriprep-docker -h ``` 15. If the usage statement appears and this is a new installation of fmriprep-docker, go ahead and type 'Y' to accept the installation of the latest fmriprep container. If the you still get the message about fmriprep-docker not being in your PATH, restart your computer to force the changes you made in step 12 to take affect. Then try again with steps 13 and 14. **N.B.: As with the Mac OS installation, once you have begun to preprocess data using fmriprep, you do NOT want to update the fmriprep container unless you intend to re-preprocess all of the data for a given study with the new version of the container.** ---------- ## Examples of common fmriprep-docker usage statements Below are several examples of usage statements for fmriprep-docker covering some of the more common options. This list is by no means exhaustive, and users are encouraged to consult the fmriprep [usage documentation][10] for information on all options. **N.B.: When specifying an output (or working) directory for fmriprep-docker to write to, make sure the output (or working) directory is not located inside the BIDS directory.** ### Basic usage The following will run the basic fmriprep pipeline including Freesurfer. No intermediate output will be saved. The pipeline will be run on **all** subjects in ```<bidsDir>```. ``` fmriprep-docker <bidsDir> <outputDir> participant --fs-license-file <full path to Freesurfer license.txt> ``` On a Mac, the above command will look something like this: ``` fmriprep-docker /Users/JaneDoe/Documents/fMRIStudy/bids /Users/JaneDoe/Documents/fMRIStudy/fmriprep_output participant --fs-license-file /Users/JaneDoe/Documents/freesurfer/license.txt ``` On a Windows machine, the above command will look something like this: ``` fmriprep-docker C:\Users\JaneDoe\Documents\fMRIStudy\bids C:\Users\JaneDoe\Documents\fMRIStudy\fmriprep_output participant --fs-license-file C:\Users\JaneDoe\Documents\freesurfer\license.txt ``` ### Single subject To run fmriprep on a specific subject, rather than all subjects contained in a BIDS directory, you can specify a single subject ID (omitting the ```sub-``` prefix). ``` fmriprep-docker <bidsDir> <outputDir> participant --fs-license-file <full path to Freesurfer license.txt> --participant-label <bidsSubjectID> ``` **N.B.: The fmriprep-docker people recommend running the docker version of the fmriprep pipeline on a single subject at a time. If you are based at Western and need a more efficient way to run fmriprep (e.g., submitting multiple subjects at a time), please see the documentation for getting started with Compute Canada [here][11] and the documentation for running BIDS apps on Compute Canada [here][12].** ### Omitting Freesurfer If processing time or memory constraints may be an issue, Freesurfer can be omitted. ``` fmriprep-docker <bidsDir> <outputDir> participant --fs-license-file <full path to Freesurfer license.txt> --fs-no-reconall ``` ### Saving out intermediate output To save the intermediate output, specify the location of a working directory. Using this option requires more disk storage. This option, though, can save time if fmriprep exits with an error, as re-executing the exact same fmriprep-docker command again will skip over any modules that have already been run without error. (The working directory can be safely deleted after successful completion of fmriprep pipeline on all subjects in a given BIDS directory.) ``` fmriprep-docker <bidsDir> <outputDir> participant --fs-license-file <full path to Freesurfer license.txt> -w <workingDir> ``` ### General procedure for including options The fmriprep-docker command will take multiple options. Options can be specified in any order **but must be specified after the mandatory inputs of** ```<bidsDir>```, ```<outputDir>```, ```participant```. For example, to run fmriprep on a single subject, omitting Freesurfer, the following commmand can be used: ``` fmriprep-docker <bidsDir> <outputDir> participant --fs-license-file <full path to Freesurfer license.txt> --participant-label <bidsSubjectID> --fs-no-reconall ``` ---------- ## Additional Resources 1. Stanford Center for Reproducible Neuroscience fmriprep-docker [tutorial][13] 2. Help forum: https://neurostars.org/ ---------- ## Appendix ### Unix commands and Windows CMD equivalents |Description |Unix Command | CMD Command | |------------|-------------|-------------| |Current directory | . | . | |One directory up from current directory | .. | ..| |Print current directory | pwd | cd | |List directory contents, list details, list hidden items |ls, ls -l, ls -a | dir, dir /N, dir /H | |Clear terminal screen |clear | cls | |Remove file, directory |rm <fileName>, rm -r <dirName> | erase <fileName>, rmdir <dirName>| |Copy file, directory |cp <fileName>, cp -r <dirName>| copy <filename> or <dirName> | |Move file, directory |mv | move | |Rename file, directory |mv | rename | |Display text file contents |cat | type | |Change directory |cd <dirPath> | cd <dirPath> | |Make new directory |mkdir <dirName> | md <dirName> | |Temporarily save path |pushd | pushd | |Return to path saved in pushd |popd | popd | |Find path of command | which <commandName> | where <commandName> | |Display full path of file | realpath <dirName> or <fileName> | dir /S /B <dirName> or <fileName> | |Make symbolic link of directory | ln -s <dirPath> <linkPath> | mklink /d <dirPath> <linkPath> Adapted from [here][14]. ## Acknowledgements A big thank you to Lien Peters, Aysha Motala, and Cassie Lowe for their help in correcting and clarifying the Windows instructions and usage statements. [1]: https://osf.io/k89fh/wiki/Docker [2]: https://files.osf.io/v1/resources/k89fh/providers/osfstorage/5d3f6eba532261001cda3e68?mode=render [3]: https://www.anaconda.com/distribution/ [4]: https://fmriprep.readthedocs.io/en/stable/installation.html [5]: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-technology-overview [6]: https://docs.docker.com/docker-for-windows/troubleshoot/ [7]: https://support.bluestacks.com/hc/en-us/articles/115003910391-How-can-I-enable-virtualization-VT-on-my-PC- [8]: https://docs.docker.com/docker-for-windows/ [9]: https://www.datacamp.com/community/tutorials/installing-anaconda-windows [10]: https://fmriprep.readthedocs.io/en/stable/usage.html [11]: https://osf.io/k89fh/wiki/Compute%20Canada/ [12]: https://osf.io/k89fh/wiki/neuroglia-helpers/ [13]: http://reproducibility.stanford.edu/fmriprep-tutorial-running-the-docker-image/ [14]: https://docs.microsoft.com/en-us/powershell/scripting/samples/appendix-1---compatibility-aliases?view=powershell-6