FIX: Dilate BOLD mask by 2 voxels to prevent over-aggressive masking degrading T2* map estimation

[effigies]

Changes proposed in this pull request

Dilates BOLD mask by two voxels before passing to tedana's t2smap command. This accounts for BOLD masking sometimes being overly aggressive. Tedana is tolerant of a relaxed mask, so this is cheaper than attempting to rework mask generation to cover more cases without becoming worse in others.

Could consider dilating by more voxels to reduce the odds of clipping further.

Documentation that should be reviewed

[effigies]

Just to pull the conversation from Mattermost (@'ing folks for due credit; feel free to unsubscribe if you don't want to participate in this conversation further):

---

@effigies: Here's a question: How sensitive is t2smap to the BOLD mask? We're running into issues with over-aggressive masking on some BOLD files, and our options are either to create an ever-more-baroque masking algorithm or just accept that masks might be a bit aggressive and dilate them before passing to the T2* workflow. I see it's optional, so I'm hopeful it's just a matter of efficiency to relax the mask.

@tsalo: Having a mask ahead of time reduces the problem, but the adaptive masking procedure can be really wonky. It can definitely be over-aggressive, but no one has been able to come up with a reasonable alternative.

@effigies: Just to make sure I'm understanding... the over-aggressive mask I'm talking about is pre-tedana. Would it be safe to use a dilated mask without changing the behavior of tedana, or would that require us to use tedana's adaptive masking?

@tsalo: Oh... I thought you were referring to how tedana creates its adaptive mask. There's no way to disable adaptive masking, so there's always a chance that the mask that you feed into tedana will be over-aggressively reduced by the adaptive masking process, in which case you'll end up with an over-aggressively masked optimally combined file. Feeding a dilated mask into t2smap sounds like a reasonable workaround to me, but there's no guarantee that the adaptive mask won't still reduce the mask more than you want, unfortunately.

@handwerkerd: I think our automasking can be aggressive and a bit quirky, but the adaptive masking is not. I can double check, but the adaptive masking will only remove voxels with a large magnitude drop for later echoes. Also t2smap should include all voxels with at least 1 good echo, which would be all voxels in the originally supplied mask. You can confirm this by supplying a mask and then looking at the t2smap and the adaptive mask. Any value in the supplied mask should be at least a 1 in the adaptive mask and also have data in the t2smap.

@effigies: Thanks, Dan. Does that mean that providing a dilated mask will produce spurious results outside the "true" mask? Would it be better not to provide a mask at all?

@handwerkerd I think that depends on what else you are doing with the data. The ICA denoising part of tedana really needs a reasonably accurate brain main since out-of-brain noisy voxels can mess up out ICA separates the data into components. If you just care about the t2smap and the "optimally combined" image then you'll just have data outside of the brain, and noisy out-of-brain voxels will just continue to be noisy out-of-brain voxels.

---

We generally avoid applying masks to derivatives, instead just calculating them and using them internally when needed. So noisy out-of-brain voxels in the fMRIPrep outputs are fine from the fMRIPrep perspective, but I don't really understand the tedana use-case enough to be sure that this won't cause some problem somewhere.

cc @madisoth

[handwerkerd]

To answer your last question, the critical need for a mask in tedana is to only run ICA on voxels with good data. ICA can give problematic components if a significant portion of the total variance is from voxels with out-of-brain artifacts. The denoising step is a simple linear regression of the ICA component time series so that regression could be applied to fully unmasked data.