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