Customizing the Pipeline - McIntosh-Lab/tvb-ukbb GitHub Wiki

This page contains instructions for customizing the TVB-UKBB pipeline for different datasets.

Parameter settings for processing toolboxes need to be customized to the acquisitions. It is advised that you review parameter choices for FSL tools including, but not limited to, VBM, EDDY, BEDPOSTX, PROBTRACKX2, FEAT, and FIX. BIANCA (if you have T2 FLAIR images) will also require a manually segmented WM lesion training set.

Currently, gradient distortion correction, NODDI, AUTOPTX, task fMRI and susceptibility-weighted imaging processing from the original UKBiobank pipeline are either not implemented or remain untested.

init_vars file

init_vars is the file where most of the model configuration is specified and instantiated as BASH environment variables prior to execution. For more information on customizing and configuring init_vars, visit the Modifying init_vars wiki page.

Parcellations

We provide some parcellations in /templates/parcellations but you may use any brain parcellation you wish with the TVB-UKBB pipeline. Your parcellation should be a NIFTI image of gray matter ROIs specified on FSL's MNI152 1mm template and placed in /templates/parcellations. A tab-separated look-up table with ROI label numbers and ROI names must also be provided in the same directory. Both the parcellation and look-up table should be referenced appropriately in the init_vars file. Connectivity matrices are organized in the order that ROIs appear in the look-up table, regardless of the ROI label numbers. In this way, a user may wish to specify an order different from ascending ROI labels.

If you also wish to compute the temporal signal-to-noise ratio of highly susceptible areas separately from the rest of the brain (part of the IDP pipeline), you must also provide a mask of those areas and place it in /templates/parcellations. Its filename must also be specified in the init_vars file. This mask is typically created using some subset of ROIs from the parcellation image.

You may also want to run the pipeline on an already processed subject using a different parcellation. In that case, check out the page on running the reparcellation script.

IMPORTANT: Currently, the pipeline recognizes subcortical regions according to the parcellation lookup table. Cortical regions must have a "RH" or "LH" in their ROI name while subcortical regions should have a "rh" or "lh" in their ROI names.

.RData Training File

FIX works best with a trained-weights (.RData) file that is specific to your dataset. Steps for creating one are described in the FIX User Guide here.

.RData training files for FIX should be compatible with R 3.4.1. .RData files created in newer versions of R may work but there is no guarantee. We recommend that you create training files using the conda env and included R version.

Your .RData file should be placed in bb_functional_pipeline/bb_fix_dir/training_files and referenced appropriately in the init_vars file in the line export TRAINING_FILE=.

Age-specific Templates

Age-specific priors are used in the Cam-CAN branch in order to address inaccuracies in tissue segmentation. See Age-Specific Segmentation for details.

Users must provide a tab-separated values (tsv) file containing subject IDs and ages. SUBJECT_AGE_LIST in init_vars must point to this file. A sample subject age list file can be found in bb_structural_pipeline/FAST_age_spec/sample_subject_age_file.tsv.

Image-Derived Phenotypes (IDPs)

Image-Derived Phenotypes are quantitative metrics generated from various processing steps throughout the pipeline. These IDPs can be found in text files from the IDP_files_<parcellation name> directory within each processed subject directory. Especially important IDPs are featured in the QC Report.

Users may choose to generate new IDPs, set a range of acceptable values for each IDP, and specify IDPs to be included in the QC Report. See Modifying IDP Generation.

Quality Control (QC) Report

Analyses generated by the QC Report can be modified to better suit your dataset; users may alter brightness, contrast, colormaps, ranges of slices, and specific NIfTI files being depicted in each QC image. See Modifying QC Generation.

We do not currently provide a tool for users to add new analyses or overlay images to the QC Report. If you have any suggestions for analyses to be included in the QC Report, please let us know in the Discussions Page.