Tractography Parameters#

This page documents the configuration options for controlling tractography in pyAFQ. These parameters can be passed directly when using the CLI or passed as arguments when using the API.

Example Usage#

from AFQ.api.group import GroupAFQ
import AFQ.data.fetch as afd
import os.path as op

afd.organize_stanford_data()

myafq = GroupAFQ(
    bids_path=op.join(afd.afq_home, 'stanford_hardi'),
    preproc_pipeline='vistasoft',
    tracking_params=dict(
        n_seeds=25000,
        random_seeds=True,
        rng_seed=2025,
        trx=True)
    )

Tractography Parameter Reference#

AFQ.tractography.tractography.track(params_file, pve, n_threads, directions='prob', max_angle=30.0, sphere='repulsion724', seed_mask=None, seed_threshold=0.5, gm_threshold=0.4, thresholds_as_percentages=False, n_seeds=10000000.0, random_seeds=True, rng_seed=None, step_size=0.5, minlen=20, maxlen=500, odf_model='CSD_AODF', basis_type='descoteaux07', legacy=True, trx=True, jit_backend='numba', jit_chunk_size=None)[source]

Tractography

Parameters:

params_filestr, nibabel img.: Full path to a nifti file containing CSD spherical harmonic coefficients, or nibabel img with model params.
pvestr, nibabel img: Full path to a nifti file containing tissue probability maps, or nibabel img with tissue probability maps. This should be of the order (pve_csf, pve_gm, pve_wm).
n_threadsint: The number of threads to use in tracking. If 0 or -1, uses all available threads.
directionsstr: How tracking directions are determined. One of: {“det” | “prob” | “pft”} pft refers to Particle Filtering Tracking ([Girard2014]). Default: “prob”
max_anglefloat, optional.: The maximum turning angle in each step. Default: 30
spherestr or DIPY Sphere: The discretization of the ODF. Can be a DIPY Sphere or a string name of a DIPY Sphere. Default: “repulsion724”
seed_maskarray, optional.: Float or binary mask describing the ROI within which we seed for tracking. If None, use the entire volume (all ones). Default: None
seed_thresholdfloat, optional.: A value of the seed_mask above which tracking is seeded. Default: 0.5
gm_thresholdfloat, 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_seedsint 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 in RASMM. 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_seedsbool: Whether to generate a total of n_seeds random seeds in the mask. Default: True
rng_seedint: random seed used to generate random seeds if random_seeds is set to True. Default: None
thresholds_as_percentagesbool, 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_sizefloat, 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: 500
odf_modelstr or Definition, optional: Can be either a string or Definition. If a string, it must be one of {“DTI”, “CSD”, “DKI”, “GQ”, “RUMBA”, “MSMT_AODF”, “CSD_AODF”, “MSMTCSD”}. If a Definition, we assume it is a definition of a file containing Spherical Harmonics coefficients. Default: “CSD_AODF”
basis_typestr, optional: The spherical harmonic basis type used to represent the coefficients. One of {“descoteaux07”, “tournier07”}. Default: “descoteaux07”
legacybool, optional: Whether the legacy SH basis definition should be used. See Dipy documentation for more details. Default: True
trxbool, optional: Whether to return the streamlines compatible with input to TRX file (i.e., as a LazyTractogram class instance). Default: True
jit_backendstr, optional: If directions is “prob” or “ptt”, the JIT backend to use. One of {“auto”, “cuda”, “metal”, “webgpu”, or “numba”}. Default: “numba”
jit_chunk_sizeint, optional: If directions is “prob” or “ptt”, the chunk size to use for JIT tracking. If None, chooses 25000 for numba backend and 5000 for other backends. Default: None

Returns:

list of streamlines ()

References

[Girard2014]

Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. Towards quantitative connectivity analysis: reducing tractography biases. NeuroImage, 98, 266-278, 2014.

[Smith2012]

Smith RE, Tournier JD, Calamante F, Connelly A. Anatomically-constrained tractography: improved diffusion MRI streamlines tractography through effective use of anatomical information. Neuroimage. 2012 Sep;62(3):1924-38. doi: 10.1016/j.neuroimage.2012.06.005. Epub 2012 Jun 13.