[ENH/FIX] Changes for reward bundles and VOF by 36000 · Pull Request #166 · tractometry/pyAFQ

36000 · 2026-01-28T01:35:12Z

Better seeding on WMGMI when using ROIs
Allow "mixed" bundle definitions - some ROIs from subject space, some from template space for the same bundle.
Much needed efficiency gains in bundle recognition by making more extensive use of the resampled tractogram in endpoint/startpoint filtering and length filtering
Changed the way SYN registration (the default) is saved. Previously, it was as a prealign and mapping file where you needed dipy to combine and handle them. Now, it is 2 displacement fields in two different files: one going template to subject, the other subject to template. This should be more straightforward for QC and for other software to read. As a part of this, all transform become transform_inverse and vice versa, because we are no longer dealing with the .is_inverse flag. Additionally, we can remove the conformedaffinemapping custom class we used to use.
Added some vendored code from white matter analysis to cluster segmented tracts based on the ORG 800 atlas. This is then used to subbundle the VOF using new subbundle code. These subbundles can then be recursively filtered using the same recognition code as the original bundle (ie, you could imagine a pipeline: identify bundle, clean it, subbundle it, refine each subbundle according to their own criteria, clean each subbundle, then subbundle again, as many times as necessary)
Re-introduced code that will assign streamlines to bundles preferentially according to which bundle's inclusion ROI they are closest to. This was solely because it makes Callosum Orbital slightly better, the rest of the bundles are largely unaffected.
Rewrote some of the recognition code such that we no longer allocate arrays the size of the n_streamlines (with the exception of the resampled streamlines array). This should reduce memory usage in that part.
Bundle Recognition now occurs with streamlines largely in RASMM space.
loosen default mahalonobis distance cleaning threshold to 4
Other minor bug fixes

For large tractographies these changes make pyAFQ much much faster in my testing. Thus, I changed default number of seeds to 10 million! On my laptop with 32GB of RAM this is still fast, even with other applications running. The testing should be much faster too.

Also, this changes the mapping output files, so we should merge it before 3.0!

Copilot

Pull request overview

This PR appears to add support for “reward bundles” by introducing new template assets and enabling more flexible ROI handling (including mixed-space ROI definitions and ROI dilation behavior used in recognition/tracking workflows).

Changes:

Add MassP template fetching/loading utilities and update bibliography references.
Extend BundleDict ROI handling to support mixed-space ROI specifications and update ROI transformation call sites to pass images (not affines).
Enhance RoiImage generation with optional ROI dilation and WM-only masking.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
docs/source/references.bib	Adds two new literature references.
AFQ/tasks/utils.py	Adjusts base filename generation to avoid unconditional trailing-char stripping.
AFQ/tasks/mapping.py	Updates `transform_rois` call to pass the DWI image (aligning with new API).
AFQ/tasks/decorators.py	Removes forced logger level configuration.
AFQ/recognition/utils.py	Introduces shared `tolerance_mm_to_vox` utility.
AFQ/recognition/preprocess.py	Refactors to delegate tolerance conversion to `AFQ.recognition.utils`.
AFQ/recognition/criteria.py	Updates ROI transformation call to pass the image instead of the affine.
AFQ/nn/synthseg.py	Updates label groupings used to derive PVE outputs.
AFQ/definitions/image.py	Adds ROI dilation + WM-only masking options for ROI-derived images.
AFQ/data/fetch.py	Adds MassP template fetcher/reader utilities.
AFQ/api/group.py	Removes logger level forcing; docstring example was modified.
AFQ/api/bundle_dict.py	Adds mixed-space ROI support and updates transformation helper signature to use an image object.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

AFQ/definitions/image.py

AFQ/api/bundle_dict.py

AFQ/definitions/image.py

AFQ/api/bundle_dict.py

AFQ/definitions/image.py

AFQ/api/group.py

AFQ/data/fetch.py

AFQ/api/bundle_dict.py

Copilot

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 11 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

AFQ/definitions/mapping.py

AFQ/api/participant.py

AFQ/recognition/recognize.py

AFQ/recognition/other_bundles.py

AFQ/api/group.py

docs/source/reference/bundledict.rst

AFQ/recognition/criteria.py

AFQ/api/participant.py

Copilot

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

AFQ/api/participant.py

AFQ/api/group.py

AFQ/registration.py

AFQ/recognition/recognize.py

AFQ/recognition/criteria.py

Copilot

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

AFQ/api/participant.py

AFQ/api/group.py

36000 · 2026-02-12T09:03:59Z

@arokem This is ready for review / merge. It is a grab bag of a bunch of minor features for pyAFQ that will be useful for VOF and reward stuff. I figured it was in a spot where we could try to merge and then start a new PR, just so the PR doesn't get too big, but some of the code (like the ORG stuff) is currently unused but will be used later. A description of the main things added in this PR is available in the first comment.

Also, copilot is super useful! Caught a few bugs.

36000 · 2026-02-13T03:12:36Z

Actually - go ahead and review this when you get the chance but don't merge it yet, I found a bug in streamline transformation.

arokem · 2026-02-13T03:21:26Z

OK - heads up that I have travel and deadlines in the next couple of weeks, so probably will not get to this before end of February.

36000 · 2026-02-13T04:09:56Z

OK - I will just keep adding changes to this PR then, no need to merge it soon.

36000 · 2026-03-16T14:00:41Z

@arokem This is ready for review once you get the chance

arokem · 2026-03-16T15:29:55Z

AFQ/api/bundle_dict.py


+class SpectralSubbundleDict(BundleDict):
+    """
+    A BundleDict where each bundle is defined as a spectral subbundle of a


Clarification question: what makes it "spectral"?

It could also be named ORGSubbundleDict, here we use spectral embedding of the distance matrix of each streamline to some reference streamlines, then compare that embedding to the embedding of known clusters to cluster the streamline. It's all based on the ORG 800 atlas.

Copilot

Pull request overview

Copilot reviewed 58 out of 58 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/source/reference/methods.rst

AFQ/api/participant.py

AFQ/recognition/other_bundles.py

AFQ/tractography/tractography.py

AFQ/tractography/gputractography.py

AFQ/tasks/segmentation.py

arokem

Some comments from an initial read through

arokem · 2026-03-24T00:29:47Z

AFQ/tasks/segmentation.py


    if is_trx:
-        seg_sft.sft.dtype_dict = {"positions": np.float16, "offsets": np.uint32}
+        seg_sft.sft.dtype_dict = {"positions": np.float32, "offsets": np.uint32}


This will result in a large increase in file size. Why is it necessary?

Many of the DIPY functions currently require np.float32 or np.float64, and converting this to np.float16 then back for DIPY adds a lot of time. We can change it back if we change some of the Cython in DIPY, or we can write scripts to transfer tractograms to np.float16 for long term storage.

But it works on the current main branch without these conversions, no? Is there something new here that breaks that? I think we'd want to change this on DIPY as needed, so that we can save all that memory and storage down the line.

arokem · 2026-03-24T00:31:00Z

AFQ/tractography/tractography.py

    seed_threshold=0.5,
    thresholds_as_percentages=False,
-    n_seeds=2000000,
+    n_seeds=1e7,


This is a pretty big jump. I assume this makes a big difference in some of the new tracts?

I chose 10 million because it fits well in 32GB of RAM for HBN style subjects and improves all of the tracts. I guess 5 million or 2 million would also work, but I think 10 million is reasonable.

AFQ/tractography/tractography.py

arokem · 2026-03-24T00:34:48Z

AFQ/_fixes.py



-def gwi_odf(gqmodel, data):
+def get_simplified_transform(self):


I wonder if we would rather conform with conventions described here: https://github.com/nipy/nitransforms

Maybe we can do this in another PR? I like this simplified transform here for now, its really easy to not have to worry about affines or pre-aligns at all when applying a transform.

AFQ/_fixes.py

Copilot AI review requested due to automatic review settings January 28, 2026 01:35

Copilot started reviewing on behalf of 36000 January 28, 2026 01:35 View session

36000 changed the title ~~Reward bundles~~ [WIP] Changes for reward bundles Jan 28, 2026

36000 added this to the pyAFQ 3.0 milestone Jan 28, 2026

Copilot AI reviewed Jan 28, 2026

View reviewed changes

36000 force-pushed the reward_bundles branch from ce5c8f2 to e7f2d67 Compare January 29, 2026 00:16

36000 changed the title ~~[WIP] Changes for reward bundles~~ [WIP] Changes for reward bundles and VOF Feb 12, 2026

36000 requested a review from Copilot February 12, 2026 06:11

Copilot started reviewing on behalf of 36000 February 12, 2026 06:11 View session

36000 changed the title ~~[WIP] Changes for reward bundles and VOF~~ [ENH/FIX] Changes for reward bundles and VOF Feb 12, 2026

Copilot AI reviewed Feb 12, 2026

View reviewed changes

36000 requested a review from Copilot February 12, 2026 08:44

Copilot started reviewing on behalf of 36000 February 12, 2026 08:45 View session

Copilot AI reviewed Feb 12, 2026

View reviewed changes

AFQ/api/participant.py Outdated Show resolved Hide resolved

AFQ/api/group.py Outdated Show resolved Hide resolved

AFQ/registration.py Show resolved Hide resolved

AFQ/recognition/recognize.py Outdated Show resolved Hide resolved

AFQ/recognition/criteria.py Show resolved Hide resolved

36000 requested a review from Copilot February 12, 2026 08:55

Copilot started reviewing on behalf of 36000 February 12, 2026 08:56 View session

Copilot AI reviewed Feb 12, 2026

View reviewed changes

AFQ/api/participant.py Show resolved Hide resolved

AFQ/api/group.py Outdated Show resolved Hide resolved

36000 added 9 commits February 23, 2026 16:22

start allowing mixed bundle defs

1c2eb04

finish up wmgmi seeding changes

6e2bb56

more mixed ROI fixes

0545fa7

BFs

643395d

return to setting logging to info

03dc8b0

minor docs fixes from copilot

b0ce1a0

toy with vof

bdf4b58

much needed speedups in bundle recognition

806e53d

tighter node thresh

cc725ca

36000 added 16 commits March 10, 2026 13:37

add for all spectral constraints

4a28cb1

VOF updates, up tractography numbers

8d83d56

handle trxfile in recognition

5686bd3

limit new fury version

874b5b5

more inclusive VOF

383ce84

better conforming for nn

aea24e2

maximum bundle filtering

daf2f82

try this

aa238b1

try this

694dea6

more reliable other bundle cleaning

36db871

convenient api for bd

b13aaab

add synthseg cortex parcellation

d4b2a22

update tests

a63ac8c

example updates and VOF refinement

beb40ad

add nn utils file

5e9b8f9

put examples back to aodf

0536581

arokem reviewed Mar 16, 2026

View reviewed changes

36000 requested a review from Copilot March 17, 2026 01:33

Copilot started reviewing on behalf of 36000 March 17, 2026 01:33 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

36000 added 7 commits March 17, 2026 11:17

copilot docs fixes

2573bfa

bf

0882b8c

add hypothalamus segmentation

c93089b

bf

cc7d28d

bf

808f7a6

bf

24e801f

rationalization of pyAFQ sphere handling

86040ca

arokem reviewed Mar 24, 2026

View reviewed changes

update tests, fix typ

55a4280



		def gwi_odf(gqmodel, data):
		def get_simplified_transform(self):

Conversation

36000 commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

36000 commented Feb 12, 2026

Uh oh!

36000 commented Feb 13, 2026

Uh oh!

arokem commented Feb 13, 2026

Uh oh!

36000 commented Feb 13, 2026

Uh oh!

36000 commented Mar 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

arokem left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

36000 commented Jan 28, 2026 •

edited

Loading