Tractography Parameters#

This page documents the configuration options for controlling tractography in pyAFQ. These parameters can be set in your configuration file 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. Default to the entire volume (all ones).
seed_thresholdfloat, optional.: A value of the seed_mask above which tracking is seeded. Default to 0.
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: 250
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. Defaults to use “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.