To consider: RapidTide

[oesteban]

https://github.com/bbfrederick/rapidtide

cc @poldrack

[bbfrederick]

I'd be happy to help with that...

[tsalo]

What stage in preprocessing should rapidtide be run on? If we break it down into fMRIPrep's basic stages:

1. Motion correction
2. Slice timing correction
3. Susceptibility distortion correction
4. Coregistration to T1w
5. Normalization to standard space

[bbfrederick]

It definitely needs to be done after motion correction and slice timing correction, and ideally after susceptibility distortion correction, since that can interact with motion.

It can be done any time after that, and there are good reasons to do it in various stages, so this is a topic for discussion.

A) For computational efficiency, it would be best to do it in native space, before Coregistration to T1w or Normalization to standard space, since these typically increase the image size, and compute time is directly proportional to the number of voxels in the image. However, fmriprep doesn't make a motion, slice time, and sdc corrected image (or transform matrices from native to T1 space) available in the normal pathway, so this may be a non-starter.

B) After T1w coregistration, we have a good brain mask, which can be used to limit the processing area more cleanly than using rapidtide's internal mask generation function. However, this brain mask removes the superior sagittal sinus, which usually provides a large area with a nice robust signal for generating the initial regressor if you are using rapidtide's internal mask. The T1w dataset has the brain mask applied, so this data is gone. This is more an issue for people with gross vascular pathology - using the global mean as a starting regressor usually works fine.

C) After freesurfer runs (if it is run), you can generate your initial regressor using an anatomic mask. Using cerebellar gray matter tends to give a nice clean initial signal, in my experience, even in a lot of people with disturbed circulation.

B and C can both be done in T1w space or MNI space; which may be larger or smaller (T1w or destination MNI152 space) depends on your target resolution. If you do it in standard space, you don't have to transform the maps to standard when you're done, so it might be the most efficient computationally, especially since in the end you produce a filtered dataset, which will be the same size as the unfiltered one - transforming that will take a while.

In the "you didn't ask but I'll answer it anyway" section, whether you should do rapidtide before or after AROMA is unclear. My gut says run it before, in case AROMA removes some global mean signals. You should certainly do it before running FIX, if you're going to us it, because FIX pulls out a lot of blood signal in a way that makes it harder for rapidtide to generate a good initial regressor.

[effigies]

A) For computational efficiency, it would be best to do it in native space, before Coregistration to T1w or Normalization to standard space, since these typically increase the image size, and compute time is directly proportional to the number of voxels in the image.

Resampling to T1w should not upsample. Might slightly increase the FoV to ensure that the original bounding box fits inside the new, rotated one. I'm not sure from B whether the brain mask is used to focus processing or just to retrieve an initial signal and then all voxels are processed... As long as it accepts a brain mask, the number of voxels should be quite close to the original.

However, fmriprep doesn't make a motion, slice time, and sdc corrected image (or transform matrices from native to T1 space) available in the normal pathway, so this may be a non-starter.

I believe we actually do CompCor in the HMC+STC+SDC space, so this might not cost anything. If we don't create the time series in BOLD space, it would be worth testing whether it's cheaper to run RapidTide in the T1w or generate the BOLD space and run RapidTide.

[bbfrederick]

I'm not sure from B whether the brain mask is used to focus processing or just to retrieve an initial signal and then all voxels are processed... As long as it accepts a brain mask, the number of voxels should be quite close to the original.

By default, the same mask is used to retrieve the initial regressor and the mask to focus processing, but they can be specified individually. In subjects who have had strokes, or other conditions that can cause a large variation in delay time across the brain (10's of seconds), using the same mask for both can generate a bad initial regressor with multiple delay components that can't be separated by refinement, which hinders delay mapping because the probe regressor has autocorrelation sidelobes. So in those cases it's good to limit the global mean regressor estimation to a region with putatively "normal" circulation. In healthy young subjects, this is almost never a problem, since the delay histogram is a single peak with a halfwidth of only a couple of seconds. Older healthy subjects more frequently have wider, more complex delay histograms.

For data denoising this isn't that big a deal - if you can't distinguish the global mean signal from a delayed copy of itself, regressing out either will remove the hemodynamic noise effectively. It's only if you care what the delay value is in any voxel that this is an issue you have to deal with.

[effigies]

We do accept lesion masks in T1w space to improve normalization, so we could construct the initial regressor mask by intersecting the FreeSurfer (or FAST) gray matter mask with the negated lesion mask (if present).

We could also consider accepting a manual rapidtide mask, to permit researchers with pathological or otherwise unusual cases to create it directly when the automatic generation fails.

[tsalo]

If rapidtide can be run post-fMRIPrep (i.e., on standard space data with no denoising and no smoothing), then I think it would make sense to ensure that there is good documentation on rapidtide's side regarding running on fMRIPrepped data. At minimum, I think that means (1) fMRIPrep config recommendations, (2) recommendations for Freesurfer ROIs, (3) fMRIPrep-specific (or BIDS-Derivatives-specific) confounds ingestion functions, and (4) a wrapper to select fMRIPrep preprocessed data and confounds files, e.g., as a BIDS App.

In case it really would be better to run on T1w-space data instead of standard-space data, then the T1w-to-template transform that fMRIPrep outputs can be automatically applied on rapidtide's side.

Perhaps I'm misunderstanding the ROI issue though.

In the "you didn't ask but I'll answer it anyway" section, whether you should do rapidtide before or after AROMA is unclear.

fMRIPrep outputs the raw AROMA regressors, right? So one recommendation could be to run rapidtide on the regular preprocessed data instead of the AROMA aggressively denoised data, and then include the AROMA components in a GLM with the voxel-wise lagged regressors from rapidtide.

[bbfrederick]

Chris - I think both of those ideas are good ones. The first is certainly easy to implement - masks in rapidtide are specified as the logical and of an include mask and the inverse of an exclude mask. So simply passing the lesion mask directly to rapidtide as an exclude mask will do this. The second might be a little tricky, as you probably need the results of the initial fmriprep run before the masks you will want to use exist.

Taylor - yes, I really do need to up the documentation section, and that's a good section to add first (since I've already worked that all out). Rapidtide is good about taking in bidsified files as input, but I should change the outputs to be bidsified as well.

You are correct, AROMA and rapidtide can be run in parallel and the regressors can be applied after the fact in one go.

[tsalo]

To clarify, should rapidtide then be considered more a post-fMRIPrep workflow, or is it crucial to integrate it into fMRIPrep?

I am concerned about feature creep, but on the other hand I feel like leaving rapidtide out of the workflow is an implicit statement about its importance, rather than the preprocessing stage at which it should be performed. Everything I've read indicates to me that dealing with sLFOs is, well, really important. Would it make sense for fMRIPrep to document workflows designed to operate on fMRIPrepped data in the documentation somewhere? That way users would at least be aware of rapidtide and could use it more easily.

[bbfrederick]

Well, I'm obviously biased, but I'd say that if you don't remove the blood flow signal, any claims you make about "neuronal" connectivity should be taken with a grain of salt. Making rapidtide part of the workflow removes the friction of applying it, and that's probably a good thing.

[tsalo]

That's a good point. One issue, though, is the sheer number of parameters that can be set for rapidtide. Would you recommend hardcoding those parameters in the fMRIPrep calls?

The alternative, I think, is to support configuration files. I'm not sure if there are plans for that yet in fMRIPrep, but it wouldn't be the worst idea for some of the third-party tools like rapidtide, AROMA, and tedana.

[bbfrederick]

One of the goals for 2.0 has been to make the defaults much smarter, and to a large extent that has succeeded. If you run "rapidtide inputfile outputroot --denoise" that will usually do what you want now. But it would be good to have a mechanism for setting other parameters.

[tsalo]

That definitely makes integration easier!

[tsalo]

@bbfrederick What rapidtide-generated files would you like to retain in the fMRIPrep outputs?

[bbfrederick]

That depends a little on how you want to do the final filtering. I would suggest the _filtereddata.nii.gz file (the data with the hemodynamic signal regressed out), although you could also save the "_lagregressors.nii.gz" file, which is the voxel specific delayed hemodynamic regressors, so you could regress everything out in one model.

Other than that, I'd save the final regressor timecourse, and the _lagtimes.nii.gz, _lagstrengths.nii.gz, _lagsigma.nii.gz, and _lagmask.nii.gz files. These are the 3D maps of the correlation parameters, and can be very useful if you are interested in the hemodynamic delays. They are small and generally useful.

[tsalo]

I think that produces six new files for each functional run. I don't know if that number of additional derivatives is an issue the fMRIPrep devs would want to avoid, or if it's fine, but it's good to know.

1. _lagregressors.nii.gz
2. final regressor timecourse (txt file I believe)
   • This could possibly be integrated into the confounds file, if that wouldn't be too confusing to users.
3. _lagtimes.nii.gz
4. _lagstrengths.nii.gz
5. _lagsigma.nii.gz
6. _lagmask.nii.gz

[tsalo]

Given that rapidtide can be run on fMRIPrep outputs, it seems like the best solution is to build a rapidtide postprocessing BIDS App, like fmripost-aroma will do for ICA-AROMA and XCP-D does for a range of old-school resting-state nuisance regression strategies.

[bbfrederick]

Works for me. What do I need to do for that?

Blaise

[oesteban]

I agree too - and I'd be very happy to work with @bbfrederick toward this. cc/ @celprov @acionca

[tsalo]

I haven't looked at the source code for fmripost-aroma, but if it's fairly mature then you could adapt that and just swap out the AROMA-specific elements with rapidtide ones.

I'm also thinking of developing a similar workflow to run tedana on fMRIPrep outputs (and hopefully other preprocessing BIDS Apps), so having some kind of generic postprocessing template repo would be very useful for multiple projects.

[poldrack]

+1 for a generic postprocessing template repo

[effigies]

I haven't looked at the source code for fmripost-aroma, but if it's fairly mature

It's a stub repository at the moment. If this is important to someone, I would be happy to guide development (https://github.com/nipreps/fmripost-aroma/issues is a rough roadmap), but I don't have the time to spend on it right now. I also think rapidtide would be a good first project, and possibly more impactful.

If you want an example app that takes in an fMRIPrep output directory as an input, you could have a look at https://github.com/nipreps/resampler. It's a little rough, but it's also pretty light. The only thing it uses from other nipreps packages is a data file that makes it easy to query nipreps derivatives with pybids.

[tsalo]

I've created nipreps/fMRIPost-rapidtide, so I'm going to close this issue now.