[ENH]: Add scrubbing support in fMRIPrepConfoundRemover

[synchon]

• description of feature/fix
• tests added/passed
• add an entry for the latest changes

This PR adds scrubbing support in fMRIPrepConfoundRemover by using std_dvars from fMRIPrep output.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 85.73%. Comparing base (02e0b6f) to head (e5ada55).
Report is 15 commits behind head on main.

❌ Your project status has failed because the head coverage (85.72%) is below the target coverage (90.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #421      +/-   ##
==========================================
+ Coverage   85.67%   85.73%   +0.05%     
==========================================
  Files         133      133              
  Lines        5633     5656      +23     
  Branches      954      958       +4     
==========================================
+ Hits         4826     4849      +23     
  Misses        618      618              
  Partials      189      189              

Flag	Coverage Δ
junifer	85.72% <100.00%> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
.../preprocess/confounds/fmriprep_confound_remover.py	99.46% <100.00%> (+0.07%)	⬆️

[github-actions]

PR Preview Action v1.6.0
🚀 View preview at https://juaml.github.io/junifer/pr-preview/pr-421/
Built to branch gh-pages at 2025-01-29 11:06 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[fraimondo]

Two comments:

1. Why using DVARS? where did you get the reference for this method? I've seen scrubbing also using the FD
2. As it is, it nows also adds DVARS as a regressor.

I think the implementation should come from nilearn: https://nilearn.github.io/stable/modules/generated/nilearn.interfaces.fmriprep.load_confounds.html#nilearn.interfaces.fmriprep.load_confounds

Basically here you can set the fd_threshold and std_dvars_threshold and it will give you the sample_mask

[synchon]

Two comments:

1. Why using DVARS? where did you get the reference for this method? I've seen scrubbing also using the FD

nilearn.image.load_confounds has a parameter std_dvars_threshold for scrubbing, so I went for it as well. We support FD via the spike parameter of fMRIPrepConfoundRemover.

2. As it is, it nows also adds DVARS as a regressor.

It generates a mask for indexing the time dimension and passes it to nilearn.image.clean as you suggested in your previous comment.

I think the implementation should come from nilearn: https://nilearn.github.io/stable/modules/generated/nilearn.interfaces.fmriprep.load_confounds.html#nilearn.interfaces.fmriprep.load_confounds

Basically here you can set the fd_threshold and std_dvars_threshold and it will give you the sample_mask

We don't use load_confounds but select the confounds we want to remove and pass it to nilearn.image.clean_img. Also, load_confounds relies on the confound file by following the path from the image file. Is that something we go for?

[fraimondo]

Two comments:

1. Why using DVARS? where did you get the reference for this method? I've seen scrubbing also using the FD

nilearn.image.load_confounds has a parameter std_dvars_threshold for scrubbing, so I went for it as well. We support FD via the spike parameter of fMRIPrepConfoundRemover.

spike is to add as a regressor, which is not scrubbing:

junifer/junifer/preprocess/confounds/fmriprep_confound_remover.py

Line 411 in e392c7b

if self.spike is not None:

2. As it is, it nows also adds DVARS as a regressor.

It generates a mask for indexing the time dimension and passes it to nilearn.image.clean as you suggested in your previous comment.

I see that you use input["confounds"] for the scrub mask and not confounds_df. We are good as long as dvars or any confounds used for the scrubbing appear in the confounds of clean_img

I think the implementation should come from nilearn: https://nilearn.github.io/stable/modules/generated/nilearn.interfaces.fmriprep.load_confounds.html#nilearn.interfaces.fmriprep.load_confounds
Basically here you can set the fd_threshold and std_dvars_threshold and it will give you the sample_mask

We don't use load_confounds but select the confounds we want to remove and pass it to nilearn.image.clean_img. Also, load_confounds relies on the confound file by following the path from the image file. Is that something we go for?

We need to somehow "mimic" that behaviour. That's what I meant. The scrubbing mask can be either from dvars or fd.

[synchon]

I see that you use input["confounds"] for the scrub mask and not confounds_df. We are good as long as dvars or any confounds used for the scrubbing appear in the confounds of clean_img

Do the new commits address it?

[fraimondo]

I see that you use input["confounds"] for the scrub mask and not confounds_df. We are good as long as dvars or any confounds used for the scrubbing appear in the confounds of clean_img

Do the new commits address it?

We are still missing the fd_threshold and the scrub parameter. Also check the reference for scrubbing: https://www.sciencedirect.com/science/article/abs/pii/S1053811913009117?via%3Dihub

Coverage is low, meaning that we are missing tests.

[synchon]

We are still missing the fd_threshold and the scrub parameter.

Just so that it's explicit:

• Does fMRIPrepConfoundRemover's strategy take a key named scrub or does one pass it via the parameters?
• From load_confounds docs: “scrub” regressors for Power et al.[[3]](https://nilearn.github.io/stable/modules/generated/nilearn.interfaces.fmriprep.load_confounds.html#footcite-power2014) scrubbing approach. Associated parameter: scrub, fd_threshold, std_dvars_threshold. It treats them as "regressors" and when you pass "scrub" in the strategy, it does not return either framewise_displacement or std_dvars in the returned confounds dataframe.

We are good as long as dvars or any confounds used for the scrubbing appear in the confounds of clean_img

I thought the columns should be in the returned dataframe?

• If you are ok with how the std_dvars_threshold is currently implemented for fMRIPrepConfoundRemover, I can add fd_threshold as well. I'm not sure how scrub is supposed to be implemented?

[synchon]

@fraimondo would really appreciate your feedback to the previous comment.

[synchon]

I've updated the interface and also improved the logic by replicating nilearn's implementation, would appreciate a review @fraimondo @kaurao

[fraimondo]

Once CI is ready, we can merge