create_stats_report#

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

create_stats_report(sinfo, options, overwrite=False, thread=0)

Processes movement correction parameters and computed BOLD statistics to create per session plots and fidl snippets and group reports.

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.

--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.

--tr (float, default 2.5):

TR of the BOLD files.

--mov_pref (str, default ''):

The prefix to be used for the figure plot files.

--mov_plot (str, default 'mov_report'):

The base name of the plot files. If set to empty no plots are generated.

--mov_mreport (str, default 'movement_report.txt'):

The name of the group movement report file. If set to an empty string, no file is generated.

--mov_sreport (str, default 'movement_scrubbing_report.txt'):

The name of the group scrubbing report file. If set to an empty string, no file is generated.

--mov_preport (str, default 'movement_report_post.txt'):

The name of group report file with stats computed with frames identified as bad exluded from analysis. If set to an empty string, no file is generated.

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

The criterium for identification of bad frames that is used when generating a post scrubbing statistics group report:

'fd'
'dvars'
'dvars'
'dvarsme'
'idvars'
'idvarsme'
'udvars'
'udvarsme' ... default
'none'.

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

Whether to create fidl file snippets with listed bad frames, and what criterium to use for the definition of bad frames:

'fd'
'dvars'
'dvars'
'dvarsme'
'idvars'
'idvarsme'
'udvars'
'udvarsme' ... default
'none' ... Set to 'none' to not generate them.

--mov_pdf (str, default 'movement_plots'):

The name of the folder in sessions/QC/movement in which to copy the individuals' movement plots.

Notes

Use:

create_stats_report processes movement correction parameters and computed BOLD statistics to create per session plots and fidl snippets and group reports.

For each session it saves into images/functional/movement:

--bold<nifti_tail>_<mov_plot>_cor.pdf: A plot of movement correction parameters for each of the BOLD files.
--bold<nifti_tail>_<mov_plot>_dvars.pdf: A plot of frame displacement and dvarsm statistics with frames that are identified as bad marked in blue.
--bold<nifti_tail>_<mov_plot>_dvarsme.pdf: A plot of frame displacement and dvarsme statistics with frames that are identified as bad marked in blue.
--bold[N]<nifti_tail>_scrub.fidl: A fidl filesnippet that lists, which frames are to be excluded from the analysis.

For the group level it creates three report files that are stored in the <sessionsfolder>/QC/movement folder. These files are:

<mov_mreport> (bold<nifti_tail>_movement_report.txt by default)
This file lists for each session and bold file mean, sd, range, max, min, median, and squared mean divided by max statistics for each of the 6 movement correction parameters. It also prints mean, median, maximum, and standard deviation of frame displacement statistics. The purpose of this file is to enable easy session and group level analysis of movement in the scanner.
<mov_preport> (bold<nifti_tail>_movement_report_post.txt by default)
This file has the same structure and information as the above, with frames marked as bad excluded from the statistics computation. This enables session and group level assessment of the effects of scrubbing.
<mov_sreport> (bold<nifti_tail>_movement_scrubbing_report.txt by default)
This file lists for each BOLD of each session the number and the percentage of frames that would be marked as bad and excluded from the analyses when a specific exclusion criteria would be used. Again, the file supports session and group level analysis of movement scrubbing.

Extra notes and dependencies:

The command runs the bold_stats.R R script that computes the statistics and plots the data. The function requires that movement correction parameters files and bold statistics data files (results of the compute_bold_stats command) are present in the expected locations.

Session statistics are appended to the group level report files as they are being computed. To avoid messy group level files, it is recommended to run the command with parsessions set to 1 (example 1), to enforce sequential processing and adding of information to group level statistics files. Another option is to run the processing in two steps. The first step with multiple parsessions to speed up generation of session level maps (example 2), and then the second step with a single core, omitting the slow generation of session specific plots.

Examples

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

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

qunex create_stats_report \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --bolds=all \
    --nifti_tail=_hp2000_clean \
    --parsessions=1 \
    --mov_plot=""

QuNex documentation

create_stats_report

create_stats_report#