QuNex 'turnkey' workflow and 'batch' engine#

The QuNex Suite enables 'Turnkey' processing across the supported functions. This feature enables full automation across selected QuNex steps. This is accomplished via the run_turnkey QuNex command that enables one step processing of sessions.

It is less flexible than running individual qunex commands; however, it offers the ability to run the entire QuNex Suite workflow in a single command, either locally or via XNAT.

The QuNex turnkey workflow can be invoked in two ways, which can be specified via the following flag:

--turnkeytype=<turnkey_run_type>

The two turnkey workflow options are local or xnat, which will differ in their parameter specification.

Note

The command examples below do not provide the exhaustive list of all run_turnkey parameters. To get a full parameter listing consult run_turnkey command reference or invoke help via qunex run_turnkey.

QuNex run_turnkey on a cluster or local workstation#

Data assumptions#

The raw data folder should be:

${RAW_DATA}
        ├── HCPA001.zip
        ├── hcp_mapping.txt
        └── parameters.txt

The folder needs to contain the individual session data (dicom, bids, compressed format). If the data is compressed, it is expected to hold a single session and be named using the following specification:

<subject id>_<session id>.zip.

For example, in the case below this would be HCPA001.zip.

In addition, the folder needs to contain the two QuNex settings files:

The run_turnkey command specification#

The processing from data ingestion to creation of processing results is then completed by running the following example command, which specifies how to run the turnkey workflow for a local workstation:

# - Folder name to generate
STUDY_NAME="QUNEX_UseCase"

# - Master Working Directory
WORK_DIR="/gpfs/project/fas/n3/Studies"

# - Location for Raw Data
RAW_DATA="/gpfs/project/fas/n3/software/qunexdata/QUNEXTurnkeyUseCase"

# - Name of session to process
SESSIONS_LIST="HCPA001"

# - Input files
INPUT_BATCH_FILE="${RAW_DATA}/parameters.txt"
INPUT_MAPPING_FILE="${RAW_DATA}/hcp_mapping.txt"

# - Type of QuNex Turnkey run
RUNTURNKEY_TYPE="local"

# - QuNex Turnkey steps
RUNTURNKEY_STEPS=\
"create_study,map_raw_data,create_session_info,setup_hcp,create_batch,hcp_pre_freesurfer,hcp_freesurfer,hcp_post_freesurfer,run_qc_t1w,hcp_fmri_volume,hcp_fmri_surface,run_qc_bold,map_hcp_data,create_bold_brain_masks,compute_bold_stats,create_stats_report,extract_nuisance_signal,preprocess_bold,compute_bold_fc_seed,compute_bold_fc_gbc"

# - Command call
qunex run_turnkey \
    --rawdatainput="${RAW_DATA}" \
    --dataformat="DICOM" \
    --paramfile="${INPUT_BATCH_FILE}" \
    --mappingfile="${INPUT_MAPPING_FILE}" \
    --workingdir="${WORK_DIR}" \
    --projectname="${STUDY_NAME}" \
    --path="${WORK_DIR}/${STUDY_NAME}" \
    --sessions="${SESSIONS_LIST}" \
    --turnkeytype="${RUNTURNKEY_TYPE}" \
    --bolds="all" \
    --runparcellations=all \
    --turnkeysteps="${RUNTURNKEY_STEPS}" \
    --overwritestep="no"

The command will generate QUNEX_UseCase study folder where all the results will be present at the end.