14.2.3. Taylor et al. (2024). A Set of FMRI Quality Control Tools in AFNI: Systematic, in-depth …

Introduction

Here we present commands used in the following paper:

• Taylor PA, Glen DR, Chen G, Cox RW, Hanayik T, Rorden C, Nielson DM, Rajendra JK, Reynolds RC (2024). A Set of FMRI Quality Control Tools in AFNI: Systematic, in-depth and interactive QC with afni_proc.py and more. Imaging Neuroscience 2: 1–39. doi: 10.1162/imag_a_00246

  https://www.ncbi.nlm.nih.gov/pmc/articles/PMC11382598/

Abstract: Quality control (QC) assessment is a vital part of FMRI processing and analysis, and a typically under discussed aspect of reproducibility. This includes checking datasets at their very earliest stages (acquisition and conversion) through their processing steps (e.g., alignment and motion correction) to regression modeling (correct stimuli, no collinearity, valid fits, enough degrees of freedom, etc.) for each subject. There are a wide variety of features to verify throughout any single subject processing pipeline, both quantitatively and qualitatively. We present several FMRI preprocessing QC features available in the AFNI toolbox, many of which are automatically generated by the pipeline-creation tool, afni_proc.py. These items include: a modular HTML document that covers full single subject processing from the raw data through statistical modeling; several review scripts in the results directory of processed data; and command line tools for identifying subjects with one or more quantitative properties across a group (such as triaging warnings, making exclusion criteria or creating informational tables). The HTML itself contains several buttons that efficiently facilitate interactive investigations into the data, when deeper checks are needed beyond the systematic images. The pages are linkable, so that users can evaluate individual items across group, for increased sensitivity to differences (e.g., in alignment or regression modeling images). Finally, the QC document contains rating buttons for each “QC block”, as well as comment fields for each, to facilitate both saving and sharing the evaluations. This increases the specificity of QC, as well as its shareability, as these files can be shared with others and potentially uploaded into repositories, promoting transparency and open science. We describe the features and applications of these QC tools for FMRI.

Study keywords: FMRI, EPI, MPRAGE, quality control, visualization, quantitative

Main programs: open_apqc.py, afni_proc.py, sswarper2, @ss_review_basic, @ss_review_driver, gen_ss_review_table.py, gtykd_check

Github page:

See these authors’ github page for descriptions and downloads of codes and supplementary text files:

https://github.com/afni/apaper_apqc_etal/

Download scripts

To download, either:

• ... click the link(s) in the following table (perhaps Rightclick -> “Save Link As…”):

  do_13_ssw.bash	run sswarper2 for nonlinear alignment to a template, and skullstripping of the subject’s T1w anatomical volume
  do_20_ap.tcsh	run afni_proc.py for resting state FMRI analysis; this uses nonlinear warps estimated with sswarper2

• ... or copy+paste into a terminal:

  curl -O https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/codex/fmri/media/2024_TaylorEtal/do_13_ssw.tcsh
  curl -O https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/codex/fmri/media/2024_TaylorEtal/do_20_ap.tcsh
  

View scripts

do_13_ssw.tcsh

#!/bin/tcsh

# SSW: script to run skullstripping and nonlinear alignment for a subject

# --------------------------- env vars and init ----------------------------

# compress BRIK files
setenv AFNI_COMPRESSOR GZIP

# initial exit code
set ecode = 0

# -------------------------- subject and path info -------------------------

# subject ID
set subj  = sub-002

# script label, mainly for logs
set label = 13_ssw

# supplementary datasets (here, in known directory via environment var)
set dset_ref       = MNI152_2009_template_SSW.nii.gz 

# upper (group-level) directories
set dir_inroot     = ${PWD:h}                   # one dir above scripts/
set dir_log        = ${dir_inroot}/logs         # store tee'ed info
set dir_basic      = ${dir_inroot}              # here, same dir as inroot

# subject input directories
set sdir_basic     = ${dir_basic}/${subj}
set sdir_func      = ${sdir_basic}/func
set sdir_anat      = ${sdir_basic}/anat
set sdir_events    = ${sdir_basic}/timing

# subject derivative directories
set sdir_deriv     = ${sdir_basic}/derivatives  # for all derived outputs
set sdir_ssw       = ${sdir_deriv}/ssw
set sdir_ap        = ${sdir_deriv}/ap

\mkdir -p ${dir_log}

# ----------------------- data and control variables -----------------------

# dataset inputs
set dset_anat_00 = ${sdir_anat}/${subj}_T1w.nii.gz

# control variables

# check available N_threads and report what is being used
set nthr_avail = `afni_system_check.py -disp_num_cpu`
set nthr_using = `afni_check_omp`

echo "++ INFO: Using ${nthr_using} of available ${nthr_avail} threads"

# ----------------------------- main commands ------------------------------

# run the skullstripping+warping
sswarper2                                                                    \
    -input  ${dset_anat_00}                                                  \
    -base   ${dset_ref}                                                      \
    -subid  ${subj}                                                          \
    -odir   ${sdir_ssw}                                                      \
    |&  tee ${dir_log}/log_${subj}_${label}.txt

if ( ${status} ) then
    set ecode = 2
    goto COPY_AND_EXIT
endif

echo "++ done proc ok"

# -------------------------- finish and exit -------------------------------

COPY_AND_EXIT:

if ( ${ecode} ) then
    echo "++ BAD FINISH: ${label} (ecode = ${ecode})"
else
    echo "++ GOOD FINISH: ${label}"
endif

exit ${ecode}

do_20_ap.tcsh

#!/bin/tcsh

# AP: script to run FMRI pipeline with afni_proc.py

# --------------------------- env vars and init ----------------------------

# compress BRIK files
setenv AFNI_COMPRESSOR GZIP

# initial exit code
set ecode = 0

# -------------------------- subject and path info -------------------------

# subject ID
set subj  = sub-002

# script label, mainly for logs
set label = 20_ap

# supplementary datasets (here, in known directory via environment var)
set dset_ref       = MNI152_2009_template_SSW.nii.gz 

# upper (group-level) directories
set dir_inroot     = ${PWD:h}                   # one dir above scripts/
set dir_log        = ${dir_inroot}/logs         # store tee'ed info
set dir_basic      = ${dir_inroot}              # here, same dir as inroot

# subject input directories
set sdir_basic     = ${dir_basic}/${subj}
set sdir_func      = ${sdir_basic}/func
set sdir_anat      = ${sdir_basic}/anat
set sdir_events    = ${sdir_basic}/timing

# subject derivative directories
set sdir_deriv     = ${sdir_basic}/derivatives  # for all derived outputs
set sdir_ssw       = ${sdir_deriv}/ssw
set sdir_ap        = ${sdir_deriv}/ap

\mkdir -p ${dir_log}

# ----------------------- data and control variables -----------------------

# dataset inputs
set dsets_epi       = ( ${sdir_func}/sub-002_task-avrel_run-*nii.gz )

set dset_anat_cp    = ${sdir_ssw}/anatSS.${subj}.nii
set dset_anat_skull = ${sdir_ssw}/anatU.${subj}.nii
set dsets_NL_warp   = ( ${sdir_ssw}/anatQQ.${subj}.nii       \
                        ${sdir_ssw}/anatQQ.${subj}.aff12.1D  \
                        ${sdir_ssw}/anatQQ.${subj}_WARP.nii  )

set timing_files  = ( ${sdir_events}/times.{vis,aud}.txt )
set stim_classes  = ( vis aud )

# could add separate section here for control variables in the AP
# command, like blur size, censor thresholds, etc.

# check available N_threads and report what is being used
set nthr_avail = `afni_system_check.py -disp_num_cpu`
set nthr_using = `afni_check_omp`

echo "++ INFO: Using ${nthr_using} of available ${nthr_avail} threads"

# ----------------------------- main commands ------------------------------

# 'tis convenient to run from this dir, for the supplementary outputs
\mkdir -p ${sdir_ap}
cd ${sdir_ap}

# run the FMRI pipeline creation+execution
afni_proc.py                                                                 \
    -subj_id                  ${subj}                                        \
    -dsets                    ${dsets_epi}                                   \
    -copy_anat                ${dset_anat_cp}                                \
    -anat_has_skull           no                                             \
    -anat_follower            anat_w_skull anat ${dset_anat_skull}           \
    -blocks                   tshift align tlrc volreg blur mask scale       \
                              regress                                        \
    -radial_correlate_blocks  tcat volreg regress                            \
    -tcat_remove_first_trs    2                                              \
    -align_opts_aea           -cost lpc+ZZ                                   \
                              -giant_move                                    \
                              -check_flip                                    \
    -tlrc_base                ${dset_ref}                                    \
    -tlrc_NL_warp                                                            \
    -tlrc_NL_warped_dsets     ${dsets_NL_warp}                               \
    -volreg_align_to          MIN_OUTLIER                                    \
    -volreg_align_e2a                                                        \
    -volreg_tlrc_warp                                                        \
    -volreg_compute_tsnr      yes                                            \
    -blur_size                4.0                                            \
    -mask_epi_anat            yes                                            \
    -regress_stim_times       ${timing_files}                                \
    -regress_stim_labels      ${stim_classes}                                \
    -regress_basis            'BLOCK(20,1)'                                  \
    -regress_censor_motion    0.3                                            \
    -regress_censor_outliers  0.05                                           \
    -regress_motion_per_run                                                  \
    -regress_opts_3dD         -jobs 2                                        \
                              -gltsym 'SYM: vis -aud'                        \
                              -glt_label 1 V-A                               \
                              -gltsym 'SYM: 0.5*vis +0.5*aud'                \
                              -glt_label 2 mean.VA                           \
    -regress_compute_fitts                                                   \
    -regress_make_ideal_sum   sum_ideal.1D                                   \
    -regress_est_blur_epits                                                  \
    -regress_est_blur_errts                                                  \
    -regress_run_clustsim     no                                             \
    -html_review_style        pythonic                                       \
    -execute                                                                 \
    |& tee                    ${dir_log}/log_${subj}_${label}.txt

if ( ${status} ) then
    set ecode = 2
    goto COPY_AND_EXIT
endif

echo "++ done proc ok"

# -------------------------- finish and exit -------------------------------

COPY_AND_EXIT:

if ( ${ecode} ) then
    echo "++ BAD FINISH: ${label} (ecode = ${ecode})"
else
    echo "++ GOOD FINISH: ${label}"
endif

exit ${ecode}