run_qc_summary#

qx_utilities.processing.workflow.run_qc_summary.run_qc_summary(sinfo, options, overwrite=False, thread=0)#

run_qc_summary [... processing options]

Compile the study's quality control information into tables and a report.

Parameters

--batchfile (str, default ''):

The batch.txt file with all the session information.

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

The path to the study/sessions folder, where the imaging data is supposed to go.

--parelements (int, default 1):

How many sessions to read in parallel. The command is run once for the whole study, so this -- and not parsessions -- is the knob that speeds it up.

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

Whether to overwrite existing data (yes) or not (no). Each run writes into a folder of its own, named after the time it started, so there is normally nothing to overwrite.

--logfolder (str, default ''):

The path to the folder where logs are to be stored, if other than default.

--bolds (str, default 'all'):

Which bold images (as they are specified in the batch.txt file) to report on. It can be a single type (e.g. 'task'), a pipe separated list (e.g. 'WM|Control|rest') or 'all' to report on all.

--boldname (str, default 'bold'):

The default name of the bold files in the images folder.

--nifti_tail (str, default ''):

The tail of NIfTI volume images to use. It selects the .bstats and .scrub files the BOLD statistics are read from.

--cifti_tail (str, default ''):

The tail of CIFTI images to use. It selects the dense timeseries the temporal SNR and cortical coverage are read from.

--bold_variant (str, default ''):

Optional variant of bold preprocessing. If specified, the BOLD images in images/functional<bold_variant> will be reported on.

--img_suffix (str, default ''):

Specifies a suffix for 'images' folder to enable support for multiple parallel workflows. Empty if not used.

--hcp_suffix (str, default ''):

Specifies a suffix for the session's folder in the HCP folder, if the data is processed in multiple ways.

--mov_bad (str, default 'udvarsme'):

Which criterion to report bad frames by. The value names a column of the .scrub file that compute_bold_stats wrote, so the frames reported here are the frames preprocessing itself excluded:

'mov' ... Frame displacement threshold (fdt) is exceeded.
'dvars' ... Image intensity normalized root mean squared error (RMSE) threshold (dvarsmt) is exceeded.
'dvarsme' ... Median normalised RMSE threshold (dvarsmet) is exceeded.
'idvars' ... Both fdt and dvarsmt are exceeded (i for intersection).
'idvarsme' ... Both fdt and dvarsmet are exceeded.
'udvars' ... Either fdt or dvarsmt are exceeded (u for union).
'udvarsme' ... Either fdt or dvarsmet are exceeded (default).

For more detailed description please see wiki entry on Movement scrubbing.

--mov_fd (float, default 0.5):

Frame displacement threshold (in mm) to report bad frames by. Given explicitly, it overrides the threshold compute_bold_stats used and the frame counts are recomputed and marked as exploratory.

--mov_dvars (float, default 3.0):

The (mean normalized) dvars threshold to report bad frames by. As with --mov_fd, giving it explicitly recomputes the counts.

--mov_dvarsme (float, default 1.5):

The (median normalized) dvarsm threshold to report bad frames by. As with --mov_fd, giving it explicitly recomputes the counts.

--mov_before (int, default 0):

How many frames before each frame identified as bad to also count as bad, when the counts are recomputed.

--mov_after (int, default 0):

How many frames after each frame identified as bad to also count as bad, when the counts are recomputed.

--qc_summary_modules (str, default 'prefs fs postfs bold dwi'):

Which processing stages to compile information for. A space, comma or pipe separated list of:

'prefs' ... Registration to MNI, from the PreFreeSurfer warp.
'fs' ... The FreeSurfer recon, in native space.
'postfs' ... The fs_LR surface registration and myelin maps.
'bold' ... BOLD movement, scrubbing, temporal SNR and coverage.
'dwi' ... Diffusion, from the FSL eddy QC report.

--qc_summary_report (str, default 'yes'):

Whether to build the interactive HTML report (yes) or to write the tables alone (no).

--qc_summary_tsnr (str, default 'yes'):

Whether to compute BOLD temporal SNR and cortical coverage (yes) or not (no). This reads every dense timeseries and is the slowest part of the command.

--qc_summary_warp_jac (str, default 'yes'):

Whether to compute the Jacobian determinant of the PreFreeSurfer warp (yes) or not (no). Requires FSL; without it the columns are left blank.

--qc_summary_mni_template (str, default ''):

The path to an MNI template to compute registration similarity against. Without it, similarity is computed against the study's own group mean alone.

--qc_summary_diag_k (float, default 3.0):

The robust standard deviation threshold at which a session's value is called atypical for the study when localising the likely failure step. Lower is more sensitive.

Returns

--log (ReportLog):: The command's log object, carrying its report and its status.

Notes

Use:

run_qc_summary reads the quality control information the processing pipelines have already written for every session of the study, and compiles it into one place. It is a reporting command: it computes no new imaging results and modifies nothing it reads.

Each run writes a folder of its own, named after the time it started, into the study's QC folder:

<sessionsfolder>/QC/qc_summary_<YYYY-MM-DD_HH.MM.SS>/

Because the folder is named after the run, results of several runs sit side by side and nothing is ever overwritten. Two runs started within the same second would name the same folder, so the second of them takes a _2 suffix, the third a _3, and so on.

Missing data:

A session that has not reached a processing stage, or whose files cannot be read, contributes blank columns for that stage and a warning in the log. It is never dropped from the tables and it never fails the command: which sessions are missing what is one of the things the summary is for.

Examples

Using the defaults:

qunex run_qc_summary \
    --batchfile=processing/batch.txt \
    --sessionsfolder=sessions

Reading eight sessions at a time, without the slow temporal SNR pass:

qunex run_qc_summary \
    --batchfile=processing/batch.txt \
    --sessionsfolder=sessions \
    --parelements=8 \
    --qc_summary_tsnr=no

The structural stages alone, tables only:

qunex run_qc_summary \
    --batchfile=processing/batch.txt \
    --sessionsfolder=sessions \
    --qc_summary_modules="prefs fs postfs" \
    --qc_summary_report=no

QuNex documentation

run_qc_summary

run_qc_summary#