dwi_eddy_qc#

qx_utilities.bash.dwi_eddy_qc(sessionsfolder, session, eddybase, eddyidx, eddyparams, mask, bvalsfile, overwrite, bvecsfile, list, groupvar, update, report='individual', eddypath='<study_folder>/<session>/hcp/<session>/Diffusion/eddy/', outputdir='<eddyBase>.qc')#

dwi_eddy_qc

This function is based on FSL's eddy to perform quality control on diffusion MRI (dMRI) datasets. It explicitly assumes the that eddy has been run and that EDDY QC by Matteo Bastiani, FMRIB has been installed.

For full documentation of the EDDY QC please examine the README file.

The function assumes that eddy outputs are saved in the following folder:

<folder_with_sessions>/<session>/hcp/<session>/Diffusion/eddy/

Parameters

--sessionsfolder (str):

Path to study folder that contains sessions.

--session (str):

Session ID to run EDDY QC on.

--eddybase (str):

This is the basename specified when running EDDY (e.g. eddy_unwarped_images)

--eddyidx (str):

EDDY index file.

--eddyparams (str):

EDDY parameters file.

--mask (str):

Binary mask file (most qc measures will be averaged across voxels labeled in the mask).

--bvalsfile (str):

bvals input file.

--report (str, default 'individual'):

If you want to generate a group report ('individual' or 'group').

--overwrite (str):

Delete prior run for a given session.

--eddypath (str, default '<study_folder>/<session>/hcp/<session>/Diffusion/eddy/'):

Specify the relative path of the eddy folder you want to use for inputs.

--bvecsfile (str):

If specified, the tool will create a bvals_no_outliers.txt and a bvecs_no_outliers.txt file that contain the bvals and bvecs of the non-outlier volumes, based on the MSR estimates,

--list (str):

Text file containing a list of qc.json files obtained from SQUAD. If --report='group', then this argument needs to be specified.

--groupvar (str):

Text file containing extra grouping variable. Extra optional input if --report='group'.

--outputdir (str, default '<eddyBase>.qc'):

Output directory. Extra optional input if --report='group'.

--update (str):

Applies only if --report='group' - set to <true> to update existing single session qc reports.

Output files

Outputs for individual run:

  • qc.pdf ... single session QC report

  • qc.json ... single session QC and data info

  • vols_no_outliers.txt ... text file that contains the list of the non-outlier volumes (based on eddy residuals)

Outputs for group run:

  • group_qc.pdf ... single session QC report

  • group_qc.db ... database

Notes

  • Input: requires hcp_diffusion runs (eddy outputs here: <study_folder>/<session>/hcp/<session>/T1w/Diffusion/eddy) and hcp_pre_freesurfer-hcp_post_freesurfer to have run successfully

  • Output for individual run: /<study>/sessions/<session>/hcp/<session>/T1w/Diffusion/eddy/eddy_unwarped_images.qc

    • qc.pdf: single session QC report

    • qc.json: single session QC and data info

    • vols_no_outliers.txt: text file that contains the list of the non-outlier volumes (based on eddy residuals)

  • Output for group run: /<study>/sessions/<session>/hcp/<session>/T1w/Diffusion/eddy/eddy_unwarped_images.qc

    • group_qc.pdf: single session QC report

    • group_qc.db: database

  • Log Location: logs are created in /<study>/sessions/<session>/hcp/<session>/T1w/Diffusion/eddy/log_eddyqc

    • Run progress and error information will be logged in this folder

Examples

qunex dwi_eddy_qc \
    --sessionsfolder='<path_to_study_folder_with_session_directories>' \
    --session='<session_id>' \
    --eddybase='<eddy_base_name>' \
    --report='individual' \
    --bvalsfile='<bvals_file>' \
    --mask='<mask_file>' \
    --eddyidx='<eddy_index_file>' \
    --eddyparams='<eddy_param_file>' \
    --bvecsfile='<bvecs_file>' \
    --overwrite='yes'

Individual run example (this command runs QC on dMRI eddy outputs):

qunex dwi_eddy_qc \
    --path='<path_to_study_folder_with_session_directories>' \
    --session='<session_id>' \
    --eddybase='<eddy_base_name>' \
    --report='individual' \
    --bvalsfile='<bvals_file>' \
    --mask='<mask_file>' \
    --eddyidx='<eddy_index_file>' \
    --eddyparams='<eddy_param_file>' \
    --bvecsfile='<bvecs_file>' \
    --overwrite='yes' \
    --scheduler='<name_of_scheduler_and_options>'

Group run example (this command runs QC on dMRI eddy outputs):

qunex dwi_eddy_qc \
    --path='<path_to_study_folder_with_session_directories>'                 --session='<session_id>'                 --list=<group_list_input>                 --eddybase='<eddy_base_name>'                 --report='individual'
    --bvalsfile='<bvals_file>'                 --mask='<mask_file>'                 --eddyidx='<eddy_index_file>'                 --eddyparams='<eddy_param_file>'                 --bvecsfile='<bvecs_file>'                 --overwrite='yes'                 --scheduler='<name_of_scheduler_and_options>'