Parameters¶

The parameters are listed under the parameters key in the configuration file and passed to workflow tasks when needed. Importantly, not all parameters are used for each modality. In fact, some parameters may only be used if other parameters are defined in a certain way. When a parameter is set that is not used, CBPtools will warn about this in the log file, however.

Below is an example of what parameters look like in the configuration file:

parameters:
    clustering:
        method: kmeans
        n_clusters: [2, 3, 4, 5]
        cluster_options:
            algorithm: auto
            init: k-means++
            max_iter: 1000
            n_init: 256
            ...

In this snippet the clustering parameters are defined for the k-means clustering algorithm (method). The parameters:clustering:n_clusters field is required regardless of modality and clustering algorithm, although the parameters:clustering:cluster_options differ based on the selected method.

When a parameter is not required and not defined in the configuration file, the default value is used. This will cause the setup procedure to issue a warning in the log file. If no default value can be found, an error will be logged that must first be resolved before resuming the setup.

Parameter fields¶

masking:
- seed:
  binarization: float, default = 0.0, modality = [‘rsfmri’, ‘dmri’] Threshold above which voxels in the ROI mask image are defined as 1’s. This is only applied if the mask is not binary.
  
  median_filtering:
  
  apply: boolean, default = False, modality = [‘rsfmri’, ‘dmri’] Apply median filtering to the ROI mask
  
  distance: integer, default = 1, modality = [‘rsfmri’, ‘dmri’] Median filtering distance
  
  upsample_to:
  
  apply: boolean, default = False, modality = dmri Upsample the seed mask to the specified voxel size (e.g., from [3, 3, 3] as 3mm isotropic to [1, 1, 1] as 1mm isotropic). If left empty or as null, no upsampling will be done.
  
  voxel_dimensions: list[float], default = [1, 1, 1], modality = dmri The voxel dimensions to which the seed mask should be upsampled.
- target:
  binarization: float, default = 0.0, modality = [‘rsfmri’, ‘dmri’] Threshold above which voxels in the target mask image are defined as 1’s. This is only applied if the mask is not binary.
  
  remove_seed:
  
  apply: boolean, default = False, modality = [‘rsfmri’, ‘dmri’] Remove the seed voxels from the target mask.
  
  distance: integer, default = 0, modality = [‘rsfmri’, ‘dmri’] Expand the border around the seed mask (in milimeter) for removal from the target mask. This should only be applied if the input time-series data is smoothed, using the smoothing kernel as a value for this parameter.
  
  subsampling: boolean, default = True, modality = rsfmri Apply subsampling to the target mask to improve computational efficiency at minimal loss of specificity. This removes every second voxel from the mask and is only recommended if the data has been smoothed.
  
  downsample_to:
  
  apply: boolean, default = False, modality = dmri Downsample the target mask to the specified voxel size, similar to how upsample_seed_to works.
  
  voxel_dimensions: list[float], default = [3, 3, 3], modality = dmri The voxel dimensions to which the target mask should be downsampled.
connectivity:
- low_variance_error:
  apply: boolean, default = True, modality = rsfmri When more than this specified percentage of voxels within the seed has low or no variance over the entire time course, the processing for this participant will not continue. A detailed error report is provided once all connectivity is processed and further processing is halted until the problems are resolved.
  
  in_seed: float, default = 0.05, modality = rsfmri Percentage of allowed low-variance voxels occurring within the seed region.
  
  in_target: float, default = 0.1, modality = rsfmri Percentage of allowed low-variance voxels occurring within the target region.
- band_pass_filtering:
  apply: boolean, default = False, modality = rsfmri Perform band-pass filtering on the signal time-series.
  
  band: list[float], default = [0.01, 0.08], required, modality = any High- and low-pass value for the band-pass filter. Note that if this value is set, tr should also be defined.
  
  tr: float, default = None, required, modality = any Repetition time in seconds
- smoothing:
  apply: boolean, default = False, modality = rsfmri Apply smoothing on the signal time-series.
  
  fwhm: integer, default = 5, modality = rsfmri FWHM kernel value for smoothing.
- arctanh_transform:
  apply: boolean, default = True, modality = rsfmri Arctanh transform applied to the connectivity matrix
- pca_transform:
  apply: boolean, default = False, modality = [‘rsfmri’, ‘dmri’] PCA transform applied to the connectivity matrix.
  
  components: float, default = 0.95, modality = [‘rsfmri’, ‘dmri’] Number of components to keep (if integer) or amount of explained variance (if float). This value is equivalent to n_components in sklearn.decomposition.PCA
- dist_thresh: float, default = 5.0, modality = dmri (probtrackx2) Discards samples shorter than this threshold (in mm)
- loop_check: boolean, default = True, modality = dmri (probtrackx2) Perform loopchecks on paths - slower, but allows lower curvature threshold
- c_thresh: float, default = 0.2, modality = dmri (probtrackx2) Curvature threshold
- step_length: float, default = 0.5, modality = dmri (probtrackx2) Steplength in mm
- n_samples: integer, default = 5000, modality = dmri (probtrackx2) Number of samples
- n_steps: integer, default = 2000, modality = dmri (probtrackx2) Number of steps per sample
- correct_path_distribution: boolean, default = True, modality = dmri (probtrackx2) Correct path distribution for the length of the pathways
- cubic_transform:
  apply: boolean, default = True, modality = dmri Apply a cubic transformation on the connectivity matrix
- cleanup_fsl: boolean, default = True, modality = dmri Remove all files created by probtrackx2 (except fdt_matrix2.dot) after the connectivity matrix has been extracted.
clustering:
- method: string, default = kmeans, allowed = [‘kmeans’, ‘spectral’, ‘agglomerative’], modality = any Clustering method to be used, either kmeans, spectral, or agglomerative
- n_clusters: list[integer], default = [], required, modality = any A list of cluster numbers to be evaluated (entered as [2, 3, 8] to receive a 2, 3, and 8-cluster solution)
- cluster_options:
  algorithm: string, default = auto, allowed = [‘auto’, ‘full’, ‘elkan’], modality = any (sklearn.cluster.KMeans) K-means algorithm to use
  
  init: string, default = k-means++, allowed = [‘k-means++’, ‘random’], modality = any (sklearn.cluster.KMeans) Method for initialization
  
  max_iter: integer, default = 10000, modality = any (sklearn.cluster.KMeans) Maximum number of iterations of the k-means algorithm for a single run.
  
  n_init: integer, default = 256, modality = any (sklearn.cluster.KMeans or sklearn.cluster.SpectralClustering) Number of time the k-means algorithm will be run with different centroid seeds.
  
  kernel: string, default = nearest_neighbors, allowed = [‘additive_chi2’, ‘chi2’, ‘linear’, ‘polynomial’, ‘rbf’, ‘laplacian’, ‘sigmoid’, ‘cosine’, ‘nearest_neighbors’, ‘precomputed’, ‘precomputed_nearest_neighbors’], modality = any (sklearn.cluster.SpectralClustering; affinity) Kernel to be used.
  
  gamma: float, default = , modality = any (sklearn.cluster.SpectralClustering) Kernel coefficient for rbf, poly, sigmoid, laplacian and chi2 kernels. Ignored for affinity=nearest_neighbors.
  
  n_neighbors: integer, default = 10, modality = any (sklearn.cluster.SpectralClustering) Number of neighbors to use when constructing the affinity matrix using the nearest neighbors method.
  
  assign_labels: string, default = kmeans, allowed = [‘kmeans’, ‘discretize’], modality = any (sklearn.cluster.SpectralClustering) The strategy to use to assign labels in the embedding space.
  
  degree: float, default = 3.0, modality = any (sklearn.cluster.SpectralClustering) Degree of the polynomial kernel.
  
  coef0: float, default = 1.0, modality = any (sklearn.cluster.SpectralClustering) Zero coefficient for polynomial and sigmoid kernels
  
  eigen_tol: float, default = 1e-10, modality = any (sklearn.cluster.SpectralClustering) Stopping criterion for eigendecomposition of the Laplacian matrix when eigen_solver=”arpack”
  
  eigen_solver: string, default = None, allowed = [None, ‘arpack’, ‘lobpcg’, ‘amg’], modality = any (sklearn.cluster.SpectralClustering) The eigenvalue decomposition strategy to use. AMG requires pyamg to be installed
  
  distance_metric: string, default = euclidean, allowed = [‘euclidean’, ‘l1’, ‘l2’, ‘manhattan’, ‘cosine’], modality = any (sklearn.cluster.AgglomerativeClustering; affinity) Metric to compute the linkage. If linkage is “ward”, only “euclidean” is accepted.
  
  linkage: string, default = ward, allowed = [‘ward’, ‘complete’, ‘average’, ‘single’], modality = any (sklearn.cluster.AgglomerativeClustering) Which linkage criterion to use.
- grouping:
  linkage: string, default = complete, allowed = [‘complete’, ‘average’, ‘single’], modality = any (scipy.cluster.hierarchy.linkage) The linkage algorithm to use
  
  method: string, default = mode, allowed = [‘mode’, ‘agglomerative’], modality = any Method for obtaining group-level clustering results
- validity:
  internal: list[string], default = [‘silhouette_score’], allowed = [‘silhouette_score’, ‘davies_bouldin_score’, ‘calinski_harabasz_score’], modality = any List of internal validity metrics to assess
  
  similarity: string, default = adjusted_rand_score, allowed = [‘adjusted_rand_score’, ‘adjusted_mutual_info_score’, ‘v_measure_score’], modality = any Similarity metric to use to generate between-subject cluster comparisons and subject to group-level cluster comparisons
report:
- figure_format: string, default = png, allowed = [‘png’, ‘svg’, ‘pdf’, ‘ps’, ‘eps’], modality = any Format of the output figures generated for the summary
- individual_plots: boolean, default = False, modality = any Provide cluster-labeled ROI voxel plots for each individual subjects
- benchmark: boolean, default = False, modality = any benchmark the execution of each workflow task
- compress_output: boolean, default = True, modality = any Compress interim output (i.e., NIfTI images and NumPy arrays) to reduce the file size. This comes at the cost of slower processing speed.