[ENH/FIX] Changes for reward bundles and VOF

[36000]

1. Better seeding on WMGMI when using ROIs
2. Allow "mixed" bundle definitions - some ROIs from subject space, some from template space for the same bundle.
3. Much needed efficiency gains in bundle recognition by making more extensive use of the resampled tractogram in endpoint/startpoint filtering and length filtering
4. 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.
5. 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)
6. 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.
7. 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.
8. Bundle Recognition now occurs with streamlines largely in RASMM space.
9. loosen default mahalonobis distance cleaning threshold to 4
10. 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 5 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.

[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.

[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.

[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.

[36000]

@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]

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]

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]

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

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated 4 comments.

---

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