23.2.3 (May 20, 2024)

Bug fix release in the 23.2.x series.

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

* FIX: Write out boldref-space brain mask with minimal level (#3292)

23.2.2 (May 06, 2024)

Bug fix release in the 23.2.x series.

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

* FIX: Add datasink fill-in step to resampling level (#3254)

23.2.1 (March 06, 2024)

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.

* FIX: Preserve pixdim4+ of resampled images (#3239)
* FIX: Flip order of transforms in ``init_ds_volumes_wf`` (#3238)
* DOCKER: restore mincinfo binary (#3249)
* CI: Move to new CircleCI machine tags (#3247)

23.2.0 (January 10, 2024)

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.

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

23.2.0a3 (December 13, 2023)

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.

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

23.2.0a2 (November 21, 2023)

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.

* FIX: Tag memory estimates in resamplers (#3150)
* FIX: Final revisions for next branch (#3134)
* FIX: Minor fixes to work with MSMSulc-enabled smriprep-next (#3098)
* FIX: Connect EPI-to-fieldmap transform (#3099)
* FIX: Use Py2-compatible version file template for fmriprep-docker (#3101)
* FIX: Update connections to unwarp_wf, convert ITK transforms to text (#3077)
* ENH: Pass FLAIR images to anatomical workflow builder to include in boilerplate (#3146)
* ENH: Restore carpetplot and other final adjustments (#3131)
* ENH: Restore CIFTI-2 generation (#3129)
* ENH: Restore resampling to surface GIFTIs (#3126)
* ENH: Restore confound generation (#3120)
* ENH: Restore resampling BOLD to volumetric templates (#3121)
* ENH: Restore resampling to T1w target (#3116)
* ENH: Add MSMSulc (#3085)
* ENH: Add reporting workflow for BOLD fit (#3082)
* ENH: Generate anatomical derivatives useful for resampling (#3081)
* RF: Write out anatomical template derivatives (#3136)
* RF: Update primary bold workflow to incorporate single shot resampling (#3114)
* RF: Update derivative cache spec, calculate per-BOLD, reuse boldref2fmap (#3078)
* RF: Split fMRIPrep into fit and derivatives workflows (#2913)
* TST: Add smoke-tests for bold_fit_wf (#3152)
* DOC: Fix documentation and description for init_bold_grayords_wf (#3051)
* DOC: Minor updates in outputs.rst (#3148)
* STY: Apply a couple refurb suggestions (#3151)
* STY: Fix flake8 warnings (#3044)
* STY: Apply pyupgrade suggestions (#3043)
* MNT: Restore mritotal subcommands to Dockerfile (#3149)
* MNT: Update smriprep to 0.13.1 (#3153)
* MNT: optimise size of PNG files (#3145)
* MNT: update vendored docs script `github_link.py` (#3144)
* MNT: Update tedana pin, test on Python 3.12 (#3141)
* MNT: Bump environment (#3132)
* MNT: Bump version requirements (#3107)
* MNT: http:// → https:// (#3097)
* MNT: Remove mritotal and dependencies from FreeSurfer ignore file (#3090)
* MNT: Update environment (#3073)
* MNT: Depend on newer sphinx (#3067)
* MNT: Install ANTs from conda-forge (#3061)
* MNT: Drop Python 3.8 and numpy 1.21 support (NEP29) (#3052)
* MNT: update update_zenodo.py script (#3042)
* MNT: Fix welcome message formatting and instructions (#3039)
* MNT: Python 3.11 should be supported (#3038)
* CI: Stop testing legacy layout (#3079)
* CI: Improve tag detection for docker builds (#3066)
* CI: Clean up pre-release builds (#3040)

23.2.0a1 (November 21, 2023)

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.

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

23.1.4 (August 1, 2023)

Patch release in the 23.1.x series.

This release prioritizes single-band reference BOLD images during SyN-SDC schemes.
Additionally, an indices inconsistency was fixed for CIFTI volumetric data.

* FIX: Pass sbref files to SyN workflow (#3060)
* FIX: Generate CIFTI volume structure indices in column-major order (nipreps/niworkflows#815)

23.1.3 (June 24, 2023)

Bug fix release in the 23.1.x series.

In rare cases where Freesurfer is unable to align to its default atlas in
Talairach registration, it was unable to fall back to the Schwartz atlas
because we were not including it in the Docker image. This release exists
to provide an updated Docker image, and no upgrade is needed for users not
encountering this issue.

* DOCKER: Include 3T18yoSchwartzReactN32 FreeSurfer atlas in image (#3049)

23.1.2 (June 16, 2023)

Bug fix release in the 23.1.x series.

This release correctly generates ``*_space-fsLR_desc-reg_sphere.surf.gii``,
which was previously a copy of the standard ``*_desc-reg_sphere.surf.gii``.
Additionally, warnings are now correctly emitted when AROMA-related CLI
options are used.

* CI: Clean up pre-release builds (#3040)

23.1.1 (June 14, 2023)

Bug fix release in the 23.1.x series.

This release corrects a small error that prevented the "goodvoxels" mask from
being placed in the output directory if no FreeSurfer output spaces were specified.

* FIX: Remove bad metadata input from ds_goodvoxels_mask (#3037)

23.1.0 (June 12, 2023)

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 <https://github.com/nipreps/fmriprep/issues/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.

* 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)

23.1.0 (To be determined)

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 <https://github.com/nipreps/fmriprep/issues/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.

* 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)

23.1.0rc0 (June 9, 2023)

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<https://github.com/nipreps/fmriprep/issues/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.

* 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)

23.0.2 (April 24, 2023)

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

23.0.1 (March 24, 2023)

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.

23.0.0 (March 13, 2023)

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.

* 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)

23.0.0rc0 (March 6, 2023)

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.

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.

* 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)

22.1.1 (January 04, 2023)

Bug fix release in the 22.1.x series.

This release fixes the reported version in the distributed Docker image,
and depends on SDCFlows 2.2.2, which fixes a bug affecting SDC estimation
in some oblique datasets.

  * FIX: Ensure version installed in Docker file is clean (#2922)

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.

  * 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)