Skip to content

Preprocessing

Executing fMRIPrep

Because fMRIPrep creates a single anatomical reference for all sessions, we generate such reference first by setting the --anat-only flag. If that fMRIPrep execution finishes successfully, the anatomical processing outcomes will be stored in the output folder. We will then run one fMRIPrep process for each dataset's session, which is the recommended way for datasets with a large number of sessions (e.g., more than six sessions). We avert that session-wise fMRIPrep's processes run into race conditions by pre-computing the anatomical reference.

  • Submit the anatomical workflow:

    Launch each session through fMRIPrep in parallel
    cd code/fmriprep
    bash ss-fmriprep-anatonly.sh
    

    The sbatch file to run fMRIPrep with --anat-only
    #!/bin/bash
    # Copyright 2023 The Axon Lab <theaxonlab@gmail.com> 
    # 
    # Licensed under the Apache License, Version 2.0 (the "License"); 
    # you may not use this file except in compliance with the License. 
    # You may obtain a copy of the License at 
    # 
    #     http://www.apache.org/licenses/LICENSE-2.0 
    # 
    # Unless required by applicable law or agreed to in writing, software 
    # distributed under the License is distributed on an "AS IS" BASIS, 
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
    # See the License for the specific language governing permissions and 
    # limitations under the License. 
    # 
    # We support and encourage derived works from this project, please read 
    # about our expectations at 
    # 
    #     https://www.nipreps.org/community/licensing/ 
    #
    # STATEMENT OF CHANGES: This file is derived from work of the Nipreps
    # developers and has been adapted to run smoothly on our particular 
    # dataset.
    #
    # ORIGINAL WORK'S ATTRIBUTION NOTICE:
    #
    #     Copyright 2021 The NiPreps Developers <nipreps@gmail.com>
    #
    #     Licensed under the Apache License, Version 2.0 (the "License");
    #     you may not use this file except in compliance with the License.
    #     You may obtain a copy of the License at
    #
    #         http://www.apache.org/licenses/LICENSE-2.0
    #
    #     Unless required by applicable law or agreed to in writing, software
    #     distributed under the License is distributed on an "AS IS" BASIS,
    #     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    #     See the License for the specific language governing permissions and
    #     limitations under the License.
    
    #SBATCH --partition=russpold
    #SBATCH --mem=30GB
    #SBATCH --cpus-per-task=16
    #SBATCH --time=20:00:00
    #SBATCH --job-name=fmriprep
    #SBATCH --error="slurm-%A.err"
    
    # Run only the anatomical workflow of fMRIPrep
    
    DATADIR="/oak/stanford/groups/russpold/inprocess/cprovins/hcph-pilot/"
    SUB="sub-001"
    STUDY=`basename $DATADIR`
    
    echo "Processing the anatomical workflow on subject: $SUB"
    
    IMG="/oak/stanford/groups/russpold/users/cprovins/singularity_images/fmriprep-23.1.4.simg"
    
    WORKDIR="${L_SCRATCH}/fmriprep/${STUDY}/"
    mkdir -p ${WORKDIR}
    OUTDIR="${DATADIR}/derivatives"
    mkdir -p $OUTDIR
    
    PATCHES=""
    
    BINDINGS="-B $DATADIR/inputs:/data:ro \
    -B ${WORKDIR}:/work \
    -B ${OUTDIR}:/out \
    -B $DATADIR/code/license.txt:/opt/freesurfer/license.txt \
    $PATCHES"
    
    FMRIPREP_CMD="/data /out/fmriprep-23.1.4 participant \
            -w /work \
            --bids-filter-file /work/filter_file_undistorted.json \
            --anat-only --skip_bids_validation \
            --nprocs 4 --mem 25G --omp-nthreads 16 -vv"
    
    #Create json file to filter undistorted anatomical scans
    echo '{"t1w": {"datatype": "anat", "acquisition": "undistorted", "suffix": "T1w"}}' > ${WORKDIR}/filter_file_undistorted.json
    
    SING_CMD="singularity run -e $BINDINGS $IMG $FMRIPREP_CMD"
    echo $SING_CMD
    $SING_CMD
    echo "Completed with return code: $?"
    
  • Once the anatomical workflow ran successfully, submit a job array with one scanning session each with the --bids-filter-file argument selecting the corresponding session, and point the --fs-subjects-dir argument to the folder where FreeSurfer results were stored.

    Launch each session through fMRIPrep in parallel
    cd code/fmriprep
    bash ss-fmriprep.sh
    

    The sbatch file to run fMRIPrep session-wise
    #!/bin/bash
    # Copyright 2023 The Axon Lab <theaxonlab@gmail.com> 
    # 
    # Licensed under the Apache License, Version 2.0 (the "License"); 
    # you may not use this file except in compliance with the License. 
    # You may obtain a copy of the License at 
    # 
    #     http://www.apache.org/licenses/LICENSE-2.0 
    # 
    # Unless required by applicable law or agreed to in writing, software 
    # distributed under the License is distributed on an "AS IS" BASIS, 
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
    # See the License for the specific language governing permissions and 
    # limitations under the License. 
    # 
    # We support and encourage derived works from this project, please read 
    # about our expectations at 
    # 
    #     https://www.nipreps.org/community/licensing/ 
    #
    # STATEMENT OF CHANGES: This file is derived from work of the Nipreps
    # developers and has been adapted to run smoothly on our particular 
    # dataset.
    #
    # ORIGINAL WORK'S ATTRIBUTION NOTICE:
    #
    #     Copyright 2021 The NiPreps Developers <nipreps@gmail.com>
    #
    #     Licensed under the Apache License, Version 2.0 (the "License");
    #     you may not use this file except in compliance with the License.
    #     You may obtain a copy of the License at
    #
    #         http://www.apache.org/licenses/LICENSE-2.0
    #
    #     Unless required by applicable law or agreed to in writing, software
    #     distributed under the License is distributed on an "AS IS" BASIS,
    #     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    #     See the License for the specific language governing permissions and
    #     limitations under the License.
    
    #SBATCH --partition=russpold
    #SBATCH --mem=55GB
    #SBATCH --cpus-per-task=16
    #SBATCH --time=20:00:00
    #SBATCH --job-name=fmriprep
    #SBATCH --error="slurm-%A_%a.err"
    
    # Submit a Single Session through fMRIPrep
    
    ARGS=($@)
    DATADIR=$1
    STUDY=`basename $DATADIR`
    
    if [[ -n $SLURM_ARRAY_TASK_ID ]]; then
      SES=${ARGS[`expr ${SLURM_ARRAY_TASK_ID} + 1`]}
    else
      SES=$2
    fi
    
    echo "Processing: $SES"
    
    IMG="/oak/stanford/groups/russpold/users/cprovins/singularity_images/fmriprep-23.1.4.simg"
    
    WORKDIR="${L_SCRATCH}/fmriprep/${STUDY}/${SES}"
    mkdir -p ${WORKDIR}
    OUTDIR="${DATADIR}/derivatives"
    mkdir -p $OUTDIR
    
    PATCHES=""
    
    BINDINGS="-B $DATADIR/inputs:/data:ro \
    -B ${WORKDIR}:/work \
    -B ${OUTDIR}:/out \
    -B $DATADIR/code/license.txt:/opt/freesurfer/license.txt \
    -B ${HOME}/.cache/templateflow/tpl-MNI152NLin6Asym/:${HOME}/.cache/templateflow/tpl-MNI152NLin6Asym/
    $PATCHES"
    
    FMRIPREP_CMD="/data /out/fmriprep-23.1.4 participant \
      -w /work \
      --bids-filter-file /work/filter_file_$SES.json \
      --skip_bids_validation \
      --fs-subjects-dir /out/fmriprep-23.1.4/sourcedata/freesurfer \
      --anat-derivatives /out/fmriprep-23.1.4 \
      --nprocs 4 --mem 45G --omp-nthreads 8 -vv"
    
    #Create json file to filter one session only
    echo '{"bold": {"datatype": "func", "session": "'${SES#*-}'", "suffix": "bold"}}' > ${WORKDIR}/filter_file_${SES}.json
    
    SING_CMD="singularity run -e $BINDINGS $IMG $FMRIPREP_CMD"
    echo $SING_CMD
    $SING_CMD
    echo "Completed with return code: $?"
    
Not all fMRIPrep derivatives were generated

If some derivatives are missing, it is a sign that fMRIPrep encountered an error.

  • Check the "Errors" section of the visual report.
  • Check the log/ folder corresponding to the fMRIPrep run, carefully ensuring no errors were missed out on the reports.
  • Search for associated keywords in the issues on fMRIPrep's GitHub repository if the solution remains unclear after the first assessment; it is likely someone else experienced the same problem before you and reported it. The solution might be documented in the issue. Don't forget to check closed issues!
  • Search for the issue on NeuroStars, if the solution remains unclear.
  • If the solution remains elusive, open an issue in fMRIPrep's GitHub repository to report the problem. Your description of the problem needs to be as complete and detailed as possible to help the maintainers identify the problem efficiently.
  • Re-run fMRIPrep on that particular subject and session after implementing a solution.

If the error remains despite all efforts, the session MAY be excluded

Visualizing fMRIPrep's individual reports

Following our protocols1, the quality of unprocessed images MUST be assessed before and after preprocessing to verify it did not go awry.

  • Open each fMRIPrep report on a current Web Browser (Google Chrome is preferred).
  • Visualize the first section entitled Summary and apply the exclusion criteria.

    Running through the visual report does not have to be executed in a fixed order

    While we describe the run through the report as linear, often inspecting other reportlets can help make a decision about the exclusion criteria related to the reportlet at hand. As such, we encourage you to jump back and forth between visualizations as much as needed.

Anatomical preprocessing assessment

  • Assess the "Anatomical conformation" section and apply the exclusion criteria.
  • Assess the mosaic showing the calculated brain mask and brain tissue segmentation, and apply the exclusion criteria.
  • Visualize the spatial normalization flickering mosaic, and apply the exclusion criteria. Flickering between the subject and the template space is active while hovering your mouse on the mosaic area.
  • Assess the surface reconstruction mosaic, and apply the exclusion criteria.

Assessment of fMRI Preprocessing

  • Scrutinize the textual summary and apply the exclusion criteria.
  • Visualize the T2* map mosaic, and apply the exclusion criteria.
  • Check the T2* gray-matter intensity histogram, and apply the exclusion criteria.
  • Visualize the co-registration flickering mosaic, apply the exclusion criteria. Flickering between T1w and BOLD images is active while hovering your mouse on the mosaic area.
  • Visualize the next mosaic displaying regions of interest (ROIs) used to estimate the nuisance regressors, and apply the exclusion criteria.
  • Visualize the carpet plot and nuisance signals panel, and apply the exclusion criteria.
  • Visualize the confound correlation heatmap and use it to choose the regressors you will include in the nuisance regression model.
  • Verify that no errors are reported within the "Errors" section.

    If errors or quality issues are encountered, find the issue corresponding to that session in the dataset's repository and report a comprehensive description of the problems. In case of fMRIPrep failure, follow the procedure described above in "Not all fMRIPrep derivatives were generated".

Immediately report images deemed exclude, as an issue in the dataset's repository