BrainQC

The BrainQC pipeline contains the Brain WM Lesion/ROI Segmentation QC Shiny App, a collaborative tool designed to facilitate the evaluation of white matter lesion masks generated by segmentation algorithms like MIMoSA, brain ROI masks generated by JLF and FreeSurfer, as well as lesion center masks for CVS score calculation and PRL lesion masks for PRL score calculation. It provides a user-friendly interface where multiple users can collectively assess segmentation quality through interactive features.

Installation

Cluster:

Sys.setenv(CURL_CA_BUNDLE = "/etc/ssl/certs/ca-bundle.trust.crt")
library(devtools)
new_path = "/path/to/save/r_packages"
withr::with_libpaths(new = new_path, install_github("Zheng206/BrainQC"))
# change the QC_CLI.R Script
.libPaths(c("/misc/appl/R-4.1/lib64/R/library",new_path))

Local:

library(devtools)
new_path = "/path/to/save/r_packages"
withr::with_libpaths(new = new_path, install_github("Zheng206/BrainQC"))

Usage

This pipeline contains three stages: 1) QC Preparation: prepares for QC results, 2) Interactive Evaluation: runs interactive QC sessions to evaluate segmentation masks, and 3) Post-QC: reviews QC results interactively.

This pipeline can be run with or without a container. For containerized usage, Singularity can be used on a cluster or Docker locally. Step 1 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. Steps 2 and 3 must be run in batch mode.

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.

Step 1. QC Preparation

This step prepares all data for QC app.

Required flags:

-m or --mainpath: path to parent data folder
-i or --img: brain image name
--seg: ROI or lesion mask name
--toolpath: path to pipeline folder

Other flags:

-p or --participant: participant ID (only needed for individual mode)
--step: step of pipeline - prep, qc, post. Default is prep
-t or --type: type of QC procedure - lesion, cvs, freesurfer, JLF, PRL. Default is lesion
--defaultseg: default ROI to be evaluated first (only needed if type is freesurfer or JLF)
--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)
--cores: number of cores used for parallel computing. Default is 1
-h or --help: show help message

Lesion QC

bash /path/to/PennSIVE_neuro_pip/pipelines/BrainQC/code/bash/QC.sh -m /path/to/data -i flair_n4_brain.nii.gz --seg mimosa_mask.nii.gz -t lesion --toolpath /path/to/PennSIVE_neuro_pip 

FreeSurfer QC

bash /path/to/PennSIVE_neuro_pip/pipelines/BrainQC/code/bash/QC.sh -m /path/to/data -i ^brain.mgz --seg ^aseg.mgz -t freesurfer --defaultseg choroid-plexus --toolpath /path/to/PennSIVE_neuro_pip 

JLF QC

bash /path/to/PennSIVE_neuro_pip/pipelines/BrainQC/code/bash/QC.sh -m /path/to/data -i "*t1_brain.nii.gz" --seg fused_WMGM_seg.nii.gz -t JLF --toolpath /path/to/PennSIVE_neuro_pip 

CVS QC

bash /path/to/PennSIVE_neuro_pip/pipelines/BrainQC/code/bash/QC.sh -m /path/to/data -i epi_n4_brain.nii.gz --seg les_reg_epi.nii.gz -t cvs --toolpath /path/to/PennSIVE_neuro_pip 

PRL QC

bash /path/to/PennSIVE_neuro_pip/pipelines/BrainQC/code/bash/QC.sh -m /path/to/data -i phase_n4_brain.nii.gz --seg lesions_reg_epi_labeled.nii.gz -t PRL --toolpath /path/to/PennSIVE_neuro_pip 

Step 2. Interactive Evaluation

This step runs the QC app to evaluate accuarcy of segmentation masks with processed images.

Required flags:

-m or --mainpath: path to parent data folder
-t or --type: type of QC procedure - lesion, cvs, freesurfer, JLF, PRL. Default is lesion
--step: step of pipeline - prep, qc, post. Default is prep. This step is qc
--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)
--cores: number of cores used for parallel computing. Default is 1
-h or --help: show help message

For this step, the only flag that will differ across QC types is -t or --type. Be sure to use the same type as Step 1.

bash /path/to/PennSIVE_neuro_pip/pipelines/BrainQC/code/bash/QC.sh -m /path/to/data --step qc -t lesion --toolpath /path/to/PennSIVE_neuro_pip 

Step 3. Post-QC

This step allows for reviewing QC results in the app.

Required flags:

-m or --mainpath: path to parent data folder
--step: step of pipeline - prep, qc, post. Default is prep. This step is qc
--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)
--cores: number of cores used for parallel computing. Default is 1
-h or --help: show help message

bash /path/to/PennSIVE_neuro_pip/pipelines/BrainQC/code/bash/QC.sh -m /path/to/data --step post --toolpath /path/to/PennSIVE_neuro_pip