23.2

[effigies]

23.2.0

Release notes

New feature release in the 23.2.x series.

This release wraps up a significant refactor of fMRIPrep. The main new features can be used with the --level and --derivatives flags.

The --level flag can take the arguments minimal, resampling or full. The default is full, which should produce nearly the same results as previous versions. minimal will produce only the minimum necessary to deterministically generate the remaining derivatives. resampling will produce some additional derivatives, intended to simplify resampling with other tools.

The --derivatives flag takes arguments of the form name=/path/to/dir, for example --derivatives anat=$SMRIPREP_DIR. If provided, fMRIPrep will read the specified directories for pre-computed derivatives. If a derivative is found, it will be used instead of computing it from scratch. If a derivative is not found, fMRIPrep will compute it and proceed as usual.

Taken together, these features can allow a dataset provider to run a minimal fMRIPrep run, targeting many output spaces, while a user can then run a --derivatives run to generate additional derivatives in only the output spaces they need. Another use case is to provide an precomputed derivative to override the default fMRIPrep behavior, enabling easier workarounds for bugs or experimentation with alternatives.

Additionally, this release includes a number of bug fixes and improvements. This release adds support for MSM-Sulc, improving the alignment of subject surfaces to the fsLR template. This process is enabled by default, but may be disabled with the --no-msm flag.

This release resolves a number of issues with fieldmaps inducing distortions during correction. Phase difference and direct fieldmaps are now masked correctly, preventing the overestimation of distortions outside the brain. Additionally, we now implement Jacobian weighting during unwarping, which corrects for compression and expansion effects on signal intensity. To disable Jacobian weighting, use --ignore fmap-jacobian.

Finally, a new resampling method has been added, to better account for susceptibility distortion and motion in a single shot resampling to a volumetric target space. We anticipate extending this to surface targets in the future.

Changes

• FIX: Restore --ignore sbref functionality (FIX: Restore --ignore sbref functionality #3180)
• FIX: Retrieve atlas ROIs at requested density (FIX: Retrieve atlas ROIs at requested density #3179)
• FIX: Keep minctracc executable in FreeSurfer installation (FIX: Keep minctracc [skip ci] #3175)
• FIX: Exclude echo entity from optimally combined derivatives (Exclude echo entity from optimally combined derivatives #3166)
• FIX: Disable boldref-space outputs unless requested (FIX: Disable boldref-space outputs unless requested #3159)
• FIX: Tag memory estimates in resamplers (FIX: Tag memory estimates in resamplers #3150)
• FIX: Final revisions for next branch (Final revisions for next branch #3134)
• FIX: Minor fixes to work with MSMSulc-enabled smriprep-next (FIX: Minor fixes to work with MSMSulc-enabled smriprep-next #3098)
• FIX: Connect EPI-to-fieldmap transform (FIX: Connect EPI-to-fieldmap transform #3099)
• FIX: Use Py2-compatible version file template for fmriprep-docker (FIX: Use Py2-compatible version file template for fmriprep-docker #3101)
• FIX: Update connections to unwarp_wf, convert ITK transforms to text (FIX: Update connections to unwarp_wf, convert ITK transforms to text #3077)
• ENH: Allow --ignore fmap-jacobian to disable Jacobian determinant modulation during fieldmap correction (ENH: Allow --ignore fmap-jacobian to disable Jacobian determinant modulation during fieldmap correction #3186)
• ENH: Exclude non-steady-state volumes from confound correlation plot (Exclude non-steady-state volumes from confound correlation plot #3171)
• ENH: Pass FLAIR images to anatomical workflow builder to include in boilerplate (ENH: Pass FLAIR images to anatomical workflow builder to include in boilerplate #3146)
• ENH: Restore carpetplot and other final adjustments (ENH: Restore carpetplot and other final adjustments #3131)
• ENH: Restore CIFTI-2 generation (ENH: Restore CIFTI-2 generation #3129)
• ENH: Restore resampling to surface GIFTIs (ENH: Restore resampling to surface GIFTIs #3126)
• ENH: Restore confound generation (ENH: Restore confound generation #3120)
• ENH: Restore resampling BOLD to volumetric templates (ENH: Restore resampling BOLD to volumetric templates #3121)
• ENH: Restore resampling to T1w target (ENH: Restore resampling to T1w target #3116)
• ENH: Add MSMSulc (ENH: Add MSMSulc #3085)
• ENH: Add reporting workflow for BOLD fit (ENH: Add reporting workflow for BOLD fit #3082)
• ENH: Generate anatomical derivatives useful for resampling (ENH: Generate anatomical derivatives useful for resampling #3081)
• RF: Load reportlets interfaces from nireports rather than niworkflows (MAINT: load reportlets interfaces from nireports rather than niworkflows #3176, MNT: Load reportlets interfaces from nireports rather than niworkflows #3184)
• RF: Separate goodvoxels mask creation from fsLR resampling (Separate goodvoxels mask creation from fsLR resampling #3170)
• RF: Write out anatomical template derivatives (RF: Write out anatomical template derivatives #3136)
• RF: Update primary bold workflow to incorporate single shot resampling (RF: Update primary bold workflow to incorporate single shot resampling #3114)
• RF: Update derivative cache spec, calculate per-BOLD, reuse boldref2fmap (RF: Update derivative cache spec, calculate per-BOLD, reuse boldref2fmap #3078)
• RF: Split fMRIPrep into fit and derivatives workflows (RF: Split fMRIPrep into fit and derivatives workflows #2913)
• RPT: Rename CSF/WM confounds in fMRIPlot (RPT: Rename CSF/WM confounds in fMRIPlot #3172)
• TST: Add smoke tests for full workflow and most branching flags (TEST: Add smoke tests for full workflow and most branching flags #3155)
• TST: Add smoke-tests for bold_fit_wf (TEST: Add smoke-tests for bold_fit_wf #3152)
• DOC: Fix documentation and description for init_bold_grayords_wf (DOC: Fix documentation and description for init_bold_grayords_wf #3051)
• DOC: Minor updates in outputs.rst (DOC: Minor updates in outputs.rst #3148)
• STY: Apply a couple refurb suggestions (STY: Apply a couple refurb suggestions #3151)
• STY: Fix flake8 warnings (MNT: fix flake8 warnings #3044)
• STY: Apply pyupgrade suggestions (STY: Apply pyupgrade suggestions #3043)
• MNT: Restore mritotal subcommands to Dockerfile (DOCKER: Restore mritotal subcommands #3149)
• MNT: Update smriprep to 0.13.1 (MNT: Update smriprep to 0.13.1 #3153)
• MNT: optimise size of PNG files (MNT: optimise size of PNG files #3145)
• MNT: update vendored docs script github_link.py (MNT: update vendored docs script github_link.py #3144)
• MNT: Update tedana pin, test on Python 3.12 (MNT: Update tedana pin, test on Python 3.12 #3141)
• MNT: Bump environment (MNT: Bump environment #3132)
• MNT: Bump version requirements (MNT: Bump version requirements #3107)
• MNT: http:// → https:// (MNT: http:// → https:// #3097)
• MNT: Remove mritotal and dependencies from FreeSurfer ignore file (DOCKER: Remove mritotal and dependencies from FreeSurfer ignore file #3090)
• MNT: Update environment (MNT: Update environment #3073)
• MNT: Depend on newer sphinx (MNT: Depend on newer sphinx #3067)
• MNT: Install ANTs from conda-forge (MNT: Install ANTs from conda-forge #3061)
• MNT: Drop Python 3.8 and numpy 1.21 support (NEP29) (MNT: Drop Python 3.8 and numpy 1.21 support (NEP29) #3052)
• MNT: update update_zenodo.py script (MNT: update update_zenodo.py script #3042)
• MNT: Fix welcome message formatting and instructions (MNT: Fix welcome message formatting and instructions #3039)
• MNT: Python 3.11 should be supported (MNT: Python 3.11 should be supported #3038)
• CI: Bump actions/setup-python from 4 to 5 (Bump actions/setup-python from 4 to 5 #3181)
• CI: Stop testing legacy layout (CI: Stop testing legacy layout #3079)
• CI: Improve tag detection for docker builds (CI: Improve tag detection for docker builds #3066)
• CI: Clean up pre-release builds (CI: Clean up pre-release builds #3040)

New Contributors

• @DimitriPapadopoulos made their first contribution in MNT: Python 3.11 should be supported #3038
• @Shotgunosine made their first contribution in DOC: Fix documentation and description for init_bold_grayords_wf #3051
• @E-Loba made their first contribution in DOCKER: Remove mritotal and dependencies from FreeSurfer ignore file #3090
• @smeisler made their first contribution in MNT: Update smriprep to 0.13.1 #3153

Full Changelog: 23.1.4...23.2.0

[effigies]

23.2.0a1 - Alpha release series

Release notes

New feature release in the 23.2.x series.

This release wraps up a significant refactor of fMRIPrep. The main new features can be used with the --level and --derivatives flags.

The --level flag can take the arguments minimal, resampling or full. The default is full, which should produce nearly the same results as previous versions. minimal will produce only the minimum necessary to deterministically generate the remaining derivatives. resampling will produce some additional derivatives, intended to simplify resampling with other tools.

The --derivatives flag takes arguments of the form name=/path/to/dir, for example --derivatives anat=$SMRIPREP_DIR. If provided, fMRIPrep will read the specified directories for pre-computed derivatives. If a derivative is found, it will be used instead of computing it from scratch. If a derivative is not found, fMRIPrep will compute it and proceed as usual.

Taken together, these features can allow a dataset provider to run a minimal fMRIPrep run, targeting many output spaces, while a user can then run a --derivatives run to generate additional derivatives in only the output spaces they need. Another use case is to provide an precomputed derivative to override the default fMRIPrep behavior, enabling easier workarounds for bugs or experimentation with alternatives.

Additionally, this release includes a number of bug fixes and improvements. This release adds support for MSM-Sulc, improving the alignment of subject surfaces to the fsLR template. This process is enabled by default, but may be disabled with the --no-msm flag.

This release resolves a number of issues with fieldmaps inducing distortions during correction. Phase difference and direct fieldmaps are now masked correctly, preventing the overestimation of distortions outside the brain. Additionally, we now implement Jacobian weighting during unwarping, which corrects for compression and expansion effects on signal intensity.

Finally, a new resampling method has been added, to better account for susceptibility distortion and motion in a single shot resampling to a volumetric target space. We anticipate extending this to surface targets in the future.

Changes

• FIX: Final revisions for next branch (Final revisions for next branch #3134)
• FIX: Minor fixes to work with MSMSulc-enabled smriprep-next (FIX: Minor fixes to work with MSMSulc-enabled smriprep-next #3098)
• FIX: Connect EPI-to-fieldmap transform (FIX: Connect EPI-to-fieldmap transform #3099)
• FIX: Use Py2-compatible version file template for fmriprep-docker (FIX: Use Py2-compatible version file template for fmriprep-docker #3101)
• FIX: Update connections to unwarp_wf, convert ITK transforms to text (FIX: Update connections to unwarp_wf, convert ITK transforms to text #3077)
• ENH: Restore carpetplot and other final adjustments (ENH: Restore carpetplot and other final adjustments #3131)
• ENH: Restore CIFTI-2 generation (ENH: Restore CIFTI-2 generation #3129)
• ENH: Restore resampling to surface GIFTIs (ENH: Restore resampling to surface GIFTIs #3126)
• ENH: Restore confound generation (ENH: Restore confound generation #3120)
• ENH: Restore resampling BOLD to volumetric templates (ENH: Restore resampling BOLD to volumetric templates #3121)
• ENH: Restore resampling to T1w target (ENH: Restore resampling to T1w target #3116)
• ENH: Add MSMSulc (ENH: Add MSMSulc #3085)
• ENH: Add reporting workflow for BOLD fit (ENH: Add reporting workflow for BOLD fit #3082)
• ENH: Generate anatomical derivatives useful for resampling (ENH: Generate anatomical derivatives useful for resampling #3081)
• RF: Write out anatomical template derivatives (RF: Write out anatomical template derivatives #3136)
• RF: Update primary bold workflow to incorporate single shot resampling (RF: Update primary bold workflow to incorporate single shot resampling #3114)
• RF: Update derivative cache spec, calculate per-BOLD, reuse boldref2fmap (RF: Update derivative cache spec, calculate per-BOLD, reuse boldref2fmap #3078)
• RF: Split fMRIPrep into fit and derivatives workflows (RF: Split fMRIPrep into fit and derivatives workflows #2913)
• DOC: Fix documentation and description for init_bold_grayords_wf (DOC: Fix documentation and description for init_bold_grayords_wf #3051)
• STY: Fix flake8 warnings (MNT: fix flake8 warnings #3044)
• STY: Apply pyupgrade suggestions (STY: Apply pyupgrade suggestions #3043)
• MNT: Bump environment (MNT: Bump environment #3132)
• MNT: Bump version requirements (MNT: Bump version requirements #3107)
• MNT: http:// → https:// (MNT: http:// → https:// #3097)
• MNT: Remove mritotal and dependencies from FreeSurfer ignore file (DOCKER: Remove mritotal and dependencies from FreeSurfer ignore file #3090)
• MNT: Update environment (MNT: Update environment #3073)
• MNT: Depend on newer sphinx (MNT: Depend on newer sphinx #3067)
• MNT: Install ANTs from conda-forge (MNT: Install ANTs from conda-forge #3061)
• MNT: Drop Python 3.8 and numpy 1.21 support (NEP29) (MNT: Drop Python 3.8 and numpy 1.21 support (NEP29) #3052)
• MNT: update update_zenodo.py script (MNT: update update_zenodo.py script #3042)
• MNT: Fix welcome message formatting and instructions (MNT: Fix welcome message formatting and instructions #3039)
• MNT: Python 3.11 should be supported (MNT: Python 3.11 should be supported #3038)
• CI: Stop testing legacy layout (CI: Stop testing legacy layout #3079)
• CI: Improve tag detection for docker builds (CI: Improve tag detection for docker builds #3066)
• CI: Clean up pre-release builds (CI: Clean up pre-release builds #3040)

---

This discussion was created from the release 23.2.0a1.

[effigies]

23.2.0a2

Release notes

A quick turnaround patch for the 23.2.0a pre-releases. Thanks to @smeisler for spotting a bug. This release includes the necessary fix in sMRIPrep, as well as several improvements to tests and opportunistic cleanups.

What's Changed

• FIX: Update smriprep to 0.13.1 by @smeisler in MNT: Update smriprep to 0.13.1 #3153
• FIX: Tag memory estimates in resamplers by @effigies in FIX: Tag memory estimates in resamplers #3150
• ENH: Pass FLAIR images to anatomical workflow builder to include in boilerplate by @effigies in ENH: Pass FLAIR images to anatomical workflow builder to include in boilerplate #3146
• TEST: Add smoke-tests for bold_fit_wf by @effigies in TEST: Add smoke-tests for bold_fit_wf #3152
• MNT: Update tedana pin, test on Python 3.12 by @effigies in MNT: Update tedana pin, test on Python 3.12 #3141
• MNT: update vendored docs script github_link.py by @DimitriPapadopoulos in MNT: update vendored docs script github_link.py #3144
• MNT: optimise size of PNG files by @DimitriPapadopoulos in MNT: optimise size of PNG files #3145
• DOC: Minor updates in outputs.rst by @effigies in DOC: Minor updates in outputs.rst #3148
• DOCKER: Restore mritotal subcommands by @effigies in DOCKER: Restore mritotal subcommands #3149
• STY: Apply a couple refurb suggestions by @DimitriPapadopoulos in STY: Apply a couple refurb suggestions #3151

New Contributors

• @smeisler made their first contribution in MNT: Update smriprep to 0.13.1 #3153

Full Changelog: 23.2.0a1...23.2.0a2

[effigies]

23.2.0a3

Release notes

The final alpha release of fMRIPrep 23.2.0.

With thanks to everybody who has reported bugs and shared data for testing.

What's Changed

• FIX: Disable boldref-space outputs unless requested by @effigies in FIX: Disable boldref-space outputs unless requested #3159
• FIX: Exclude echo entity from optimally combined derivatives by @tsalo in Exclude echo entity from optimally combined derivatives #3166
• FIX: Keep minctracc executable in FreeSurfer installation by @effigies in FIX: Keep minctracc [skip ci] #3175
• FIX: Retrieve atlas ROIs at requested density by @effigies in FIX: Retrieve atlas ROIs at requested density #3179
• FIX: Restore --ignore sbref functionality by @effigies in FIX: Restore --ignore sbref functionality #3180
• ENH: Exclude non-steady-state volumes from confound correlation plot by @tsalo in Exclude non-steady-state volumes from confound correlation plot #3171
• RF: Separate goodvoxels mask creation from fsLR resampling by @tsalo in Separate goodvoxels mask creation from fsLR resampling #3170
• RPT: Rename CSF/WM confounds in fMRIPlot by @tsalo in RPT: Rename CSF/WM confounds in fMRIPlot #3172
• TST: Add smoke tests for full workflow and most branching flags by @effigies in TEST: Add smoke tests for full workflow and most branching flags #3155
• MNT: Load reportlets interfaces from nireports rather than niworkflows by @celprov in MAINT: load reportlets interfaces from nireports rather than niworkflows #3176
• CI: Bump actions/setup-python from 4 to 5 by @dependabot in Bump actions/setup-python from 4 to 5 #3181

Full Changelog: 23.2.0a2...23.2.0a3

[effigies]

23.2.1

Release notes

Bug fix release in the 23.2.x series.

Masks, BOLD references and T2* maps resampled into template spaces had
their order of transforms inverted. BOLD files were unaffected.

This release also preserves the TR in the NIfTI header of BOLD series.

Changes

• FIX: Preserve pixdim4+ of resampled images (FIX: Preserve pixdim4+ of resampled images #3239)
• FIX: Flip order of transforms in init_ds_volumes_wf (Flip order of transforms in init_ds_volumes_wf #3238)
• DOCKER: restore mincinfo binary (DOCKER: Restore mincinfo binary #3249)
• CI: Move to new CircleCI machine tags (MNT: Drop copyright year, unused dunder fields #3247)

Full Changelog: 23.2.0...23.2.1

[effigies]

23.2.2

Release Notes

Bug fix release in the 23.2.x series.

Fixes an issue with broken connections, which only affects --level resampling.

What's Changed

• FIX: Add datasink fill-in step to resampling level by @tsalo in FIX: Add datasink fill-in step to resampling level #3254

Full Changelog: 23.2.1...23.2.2

[effigies]

23.2.3

Release notes

Bug fix release in the 23.2.x series.

Writes brain masks in space-boldref with --level minimal, bringing behavior in line with documentation.

Changelog

• FIX: Write out boldref-space brain mask with minimal level by @tsalo in FIX: Write out boldref-space brain mask with minimal level #3292

Full Changelog: 23.2.2...23.2.3