ENH: Add initial FastSurfer interface (WIP)

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "esbonio.server.enabled": false
+}

.zenodo.json

@@ -47,6 +47,11 @@
       "orcid": "0000-0002-5312-6729",
       "type": "Researcher"
     },
+    {
+      "affiliation": "Beckman Institute for Advanced Science & Technology, University of Illinois at Urbana-Champaign, IL, USA",
+      "name": "Camacho, Paul B.",
+      "orcid": "0000-0001-9048-7307",
+    },
     {
       "affiliation": "Department of Pediatrics, University of Minnesota, MN, USA",
       "name": "Feczko, Eric",

Dockerfile

@@ -33,6 +33,12 @@ RUN python -m build /src/fmriprep
 FROM ubuntu:jammy-20221130
 
 # Prepare environment
+ENV DEBIAN_FRONTEND="noninteractive"
+ENV LANG=C.UTF-8
+ARG PYTHON_VERSION=3.8
+ARG CONDA_FILE=Miniconda3-py38_4.11.0-Linux-x86_64.sh
+ENV DEBIAN_FRONTEND=noninteractive
+
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
                     apt-utils \
@@ -41,6 +47,9 @@ RUN apt-get update && \
                     bzip2 \
                     ca-certificates \
                     curl \
+                    wget \
+                    upx \
+                    file \
                     git \
                     gnupg \
                     libtool \
@@ -51,15 +60,45 @@ RUN apt-get update && \
                     xvfb && \
     apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
-ENV DEBIAN_FRONTEND="noninteractive" \
-    LANG="en_US.UTF-8" \
-    LC_ALL="en_US.UTF-8"
+# git clone stable branch of FastSurfer
+RUN cd /opt && mkdir /fastsurfer \
+    && git clone -b v2.0.4 https://github.com/Deep-MI/FastSurfer.git \
+    && cp /opt/FastSurfer/fastsurfer_env_gpu.yml /fastsurfer/fastsurfer_env_gpu.yml 
+
+# Copy fastsurfer from git folder
+RUN cp -R /opt/FastSurfer/* /fastsurfer/ && rm -rf /opt/FastSurfer
+
+# Install conda
+RUN wget --no-check-certificate -qO ~/miniconda.sh https://repo.continuum.io/miniconda/$CONDA_FILE  && \
+     chmod +x ~/miniconda.sh && \
+     ~/miniconda.sh -b -p /opt/conda && \
+     rm ~/miniconda.sh 
 
 # Installing freesurfer
 COPY docker/files/freesurfer7.3.2-exclude.txt /usr/local/etc/freesurfer7.3.2-exclude.txt
 RUN curl -sSL https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/7.3.2/freesurfer-linux-ubuntu22_amd64-7.3.2.tar.gz \
      | tar zxv --no-same-owner -C /opt --exclude-from=/usr/local/etc/freesurfer7.3.2-exclude.txt
 
+# Install required packages for freesurfer to run
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      tcsh \
+      time \
+      bc \
+      gawk \
+      libgomp1 && \
+    apt clean && \
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* 
+
+# Add FreeSurfer Environment variables
+ENV OS=Linux \
+    FS_OVERRIDE=0 \
+    FIX_VERTEX_AREA= \
+    SUBJECTS_DIR=/opt/freesurfer/subjects \
+    FSF_OUTPUT_FORMAT=nii.gz \
+    FREESURFER_HOME=/opt/freesurfer \
+    PYTHONUNBUFFERED=0 \
+    PATH=/opt/freesurfer/bin:$PATH
+
 # Simulate SetUpFreeSurfer.sh
 ENV FSL_DIR="/opt/fsl-6.0.5.1" \
     OS="Linux" \
@@ -89,7 +128,6 @@ RUN apt-get update -qq \
            libgl1-mesa-dev \
            libgl1-mesa-dri \
            libglu1-mesa-dev \
-           libgomp1 \
            libice6 \
            libxcursor1 \
            libxft2 \
@@ -98,6 +136,7 @@ RUN apt-get update -qq \
            libxrender1 \
            libxt6 \
            sudo \
+           curl \
            wget \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/* \
@@ -167,21 +206,16 @@ RUN GNUPGHOME=/tmp gpg --keyserver hkps://keyserver.ubuntu.com --no-default-keyr
 # AFNI latest (neurodocker build)
 RUN apt-get update -qq \
     && apt-get install -y -q --no-install-recommends \
-           apt-utils \
            ed \
            gsl-bin \
            libglib2.0-0 \
-           libglu1-mesa-dev \
            libglw1-mesa \
-           libgomp1 \
            libjpeg62 \
            libpng12-0 \
            libxm4 \
            libxp6 \
            netpbm \
-           tcsh \
            xfonts-base \
-           xvfb \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/* \
     && curl -sSL --retry 5 -o /tmp/multiarch.deb http://archive.ubuntu.com/ubuntu/pool/main/g/glibc/multiarch-support_2.27-3ubuntu1.5_amd64.deb \
@@ -281,10 +315,16 @@ RUN /opt/conda/bin/python fetch_templates.py && \
     find $HOME/.cache/templateflow -type d -exec chmod go=u {} + && \
     find $HOME/.cache/templateflow -type f -exec chmod go=u {} +
 
+# Installing FastSurfer gpu dependencies
+RUN conda env update -n base --file /fastsurfer/fastsurfer_env_gpu.yml 
+
 # Installing sMRIPREP
 COPY --from=src /src/fmriprep/dist/*.whl .
 RUN /opt/conda/bin/python -m pip install --no-cache-dir $( ls *.whl )[all]
 
+# Installing nibabel version 4.0.2
+RUN /opt/conda/bin/python -m pip install --no-cache-dir nibabel==4.0.2
+
 RUN find $HOME -type d -exec chmod go=u {} + && \
     find $HOME -type f -exec chmod go=u {} + && \
     rm -rf $HOME/.npm $HOME/.conda $HOME/.empty
@@ -294,6 +334,12 @@ RUN find $HOME -type d -exec chmod go=u {} + && \
 ENV FREESURFER="/opt/freesurfer"
 
 ENV IS_DOCKER_8395080871=1
+ENV FASTSURFER_HOME=/fastsurfer
+ENV PATH="$PATH:/fastsurfer"
+
+# Download all remote network checkpoints already
+ENV PYTHONPATH=/fastsurfer:$PYTHONPATH
+RUN cd /fastsurfer ; python3 FastSurferCNN/download_checkpoints.py --all
 
 RUN ldconfig
 WORKDIR /tmp

docker/files/freesurfer7.3.2-exclude.txt

@@ -4,20 +4,10 @@ freesurfer/average/3T18yoSchwartzReactN32_as_orig.4dfp.img
 freesurfer/average/3T18yoSchwartzReactN32_as_orig.4dfp.img.rec
 freesurfer/average/3T18yoSchwartzReactN32_as_orig.4dfp.mat
 freesurfer/average/3T18yoSchwartzReactN32_as_orig.lst
-freesurfer/average/711-2B_as_mni_average_305.4dfp.hdr
-freesurfer/average/711-2B_as_mni_average_305.4dfp.ifh
-freesurfer/average/711-2B_as_mni_average_305.4dfp.img
-freesurfer/average/711-2B_as_mni_average_305.4dfp.img.rec
-freesurfer/average/711-2B_as_mni_average_305_mask.4dfp.hdr
-freesurfer/average/711-2B_as_mni_average_305_mask.4dfp.img.rec
-freesurfer/average/711-2C_as_mni_average_305.4dfp.hdr
-freesurfer/average/711-2C_as_mni_average_305.4dfp.img.rec
-freesurfer/average/711-2C_as_mni_average_305.4dfp.mat
 freesurfer/average/aseg+spmhead+vermis+pons.ixi.gca
 freesurfer/average/BrainstemSS
 freesurfer/average/Buckner_JNeurophysiol11_MNI152
 freesurfer/average/Choi_JNeurophysiol12_MNI152
-freesurfer/average/colortable_desikan_killiany.txt
 freesurfer/average/face.gca
 freesurfer/average/HippoSF
 freesurfer/average/label_scales.dat
@@ -41,7 +31,6 @@ freesurfer/average/mni305.cor.subfov1.mgz
 freesurfer/average/mni305.cor.subfov1.reg
 freesurfer/average/mni305.cor.subfov2.mgz
 freesurfer/average/mni305.cor.subfov2.reg
-freesurfer/average/mni305.mask.cor.mgz
 freesurfer/average/mni_average_305.4dfp.hdr
 freesurfer/average/mni_average_305.4dfp.ifh
 freesurfer/average/mni_average_305.4dfp.img
@@ -420,7 +409,6 @@ freesurfer/bin/mri_make_template
 freesurfer/bin/mri_map_cpdat
 freesurfer/bin/mri_maps2csd
 freesurfer/bin/mri_mark_temporal_lobe
-freesurfer/bin/mri_mc
 freesurfer/bin/mri_mcsim
 freesurfer/bin/mri_mergelabels
 freesurfer/bin/mri_mi
@@ -504,7 +492,6 @@ freesurfer/bin/mris_gradient
 freesurfer/bin/mris_hausdorff_dist
 freesurfer/bin/mris_image2vtk
 freesurfer/bin/mri_simulate_atrophy
-freesurfer/bin/mris_info
 freesurfer/bin/mris_init_global_tractography
 freesurfer/bin/mris_intensity_profile
 freesurfer/bin/mris_interpolate_warp
@@ -548,7 +535,6 @@ freesurfer/bin/mris_rf_label
 freesurfer/bin/mris_rf_train
 freesurfer/bin/mris_rotate
 freesurfer/bin/mris_sample_label
-freesurfer/bin/mris_sample_parc
 freesurfer/bin/mris_seg2annot
 freesurfer/bin/mris_segment
 freesurfer/bin/mris_segmentation_stats
@@ -749,11 +735,9 @@ freesurfer/bin/xhemireg
 freesurfer/bin/xhemi-tal
 freesurfer/bin/xsanatreg
 freesurfer/bin/zero_lt_4dfp
-freesurfer/DefectLUT.txt
 freesurfer/diffusion
 freesurfer/docs/xml
 freesurfer/FreeSurferEnv.csh
-freesurfer/FreeSurferEnv.sh
 freesurfer/fsfast
 freesurfer/lib/bem/ic0.tri
 freesurfer/lib/bem/ic1.tri
@@ -861,11 +845,8 @@ freesurfer/python/lib/python3.8/site-packages/torch
 freesurfer/python/lib/python3.8/site-packages/**/tests
 freesurfer/python/**/__pycache__
 freesurfer/python/share
-freesurfer/SegmentNoLUT.txt
 freesurfer/sessions
 freesurfer/SetUpFreeSurfer.csh
-freesurfer/SetUpFreeSurfer.sh
-freesurfer/Simple_surface_labels2009.txt
 freesurfer/sources.sh
 freesurfer/subjects/bert
 freesurfer/subjects/cvs_avg35

docs/installation.rst

@@ -148,5 +148,6 @@ the ``smriprep`` package:
 - ANTs_ (version 2.2.0 - NeuroDocker build)
 - AFNI_ (version Debian-16.2.07)
 - `C3D <https://sourceforge.net/projects/c3d/>`_ (version 1.0.0)
-- FreeSurfer_ (version 6.0.1)
+- FreeSurfer_ (version 7.2.0)
 - `bids-validator <https://github.com/bids-standard/bids-validator>`_ (version 1.1.0)
+- FastSurfer_ (version 2.0.1)

docs/requirements.txt

@@ -10,4 +10,4 @@ sphinx
 sphinx_rtd_theme
 sphinxcontrib-apidoc ~= 0.3.0
 templateflow
-networkx != 2.8.1
+networkx != 2.8.1

smriprep/cli/run.py

@@ -222,14 +222,21 @@ def get_parser():
         dest="hires",
         help="disable sub-millimeter (hires) reconstruction",
     )
-    g_surfs_xor = g_surfs.add_mutually_exclusive_group()
 
+    g_surfs_xor = g_surfs.add_mutually_exclusive_group()
     g_surfs_xor.add_argument(
         "--fs-no-reconall",
         action="store_false",
         dest="run_reconall",
         help="disable FreeSurfer surface preprocessing.",
     )
+    g_surfs_xor.add_argument(
+        "--fastsurfer",
+        action="store_true",
+        default=False,
+        dest="fastsurfer",
+        help="enable FastSurfer surface preprocessing.",
+    )
 
     g_other = parser.add_argument_group("Other options")
     g_other.add_argument(
@@ -394,6 +401,17 @@ def _warn_redirect(message, category, filename, lineno, file=None, line=None):
             from templateflow import api
             from niworkflows.utils.misc import _copy_any
 
+            dseg_tsv = str(api.get("fsaverage", suffix="dseg", extension=[".tsv"]))
+            _copy_any(
+                dseg_tsv, str(Path(output_dir) / "smriprep" / "desc-aseg_dseg.tsv")
+            )
+            _copy_any(
+                dseg_tsv, str(Path(output_dir) / "smriprep" / "desc-aparcaseg_dseg.tsv")
+            )
+        elif opts.fastsurfer:
+            from templateflow import api
+            from niworkflows.utils.misc import _copy_any
+
             dseg_tsv = str(api.get("fsaverage", suffix="dseg", extension=[".tsv"]))
             _copy_any(
                 dseg_tsv, str(Path(output_dir) / "smriprep" / "desc-aseg_dseg.tsv")
@@ -584,6 +602,7 @@ def build_workflow(opts, retval):
         freesurfer=opts.run_reconall,
         fs_subjects_dir=opts.fs_subjects_dir,
         hires=opts.hires,
+        fastsurfer=opts.fastsurfer,
         layout=layout,
         longitudinal=opts.longitudinal,
         low_mem=opts.low_mem,

smriprep/data/boilerplate.bib

@@ -74,6 +74,34 @@ @article{fs_reconall
     year = 1999
 }
 
+@article{fastsurfer,
+title = {FastSurfer - A fast and accurate deep learning based neuroimaging pipeline},
+journal = {NeuroImage},
+volume = {219},
+pages = {117012},
+year = {2020},
+issn = {1053-8119},
+doi = {https://doi.org/10.1016/j.neuroimage.2020.117012},
+url = {https://www.sciencedirect.com/science/article/pii/S1053811920304985},
+author = {Leonie Henschel and Sailesh Conjeti and Santiago Estrada and Kersten Diers and Bruce Fischl and Martin Reuter},
+keywords = {Freesurfer, Computational neuroimaging, Deep learning, Structural MRI, Artificial intelligence},
+abstract = {Traditional neuroimage analysis pipelines involve computationally intensive, time-consuming optimization steps, and thus, do not scale well to large cohort studies with thousands or tens of thousands of individuals. In this work we propose a fast and accurate deep learning based neuroimaging pipeline for the automated processing of structural human brain MRI scans, replicating FreeSurfer’s anatomical segmentation including surface reconstruction and cortical parcellation. To this end, we introduce an advanced deep learning architecture capable of whole-brain segmentation into 95 classes. The network architecture incorporates local and global competition via competitive dense blocks and competitive skip pathways, as well as multi-slice information aggregation that specifically tailor network performance towards accurate segmentation of both cortical and subcortical structures. Further, we perform fast cortical surface reconstruction and thickness analysis by introducing a spectral spherical embedding and by directly mapping the cortical labels from the image to the surface. This approach provides a full FreeSurfer alternative for volumetric analysis (in under 1 ​min) and surface-based thickness analysis (within only around 1 ​h runtime). For sustainability of this approach we perform extensive validation: we assert high segmentation accuracy on several unseen datasets, measure generalizability and demonstrate increased test-retest reliability, and high sensitivity to group differences in dementia.}
+}
+
+@article{fastsufrer_hires,
+title = {FastSurferVINN: Building resolution-independence into deep learning segmentation methods—A solution for HighRes brain MRI},
+journal = {NeuroImage},
+volume = {251},
+pages = {118933},
+year = {2022},
+issn = {1053-8119},
+doi = {https://doi.org/10.1016/j.neuroimage.2022.118933},
+url = {https://www.sciencedirect.com/science/article/pii/S1053811922000623},
+author = {Leonie Henschel and David Kügler and Martin Reuter},
+keywords = {Computational neuroimaging, Deep learning, Structural MRI, Artificial intelligence, High-resolution},
+abstract = {Leading neuroimaging studies have pushed 3T MRI acquisition resolutions below 1.0 mm for improved structure definition and morphometry. Yet, only few, time-intensive automated image analysis pipelines have been validated for high-resolution (HiRes) settings. Efficient deep learning approaches, on the other hand, rarely support more than one fixed resolution (usually 1.0 mm). Furthermore, the lack of a standard submillimeter resolution as well as limited availability of diverse HiRes data with sufficient coverage of scanner, age, diseases, or genetic variance poses additional, unsolved challenges for training HiRes networks. Incorporating resolution-independence into deep learning-based segmentation, i.e., the ability to segment images at their native resolution across a range of different voxel sizes, promises to overcome these challenges, yet no such approach currently exists. We now fill this gap by introducing a Voxel-size Independent Neural Network (VINN) for resolution-independent segmentation tasks and present FastSurferVINN, which (i) establishes and implements resolution-independence for deep learning as the first method simultaneously supporting 0.7–1.0 mm whole brain segmentation, (ii) significantly outperforms state-of-the-art methods across resolutions, and (iii) mitigates the data imbalance problem present in HiRes datasets. Overall, internal resolution-independence mutually benefits both HiRes and 1.0 mm MRI segmentation. With our rigorously validated FastSurferVINN we distribute a rapid tool for morphometric neuroimage analysis. The VINN architecture, furthermore, represents an efficient resolution-independent segmentation method for wider application.}
+}
+
 @article{mindboggle,
     author = {Klein, Arno and Ghosh, Satrajit S. and Bao, Forrest S. and Giard, Joachim and Häme, Yrjö and Stavsky, Eliezer and Lee, Noah and Rossa, Brian and Reuter, Martin and Neto, Elias Chaibub and Keshavan, Anisha},
     doi = {10.1371/journal.pcbi.1005350},