Using RecoBundles for bundle recognition#
For bundle recognition, pyAFQ defaults to use the waypoint ROI approach described in [Yeatman2012]. However, as an alternative approach, pyAFQ also supports using the RecoBundles algorithm [Garyfallidis2017], which uses an atlas of bundles in streamlines. This example shows how to use RecoBundles for bundle recognition.
The code closely resembles the code used in sphx_glr_tutorial_examples_plot_001-plot_afq_api.py.
import os.path as op
import AFQ.data.fetch as afd
from AFQ.api.group import GroupAFQ
import AFQ.api.bundle_dict as abd
afd.organize_stanford_data(clear_previous_afq="track")
tracking_params = dict(n_seeds=25000,
random_seeds=True,
rng_seed=42)
/opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
from .autonotebook import tqdm as notebook_tqdm
2026-05-19 01:01:43,851 INFO util.py:154 -- Missing packages: ['ipywidgets']. Run `pip install -U ipywidgets`, then restart the notebook server for rich notebook output.
Defining the segmentation params#
We also refer to bundle recognition as the “segmentation” of the tractogram.
Parameters of this process are set through a dictionary input to the
segmentation_params argument of the GroupAFQ object. In this case, we
use abd.reco_bd(16), which tells pyAFQ to use the RecoBundles
algorithm for bundle recognition. This uses 16 bundles, there is also
an atlas abd.reco_bd(80) which uses 80 bundles.
myafq = GroupAFQ(
output_dir=op.join(afd.afq_home, 'stanford_hardi', 'derivatives',
'recobundles'),
bids_path=op.join(afd.afq_home, 'stanford_hardi'),
# Set the algorithm to use RecoBundles for bundle recognition:
bundle_info=abd.reco_bd(16),
dwi_preproc_pipeline='vistasoft',
t1_preproc_pipeline='freesurfer',
tracking_params=tracking_params,
viz_backend_spec='plotly_no_gif')
fig_files = myafq.export_all()
0%| | 0/12916 MB [00:00]
0%| | 2/12916 MB [00:00]
0%| | 5/12916 MB [00:00]
0%| | 10/12916 MB [00:00]
0%| | 15/12916 MB [00:00]
0%| | 24/12916 MB [00:00]
0%| | 33/12916 MB [00:00]
0%| | 49/12916 MB [00:00]
0%| | 64/12916 MB [00:00]
1%| | 94/12916 MB [00:00]
1%| | 124/12916 MB [00:01]
1%|▏ | 181/12916 MB [00:01]
2%|▏ | 236/12916 MB [00:01]
3%|▎ | 347/12916 MB [00:01]
4%|▎ | 455/12916 MB [00:01]
5%|▌ | 670/12916 MB [00:01]
7%|▋ | 889/12916 MB [00:01]
9%|▉ | 1134/12916 MB [00:01]
11%|█ | 1380/12916 MB [00:01]
13%|█▎ | 1626/12916 MB [00:02]
14%|█▍ | 1871/12916 MB [00:02]
16%|█▋ | 2115/12916 MB [00:02]
18%|█▊ | 2359/12916 MB [00:02]
20%|██ | 2605/12916 MB [00:02]
22%|██▏ | 2849/12916 MB [00:02]
24%|██▍ | 3094/12916 MB [00:02]
26%|██▌ | 3337/12916 MB [00:02]
28%|██▊ | 3580/12916 MB [00:02]
30%|██▉ | 3825/12916 MB [00:03]
32%|███▏ | 4071/12916 MB [00:03]
33%|███▎ | 4315/12916 MB [00:03]
35%|███▌ | 4558/12916 MB [00:03]
37%|███▋ | 4799/12916 MB [00:03]
39%|███▉ | 5045/12916 MB [00:03]
41%|████ | 5289/12916 MB [00:03]
43%|████▎ | 5534/12916 MB [00:03]
45%|████▍ | 5781/12916 MB [00:03]
47%|████▋ | 6027/12916 MB [00:04]
49%|████▊ | 6272/12916 MB [00:04]
50%|█████ | 6519/12916 MB [00:04]
52%|█████▏ | 6742/12916 MB [00:04]
54%|█████▍ | 6943/12916 MB [00:04]
55%|█████▌ | 7163/12916 MB [00:04]
57%|█████▋ | 7408/12916 MB [00:04]
59%|█████▉ | 7656/12916 MB [00:04]
61%|██████ | 7868/12916 MB [00:04]
63%|██████▎ | 8110/12916 MB [00:05]
65%|██████▍ | 8357/12916 MB [00:05]
67%|██████▋ | 8606/12916 MB [00:05]
69%|██████▊ | 8851/12916 MB [00:05]
70%|███████ | 9093/12916 MB [00:05]
72%|███████▏ | 9336/12916 MB [00:05]
74%|███████▍ | 9586/12916 MB [00:05]
76%|███████▌ | 9831/12916 MB [00:05]
78%|███████▊ | 10053/12916 MB [00:06]
80%|███████▉ | 10298/12916 MB [00:06]
82%|████████▏ | 10541/12916 MB [00:06]
84%|████████▎ | 10787/12916 MB [00:06]
85%|████████▌ | 11028/12916 MB [00:06]
87%|████████▋ | 11274/12916 MB [00:06]
89%|████████▉ | 11516/12916 MB [00:06]
91%|█████████ | 11757/12916 MB [00:06]
93%|█████████▎| 12001/12916 MB [00:06]
95%|█████████▍| 12247/12916 MB [00:07]
97%|█████████▋| 12465/12916 MB [00:07]
98%|█████████▊| 12694/12916 MB [00:07]
100%|██████████| 12916/12916 MB [00:07]
INFO:bidsschematools:No schema path specified, defaulting to the bundled schema, `/opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages/bidsschematools/data/schema.json`.
INFO:AFQ:Using the following files for subject 01 and session 01:
INFO:AFQ: DWI: /home/runner/AFQ_data/stanford_hardi/derivatives/vistasoft/sub-01/ses-01/dwi/sub-01_ses-01_dwi.nii.gz
INFO:AFQ: BVAL: /home/runner/AFQ_data/stanford_hardi/derivatives/vistasoft/sub-01/ses-01/dwi/sub-01_ses-01_dwi.bval
INFO:AFQ: BVEC: /home/runner/AFQ_data/stanford_hardi/derivatives/vistasoft/sub-01/ses-01/dwi/sub-01_ses-01_dwi.bvec
INFO:AFQ: T1: /home/runner/AFQ_data/stanford_hardi/derivatives/freesurfer/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii.gz
WARNING:AFQ:It is recommended to provide CSF/GM/WM segmentations using PVEImage or PVEImages in AFQ.definitions.image. Otherwise, SynthSeg2 will be used
INFO:AFQ:Calculating _b0ref.nii.gz...
INFO:AFQ:_b0ref.nii.gz completed. Saving to /home/runner/AFQ_data/stanford_hardi/derivatives/recobundles/sub-01/ses-01/dwi/sub-01_ses-01_b0ref.nii.gz
INFO:AFQ:Calculating _desc-brain_mask.nii.gz...
2026-05-19 01:02:02.139126100 [W:onnxruntime:Default, device_discovery.cc:133 GetPciBusId] Skipping pci_bus_id for PCI path at "/sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0004:00/MSFT1000:00/5620e0c7-8062-4dce-aeb7-520c7ef76171" because filename "5620e0c7-8062-4dce-aeb7-520c7ef76171" did not match expected pattern of [0-9a-f]+:[0-9a-f]+:[0-9a-f]+[.][0-9a-f]+
INFO:AFQ:Calculating _desc-T1w_mask.nii.gz...
INFO:AFQ:Running mindgrab...
References:#
.. [Garyfallidis2017] Garyfallidis, Eleftherios, Marc-Alexandre Côté, Francois Rheault, Jasmeen Sidhu, Janice Hau, Laurent Petit, David Fortin, Stephen Cunanne, and Maxime Descoteaux. 2017.“Recognition of White Matter Bundles Using Local and Global Streamline-Based Registration and Clustering.”NeuroImage 170: 283-295.