hcp_run_qc#

qx_utilities.hcp.qc_hcp.hcp_run_qc(sinfo, options, overwrite=False, thread=0)#

hcp_run_qc [... processing options]

Run visual QC for a session.

Parameters

--qc_modality (str, default 'BOLD'):

One or more modalities to run QC for, as a comma-separated list (e.g. 'BOLD,T1w,DWI'). Supported: 'rawNII', 'BOLD', 'BOLD_FC', 'T1w', 'T2w', 'myelin', 'general', 'DWI'. Modalities (and, within BOLD/BOLD_FC, the individual runs) are processed in parallel (see Notes).

--qc_outpath (str, default '<sessionsfolder>/QC/<modality>'):

Output folder for QC artifacts. With multiple modalities and an explicit path, a per-modality subfolder is used.

--qc_scenetemplatefolder (str, default '<QUNEXPATH>/qx_library/data/scenes/qc'):

Folder containing the Workbench scene templates.

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

If 'yes', also create a self-contained Workbench scene zip and copy it into <hcp>/qc/ (or the session's qc/ folder for the 'general' modality).

--timestamp (str, default now):

Timestamp suffix for the generated outputs.

--parelements (int, default 1):

Number of QC jobs to run in parallel within a session (see Notes). A job is a single non-BOLD modality, a single BOLD run, or a single BOLD_FC run/type.

--hcp_suffix (str, default ''):

Optional suffix for HCP folder naming (matches the bash --hcp_suffix).

--on_existing (str, default 'leave'):

Policy for pre-existing QC outputs of the requested modalities:

'leave' ... do nothing special; per-file recompute is still governed by --overwrite.
'skip' ... if outputs already exist for a modality/run, skip it.
'delete' ... remove existing outputs for a modality/run before running.

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

If 'yes', skip the default template scene(s) for the requested modalities and only render user/custom scenes (see --qc_userscenefile / --qc_processcustom).

--qc_userscenefile (str, default ''):

A user-supplied scene template to render (in addition to the defaults). May be an absolute path or a bare name resolved against --qc_userscenepath (or the template folder). Non-BOLD user scenes are rendered with the common DUMMYPATH/DUMMYCASE/DUMMYTIMESTAMP/DUMMYPNGNAME substitutions; BOLD user scenes are rendered as full BOLD QC (with TSNR).

--qc_userscenepath (str, default ''):

Folder for --qc_userscenefile when it is given as a bare name.

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

If 'yes', also render every *.scene under <studyfolder>/processing/scenes/QC/<modality> for each requested modality.

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

Which BOLDs to run QC for (BOLD and BOLD_FC modalities). Follows the standard selection rules; may be numbers, tags, or 'all'.

--hcp_bold_prefix (str, default ''):

Prefix used for HCP BOLD names (e.g. BOLD_ for BOLD_1). With hcp_filename=userdefined the filename from the batch file is used.

--hcp_cifti_tail (str, default ''):

CIFTI tail used in .dtseries naming (e.g. '_Atlas'). If empty, the code attempts to infer it by globbing (BOLD modality).

--qc_bold_skipframes (int, default 0):

Number of initial frames to omit from the GS plot range (BOLD modality).

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

If 'yes', compute the TSNR report only and skip scene/png (BOLD modality).

--qc_boldfc (str, default 'pscalar,pconn'):

Which BOLD FC map type(s) to QC for the BOLD_FC modality: 'pscalar', 'pconn', or both (comma-separated, or 'both'). The two are not mutually exclusive. Only used when 'BOLD_FC' is in --qc_modality.

--qc_boldfcinput (str, default ''):

Generic FC input file name after the 'bold<N>_' prefix, e.g. 'Atlas_hpss_res-mVWMWB_lpss_CAB-NP-718_r_Fz_GBC.pscalar.nii'. Used for a requested FC type unless a type-specific input is provided below.

--qc_boldfcpscalarinput (str, default ''):

FC input file name (after 'bold<N>_') for the 'pscalar' type. Overrides --qc_boldfcinput for pscalar; required when running both types.

--qc_boldfcpconninput (str, default ''):

FC input file name (after 'bold<N>_') for the 'pconn' type. Overrides --qc_boldfcinput for pconn; required when running both types.

--qc_boldfcpath (str, default '<sessionsfolder>/<session>/images/functional'):

Folder holding the FC input file(s) (BOLD_FC modality).

--qc_datapath (str, default ''):

For the 'general' modality: path, relative to <sessionsfolder>/<session>, of the folder holding the image to visualise. Required for 'general'.

--qc_datafile (str, default ''):

For the 'general' modality: file name of the image to visualise (found under --qc_datapath). Required for 'general'.

--qc_dwi_path (str, default 'Diffusion'):

DWI input folder under <hcp>/T1w (DWI modality).

--qc_dwi_data (str, default 'data'):

DWI data file name (without extension) under --qc_dwi_path (DWI modality).

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

If 'yes', also render a dtifit (FA/L3) variant scene; requires that FSL dtifit has run (dti_FA.nii.gz present).

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

If 'yes', also render a BedpostX variant scene; requires a complete Diffusion.bedpostX output.

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

If 'yes', hard-link the FSL EDDY qc.pdf into the QC folder and record qc_mot_abs motion into an EddyQCReport file; requires EDDY QC output.

Notes

How the command runs:

QC is a session-level command: it is dispatched across sessions in parallel using --parsessions. Within each session, the requested modalities (and, for BOLD/BOLD_FC, the individual runs and FC types) are expanded into independent jobs and run in parallel using --parelements. Each modality writes into <qc_outpath>/<modality> (default <sessionsfolder>/QC/<modality>) and keeps per-run logs under a qclog subfolder.

With the exception of 'rawNII', each modality renders one or more Workbench scenes to PNG and, when --qc_scenezip=yes, produces a self-contained scene zip for re-loading in Connectome Workbench. --on_existing controls whether existing outputs are left, skipped, or deleted before a run; --overwrite governs per-file recomputation.

rawNII:

Generates: <session>.RawNII.QC.<timestamp>.zip (all slicesdir PNGs and the original index.html) and <session>.RawNII.QC.<timestamp>.html -- a single self-contained HTML report with the PNGs embedded and, per raw sequence, its name and key parameters (TR, TE, resolution, dimensions x/y/z, number of volumes/directions) read from the JSON sidecars and NIfTI headers.
Prerequisites: raw NIfTIs (and, ideally, JSON sidecars) in <sessionsfolder>/<session>/nii after DICOM/BIDS import. Uses FSL slicesdir.
Required parameters: none beyond --sessions / --sessionsfolder.

T1w / T2w / myelin:

Generates: a <session>.<modality>.QC.wb.scene, a PNG, and (if enabled) a scene zip.
Prerequisites: a successful HCP structural run -- T1w/T2w require MNINonLinear/T{1,2}w_restore.nii.gz; myelin requires the SmoothedMyelinMap gifti files.
Required parameters: none beyond session selection.

BOLD:

Generates, per selected BOLD: a TSNR report, a <session>.BOLD.<bold>.QC.wb.scene, GSmap and GStimeseries PNGs, and (if enabled) a scene zip.
Prerequisites: processed BOLD dtseries under MNINonLinear/Results/<bold>.
Useful parameters: --bolds, --hcp_bold_prefix, --hcp_cifti_tail, --qc_bold_skipframes, --qc_bold_snronly.

BOLD_FC:

An independent modality (not a BOLD sub-option). Generates, per selected BOLD and per requested FC type, a <session>.<type>.BOLD.<bold>.QC.wb.scene, a PNG, and (if enabled) a self-contained scene zip (the FC input is copied into the zip).
The two types 'pscalar' and 'pconn' are independent -- run one, the other, or both via --qc_boldfc.
Prerequisites: the FC input file(s) at <qc_boldfcpath>/bold<N>_<input>.
Required parameters: --qc_boldfc and an input per requested type (--qc_boldfcinput and/or the type-specific --qc_boldfcpscalarinput / --qc_boldfcpconninput).

general:

Generates a <session>.general.QC.wb.scene and PNG for an arbitrary image within the session hierarchy.
Required parameters: --qc_datapath and --qc_datafile.

DWI:

Generates a <session>.DWI.QC.wb.scene and PNG (first/tenth frame), plus optional dtifit and BedpostX variant scenes and optional EDDY QC stats.
Prerequisites: <hcp>/T1w/<qc_dwi_path>/<qc_dwi_data>.nii.gz and nodif_brain_mask.nii.gz; sub-steps require their own outputs (dtifit, Diffusion.bedpostX, EDDY qc).
Useful parameters: --qc_dwi_path, --qc_dwi_data, --qc_dwi_dtifit, --qc_dwi_bedpostx, --qc_dwi_eddyqcstats.

Examples

Run BOLD and structural QC for all sessions in a batch, 4 runs in parallel:

qunex hcp_run_qc \
    --sessionsfolder='<study>/sessions' \
    --batchfile='<study>/processing/batch.txt' \
    --qc_modality='BOLD,T1w,T2w,myelin' \
    --parelements='4'

Raw NIfTI QC (produces the zip + single-file HTML report):

qunex hcp_run_qc \
    --sessionsfolder='<study>/sessions' \
    --sessions='OP101,OP102' \
    --qc_modality='rawNII'

BOLD FC QC for both map types (each needs its own input):

qunex hcp_run_qc \
    --sessionsfolder='<study>/sessions' \
    --sessions='OP101' \
    --qc_modality='BOLD_FC' \
    --qc_boldfc='pscalar,pconn' \
    --qc_boldfcpscalarinput='Atlas_..._GBC.pscalar.nii' \
    --qc_boldfcpconninput='Atlas_..._Fz.pconn.nii' \
    --bolds='1,2'

DWI QC with dtifit, BedpostX and EDDY stats:

qunex hcp_run_qc \
    --sessionsfolder='<study>/sessions' \
    --sessions='OP101' \
    --qc_modality='DWI' \
    --qc_dwi_dtifit='yes' \
    --qc_dwi_bedpostx='yes' \
    --qc_dwi_eddyqcstats='yes'

General QC of an arbitrary image:

qunex hcp_run_qc \
    --sessionsfolder='<study>/sessions' \
    --sessions='OP101' \
    --qc_modality='general' \
    --qc_datapath='images/functional' \
    --qc_datafile='bold1_Atlas.dtseries.nii'

Notes on the examples:

Combine modalities in a single call; they run in parallel per session.
For BOLD_FC, provide --qc_boldfcinput alone if running a single type, or the type-specific inputs when running both.
Use --on_existing='delete' to force a clean re-run, or --on_existing='skip' to leave completed sessions untouched.

QuNex documentation

hcp_run_qc

hcp_run_qc#