The pyAFQ configuration file

This file should be a toml file. At minimum, the file should contain the BIDS path:

[files]
bids_path = "path/to/study"

But additional configuration options can be provided. See an example configuration file below:

title = "My AFQ analysis"

# Initialize a GroupAFQ object from a BIDS dataset.

# Use '' to indicate None
# Wrap dictionaries in quotes
# Wrap definition object instantiations in quotes

[BIDS_PARAMS]

# The path to preprocessed diffusion data organized in a BIDS dataset. This should contain a BIDS derivative dataset with preprocessed dwi/bvals/bvecs.
bids_path = ""

# Filter to pass to bids_layout.get when finding DWI files. Default: {"suffix": "dwi"}
bids_filters = "{'suffix': 'dwi'}"

# The name of the pipeline used to preprocess the DWI data. Default: "all".
dwi_preproc_pipeline = "all"

# The name of the pipeline used to preprocess the T1w data. If None, defaults to the same as dwi_preproc_pipeline. Default: None
t1_preproc_pipeline = ""

# List of participant labels (subject IDs) to perform processing on. If None, all subjects are used. Default: None
participant_labels = ""

# Path to output directory. If None, outputs are put in a AFQ pipeline folder in the derivatives folder of the BIDS directory. pyAFQ will use existing derivatives from the output directory if they exist, instead of recalculating them (this means you need to clear the output folder if you want to recalculate a derivative). Default: None
output_dir = ""

# Parameters to pass to paramap in AFQ.utils.parallel, to parallelize computations across subjects and sessions. Set "n_jobs" to -1 to automatically parallelize as the number of cpus. Here is an example for how to do multiprocessing with 4 cpus: {"n_jobs": 4, "engine": "ray"} Default: {"engine": "serial"}
parallel_params = "{'engine': 'serial'}"

# Additional arguments to give to BIDSLayout from pybids. For large datasets, try: {"validate": False, "index_metadata": False} Default: {}
bids_layout_kwargs = "{}"

# The logging level to use for this class. Default: logging.INFO
logging_level = "logging.INFO"

# You can set additional parameters for any step of the process. See :ref:`usage/kwargs` for more details.
kwargs = ""

[TRACTOGRAPHY_PARAMS]

# Full path to a nifti file containing CSD spherical harmonic coefficients, or nibabel img with model params.
params_file = ""

# 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).
pve = ""

# The number of threads to use in tracking. If 0 or -1, uses all available threads.
n_threads = ""

# How tracking directions are determined. One of: {"det" | "prob" | "pft"} pft refers to Particle Filtering Tracking ([Girard2014]_). Default: "prob"
directions = "prob"

# The maximum turning angle in each step. Default: 30
max_angle = 30

# The discretization of the ODF. Can be a DIPY Sphere or a string name of a DIPY Sphere. Default: "repulsion724"
sphere = "repulsion724"

# Float or binary mask describing the ROI within which we seed for tracking. Default to the entire volume (all ones).
seed_mask = ""

# A value of the seed_mask above which tracking is seeded. Default to 0.
seed_threshold = ""

# 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.
gm_threshold = 0.4

# 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
n_seeds = 10000000.0

# Whether to generate a total of n_seeds random seeds in the mask. Default: True
random_seeds = true

# random seed used to generate random seeds if random_seeds is set to True. Default: None
rng_seed = ""

# 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
thresholds_as_percentages = false

# The size of a step (in mm) of tractography. Default: 0.5
step_size = 0.5

# The minimal length (mm) in a streamline. Default: 20
minlen = 20

# The maximum length (mm) in a streamline. Default: 250
maxlen = 250

# 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"
odf_model = ""

# The spherical harmonic basis type used to represent the coefficients. One of {"descoteaux07", "tournier07"}. Default: "descoteaux07"
basis_type = "descoteaux07"

# Whether the legacy SH basis definition should be used. See Dipy documentation for more details. Default: True
legacy = true

# Whether to return the streamlines compatible with input to TRX file (i.e., as a LazyTractogram class instance). Default: True
trx = true

# If directions is "prob" or "ptt", the JIT backend to use. One of {"auto", "cuda", "metal", "webgpu", or "numba"}. Default: "numba"
jit_backend = "numba"

# 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
jit_chunk_size = ""

[SEGMENTATION_PARAMS]

# Tractogram to segment.
tg = ""

# Image for reference.
img = ""

# Mapping from subject to template.
mapping = ""

# Dictionary of bundles to segment.
bundle_dict = ""

# Template image for registration.
reg_template = ""

# Resample streamlines to nb_points number of points. If False, no resampling is done. Can only be done on a StatefulTractogram. Default: False
nb_points = false

# Subsample streamlines to nb_streamlines. Can only be done on a StatefulTractogram. If False, no subsampling is done. Default: False
nb_streamlines = false

# Whether to clip the streamlines to be only in between the ROIs. Default: False
clip_edges = false

# RecoBundles parameters for the recognize function. Default: dict(model_clust_thr=1.25, reduction_thr=25, pruning_thr=12)
rb_recognize_params = "{'model_clust_thr': 1.25, 'reduction_thr': 25, 'pruning_thr': 12}"

# Whether to refine the RecoBundles segmentation. Default: False
refine_reco = false

# Using AFQ Algorithm. Initial cleaning of fiber groups is done using probability maps from [Hua2008]_. Here, we choose an average probability that needs to be exceeded for an individual streamline to be retained. Default: 0.
prob_threshold = 0

# The distance that a streamline node has to be from the waypoint ROI in order to be included or excluded. If set to None (default), will be calculated as the center-to-corner distance of the voxel in the diffusion data. If a bundle has inc_addtol or exc_addtol in its bundle_dict, that tolerance will be added to this distance. For example, if you wanted to increase tolerance for the right arcuate waypoint ROIs by 3 each, you could make the following modification to your bundle_dict: bundle_dict["Right Arcuate"]["inc_addtol"] = [3, 3] Additional tolerances can also be negative. Default: None.
dist_to_waypoint = ""

# If None, creates RandomState. If int, creates RandomState with seed rng. Used in RecoBundles Algorithm. Default: None.
rng = ""

# Whether to return the indices in the original streamlines as part of the output of segmentation. Default: False.
return_idx = false

# Whether to filter the bundles based on their endpoints. Default: True.
filter_by_endpoints = true

# If filter_by_endpoints is True, this is the required distance from the endpoints to the atlas ROIs. Default: 4
dist_to_atlas = 4

# The full path to a folder into which intermediate products are saved. Default: None, means no saving of intermediates.
save_intermediates = "None, means no saving of intermediates"

# Cleaning params to pass to seg.clean_bundle. This will override the default parameters of that method. However, this can be overridden by setting the cleaning parameters in the bundle_dict. Default: {}.
cleaning_params = "{}"

# Number of streamlines to preprocess at a time. The full tractogram is processed in chunks of this size to keep peak memory bounded. Per-chunk surviving candidates are merged before the global per-bundle filtering steps run. Default: 1e6.
chunk_size = 1000000.0

[CLEANING_PARAMS]

# A whole-brain tractogram to be segmented.
tg = ""

# Number of points to resample streamlines to. Default: 100
n_points = 100

# Number of rounds of cleaning based on the Mahalanobis distance from the mean of extracted bundles. Default: 5
clean_rounds = 5

# Threshold of cleaning based on the Mahalanobis distance (the units are standard deviations). Default: 4.
distance_threshold = 4

# Threshold for cleaning based on length (in standard deviations). Length of any streamline should not be *more* than this number of stdevs from the mean length.
length_threshold = ""

# Number of streamlines in a bundle under which we will not bother with cleaning outliers. Default: 20.
min_sl = 20

# The statistic of each node relative to which the Mahalanobis is calculated. Default: `np.mean` (but can also use median, etc.)
stat = "`np.mean` (but can also use median, etc.)"

# If non-zero, only the core of the bundle is used for cleaning. The core is defined as the middle 60% of each streamline, thus our default is 0.6. This means streamlines are allowed to deviate in the starting and ending 20% of the bundle. This is useful for allowing more diverse endpoints. Default: 0.6
core_only = 0.6

# Whether to return indices in the original streamlines. Default: False.
return_idx = false

# Specifies which streamlines to remove based on their length. Options are "long" (remove long streamlines), "short" (remove short streamlines), or "both" (remove both long and short streamlines). Default: "long"
remove_lengths = "long"

[STRUCTURAL]

# The number of threads to use for Numba and DIPY tracking. If None, uses the number of available CPUs minus one. Default: None
numba_n_threads = ""

# Whether to use low-memory versions of algorithms where available. Default: False
low_memory = false

# The execution provider to use for onnx models. By default this is set to CPUExecutionProvider which should work on all systems. If you have a compatible GPU and the appropriate onnxruntime installed you can set this to "CUDAExecutionProvider" or "OpenVINOExecutionProvider" for potentially faster inference. Default: "CPUExecutionProvider"
onnx_execution_provider = "CPUExecutionProvider"

# The number of inter threads to use for onnx models. Increasing will increase memory usage significantly. Default: 1
onnx_inter_threads = 1

# This will be used to create the brain mask, which gets applied before registration to a template. If you want no brain mask to be applied, use FullImage. If None, use Brainchop Mindgrab model. Default: None
brain_mask_definition = ""

[DATA]

# Minimum b value you want to use from the dataset (other than b0), inclusive. If None, there is no minimum limit. Default: -np.inf
min_bval = -inf

# Maximum b value you want to use from the dataset (other than b0), inclusive. If None, there is no maximum limit. Default: np.inf
max_bval = inf

# The value of b under which it is considered to be b0. Default: 50.
b0_threshold = 50

# The minimum value of b0 to consider when doing the division. This is to avoid dividing by small numbers. Default: 1e-2
min_b0_for_r1_approximation = 0.01

# Whether to use robust_tensor_fitting when doing dti. Only applies to dti. Default: False
robust_tensor_fitting = false

# The response function to be used by CSD, as a tuple with two elements. The first is the eigen-values as an (3,) ndarray and the second is the signal value for the response function without diffusion-weighting (i.e. S0). If not provided, auto_response will be used to calculate these values. Default: None
csd_response = ""

# If None, infer the number of parameters from the number of data volumes, but no larger than 8. Default: None
csd_sh_order_max = ""

# weight given to the constrained-positivity regularization part of the deconvolution equation. Default: 1
csd_lambda_ = 1

# threshold controlling the amplitude below which the corresponding fODF is assumed to be zero. Ideally, tau should be set to zero. However, to improve the stability of the algorithm, tau is set to tau*100 percent of the mean fODF amplitude (here, 10 percent by default) (see [1]_). Default: 0.1
csd_tau = 0.1

# The threshold on the FA used to calculate the single shell auto response. Can be useful to reduce for baby subjects. Default: 0.7
csd_fa_thr = 0.7

# Diffusion sampling length. Default: 1.2
gq_sampling_length = 1.2

# Able to take response[0] from auto_response_ssst. default: array([0.0017, 0.0002, 0.0002])
rumba_wm_response = ""

# Mean diffusivity for GM compartment. If None, then grey matter volume fraction is not computed. Default: 0.8e-3
rumba_gm_response = 0.0008

# Mean diffusivity for CSF compartment. If None, then CSF volume fraction is not computed. Default: 3.0e-3
rumba_csf_response = 0.003

# Number of iterations for fODF estimation. Must be a positive int. Default: 600
rumba_n_iter = 600

# Spherical harmonics order for OPDT model. Must be even. Default: 8
opdt_sh_order_max = 8

# Spherical harmonics order for CSA model. Must be even. Default: 8
csa_sh_order_max = 8

# This input is to refine kurtosis maxima under the precision of the directions sampled on the sphere class instance. The gradient of the convergence procedure must be less than gtol before successful termination. If gtol is None, fiber direction is directly taken from the initial sampled directions of the given sphere object. Default: 1e-2
gtol = 0.01

# A dictionary or BundleDict for use in segmentation. See `Defining Custom Bundle Dictionaries` in the `usage` section of pyAFQ's documentation for details. If None, will get all appropriate bundles for the chosen segmentation algorithm. Default: None
bundle_info = ""

# The target image data for registration. Can either be a Nifti1Image, a path to a Nifti1Image, or if "mni_T2", "dti_fa_template", "hcp_atlas", or "mni_T1", image data will be loaded automatically. If "hcp_atlas" is used, slr registration will be used and reg_subject should be "subject_sls". Default: "mni_T1"
reg_template_spec = "mni_T1"

# Name to use in file names for the template space. Default: "mni"
reg_template_space_name = "mni"

[TISSUE]

# Method to use for PVE estimation. Can be a string defining a built-in method from neural networks, or a Definition object to import the PVE. Importing a PVE from software like Freesurfer or FSL FAST is recommended if they are available. The built-in methods are "synthseg" or "multiaxial+brainchop". "synthseg" uses SynthSeg2 [1] to get the PVE. "multiaxial+brainchop" uses MultiAxial [2] and BrainChop [3] segmentations to get the PVE. Note this requires downloading the pre-trained multi-axial model which is licensed with Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International. Default: "synthseg"
pve = "synthseg"

# Spherical harmonic order to use for the MSMT CSD fit. Default: 8
msmt_sh_order = 8

# The threshold on the FA used to calculate the multi shell auto response. Can be useful to reduce for baby subjects. Default: 0.7
msmt_fa_thr = 0.7

[MAPPING]

# This defines how to either create a mapping from each subject space to template space or load a mapping from another software. If creating a map, will register reg_subject and reg_template. If None, use SynMap() Default: None
mapping_definition = ""

# The source image data to be registered. Can either be a Nifti1Image, an ImageFile, or str. if "b0", "dti_fa_subject", "subject_sls", "t1w", or "power_map," image data will be loaded automatically. If "subject_sls" is used, slr registration will be used and reg_template should be "hcp_atlas". Default: "t1w"
reg_subject_spec = "t1w"

[SEGMENTATION]

# How to weight each streamline (1D) or each node (2D) when calculating the tract-profiles. If callable, this is a function that calculates weights. If None, no weighting will be applied. If "gauss", gaussian weights will be used. If "median", the median of values at each node will be used instead of a mean or weighted mean. Default: "gauss"
profile_weights = "gauss"

# Number of points to resample each streamline to before calculating the tract-profiles. Default: 100
n_points_profile = 100

# List of scalars to use. Can be any of: "dti_fa", "dti_md", "dki_fa", "dki_md", "dki_awf", "dki_mk", or other scalars found in AFQ.tasks.data. Can also be a scalar from AFQ.definitions.image. Finally, can also be "t1w". Defaults for single shell data to ["dti_fa", "dti_md", "t1w"], and for multi-shell data to ["dki_fa", "dki_md", "dki_kfa", "dki_mk", "t1w"]. Default: ['dti_fa', 'dti_md', 't1w']
scalars = ""

[TRACTOGRAPHY]

# BIDS filters for inputing a user made tractography file, or a path to the tractography file. If None, DIPY is used to generate the tractography. Default: None
import_tract = ""

[VIZ]

# Of the form (lower bound, upper bound). Shading based on shade_by_volume will only differentiate values within these bounds. If lower bound is None, will default to 0. If upper bound is None, will default to the maximum value in shade_by_volume. Default: [None, None]
sbv_lims_bundles = ""

# Opacity of volume slices. Default: 0.3
volume_opacity_bundles = 0.5

# n_points to resample streamlines to before plotting. If None, no resampling is done. Default: 40
n_points_bundles = 40

# Of the form (lower bound, upper bound). Shading based on shade_by_volume will only differentiate values within these bounds. If lower bound is None, will default to 0. If upper bound is None, will default to the maximum value in shade_by_volume. Default: [None, None]
sbv_lims_indiv = ""

# Opacity of volume slices. Default: 0.3
volume_opacity_indiv = 0.5

# n_points to resample streamlines to before plotting. If None, no resampling is done. Default: 40
n_points_indiv = 40

# Which visualization backend to use. See Visualization Backends page in documentation for details https://tractometry.org/pyAFQ/reference/viz_backend.html One of {"fury", "plotly", "plotly_no_gif"}. Default: "plotly_no_gif"
viz_backend_spec = "plotly_no_gif"

pyAFQ will store a copy of the configuration file alongside the computed results. Note that the title variable and [metadata] section are both for users to enter any title/metadata they would like and pyAFQ will generally ignore them.