# dMRI Connectivity¶

The wildcards {participant_id} and {session} are placeholders for the ID of the participant in the data set, and the session string defined in the data:session field, respectively. This applies to the output, as well as the logging and benchmark output files.

This task can be I/O heavy if bedpostX output images are large and have to be accessed from a remote source. To mitigate the effects on computation time, it is possible to define the io parameter in the –resources directive of snakemake. This task is given 1 io token, so if snakemake –resources io=10 is used, then at most 10 connectivity tasks can be run in parallel.

- Configuration fields
data.masks.seed

data.masks.target (optional)

data.bet_binary_mask

data.xfm

data.inv_xfm

data.samples

parameters.connectivity.dist_thresh

parameters.connectivity.c_thresh

parameters.connectivity.step_length

parameters.connectivity.n_samples

parameters.connectivity.n_steps

parameters.connectivity.loop_check

parameters.connectivity.correct_path_distribution

parameters.connectivity.cubic_transform (optional)

parameters.connectivity.pca_transform (optional)

parameters.report.compress_output (optional)

parameters.connectivity.cleanup_fsl (optional)- Output
individual/{participant_id}/probtrackx2 (temporary folder)

individual/{participant_id}/probtrackx2_{session} (temporary folder; multi-session)

individual/{participant_id}/connectivity.npz

individual/{participant_id}/connectivity_{session}.npz (temporary file; multi-session)- Logging
log/{participant_id}.connectivity_dmri.log (single-session)

log/{participant_id}.{session}.connectivity_dmri.log (multi-session)

log/{participant_id}.merge_sessions.log (multi-session)- Benchmarking
benchmarks/{participant_id}.probtrackx2.log (single-session)

benchmarks/{participant_id}.{session}.probtrackx2.log (multi-session)

benchmarks/{participant_id}.connectivity_dmri.log (single-session)

benchmarks/{participant_id}.{session}.connectivity_dmri.log (multi-session)

benchmarks/{participant_id}.merge_sessions.log (multi-session)

## Probabilistic Diffusion Tractography¶

Using FSL’s probtrackx2 a tractography analysis is run which produces sample streamlines. For more information, see the probtrackx2 documentation. This produces a folder with various output files, of which the fdt_matrix2.dot file is used for further processing.

The fdt_matrix2.dot file is a sparse FDT matrix in F-contiguous order, which is densified using the scipy package (scipy.sparse.coo_matrix and the .todense() method). This matrix is now referred to as a connectivity matrix.

## Transforms (optional)¶

A cubic transform is optionally applied to the connectivity matrix using the numpy package (numpy.power) and a power of 1/3.

Furthermore optional, a principal component analysis (PCA) transform can be applied to the connectivity matrix using the sklearn package (sklearn.decomposition.PCA). First, the scipy package is used for detrending (scipy.signal.detrend, using the ‘constant’ type of detrending). PCA then reduces the number of target features in the connectivity matrix based on the value entered as the components in the configuration file. If a component value below 1 is used, then a number of components will be returned explaining that much of the variance (i.e., for 0.95, the components explaining 95% of the variance are returned as target features). If a number at or above 1 is used, that many components are returned.

## Reordering the Matrix¶

Since the fdt_matrix2.dot is in F-contiguous order, the connectivity matrix will be reordered to C-contiguous order.
This keeps all the CBPtools output files consistent in terms of their ordering. This is done using the
cbptools.image.get_f2c_order method, which provides reordering indices using the seed mask such that an F extraction
order is turned into a C extraction order. This new order is applied to the x-axis (seed voxels) of the connectivity
matrix, but not the y-axis (as the target value ordering is not important for the remaining procedures in the
*CBPtools* workflow).

## Merge Sessions¶

If multi-session input data is used, then each participant will provide multiple connectivity matrices. These matrices are averaged and the result is used as the one connectivity matrix for that participant. Note that if multi-session data is being used, then the (optional) PCA transformation will instead be performed after the sessions have been averaged. This is necessary, as each session may return a different number of components causing the averaging to fail.