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: $?"
  

How to proceed if some fMRIPrep derivatives are missing

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

Anatomical preprocessing assessment

• Open the fMRIPrep anatomical report on a Web Browser.
• Assess the "Summary" section and apply the QA/QC criteria.
• Assess the "Anatomical conformation" section and apply the QA/QC criteria.
• Assess the mosaic showing the calculated brain mask and brain tissue segmentation, and apply the QA/QC criteria.
• Visualize the spatial normalization flickering mosaic, and apply the QA/QC criteria. Flickering between the subject and the template space is active while your mouse pointer hovers the mosaic area.
• Assess the surface reconstruction mosaic, and apply the exclusion criteria.
• Visualize the first section entitled Summary and apply the QA/QC criteria.

Assessment of fMRI Preprocessing

• Open each fMRIPrep functional report on a Web Browser.

• Go through the section of each fMRI run and proceed as follows:

  IMPORTANT — QCT and BHT are assessed first as proxies for the RSfMRI run's quality.

  We employ the QCT (mainly) and the BHT as proxies for the quality of the RSfMRI run. Screening the reports in the prescribed order (QCT — BHT — RSfMRI) helps identify issues in the QCT and BHT that may anticipate problems in the RSfMRI.

  • Assess the textual summary and apply the corresponding QA/QC criteria.
  • Visualize the T₂^☆ map mosaic, and apply the QA/QC criteria.
  • Check the T₂^☆ gray-matter intensity histogram, and apply the QA/QC criteria.
  • Visualize the co-registration flickering mosaic, apply the QA/QC 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 QA/QC criteria.
  • Visualize the carpet plot and nuisance signals panel,
    • Apply the exclusion criteria
    • If you are visualizing the carpet plot corresponding to a RSfMRI run, apply additional QA criteria.
  • Visualize the confound correlation heatmap and use it to choose the regressors you will include in the nuisance regression model.
  • Proceed as indicated above if errors are reported within the "Errors" section.
  • Continue with the next fMRI run section