HCP105 bundle templates

Abstract

Overview Utilities for bringing the HCP105 white-matter reference tract dataset into a shared atlas space and creating bundle-wise tractogram templates. The repository provides the transformations from each subject to the atlas, together with scripts that: apply an individual subject transformation to one or all of its tractograms; convert tractograms between VTK, TRK, and TCK formats; and merge the transformed tractograms into one atlas tractogram per bundle. The resulting bundle templates retain inter-subject anatomical variability. Optional per-subject QuickBundles clustering reduces the number of streamlines before merging. Contents Path Purpose apply_transform_to_HCP.py Transform source HCP105 tractograms into atlas space. convert_tractogram.py Batch conversion between tractogram formats, with optional LPS/RAS coordinate flipping. concat_tracts.py Merge transformed tractograms by bundle, with optional QuickBundles clustering. Transfos/ Subject-to-atlas transformation series. residualDir/ Transformation data referenced by the transformation series. Requirements Python environment Tested with Python 3.13.13. pip install -r requirements.txt Anima Install Anima and make its binaries available on your PATH. In particular, apply_transform_to_HCP.py uses animaFibersApplyTransformSerie. Input data Extract both residualDir.zip and Transfos.zip at the project root. Transformation lists are stored in Transfos/; their associated data are in residualDir/. Download and extract the High quality white matter reference tract dataset. By default, the transformation script expects it in ./HCP105_Zenodo_NewTrkFormat with the following layout: HCP105_Zenodo_NewTrkFormat/ / tracts/ .trk This repository does not include scripts for transforming the original HCP DTI or T1 images. Generated reference images are provided below. File Description average_anat.nii.gz Average T1-weighted anatomical image. average_brain_mask.nii.gz Average brain mask. average_fa.nii.gz Average fractional anisotropy (FA) image. Workflow 1. Transform tractograms to atlas space Transform every bundle for every subject using the default input and output directories: python apply_transform_to_HCP.py To process a specific bundle or subject, use --bundle and --subject: python apply_transform_to_HCP.py \ --input-dir /path/to/HCP105_Zenodo_NewTrkFormat \ --bundle CST_left \ --subject 599469 \ --output-dir transformed \ --n-proc 4 Outputs are written as VTK tractograms in / / with a transformed_ prefix. The input TRK files are flipped from RAS to LPS before Anima applies the transformation. Command-line options python apply_transform_to_HCP.py --help usage: apply_transform_to_HCP.py [-h] [--input-dir INPUT_DIR] [--bundle BUNDLE] [--subject SUBJECT] [--output-dir OUTPUT_DIR] [--n-proc N_PROC] Apply transformations to tractograms from the HCP105 atlas. options: -h, --help show this help message and exit --input-dir, -i INPUT_DIR Directory containing the HCP105 atlas (https://zenodo.org/records/1477956) --bundle, -b BUNDLE Name of the bundle to process --subject, -s SUBJECT Subject ID to process (e.g. 1, 12, or ALL) --output-dir, -o OUTPUT_DIR Output paths. Repeat the option or provide multiple values to match the input files. --n-proc N_PROC Number of processes used to process subjects in parallel. 2. Convert tractogram formats The transformation workflow produces VTK files. Convert them to TRK or TCK when needed. For example, this creates a TRK file next to its VTK input: python convert_tractogram.py transformed/599469/transformed_CST_left.vtk \ --output-format trk \ --reference average_brain_mask.nii.gz Use --flip only when an LPS/RAS orientation conversion is required. Command-line options python convert_tractogram.py --help usage: convert_tractogram.py [-h] [--output-file OUTPUT_FILE [OUTPUT_FILE ...]] [--output-format {vtk,trk,tck}] [--reference REFERENCE] [--flip] input_files [input_files ...] Convert tractograms between formats in batch, with optional orientation flipping (LPS<->RAS). positional arguments: input_files Paths to the input tractogram files options: -h, --help show this help message and exit --output-file, -o OUTPUT_FILE [OUTPUT_FILE ...] Output paths. Repeat the option or provide multiple values to match the input files. --output-format, -of {vtk,trk,tck} Global output format (replaces the extension of each input file). --reference, -r REFERENCE Reference file(s). One for all inputs or one per input. --flip, -f Enable LPS<->RAS orientation flipping 3. Merge subject tractograms by bundle Merge transformed subject tractograms into one template per bundle. A QuickBundles reduction is applied per subject by default; --cluster-thr 0 disables it. python concat_tracts.py \ --input-dir transformed \ --out-dir concatenated \ --output-format vtk \ --cluster-thr 3 \ --n-proc 8 \ --with-subid When --with-subid is set, VTK outputs include a subject_id point-data array. Command-line options python concat_tracts.py --help usage: concat_tracts.py [-h] [--input-dir INPUT_DIR] [--out-dir OUT_DIR] [--output-format OUTPUT_FORMAT] [--cluster-thr CLUSTER_THR] [--n-proc N_PROC] [--with-subid] Concatenate tractograms from multiple subjects into a single template bundle, with optional QuickBundles clustering. options: -h, --help show this help message and exit --input-dir, -i INPUT_DIR Directory containing the transformed subject folders --out-dir, -o OUT_DIR Output directory for concatenated bundles --output-format, -of OUTPUT_FORMAT Output format for the bundles --cluster-thr CLUSTER_THR QuickBundles clustering threshold (in mm). If 0, bundles are concatenated without clustering. --n-proc, -n N_PROC Number of processes used by multiprocessing --with-subid Adds a 'subject_id' array to the VTK files References 1. Suarez, R. O., Commowick, O., Prabhu, S. P. & Warfield, S. K. Automated delineation of white matter fiber tracts with a multiple region-of-interest approach. Neuroimage 59, 3690–3700 (2012). 2. Guimond, A., Meunier, J. & Thirion, J. P. Average Brain Models: A Convergence Study. Computer Vision and Image Understanding 77, 192–210 (2000). 3. Wasserthal, J., Neher, P. & Maier-Hein, K. H. TractSeg - Fast and accurate white matter tract segmentation. Neuroimage 183, 239–253 (2018). 4. Garyfallidis, E. et al. Dipy, a library for the analysis of diffusion MRI data. Front Neuroinform 8, 71423 (2014). 5. Jakob, W., Peter, N. & Klaus, M.-H. High quality white matter reference tracts. https://doi.org/10.5281/ZENODO.1477956 doi:10.5281/ZENODO.1477956. 6. Durantel, T., Girard, G., Caruyer, E., Commowick, O. & Coloigner, J. A Riemannian framework for incorporating white matter bundle prior in orientation distribution function based tractography algorithms. PLoS One 20, e0304449 (2025). 7. Garyfallidis, E., Brett, M., Correia, M. M., Williams, G. B. & Nimmo-Smith, I. QuickBundles, a Method for Tractography Simplification. Front Neurosci 6, 175 (2012).