fPrep

Preprocessing of fMRI data.

fPrep combines preprocessing utilities from FSL and FreeSurfer with advanced image registration using ANTS. Commands are logged and most scripts support doing a "dry run" that prints the commands that would be run. This helps make it easier to understand how the preprocessing works. Scripts are modular, separating out individual steps for easier modification.

The fPrep pipeline supports the following preprocessing steps:

• Conversion of source files from DICOM to NIfTI format.
• Basic preprocessing of functional data, including motion correction and quality assurance.
• Basic preprocessing of anatomical data, including surface reconstruction using FreeSurfer.
• Unwarping and registration of functional data.

Installation on TACC resources

On TACC clusters (e.g., Lonestar 6), use the module system to load dependencies. Version numbers of dependencies list below are what have been previously tested. Newer versions will generally also work, though look at the release notes for each package to be sure.

module use /work/03206/mortonne/software/modules
module load fsl/5.0.11  # earlier versions do not support Python 3
module load ants/2.1.0
module load matlab
module load freesurfer/6.0.0  # 5.3 will likely also work
module load fprepcore/1.0.0  # utilities needed for the pipeline
module load python3/3.9.7  # most versions of Python 3 should work

Set up a Python 3 environment to run the scripts (this only has to be done once):

python3 -m venv $WORK/fprep  # create environment directory
. $WORK/fprep/bin/activate  # activate the environment
pip install git+https://github.com/prestonlab/fprep.git
pip install ezlaunch  # utilities for submitting jobs

After Python 3 packages have been installed, for later sessions you only need to activate the environment.

Procedure

See the tutorial for instructions for running on a sample dataset on TACC.

Related code

The quality assurance code is adapted from fmriqa by Russ Poldrack. The epi_reg_ants script is adapted from epi_reg from FSL 5.

Citation

If you use fPrep, please cite the following:

Morton NW, Schlichting ML, Preston AR. 2020. Events with common structure become organized within a hierarchical cognitive map in hippocampus and frontoparietal cortex. Proceedings of the National Academy of Sciences. 117(47): 29338-29345. https://doi.org/10.1073/pnas.1912338117.

The zenodo archive. Use the DOI corresponding to the version you used.