Release notes

New feature release in the 23.1.x series.

This release substantially reworks the resampling to fsLR grayordinate space, better accounting for partial volumes and high variance voxels. If you are resampling using --project-goodvoxels, we strongly recommend upgrading.

Fieldmap handling is improved, with better preference given to single-band references in both PEPolar and SyN-SDC schemes. Additionally, fMRIPrep will no longer estimate fieldmaps that are not intended to be used to correct BOLD series, reducing unneeded processing.

This release removes ICA-AROMA from the fMRIPrep workflow. To use ICA-AROMA, set MNI152NLin6Asym:res-2 as a target output space. MELODIC and ICA-AROMA can be run on the resulting images in a separate pipeline. For further information on the reasoning behind this change, see GitHub issue #2936.

This release increments the versions of ANTs and FSL bundled in the Docker image.

With thanks to Eilidh MacNicol, Basille Pinsard and Taylor Salo for contributions in fMRIPrep and SDCflows.

Changes

• FIX: Raise RuntimeError at build if echos have mismatched shapes (#3028)
• FIX: Inconsistent fmapless estimation when ignoring fieldmaps (#2994)
• FIX: Dilate BOLD mask by 2 voxels to prevent over-aggressive masking degrading T2* map estimation (#2986)
• FIX: Estimate free memory with "available", not "free" (#2985)
• ENH: Add --me-t2s-fit-method parameter (#3030)
• ENH: Resample BOLD to fsLR directly, dropping fsaverage intermediate (#3011)
• ENH: Allow SBref+EPI PEPolar fieldmaps to correct BOLD series (#3008)
• ENH: Remove ICA-AROMA from workflow and docs (#2966)
• RF: Filter fieldmaps based on whether they will be used to correct a BOLD series (#3025)
• MNT: Update ANTs pin in Docker image (#3016)
• MNT: Update governance docs (#2992)
• MNT: Refactor Docker build process (#2982)
• MNT: Pin conda environment more strictly (#2853)
• MNT: Require niworkflows ~1.3.6 (#2740)
• CI: Use registry for layer caching (#3012)
• CI: Upgrade docker orb (#2865)

Full Changelog: https://github.com/nipreps/fmriprep/compare/23.0.2...23.1.0

Release notes

New feature release in the 23.1.x series.

This release substantially reworks the resampling to fsLR grayordinate space, better accounting for partial volumes and high variance voxels. If you are resampling using --project-goodvoxels, we strongly recommend upgrading.

Fieldmap handling is improved, with better preference given to single-band references in both PEPolar and SyN-SDC schemes. Additionally, fMRIPrep will no longer estimate fieldmaps that are not intended to be used to correct BOLD series, reducing unneeded processing.

This release removes ICA-AROMA from the fMRIPrep workflow. To use ICA-AROMA, set MNI152NLin6Asym:res-2 as a target output space. MELODIC and ICA-AROMA can be run on the resulting images in a separate pipeline. For further information on the reasoning behind this change, see GitHub issue #2936.

This release increments the versions of ANTs and FSL bundled in the Docker image.

With thanks to Eilidh MacNicol, Basille Pinsard and Taylor Salo for contributions in fMRIPrep and SDCflows.

Changes

• FIX: Raise RuntimeError at build if echos have mismatched shapes (#3028)
• FIX: Inconsistent fmapless estimation when ignoring fieldmaps (#2994)
• FIX: Dilate BOLD mask by 2 voxels to prevent over-aggressive masking degrading T2* map estimation (#2986)
• FIX: Estimate free memory with "available", not "free" (#2985)
• ENH: Add --me-t2s-fit-method parameter (#3030)
• ENH: Resample BOLD to fsLR directly, dropping fsaverage intermediate (#3011)
• ENH: Allow SBref+EPI PEPolar fieldmaps to correct BOLD series (#3008)
• ENH: Remove ICA-AROMA from workflow and docs (#2966)
• RF: Filter fieldmaps based on whether they will be used to correct a BOLD series (#3025)
• MNT: Update ANTs pin in Docker image (#3016)
• MNT: Update governance docs (#2992)
• MNT: Refactor Docker build process (#2982)
• MNT: Pin conda environment more strictly (#2853)
• MNT: Require niworkflows ~1.3.6 (#2740)
• CI: Use registry for layer caching (#3012)
• CI: Upgrade docker orb (#2865)

Full Changelog: https://github.com/nipreps/fmriprep/compare/23.0.2...23.1.0rc0

Release Notes

This release fixes issues with _phase1+2, _phasediff and _fieldmap fieldmap files that are found with an orientation other than RAS.

See SDCflows 2.4.3 for changes.

Release Notes

Bug fix release in the 23.0.x series.

This release fixes issues with detecting partial fieldmaps, emitting a warning instead of an error. A small change in sMRIPrep fixes the name of a workflow, which may cause a duplication in a reused work directory from 23.0.0, but should not break any workflows or produce a change in derivatives.

Changes

• DOC: Add TemplateFlow's citation into bibtex file by @oesteban in https://github.com/nipreps/fmriprep/pull/2969

Full Changelog: https://github.com/nipreps/fmriprep/compare/23.0.0...23.0.1

Release Notes

New feature release in the 23.0.x series.

This release adds improvements for workflows targeting the fsLR grayordinate space. Namely, morphometric (curvature, sulcal depth and cortical thickness) measures are output as .dscalar.nii files and high-variance voxels can be excluded from the resampling step using --project-goodvoxels.

Additionally, T2w images are now resampled to the T1w-defined subject space if FreeSurfer reconstruction is used. If multiple T2w images are provided, they are merged into a single image first.

PEPolar fieldmaps with R/L phase-encoding directions or in non-standard orientations are now better supported. We continue to work toward better support for more SDC configurations.

23.0.0 supports FreeSurfer 7.3.2, which is now bundled in the Docker image.

ICA-AROMA support will be removed in 23.1.0.

With thanks to Thomas Madison, Greg Conan, Celine Provins, Robert Smith and Yaroslav Halchenko for contributions. Thanks also to Steve Giavasis and colleagues at the Child Mind Institute for feedback on SDC processing.

Changes

• FIX: Pass reference image to unwarp_wf, use reference fieldwarp for single shot (#2945)
• FIX: Pass fmap filters to sdcflows (#2932)
• ENH: Resample morphometrics to fsLR dscalar CIFTI-2 files if --cifti-output is used (#2959)
• ENH: Add option to exclude projecting high variance voxels to surface (update of #2855) (#2956)
• ENH: Separate deep from shallow WM+CSF in the carpetplot (#2744)
• ENH: Merge T2w images and coregister to T1w template (#2941)
• RF: Use DataFrame.rename instead of ad hoc process (#2937)
• DOC: Update the description of the carpetplot in the sample report (#2950)
• DOC: Altered CLI option grouping (#2944)
• DOC: Update lesion ROI documentation, warn in docs and app about upcoming changes (#2943)
• DOC: Update docs following read-through (#2930)
• DOC: Update carpetplot in "Outputs of fMRIPrep" (#2923)
• MNT: Codespell config, action + some typo fixups (#2958)
• MNT: Warn that AROMA support will be removed in a future version (#2940)
• MNT: Update Ubuntu, FreeSurfer, AFNI and Convert3D (#2931)
• MNT: Switch to hatch build backend and update package metadata (#2914 + #2939)
• MNT: Rotate CircleCI secrets and setup up org-level context (#2928)
• CI: Minor updates to CircleCI config to improve resilience (#2957)
• CI: Weekly docker build from scratch (#2938)

New Contributors

• @Lestropie made their first contribution in https://github.com/nipreps/fmriprep/pull/2944
• @madisoth made their first contribution in https://github.com/nipreps/fmriprep/pull/2956

Full Changelog: https://github.com/nipreps/fmriprep/compare/22.1.1...23.0.0

22.1.0 (December 12, 2022)

New feature release in the 22.1.x series.

This is an incremental improvement on the 22.0.x series, including features and fixes that are backwards incompatible with the 22.0.x work tree.

Several significant issues with susceptibility distortion correction (SDC) have been fixed in SDCFlows 2.2.0, in addition to the changes listed below. If you have been seeing issues with SDC in 21.0.x or 22.0.x, please test out this version and submit issues.

Additionally, this version includes improvements to structural preprocessing, generating morphometric .shape.gii files from FreeSurfer derivatives.

Finally, this release introduces a method for estimating the carbon footprint of using fMRIPrep. Add --track-carbon to your command to try this out. Note that it does not work in Docker containers, but should work for Singularity containers.

With thanks to Nikhil Bhagwat for contributions.

Changes

• FIX: Conform --reports-only to match post-run report generation (#2900)
• FIX: Remove cortex masking during vol2surf sampling (#2879)
• FIX: Do not attempt to calculate TA if SliceTiming is degenerate (#2901)
• FIX: Pass CrownCompCor components to GatherConfounds (#2897)
• FIX: Output brain mask and boldref in BOLD space if individual echos requested (#2852)
• FIX: Check for empty ACompCor results before trying to rename (#2851)
• FIX: Filter sbrefs by BIDS filters if available (#2843)
• ENH: Provide free memory estimate to unwarp_wf for better resources allocation (#2910)
• ENH: Add migas telemetry in addition to sentry (#2817)
• ENH: Tag memory based on data shape, annotate T2SMap (#2898)
• ENH: Add of carbon tracker to estimate workflow emissions (#2834)
• ENH: Output BOLD HMC transforms and reference volume (#2860)
• RF: CIFTI generation (#2884)
• DOC: Correct description of --longitudinal behavior (#2905)
• MNT: Update fast track outputs, use latest smriprep (#2894)
• MNT: Deprecate --topup-max-vols (#2881)
• MNT: Add a --debug pdb to allow easier line-by-line debugging (#2871)
• MNT: Generate more verbose reports (here, showing fieldmaps) if running in debug mode (#2872)
• DOCKER: Build wheel and install in two-stage build (#2859)
• CI: Various updates (#2899)
• CI: Test on Python 3.10, bump actions versions (#2895)
• CI: Fix non-fasttrack outputs for maint/21.0.x (#2866)

New Contributors

• @nikhil153 made their first contribution in https://github.com/nipreps/fmriprep/pull/2834

Full Changelog: https://github.com/nipreps/fmriprep/compare/22.0.2...22.1.0

Release Notes

A patch release in the 22.0.x series.

This release increases the minimum Nipype version to include better error messages on failures. Additionally, this includes a fix to allow SyN distortion correction in combination with the --ignore fieldmaps option.

Changes

• MAINT: Add pre-commit, dev installation for consistent styling (https://github.com/nipreps/fmriprep/pull/2857)
• CI: Upgrade docker orb (https://github.com/nipreps/fmriprep/pull/2858)

Release Notes

A patch release in the 22.0.x series.

This release includes relaxed tolerance in the case where fieldmap affines slightly differed, and a fix for running FreeSurfer 7 with an outdated fsaverage folder.

Changes

• ENH: Add check to ensure latest fsaverage folder is used (https://github.com/nipreps/fmriprep/pull/2847)
• FIX: Filter sbrefs by BIDS filters if available (https://github.com/nipreps/fmriprep/pull/2843)
• FIX: Avoid crashing on empty ACompCor results (https://github.com/nipreps/fmriprep/pull/2850)

Release Notes

New feature release in the 22.0.x series.

This release has been tested to work with Python 3.9 and FreeSurfer 7.2, which are now bundled in the Docker image.

This release also features improvements to T2* and carpetplot reporting.

For the next release, we are investigating issues with susceptibility distortion correction (SDC). Please check your results carefully and report any issues you find.

Changes

• FIX: Update wrapper python path (#2783)
• FIX: Preserve collect_data behavior by using named args (#2754)
• FIX: Update fMRIPrep version in bibliography at run time (#2738)
• FIX: Plot carpetplot with CIFTI-specific colorbar (#2737)
• FIX: Two minor typos in report spec (#2708)
• ENH: Clip T2* values at 100ms to keep consistent histogram axes (#2781)
• ENH: Plot histogram of T2* values in gray-matter mask (#2778)
• ENH: Save T2starmap files in all requested output spaces, if calculated (#2776)
• ENH: Compare T2* map to BOLD reference (#2751)
• ENH: Add edge-regressors to confounds & crown to carpetplot (#2621)
• ENH: Add major/minor versions to base workflow name (#2716)
• DOC: Fix JSON typo in config in FAQ (#2771)
• DOC: Clarify calculation of confounding signals (#2724)
• MNT: Build on Python 3.9 environment (#2782)
• MNT: Seed ignore-revs file and script to tag new hashes with log entries (#2748)
• MNT: Require PyBIDS 0.15+ to allow fMRIPrep to preserve zero-padding in run entity (#2745)
• MNT: Upload artifacts after each step of Circle's workflow (#2736)
• MNT: Normalize code style of workflows.confounds (#2729)
• MNT: Ask for fmriprep-docker RUNNING line (#2670)
• DOCKER: Bundle FreeSurfer 7 (#2779)
• CI: Touch up CircleCI configuration (#2764)
• CI: Update package builds to use python -m build (#2746)

New Contributors

• @keithcallenberg made their first contribution in https://github.com/nipreps/fmriprep/pull/2708
• @dillonplunkett made their first contribution in https://github.com/nipreps/fmriprep/pull/2724
• @Remi-Gau made their first contribution in https://github.com/nipreps/fmriprep/pull/2771

Full Changelog: https://github.com/nipreps/fmriprep/compare/21.0.2...22.0.0

This release candidate includes fixes for failing DVARS, running recon-all with T2w images, and misaligned GIFTI surfaces.

Full Changelog: https://github.com/nipreps/fmriprep/compare/22.0.0rc3...22.0.0rc4