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".
preproc_pipeline = "all"

# 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 = "{}"

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

# How tracking directions are determined. One of: {"det" | "prob"} Default: "prob"
directions = "prob"

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

# The discretization of direction getting. default: dipy.data.default_sphere.
sphere = "dipy.data.default_sphere"

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

# 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: 1
n_seeds = 1

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

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

# If array: A float or binary mask that determines a stopping criterion (e.g. FA). If tuple: it contains a sequence that is interpreted as: (pve_wm, pve_gm, pve_csf), each item of which is either a string (full path) or a nibabel img to be used in particle filtering tractography. A tuple is required if tracker is set to "pft". Defaults to no stopping (all ones).
stop_mask = ""

# If float, this a value of the stop_mask below which tracking is terminated (and stop_mask has to be an array). If str, "CMC" for Continuous Map Criterion [Girard2014]_. "ACT" for Anatomically-constrained tractography [Smith2012]_. A string is required if the tracker is set to "pft". Defaults to 0 (this means that if no stop_mask is passed, we will stop only at the edge of the image).
stop_threshold = ""

# Interpret seed_threshold and stop_threshold as percentages of the total non-nan voxels in the seed and stop 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 miminal length (mm) in a streamline. Default: 20
minlen = 20

# The miminal 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"}. If a Definition, we assume it is a definition of a file containing Spherical Harmonics coefficients. Defaults to use "CSD"
odf_model = ""

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

# Whether to use the legacy implementation of the direction getter. See Dipy documentation for more details. Default: True
legacy = true

# Which strategy to use in tracking. This can be the standard local tracking ("local") or Particle Filtering Tracking ([Girard2014]_). One of {"local", "pft"}. Default: "local"
tracker = "local"

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

[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. Default: False
nb_points = false

# Subsample streamlines to nb_streamlines. If False, no subsampling is don. Default: False
nb_streamlines = false

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

# How to parallelize segmentation across processes when performing waypoint ROI segmentation. Set to {"engine": "serial"} to not perform parallelization. Some engines may cause errors, depending on the system. See ``dipy.utils.parallel.paramap`` for details. Default: {"engine": "serial"}
parallel_segmentation = "{'engine': 'serial'}"

# 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 overriden by setting the cleaning parameters in the bundle_dict. Default: {}.
cleaning_params = "{}"

[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: 3.
distance_threshold = 3

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

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

[DATA]

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

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

# Whether to filter the DWI data based on min or max bvals. Default: True
filter_b = true

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

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

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

# 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 = "array([0.0017, 0.0002, 0.0002])"

# 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 = 8

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

# The sphere providing sample directions for the initial search of the maximal value of kurtosis. Default: 'repulsion100'
sphere = "repulsion100"

# 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

# 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 B0Image() Default: None
brain_mask_definition = ""

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

[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", 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: "power_map"
reg_subject_spec = "power_map"

[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". Can also be a scalar from AFQ.definitions.image. Defaults for single shell data to ["dti_fa", "dti_md"], and for multi-shell data to ["dki_fa", "dki_md"]. Default: ['dti_fa', 'dti_md']
scalars = "['dti_fa', 'dti_md']"

[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 = ""

# Number of GPUs to use in tractography. If non-0, this algorithm is used for tractography, https://github.com/dipy/GPUStreamlines PTT, Prob can be used with any SHM model. Bootstrapped can be done with CSA/OPDT. Default: 0
tractography_ngpus = 0

# Chunk size for GPU tracking. Default: 100000
chunk_size = 100000

[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 = "[None, None]"

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

# 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 = "[None, None]"

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

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

# Whether to use a virtual fram buffer. This is neccessary if generating GIFs in a headless environment. Default: False
virtual_frame_buffer = false

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