[ENH] Faster Tracking

[36000]

Updates:

• use NUMBA fast track from GPUStreamlines for prob
• otherwise use DIPY fast track
• update to dipy 1.12
• update OR exclude ROI
• remove ray from internals of pyAFQ, but keep it in GroupAFQ as an option to parallelize across subjects
• Fix in asymmetric filtering normalization code. This is tested to have no impact in practice (rtol=1e-6, atol-1e-6), as it is effectively normalized later on, but it is nicer to match the scilpy code more closely.

[Copilot]

Pull request overview

This PR updates pyAFQ’s tractography to use DIPY’s “fast tracking” APIs by default, adding explicit thread control and adjusting call sites (tasks/tests/examples) accordingly.

Changes:

• Switch AFQ.tractography.tractography.track to use dipy.tracking.tracker functions (det/prob/pft) and add n_threads support.
• Add seed-generation timing logs and update tractography task wiring to pass PVE + thread count into tracking.
• Update tractography-related tests, example config, thread defaults, and template fetch metadata.

Reviewed changes

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

Show a summary per file

File	Description
examples/howto_examples/pyafq_2.py	Updates example tracking params to align with the new tracking API.
AFQ/tractography/utils.py	Adds timing instrumentation for seed generation.
AFQ/tractography/tractography.py	Main switch to DIPY fast tracker API + new n_threads parameter and related tracking logic changes.
AFQ/tests/test_tractography.py	Updates tests for the new track() signature and pft selection via directions.
AFQ/tasks/tractography.py	Updates pipeline task to pass PVE and thread count into aft.track.
AFQ/tasks/structural.py	Updates default thread cap and documentation to reflect DIPY tracking usage.
AFQ/data/fetch.py	Updates one remote filename/id and corresponding md5 hash for template fetching.

---

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

[arokem]

I don't have much to add to co-pilot's review

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

AFQ/tractography/tractography.py:110

• Docstring defaults don’t match the function signature: seed_threshold is documented as defaulting to 0, but the signature defaults to 0.5; and maxlen is documented as default 250, but the signature default is 500. Please update the docstring so users get accurate defaults.

    seed_threshold : float, optional.
        A value of the seed_mask above which tracking is seeded.
        Default to 0.
    gm_threshold : float, optional.
        A value of the pve_gm_data above which we consider a voxel to be GM
        for the purposes of ACT stopping criterion. Default: 0.4.
    n_seeds : int or 2D array, optional.
        The seeding density: if this is an int, it is is how many seeds in each
        voxel on each dimension (for example, 2 => [2, 2, 2]). If this is a 2D
        array, these are the coordinates of the seeds. Unless random_seeds is
        set to True, in which case this is the total number of random seeds
        to generate within the mask. Default: 1e7
    random_seeds : bool
        Whether to generate a total of n_seeds random seeds in the mask.
        Default: True
    rng_seed : int
        random seed used to generate random seeds if random_seeds is
        set to True. Default: None
    thresholds_as_percentages : bool, optional
        Interpret seed_threshold as percentages of the
        total non-nan voxels in the seed mask to include
        (between 0 and 100), instead of as a threshold on the
        values themselves.
        Default: False
    step_size : float, optional.
        The size of a step (in mm) of tractography. Default: 0.5
    minlen: int, optional
        The minimal length (mm) in a streamline. Default: 20
    maxlen: int, optional
        The maximum length (mm) in a streamline. Default: 250

setup.cfg:46

• ray is still listed as a core install_requires dependency, but the codebase no longer imports it directly (and the only remaining reference appears to be the optional engine="ray" option in GroupAFQ, via dipy.utils.parallel.paramap). Consider moving ray to an extra (e.g. ray/parallel) so users don’t have to install it unless they opt into that engine.

    cuslines==2.2
    # efficiency
    numba
    osqp
    pydra
    ray

[36000]

@arokem this is ready to merge. It also fixes the callosum stuff. Once we merge this, we merge the other PR, then release 3.0 (hopefully sometime tomorrow?)