dwi_legacy_gpu#

qx_utilities.bash.dwi_legacy_gpu(sessions, echospacing, pedir, unwarpdir, usefieldmap, diffdatasuffix, overwrite, te, sessionsfolder='.', nogpu='no')#

dwi_legacy_gpu

This function runs the DWI preprocessing using the FUGUE method for legacy data that are not TOPUP compatible.

It explicitly assumes the the Human Connectome Project folder structure for preprocessing.

DWI data needs to be in the following folder:

<study_folder>/<session>/hcp/<session>/unprocessed/Diffusion

T1w data needs to be in the following folder:

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

Warning

  • If PreFreeSurfer component of the HCP Pipelines was run the function will make use of the T1w data [Results will be better due to superior brain stripping].

  • If PreFreeSurfer component of the HCP Pipelines was NOT run the function will start from raw T1w data [Results may be less optimal]. -

Parameters

--sessionsfolder (str, default '.'):

Path to study data folder.

--sessions (str):

Comma separated list of sessions to run.

--echospacing (str):

EPI Echo Spacing for data [in msec]; e.g. 0.69.

--pedir (int):

Use 1 for Left-Right Phase Encoding, 2 for Anterior-Posterior.

--unwarpdir (str):

Direction for EPI image unwarping; e.g. 'x' or 'x-' for LR/RL, 'y' or 'y-' for AP/PA; may been to try out both -/+ combinations.

--usefieldmap (str):

Whether to use the standard field map ('yes' | 'no'). If set to <yes> then the parameter --te becomes mandatory.

--diffdatasuffix (str):

Name of the DWI image; e.g. if the data is called <session>_DWI_dir91_LR.nii.gz - you would enter DWI_dir91_LR. If you provide multiple suffixes, QuNex will merge the images along with their bvals and bvecs and run processing on the merged image.

--overwrite (str):

Delete prior run for a given session ('yes' | 'no').

--te (float):

This is the echo time difference of the fieldmap sequence - find this out form the operator - defaults are usually 2.46ms on SIEMENS.

--nogpu (flag, default 'no'):

If set, this command will be processed useing a CPU instead of a GPU.

Output files

  • difffolder=${sessionsfolder}/${session}/hcp/${session}/Diffusion

  • t1wdifffolder=${sessionsfolder}/${session}/hcp/${session}/T1w/Diffusion

$difffolder/rawdata
$difffolder/eddy
$difffolder/data
$difffolder/reg
$t1wdifffolder

Notes

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

NOTE: CUDA libraries need to be loaded for this command to work, to do this you usually need to load the appropriate module on HPC systems. When scheduling for example, add the bash parameter to the command call, e.g.:

--bash="module load CUDA/11.3.1"

qunex dwi_legacy_gpu \
    --sessionsfolder='<folder_with_sessions>' \
    --sessions='<comma_separarated_list_of_cases>' \
    --pedir='1' \
    --echospacing='0.69' \
    --te='2.46' \
    --unwarpdir='x-' \
    --diffdatasuffix='DWI_dir91_LR' \
    --usefieldmap='yes' \
    --overwrite='yes'

Example with flagged parameters for submission to the scheduler using Siemens FieldMap (needs GPU-enabled queue):

qunex dwi_legacy_gpu \
    --sessionsfolder='<folder_with_sessions>' \
    --sessions='<comma_separarated_list_of_cases>' \
    --pedir='1' \
    --echospacing='0.69' \
    --te='2.46' \
    --unwarpdir='x-' \
    --diffdatasuffix='DWI_dir91_LR' \
    --usefieldmap='yes' \
    --overwrite='yes' \
    --bash="module load CUDA//11.3.1" \
    --scheduler='<name_of_scheduler_and_options>'

Example with disabled GPU processing:

qunex dwi_legacy_gpu \
    --sessionsfolder='<folder_with_sessions>' \
    --sessions='<comma_separarated_list_of_cases>' \
    --diffdatasuffix='DWI_dir91_LR' \
    --usefieldmap='no' \
    --pedir='1' \
    --echospacing='0.69' \
    --unwarpdir='x-' \
    --overwrite='yes' \
    --nogpu='yes'