Xcp_d censoring documentation question

Summary of what happened:

I am trying to understand the xcp_d documentation in regards to censoring. I was prompted to look into this because in the documentation for the recent version it highlights that using the linc settings is appropriate for immediate analysis since it does not output interpolated data, while the abcd and hcpd settings do (see in documentation “Major Differences Between Modes (Processing Pipeline Details — xcp_d 0.7.6.dev24+g14de282 documentation)”. While I am not using either of those settings, I want to set up my own parameters in a way that I get out data ready for analysis. In the linc settings, it says that setting the fd-thresh to 0 would do that. However, it also says that linc outputs censored data. That seems contradictory to me.

Further, see here:

Further, see here:

Perhaps unrelated, I also don’t understand these two green boxes in the documentation:

and:

Lastly, it is unclear to me if nuisance regression also includes flagging volumes with higher FD, and if so, what cutoff is used here (the same as fd-thresh or a different one?).

Thanks so much for clarifying my understanding of the documentation in advance!

Command used (and if a helper script was used, a link to the helper script or the command generated):

--fd-thresh 0.3

Version:

0.7.5

Screenshots / relevant information:

1 Like

The documentation you looked at is for a version that is backwards-incompatible with the version you’re using. I recommend looking at the documentation for 0.7.5 (which unfortunately wasn’t being built until I saw this issue): XCP-D : A Robust Postprocessing Pipeline of fMRI data — xcp_d 0.7.5 documentation. The concept of “modes” is introduced in version 0.8.0, so it doesn’t apply to the version you used (0.7.5).

Here’s the basic gist: If censoring is enabled (i.e., if --fd-thresh > 0), then linc mode would output censored data. If it isn’t enabled, because there’s no threshold to apply to censor the data, then the output data wouldn’t be censored.

In older versions (0.4.0 - 0.7.5), XCP-D outputted the censored data (again, censored only when censoring is enabled with --fd-thresh > 0) as desc-denoised. Interpolated data (which would only differ from the desc-denoised data if censoring was enabled) was outputted as desc-interpolated, depending on the parameters.

Could you expand on what is unclear about those boxes? I’m happy to explain them, but since I wrote them they seem clear to me.

There’s just --fd-thresh. No secondary/higher threshold. I have started drafting a PR that could probably do what you’re talking about (see Add custom censoring options by tsalo · Pull Request #1159 · PennLINC/xcp_d · GitHub), but it’s not implemented in XCP-D yet.

Thanks for releasing the 0.7.5 documentation! that’s very helpful. I’ll use --fd-thresh 0 to avoid censoring. If I want to use a motion outlier in the nuisance regression based on fd, can I pull this from fmriprep’s motion outliers and use it alongside the -p acompcor setting?

Regarding the green boxes, I’m not sure what the difference between filtering and confound regression is and what the motion parameters refer to exactly.

Just to make sure I understand, you want to include the motion outliers as one-hot regressors in the nuisance regression, rather than censoring those volumes? AFAIK the corresponding volumes won’t contain any useful information in the denoised data, so it should be functionally equivalent to XCP-D’s censoring procedure. If you want to do it, though, including those motion outlier regressors as custom confounds should work just fine. Just grab the columns you want from the fMRIPrep confounds file, put them in a TSV with the same name as the confounds file in a different folder, and point to that folder with --custom-confounds. If you want to combine those regressors with a built-in nuisance regressor set (e.g., 36P) then keep -p set to whatever that built-in set is (e.g., -p 36P) and XCP-D will use both the requested nuisance regressor set and the extra custom confounds. If you only want to use the regressors from the custom confounds file, then set -p custom.

XCP-D optionally supports motion parameter filtering to remove aliased respiration from the motion parameters. That’s what --motion-filter-type, --band-stop-min, --band-stop-max, and --motion-filter-order control. Prior to version 0.4.0, these filtered motion parameters were just used to calculate the FD time series that is used to identify high-motion outlier volumes. However, from 0.4.0 onwards, we started passing the filtered motion parameters along to the nuisance regression step and using them for denoising rather than the raw motion parameters from fMRIPrep. This involves calculating the Volterra expansion of the filtered motion parameters (squares, derivatives, and squared derivatives) as well, so, for example, if you use the 36P nuisance regressor set, then 24 of the 36 nuisance regressors in the denoising model will come from the filtered, rather than raw, motion parameters (as long as you used notch or lp for --motion-filter-type.

Thanks so much for your thorough reply! Totally makes sense how I would add the additional confounds instead of censoring. And thanks for clarifying what the green box meant :slight_smile:

1 Like