dwi_probtrackx_dense_gpu

qx_utilities.bash.dwi_probtrackx_dense_gpu(sessionsfolder, sessions, omatrix1, omatrix3, scriptsfolder, loopcheck, forcedir, overwrite='no', nsamplesmatrix1='10000', nsamplesmatrix3='3000', distancecorrection='no', storestreamlineslength='no', forcematrix1='no', fibthresh='0.01', c='0.2', sampvox='2', randfib='1', S='2000', steplength='0.5')

dwi_probtrackx_dense_gpu

This function runs the probtrackxgpu dense whole-brain connectome generation by calling ${ScriptsFolder}/run_matrix1.sh or ${ScriptsFolder}/run_matrix3.sh.

Warning

It explicitly assumes the Human Connectome Project folder structure and completed dwi_bedpostx_gpu and dwi_pre_tractography functions processing:

• HCP Pipelines

• FSL 5.0.9 or greater

Processed DWI data needs to be here:

<study_folder>/<session>/hcp/<session>/T1w/Diffusion

BedpostX output data needs to be here:

<study_folder>/<session>/hcp/<session>/T1w/Diffusion.bedpostX

T1w images need to be in MNINonLinear space here:

<study_folder>/<session>/hcp/<session>/MNINonLinear

Parameters

--sessionsfolder (str):

Path to study folder that contains sessions.

--sessions (str):

Comma separated list of sessions to run.

--overwrite (str, default 'no'):

Whether to overwrite existing data (yes) or not (no). Note that previous data is deleted before the run, so in the case of a failed command run, previous results are lost.

--omatrix1 (str):

Specify if you wish to run matrix 1 model [yes or omit flag]

--omatrix3 (str):

Specify if you wish to run matrix 3 model [yes or omit flag]

--nsamplesmatrix1 (str, default '10000'):

Number of samples.

--nsamplesmatrix3 (str, default '3000'):

Number of samples.

--distancecorrection (str, default 'no'):

Use distance correction.

--storestreamlineslength (str, default 'no'):

Store average length of the streamlines.

--forcematrix1 (str, default 'no'):

Whether to force matrix1 model calculation when storestreamlineslength is set to yes. This is not advice, as it can lead to erroneous path length calculations.

--scriptsfolder (str):

Location of the probtrackX GPU scripts.

--loopcheck (flag):

Generic parameter set by default (will be parameterized in the future).

--forcedir (flag):

Generic parameter set by default (will be parameterized in the future).

--fibthresh (str, default '0.01'):

Generic parameter set by default (will be parameterized in the future).

--c (str, default '0.2'):

Generic parameter set by default (will be parameterized in the future).

--sampvox (str, default '2'):

Generic parameter set by default (will be parameterized in the future).

--randfib (str, default '1'):

Generic parameter set by default (will be parameterized in the future).

--S (str, default '2000'):

Generic parameter set by default (will be parameterized in the future).

--steplength (str, default '0.5'):

Generic parameter set by default (will be parameterized in the future).

Output files

Dense Connectome CIFTI Results in MNI space for Matrix1 will be here:

<study_folder>/<session>/hcp/<session>/MNINonLinear/Results/Conn1.dconn.nii.gz

Dense Connectome CIFTI Results in MNI space for Matrix3 will be here:

<study_folder>/<session>/hcp/<session>/MNINonLinear/Results/Conn3.dconn.nii.gz

Notes

Use:

The function calls either of these based on the --omatrix1 and --omatrix3 flags:

$HCPPIPEDIR_dMRITractFull/tractography_gpu_scripts/run_matrix1.sh
$HCPPIPEDIR_dMRITractFull/tractography_gpu_scripts/run_matrix3.sh

Note on waytotal normalization and log transformation of streamline counts:

waytotal normalization is computed automatically as part of the run prior to any inter-session or group comparisons to account for individual differences in geometry and brain size. The function divides the dense connectome by the waytotal value, turning absolute streamline counts into relative proportions of the total streamline count in each session.

Next, a log transformation is computed on the waytotal normalized data, which will yield stronger connectivity values for longe-range projections. Log-transformation accounts for algorithmic distance bias in tract generation (path probabilities drop with distance as uncertainty is accumulated).

See Donahue et al. (2016) The Journal of Neuroscience, 36(25):6758–6770. DOI: https://doi.org/10.1523/JNEUROSCI.0493-16.2016

The outputs for these files will be in:

/<path_to_study_sessions_folder>/<session>/hcp/<session>/MNINonLinear/Results/Tractography/<MatrixName>_waytotnorm.dconn.nii
/<path_to_study_sessions_folder>/<session>/hcp/<session>/MNINonLinear/Results/Tractography/<MatrixName>_waytotnorm_log.dconn.nii

Apptainer (Singularity) and GPU support:

If nogpu is not provided, this command will facilitate GPUs to speed up processing. Since the command uses CUDA binaries, an NVIDIA GPU is required. To give access to CUDA drivers to the system inside the Apptainer (Singularity) container, you need to use the --nv flag of the qunex_container script.

Examples

Example with a scheduler and GPU processing:

qunex dwi_probtrackx_dense_gpu \
    --sessionsfolder='<path_to_study_sessions_folder>' \
    --sessions='<comma_separarated_list_of_cases>' \
    --scheduler='<name_of_scheduler_and_options>' \
    --omatrix1='yes' \
    --nsamplesmatrix1='10000' \
    --overwrite='no'

Example without GPU processing:

qunex dwi_probtrackx_dense_gpu \
    --sessionsfolder='<path_to_study_sessions_folder>' \
    --sessions='<comma_separarated_list_of_cases>' \
    --scheduler='<name_of_scheduler_and_options>' \
    --omatrix1='yes' \
    --nsamplesmatrix1='10000' \
    --overwrite='no' \
    --nogpu='yes'