Fmriprep-20.2.0 produces motion outliers in confounds_timeseries file by default - how are they derived?

1

Hi,
running #fmriprep 20.2.0 I found that the confounds_timeseries file lists “#motion_outliers”. The documentation (Outputs of fMRIPrep — fmriprep version documentation) says that spike regressors (i.e., regressors to identify and e.g. to “scrub” motion outliers during GLM analysis) will be generated when the --fd-spike-threshold or the --dvars-spike-threshold options are added to the command line when executing fmriprep. I did not add any of these options, still motion outliers are listed in the confounds_timeseries-file. I wonder whether the spike-threshold options were set to default in version 20.2.0? As there is no entry in the documentation today it would be helpful to learn how the motion outliers are defined: do they result from the framewise displacement parameter, the dvars parameter, or from both?
Thanks,
Chris

2

Hi,
There is indeed a default (I don’t know if it is new) set at 0.5mm.

See here: fmriprep/confounds.py at 0dba10208e5361bc94cdc5334826afa64d0617a1 · nipreps/fmriprep · GitHub

            from fmriprep.workflows.bold.confounds import init_bold_confs_wf
        wf = init_bold_confs_wf(
            mem_gb=1,
            metadata={},
            regressors_all_comps=False,
            regressors_dvars_th=1.5,
            regressors_fd_th=0.5,
        )
3

Thank you for the quick reply, jsein. It does not entirely address the need for clarification raised by the original post. I understand from your response that the default thresholds for dvars- and fd-dependent outlier definition is set to 1.5 and 0.5, respectively. This information is also findable in the documentation. My question addresses the presence of motion outlier regressors, even without explicit inclusion of the spike-threshold options in the fmriprep execution command. This suggests that the spike-threshold options became default, apparently in contrast to the official fmriprep documentation. Information is lacking whether the motion outlier regressors are based on both, the fd- and the dvars-method. Appreciate your feedback.

4

Thank you for your comment, it is indeed an important feedback so that the fmriprep evolves alongside with the code.
I agree with you the formulation in the documentation requires better clarification:

Spike regressors for outlier censoring can also be generated from within fMRIPrep using the command line options --fd-spike-threshold and --dvars-spike-threshold (default: FD > 0.5 mm or DVARS > 1.5). Spike regressors are stored in separate motion_outlier_XX columns.

=> The reformation could be:

Spike regressors for outlier censoring are generated within fMRIPrep and their calculation may be adjusted with command line options --fd-spike-threshold and --dvars-spike-threshold (default: FD > 0.5 mm or DVARS > 1.5). Spike regressors are stored in separate motion_outlier_XX columns.

Regarding your last point about the motion_outlier regressors calculation, this answers your question (this is taken from the boilerplate generated within each HTML report):

Frames that exceeded a threshold of {regressors_fd_th} mm FD or
{regressors_dvars_th} standardised DVARS were annotated as motion outliers.

5

Thank you for pointing me to the comment in the boilerplate, this one escaped my attention before.

6

I added a new issue raising your point: Better explanation on how spike regressors are generated is needed · Issue #2385 · nipreps/fmriprep · GitHub