fMRIPrep: Versioning and Long-Term Support

September 28, 2020

fMRIPrep: Versioning and Long-Term Support

As fMRIPrep continues to mature, we at the development team would like to take a moment to look at where we’ve been and where we’re going. Its mission of producing “analysis-grade” (or “sushi-grade”) data has proven useful, as evident by the sizeable amount of adoption within the brain-MRI community, and has spawned similar efforts generalizable to other modalities (NeuroImaging PREProcessing toolS, or NiPreps). However, like with most other software, this increase in users usually follows with an increase of new challenges. In this blog post, we’ll touch upon some of these issues (consistency among versions, and long-term support) and what we’re doing to address them.

Versioning updates

A guiding principle of fMRIPrep‘s development has been release early, release often (RERO). This philosophy promotes rapid progress, as users do not have to wait long for bug-fixes or new features and improvements. In turn, this also helps conform the software to users’ specifications, and over the years user feedback has greatly driven fMRIPrep to where it is now. However, this has resulted in a magnitude of releases throughout the years (about 145 since May 2016!)

Earlier this year, we adopted the Calendar Versioning (CalVer) scheme to improve our communication with users and ease transitions between fMRIPrep releases. Under this versioning system, each fMRIPrep release follows the structure of YY.MINOR.MICRO, where YY are the last two digits of the calendar year.
Specifically, this enables:

  • Providing users (and developers) an instant, albeit rough, idea of how recent or old a version is.
  • Guaranteeing that each minor (feature) release series maintains compatibility across micro (bug-fix) releases.

One popular question over the years has been:

I processed some of my data using version A, but can I process the rest using version B?

Since the integration of CalVer, each feature release is completely backwards compatible – so long as the YY.MINOR match. There will be no difference if later outputs are generated by newer bug-fix releases, like jumping from 20.0.0 to 20.0.7. This decision ensures consistency across results without requiring a rerun of computations, while leveraging the ability to fetch bug-fixes as needed. A more comprehensive criteria of what is and is not deemed eligible for a bug-fix release can be found on the NiPreps community website.

The lifespan of a feature release varies, depending on the development of new or compatibility-breaking changes. For users with previously acquired data, or small ongoing data, using the most recent feature release will suffice. However, for more ambitious longitudinal data collection, such as the NeuroMod or ABCD studies, this rapid turnover leaves something to be desired. This gap, originally raised via tweet, spawned the idea of providing a unique feature release dedicated to handling these cases.

Long-Term Support (LTS)

An fMRIPrep LTS is a special feature release with a greatly expanded lifespan for maintenance. LTS releases are targeted as community-driven series, meaning that an LTS manager is nominated to serve as the chief maintainer for a specific duration, no less than one year. Community members may volunteer to assume maintainership after the initial period, or to maintain a new minor release series as an LTS. Before release, LTS series are tested more rigorously than ordinary, and should include all necessary enhancements needed at the time of release.

We’re excited to announce the first fMRIPrep LTS series, 20.2.0, has been released! This LTS version will be kindly steered and maintained by the group of Dr. Basile Pinsard and Prof. Pierre Bellec at CRIUGM (Université de Montréal). The 20.2.0 LTS is planned for a window of 4 years of support (until September 2024).

What’s new?

Some of the highlights of this release include:

Revision of the reproducibility of CompCor masks

We slightly deviate from the original Behzadi et al. implementation, to ensure consistency across results and reduce user errors.


Masks are prepared in high-resolution, anatomical space before being projected to BOLD space. Instead of using binary erosion, a dilated GM map is generated. This should be equivalent to eroding the masks, except that the erosion only happens at direct interfaces with GM.


We have removed the heavy erosion of the brain mask as compares to previous fMRIPrep versions. This erosion was not part of the original proposal, and was a potential source of errors from Numpy complaining that it can’t take from an empty axis of an array. fMRIPrep implementation deviates from Behzadi’s in that we pick top 2% most variable pixels within the whole-brain mask (as opposed to the 2% slice-wise)

Updates to derivatives

Now that general derivatives are officially supported by the BIDS specification as of BIDS 1.4.0, fMRIPrep has synchronized accordingly.
Good news, there were only a few changes:

1) *desc-confounds_regressors* have been renamed to *desc-confounds_timeseries*.
2) A top level .bidsignore was added to fMRIPrep‘s output directory.

Additionally, the BOLD-anatomical transforms are now saved by default within the participant’s func directory.

Runtime improvements for large datasets

We found that one chokepoint of previous versions of fMRIPrep was during the indexing of the BIDS dataset with a large number of files. We added the option to provide a pre-indexed database, as well as a helper CLI and directions on how to use it.

Improvements to multi-echo processing

  • Ensure motion correction and fieldwarp are not applied multiple times.
  • Allow the use of single-band reference files.

All the goodies from 20.1.x series

The 20.1.x series integrated a long list of substantial changes. The reason being that 20.1 was meant to be the first LTS release. However, to keep up with our RERO principle and to allow for a more thorough testing, the development team decided to transfer the LTS qualification over to fMRIPrep 20.2.

For a comprehensive list of what’s changed, you can view the full log.

Thank you for using fMRIPrep!
As always, if you encounter any issues with this release, please let us know by posting an issue on our GitHub page!

We are an open community – get involved!

1 Comment

  1. Justin 17 hours

    Good post