compute_bold_stats#

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

compute_bold_stats [... processing options]

Processes specified BOLD files and saves images/function/movement files.

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.

--parsessions (int, default 1):

How many sessions to run in parallel.

--parelements (int, default 1):

How many elements (e.g. bolds) to run in parallel.

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

Whether to overwrite existing data (yes) or not (no).

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

Which bold images (as they are specified in the batch.txt file) to copy over. It can be a single type (e.g. 'task'), a pipe separated list (e.g. 'WM|Control|rest') or 'all' to copy 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.

--bold_variant (str, default ''):

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

--img_suffix (str, default ''):

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

--logfolder (str, default ''):

The path to the folder where runlogs and comlogs are to be stored, if other than default.

--mov_radius (int, default 50):

Estimated head radius (in mm) for computing frame displacement statistics.

--mov_fd (float, default 0.5):

Frame displacement threshold (in mm) to use for identifying bad frames.

--mov_dvars (float, default 3.0):

The (mean normalized) dvars threshold to use for identifying bad frames.

--mov_dvarsme (float, default 1.5):

The (median normalized) dvarsm threshold to use for identifying bad frames.

--mov_after (int, default 0):

How many frames after each frame identified as bad to also exclude from further processing and analysis.

--mov_before (int, default 0):

How many frames before each frame identified as bad to also exclude from further processing and analysis.

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

Which criteria to use for identification of bad frames (mov, dvars, dvarsme, idvars, uvars, idvarsme, udvarsme). See movement scrubbing documentation for further information. Criteria for identification of bad frames can be one out of:

  • 'mov' ... Frame displacement threshold (fdt) is exceeded.

  • 'dvars' ... Image intensity normalized root mean squared error (RMSE) threshold (dvarsmt) is exceeded.

  • 'dvarsme' ... Median normalised RMSE (dvarsmet) threshold is exceeded.

  • 'idvars' ... Both fdt and dvarsmt are exceeded (i for intersection).

  • 'uvars' ... Either fdt or dvarsmt are exceeded (u for union).

  • 'idvarsme' ... Both fdt and dvarsmet are exceeded.

  • 'udvarsme' ... Either fdt or udvarsmet are exceeded.

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

Notes

The parameters listed in Other parameters can be specified in command call or session.txt file.

The compute_bold_stats function processes each of the specified BOLD files and saves three files in the images/functional/movement folder:

bold[N].bstats:

bold[N]<nifti_tail>.bstats includes for each frame of the BOLD image the following computed statistics:

  • n

    Number of brain voxels.

  • m

    Mean signal intensity across all brain voxels.

  • var

    Signal variance across all brain voxels.

  • sd

    Signal standard variation across all brain voxels.

  • dvars

    RMDS measure of signal intensity difference between this and the preceeding frame.

  • dvarsm

    Mean normalized dvars measure.

  • dvarsme

    Median normalized dvarsm measure.

  • fd

    Frame displacement.

There are three additional lines at the end of the file listing maximum, mean and standard deviation of values across all timepoints / volumes.

bold[N].scrub:

bold[N]<nifti_tail>.scrub includes for each frame the information on whether the frame should be excluded (1) or not (0) based on the following criteria (note below the relevant settings that specify thresholds etc.):

  • mov

    Is frame displacement higher from the specified threshold?

  • dvars

    Is mean normalized dvars (dvarsm) higher than the specified threshold?

  • dvarsme

    Is the median normalized dvarsm higher than the specified threshold?

  • idvars

    Are both frame displacement as well as dvarsm measures above threshold (intersection of fd and dvarsm).

  • idvarsme

    Are both frame displacement as well as dvarsme measures above threshold (intersection of fd and dvarsme).

  • udvars

    Are either frame displacement or dvarsm measures above threshold (union of fs and dvarsm).

  • udvarsme

    Are either frame displacement or dvarsme measures above threshold (union of fs and dvarsme).

The last column of the file is a 'use' column, which specifies, based on the criteria provided, whether the frame should be used in further preprocessing and analysis or not.

There is an additional #sum line at the end of the file, listing how many frames are marked as bad using each criteria.

bold[N].use:

bold[N]<nifti_tail>.use file lists for each frame of the relevant BOLD image, whether it is to be used (1) or not (0).

When 'cifti' is the specified image target, the related nifti volume files will be processed as only they provide all the information for computing the relevant parameters.

Dependencies:

The command runs the general_compute_bold_stats.m Matlab function for computation of parameters. It also expects that both bold images and the related movement correction parameter files are present in the expected locations.

Examples

Using the defaults:

qunex compute_bold_stats \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --bolds=all

Specifying additional parameters for identification of bad frames:

qunex compute_bold_stats \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --bolds=all \
    --mov_fd=0.9 \
    --mov_dvarsme=1.6 \
    --mov_before=1 \
    --mov_after=2