FreeSurfer

The FreeSurfer pipeline integrates FreeSurfer software to provide a full processing stream for structural MRI data. It takes a T1-weighted image as the only input and generates brain ROI segmentation masks as well as brain-related statistics.

Usage

This pipeline contains three stages: 1) Segmentation: runs the FreeSurfer recon-all command to obtain ROI segmentation masks and brain statistics, 2) Estimation: converts the brain statistics into CSV format, and 3) Consolidation: consolidates all participants' data.

This pipeline can be run with or without a container. For containerized usage, Singularity can be used on a cluster or Docker locally. This pipeline can be run in individual or batch mode, meaning you can specify a certain subject and session or run the pipeline for all subjects in the folder, respectively.

These examples will run the pipeline in batch mode on the cluster. To run individually or locally/with a container, set --mode individual, or -c local/-c singularity/-c docker, respectively. Only Steps 1 and 2 have the option of individual or batch; Step 3 will always run in batch mode.

Step 1. Segmentation

This step runs FreeSurfer's recon-all command on a T1 image to obtain ROI segmentation masks and brain statistics.

Required flags:

-m or --mainpath: path to parent data folder
-n or --name: T1 sequence name
--toolpath: path to pipeline folder

Other flags:

-p or --participant: participant ID (only needed for individual mode)
--ses: session ID (only needed for individual mode)
-s or --step: step of pipeline - segmentation, estimation, consolidation. Default is segmentation
--mode: run pipeline individually or batch. Default is batch
-c or --container: which container to use: singularity, docker, local, cluster. Default is cluster
--sinpath: path to singularity image (only needed if using singularity container - don't need to specify if using takim cluster)
--dockerpath: path to docker image (only needed if using docker container)
-h or --help: show help message

bash /path/to/PennSIVE_neuro_pip/pipelines/freesurfer/code/bash/freesurfer.sh -m /path/to/data -n "*T1w*.nii.gz" --toolpath /path/to/PennSIVE_neuro_pip 

Step 2. Estimation

This step converts the brain statistics output from Step 1 and converts to CSV format.

Required flags:

-m or --mainpath: path to parent data folder
-s or --step: step of pipeline - segmentation, estimation, consolidation. Default is segmentation
--toolpath: path to pipeline folder

Other flags:

-p or --participant: participant ID (only needed for individual mode)
--ses: session ID (only needed for individual mode)
--parc: parcellation - aparc, aparc.a2009s. Default is aparc
--mode: run pipeline individually or batch. Default is batch
-c or --container: which container to use: singularity, docker, local, cluster. Default is cluster
--sinpath: path to singularity image (only needed if using singularity container - don't need to specify if using takim cluster)
--dockerpath: path to docker image (only needed if using docker container)
-h or --help: show help message

bash /path/to/PennSIVE_neuro_pip/pipelines/freesurfer/code/bash/freesurfer.sh -m /path/to/data --step estimation --toolpath /path/to/PennSIVE_neuro_pip 

Step 3. Consolidation

This step consolidates the brain statistics for all participants and sessions.

Required flags:

-m or --mainpath: path to parent data folder
--toolpath: path to pipeline folder

Other flags:

-c or --container: which container to use: singularity, docker, local, cluster. Default is cluster
--sinpath: path to singularity image (only needed if using singularity container - don't need to specify if using takim cluster)
--dockerpath: path to docker image (only needed if using docker container)
-h or --help: show help message

bash /path/to/PennSIVE_neuro_pip/pipelines/freesurfer/code/bash/freesurfer.sh -m /path/to/data --step consolidation --toolpath /path/to/PennSIVE_neuro_pip