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.

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)

Bug fix release in the 23.0.x series.

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)

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)

22.0.2 (September 27, 2022)

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.

MAINT: Add pre-commit, dev installation for consistent styling (#2857)

CI: Upgrade docker orb (#2858)

22.0.1 (September 13, 2022)

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.

ENH: Add check to ensure latest fsaverage folder is used (#2847)

FIX: Filter sbrefs by BIDS filters if available (#2843)

FIX: Avoid crashing on empty ACompCor results (#2850)

22.0.0 (July 28, 2022)

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.

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)

21.0.4 (September 29, 2022)

Bug-fix release in the 21.0.x series.

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)

CI: Fix non-fasttrack outputs for maint/21.0.x (#2866)

21.0.3 (September 6, 2022)

Bug-fix release in the 21.0.x series.

This release includes a fix for --bids-filter-file not respecting sbref filtering.

FIX: Filter sbrefs by BIDS filters if available (#2843)

21.0.2 (April 21, 2022)

Bug-fix release in the 21.0.x series.

This release includes a few bug-fixes for susceptibility distortion correction (SDC) and multi-echo (ME). A few notable fixes include: - Added tolerance for affine precision differences when using EPI fieldmaps. - Removed hang-ups when reusing anatomical derivatives with ME data. - Increased BOLD masking workflow robustness.

A full list of changes can be found below:

DOCKER: Update multiarch deb package link (#2758)

ENH: Add affine_tolerance flag to MergeSeries (nipreps/niworkflows#706)

FIX: Initialize BIDS layout after cleaning working directory (#2741)

FIX: Avoid double unwarping during resampling of processed multi-echo data (#2730)

FIX: Account for potential lists of lists in multi-echo cases (nipreps/niworkflows#719)

FIX: Improve reliability of BOLD masking workflow (nipreps/niworkflows#712)

FIX: Relax tolerance for different affines when concatenating blips (nipreps/sdcflows#265)

21.0.1 (January 24, 2022)

Bug-fix release in the 21.0.x series.

This release re-enables reverse-PE EPI fieldmaps, i.e. EPIs acquired with the opposite phase-encoding direction to a BOLD series. Additionally, the --use-syn-sdc option will now error by default if no PhaseEncodingDirection can be found for a BOLD series. To reduce this to a warning, use --use-syn-sdc warn. SyN-SDC will NOT be run, but the workflow will proceed.

Note

topup runtime scales with the number of volumes used, so fMRIPrep defaults to using a maximum of 5 volumes from each of the BOLD series and the EPI fieldmap. To adjust this, please use the --topup-max-vols parameter.

FIX: Create single fmap_select_std node for use with all ANAT estimators (#2692)
FIX: Re-enable reverse-PE EPI fieldmaps (#2684)
FIX: Pass boolean use_syn_sdc to find_estimators (#2685)
FIX: Ensure AROMA inputs are uncompressed if --low-mem (#2657)
ENH: Add --topup-max-vols flag to control TOPUP runtime (#2688)
ENH: Allow --use-syn-sdc to take a "warn" option to avoid exiting when PE dir is unavailable (#2680)
RF: Add extension field to differentiate from upcoming templates (#2613)
WRAPPER: Map --bids-filter-files into Docker container (#2691)
MNT: Silence warning from pybids; list packaging as dependency (#2689)
MNT: Add netbase to Docker image to ensure correct datalad operation (#2682)
MNT: Restore nitime to requirements, necessary for DVARS (#2678)

21.0.0 (December 14, 2021)

A new series is finally here!

Some highlights of this version's new features include a substantial rework of fMRIPrep's susceptibility distortion correction (including the addition of FSL's topup as the new default PEPOLAR correction technique), improved flexibility for multiecho scans, and dependency version upgrades within the Docker environment.

Note

To follow BIDS Derivatives more closely, fMRIPrep's default output layout has changed. To enable the legacy layout, use the --output-layout legacy flag. For more information, please see https://fmriprep.org/en/latest/outputs.html#layout

Caution!

As with all minor version increments, working directories from previous versions should not be reused.

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

A full list of changes can be found below.

DOC: Remove mention to epidewarp.fsl from NOTICE (#2629)
DOC: Update description of output layout, add discussion of legacy mode (#2646)
DOC: ME | Add missing output to documentation, improve boilerplate (#2608)
DOC: Add --index-metadata to pybids layout faq (#2546)
DOC: Add warning about slice timing correction in output documentation. (#2502)
DOC: Update sample report (#2519)
DOC: Refactor README and citing information (#2474)
DOC: Point documentation at SDCFlows and remove SDC section (#2470)
DOC: Transfer duplicated documentation to www.nipreps.org (#2469)
DOC: Better explanation on how spike regressors are generated (#2465)
DOC: Clarify that res-2 entity does not mean 2mm (#2466)
DOC: adds --mem metavar (#2378)
DOC: skull stripping is forced by default (#2345)
DOCKER: Shrink Docker image size (#2551)
DOCKER: Strip ABI tag from libQt5Core.so.5 to prevent Singularity failures (#2535)
ENH: Make bids the default output layout option (#2555)
ENH: Mask multi-echo data with reference mask instead of echo-specific masks (#2349)
ENH: Replace initial FLIRT with mri_coreg, use -basescale 1 for FLIRT-BBR (#2625)
ENH: Add flag for STC reference time and set in all cases (#2520)
ENH: Use BIDSLayoutIndexer and do not index unnecessary modalities (#2494)
ENH: Allow users to download templateflow templates to directory (#2482)
ENH: Detect 3D & too-short BOLD series, warn and skip run's workflow building (#2461)
ENH: Modernize Dockerfile (#2409) (#2270)
ENH: Leverage SDCFlows 2.x API (#2392)
ENH: Tedana-friendly ME derivatives (#2575)
ENH: Better integration of SDCFlows' unwarping (#2576)
ENH: Refactor workflow to adopt SDCFlows' new correction workflow (#2547)
FIX: Threshold boldref resampled values to be non-negative (#2630)
FIX: Restore SyN-SDC (#2530)
FIX: Confusing I/O field bold_mask in bold-to-bold resampling workflow (#2611)
FIX: ME | Revise SDC compute graph (#2610)
FIX: Propagate the SDC warp to resampling node also with ME (#2609)
FIX: Optimize build job on CircleCI (#2605)
FIX: Minor multiecho issues (#2574)
FIX: Missing numpy import (#2533)
FIX: Avoid eager imports from NiWorkflows causing API breaks (#2495)
FIX: Split aCompCor into aCompCor, cCompCor, wCompCor (#2523)
FIX: Avoid unnecessary connections based on branching logic (#2508)
FIX: Permit missing TR to show PyBIDS error at workflow construction time (#2513)
FIX: Simplify STC logic for too short BOLD series (#2489)
FIX: Catch FreeSurfer error related to FIPS being enabled (#2490)
FIX: DerivativesDataSink nondeterministic checksums fixed with niworkflows=~1.3.4 (#2458)
FIX: Address dependency incompatibilities by pinning specific packages (#2463)
FIX: Unprotected import of sentry_sdk, which is not a dependency (#2460)
FIX: Clarify phase encoding direction, rather than axis (#2302)
MAINT: Conform fast-track outputs to BIDS ordering (#2663)
MAINT: Reduce redundant processing of ds005 (#2649)
MAINT: Finalize the work we started with the refactor of the Docker image (#2601)
MAINT: Run full workflows on tags (#2593)
MAINT: Stage Python environment of Docker image from nipreps/miniconda (#2581)
MAINT: Stop NeuroDebian dependency in Dockerfile (#2578)
MAINT: Run pytest through GitHub actions (#2529)
MAINT: Relicense +20.3.x - BSD-3-Clause -> Apache License 2.0 (#2325)
MAINT: Add missing OASIS30 WM/BS probsegs (#2471)
MAINT: Update BIDS validator to 1.8.0 (#2443)
MAINT: Address the problems of a sloppy merge (#2468)
MAINT: Containers - remove /root/.npm (#2464)
MAINT: Remove traces of Xenial base (#2459)
MAINT: Revise CircleCI's cache tags to avoid mixups between builds (#2457)
MAINT: Back port CircleCI configuration from dev branch (#2456)
MAINT: Increase minimum tedana version (#2366)
MAINT: Docker hub has disabled password authentication (#2448)
MAINT: Add Lea Waller to contributors.json (#2304)
MAINT: Move away from nearly deprecated images (#2295)
MAINT: Migrate from poldracklab to nipreps orgs (#2290)
MAINT: Ease CI packaging tests (#2472)
RF/FIX: Iterate over echo indices, not filenames, simplifying iteration logic (#2651)

20.2.7 (January 24, 2022)

Bug-fix release in the 20.2.x LTS series.

FIX: Clarify phase encoding direction, rather than axis (#2690)

FIX: Ensure AROMA inputs are uncompressed if --low-mem (#2657)

FIX: Add -basescale 1 parameter to avoid flirt scaling (#2624)

WRAPPER: Map --bids-filter-files into Docker container (#2691)

MNT: Add netbase to Docker image to ensure correct datalad operation (#2682)

20.2.6 (October 27, 2021)

Patch release in the 20.2.x LTS series.

This release includes an updated runtime environment for Docker/Singularity users. This environment includes a newer release of indexed_gzip, fixing CrcErrors previously encountered.

CI: Run full workflows on tags (#2593)

RF: Add extension field to differentiate from upcoming templates (#2613)

20.2.5 (October 12, 2021)

Bug-fix release in the 20.2.x LTS series.

This release includes a fix to --slice-time-ref parsing. Also, some issues in anatomical processing are resolved, including poorly-interpolated labels in aseg segmentations, and probabilistic segmentations have reverted to FAST.

FIX: --slice-time-ref option parsing (#2573)

CI: Add style checks (missing since Travis got throttled) (#2570)

20.2.4 (October 04, 2021)

Bug-fix release in the 20.2.x LTS series.

This release includes some fixes to minor bugs, and includes enhancements to allow the user to specify a different slice-timing-correction (STC) target.

Each BOLD series will contain SliceTimingCorrected metadata to indicate whether STC was performed. If performed, the StartTime metadata field will be set to indicate the onset time of the BOLD series.

FIX: Avoid unnecessary connections based on branching logic (#2508)

FIX: Permit missing TR to show PyBIDS error at workflow construction time (#2513)

[BACKPORT] FIX: Catch FreeSurfer error related to FIPS being enabled (#2490)

ENH: Use BIDSLayoutIndexer and do not index unnecessary modalities (#2494)

[BACKPORT] ENH: Slice-timing correction improvements (#2565)

20.2.3 (July 21, 2021)

Patch release in the 20.2.x LTS series. Addresses minimal problems in some edge-cases, overall improves the documentation and infrastructure. Exercises some maintenance operations addressing problems surfaced when the previous tag 20.2.2 was released.

FIX: Address the problems of a sloppy merge (#2468)

FIX: DerivativesDataSink nondeterministic checksums fixed with niworkflows=~1.3.4 (#2458)

FIX: Address dependency incompatibilities by pinning specific packages (#2463)

FIX: Unprotected import of sentry_sdk, which is not a dependency (#2460)

ENH: Detect 3D & too-short BOLD series, warn and skip run's workflow building (#2461)

DOC: Transfer duplicated documentation to www.nipreps.org (#2469)

DOC: Better explanation on how spike regressors are generated (#2465)

DOC: Clarify that res-2 entity does not mean 2mm (#2466)

MAINT: Containers - remove /root/.npm (#2464)

MAINT: Back port CircleCI configuration from dev branch (#2456)

20.2.2 (July 16, 2021)

Hot-fix release in the 20.2.x LTS series. Addressing a bug on fMRIPrep's resampling to standard spaces (#2444). In addition, some other relevant bug-fixes and performance improvements are built in this patch.

FIX: Feed NiTransforms with LTAs of type RAS2RAS (#2444)
FIX: Add some clarity to BrokenProcessPool failures (#2436)
FIX: Fall-back to initializing workflow in main process (#2435)
FIX: Raise informative error when duplicate subworkflows are added (#2434)
FIX: Non-existing path or JSON syntax error for --bids-filter-file should raise on error (#2331)
FIX: Ignore SBRef files if --ignore sbref is passed (#2370)
ENH: Relax requirement for PyBIDS databases to exist (#2429)
ENH: Improve _get_series_len performance (#2406)
ENH: Set and track NumPy's random seed (#2400)
DOC: Skull-stripping is forced by default (#2430)
MAINT: Pin nilearn==0.6.2 (#2427)
MAINT: Pin tedana==0.0.9a1 for LTS branch (#2403)
MAINT: Failing CI (#2401)

20.2.1 (November 06, 2020)

Bug-fix release in the 20.2.x LTS series.

This release adds missing metadata to GIFTI and CIFTI-2 derivatives and fixes a logging bug affecting a small number of datasets.

Additionally the --output-layout bids flag will now output fMRIPrep derivatives directly into the output directory, nesting FreeSurfer derivatives by default in <output>/sourcedata/freesurfer. This layout allows the output root to be a valid BIDS Derivatives dataset, simplifying data management and provenance tracking with content tracking tools, such as DataLad. This layout will likely become the default in future release series.

ENH: Output TaskName and timing metadata for all resampled BOLD series (#2320)
ENH: Add --output-layout CLI option to enable BIDS (YODA) mode (#2303)
ENH: Add Docker authentication to increase pull rate limit (#2316)
FIX: Specify logger for warning (#2298)

20.2.0 (September 28, 2020)

With this third minor release series of 2020, the first fMRIPrep LTS (long-term support) is finally here!

This release contains a number of bug-fixes and enhancements mostly related to easing the maintenance, anticipating patch-release breaking changes to ensure a longstanding LTS, and addressing some run-to-run repeatability problems of the CompCor implementation.

Long-Term Support (LTS)

fMRIPrep 20.2 LTS introduces the long-term support program. 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 LTS is planned for a window of 4 years of support (i.e., until September 2024).

Caution!

As with all minor version increments, working directories from previous versions should not be reused.

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

A full list of changes can be found below.

FIX: Pin NiWorkflows 1.3.1 and sMRIPrep 0.7.0rc2, including bugfix for INU-correction failures (nipreps/niworkflows#567)
FIX: Get missing probseg file from MNI152NLin2009cAsym (#2271)
FIX: Restore --ignore t2w/flair options (#2260)
FIX: Revise the reproducibility of CompCor masks (#2130)
FIX: Simplify transform aggregation in resampling, pass identity transforms for multi-echo cases (#2239)
FIX: Skip the T1w check if --anat-derivatives is provided. (#2201)
FIX: Storing --bids-filters within config file (#2177)
FIX: Revise multi-echo reference generation, permitting using SBRefs too (#1803)
FIX: FreeSurfer license manipulation & canary
ENH: Output CompCor masks if --debug compcor is passed (#2248)
ENH: Conform to BIDS Derivatives as of BIDS 1.4.0 (#2223)
ENH: Reuse config (#2240)
ENH: Save BOLD-anatomical transforms to derivatives folder (#2233)
ENH: Leverage BIDSLayout's database_path (#2203)
ENH: Add --no-tty option to fmriprep-docker.py (#2204)
ENH: Report number of echoes in BOLD summary. (#2184)
ENH: Ensure NiPype telemetry is just pinged once (#2168)
DOC: Add FAQ entry for using pre-indexed layouts (#2256)
DOC: Update reference in "Refinement of Brain Mask" description (#2215)
DOC: List TemplateFlow templates that need to be prefetched (#2196)
DOC: Update references to https://github.com/nipreps (#2191)
DOC: Pin NiPype with new Sphinx extension syntax (#2092)
MAINT: Upgrade ANTs to 2.3.3 in Dockerfile (9512086)
MAINT: Track #2269 and #2269, bug-fixes on the 20.1.x series
MAINT: Remove derivatives from layout index ignores (#2258)
MAINT: Track #2252 from 20.1.x series (#2253)
MAINT: Silence PyBIDS warning by setting extension mode (#2250)
MAINT: Drop CircleCI docs build (#2247)
MAINT: Pin latest NiPreps (#2244)
MAINT: Update setup.cfg (flake8 and pytest) (#2183)
MAINT: Delete release-drafter (#2169)
MAINT: Track bug-fix release on the 20.1.x series (#2165)
MAINT: Remove auto-comment bot (#2166)
MAINT: Improve the questions on the bug-report template (#2158)

Author list for papers based on fMRIPrep 20.2 LTS series

As described in the Contributor Guidelines, anyone listed as developer or contributor may write and submit manuscripts about fMRIPrep. To do so, please move the author(s) name(s) to the front of the following list:

Markiewicz, Christopher J. ¹; Goncalves, Mathias ¹; DuPre, Elizabeth ²; Kent, James D. ³; Salo, Taylor ⁴; Ciric, Rastko ¹; Pinsard, Basile ⁵; Finc, Karolina ⁶; de la Vega, Alejandro ⁷; Feingold, Franklin ¹; Tooley, Ursula A. ⁸; Benson, Noah C. ⁹; Urchs, Sebastian ²; Blair, Ross W. ¹; Erramuzpe, Asier ¹⁰; Lurie, Daniel J. ¹¹; Heinsfeld, Anibal S. ¹²; Jacoby, Nir ¹³; Jamison, Keith W. ¹⁴; Frederick, Blaise B. ^{15, 16}; Valabregue, Romain ¹⁷; Sneve, Markus H. ¹⁸; Liem, Franz ¹⁹; Adebimpe, Azeez ²⁰; Velasco, Pablo ²¹; Wexler, Joseph B. ¹; Groen, Iris I. A. ²²; Ma, Feilong ²³; Amlien, Inge K. ¹⁸; Bellec, Pierre ⁵; Cieslak, Matthew ²⁰; Devenyi, Grabriel A. ²⁴; Ghosh, Satrajit S. ^{25, 26}; Gomez, Daniel E. P. ²⁷; Halchenko, Yaroslav O. ²³; Isik, Ayse Ilkay ²⁸; Moodie, Craig A. ¹; Naveau, Mikaël ²⁹; Rivera-Dompenciel, Adriana ³; Satterthwaite, Theodore D. ²⁰; Sitek, Kevin R. ³⁰; Stojić, Hrvoje ³¹; Thompson, William H. ¹; Wright, Jessey ¹; Ye, Zhifang ³²; Gorgolewski, Krzysztof J. ¹; Poldrack, Russell A. ¹; Esteban, Oscar ³³.

Affiliations:

Department of Psychology, Stanford University

Montreal Neurological Institute, McGill University

Neuroscience Program, University of Iowa

Department of Psychology, Florida International University

SIMEXP Lab, CRIUGM, University of Montréal, Montréal, Canada

Centre for Modern Interdisciplinary Technologies, Nicolaus Copernicus University in Toruń

University of Texas at Austin

Department of Neuroscience, University of Pennsylvania, PA, USA

Department of Psychology, New York University

Computational Neuroimaging Lab, BioCruces Health Research Institute

Department of Psychology, University of California, Berkeley

Child Mind Institute

Department of Psychology, Columbia University

Department of Radiology, Weill Cornell Medicine

McLean Hospital Brain Imaging Center, MA, USA

Consolidated Department of Psychiatry, Harvard Medical School, MA, USA

CENIR, INSERM U1127, CNRS UMR 7225, UPMC Univ Paris 06 UMR S 1127, Institut du Cerveau et de la Moelle épinière, ICM, F-75013, Paris, France

Center for Lifespan Changes in Brain and Cognition, University of Oslo

URPP Dynamics of Healthy Aging, University of Zurich

Perelman School of Medicine, University of Pennsylvania, PA, USA

Center for Brain Imaging, New York University

Department of Psychology, New York University, NY, USA

Dartmouth College: Hanover, NH, United States

Department of Psychiatry, McGill University

McGovern Institute for Brain Research, MIT, MA, USA

Department of Otolaryngology, Harvard Medical School, MA, USA

Donders Institute for Brain, Cognition and Behaviour, Radboud University Nijmegen

Max Planck Institute for Empirical Aesthetics

Cyceron, UMS 3408 (CNRS - UCBN), France

Speech & Hearing Bioscience & Technology Program, Harvard University

Max Planck UCL Centre for Computational Psychiatry and Ageing Research, University College London

State Key Laboratory of Cognitive Neuroscience and Learning, Beijing Normal University

Department of Radiology, CHUV, Université de Lausanne

20.1.4 (July 16, 2021)

Hotfix release addressing a bug on fMRIPrep's resampling to standard spaces. This release also includes some maintenance changes handling old versions of software.

FIX: Feed NiTransforms with LTAs of type RAS2RAS (#2444)
MAINT: Pin svgutils==0.3.1 for the 20.1.x series (#2450)
MAINT: Keep pip and setuptools with support for Python 3.5 (#2449)
MAINT: Some dependencies cannot be left unpinned (#2446)

20.1.3 (September 15, 2020)

Bug-fix release in the 20.1.x series.

FIX: Dependency conflict between NiWorkflows and TemplateFlow (#2269)
FIX: More targeted TemplateFlow queries to work with all later releases (#2268)
MAINT: Update dependency pinnings including niworkflows~=1.2.9 and three minimal bug-fixes.

20.1.2 (September 04, 2020)

Bug-fix release in the 20.1.x series.

FIX: Revise confounds in confounds-correlation plots (#2252)
FIX: Coerce license path to pathlike (#2180)
DOC: Update new sMRIPrep location (#2211)

20.1.1 (June 04, 2020)

Bug-fix release in the 20.1.x series.

FIX: FreeSurfer license manipulation & canary (#2165)
FIX: Dismiss echo entity from SDC reports (#2160)
FIX: Ensure the command-line alias of --nprocs is respected (#2152)
MAINT: Use legacy pip/setuptools for py2 checking (#2156)

20.1.0 (May 27, 2020)

The second minor release series of 2020 is finally here!

fMRIPrep 20.1.0 introduces a magnitude of new features and improvements. Originally nominated to become the first LTS (long-term support) version of fMRIPrep, this release has been supercharged with many new features and bug-fixes. To ensure long-term stability, we have postponed the LTS nomination to 20.2 to allow us unlocking the 20.1 earlier, and a more extensive stress testing of the series before jumping into a longer support commitment. Some key additions in this release include:

A centralized configuration module keeping track of fMRIPrep's many options and run-time and environmental circumstances and settings. The new config module, which has been also propagated to other NiPreps (dMRIPrep, MRIQC), comes to robustify the run-to-run replicability of fMRIPrep (e.g., tracking random seeds), make the option handling more modular but consistent (e.g., setting the ground for a command-line interface built off of the config module), and ease troubleshooting and telemetry.
The anatomical preprocessing fast-track: a new experimental command-line option (--anat-derivatives <PATH>) checks that all necessary anatomical derivatives required by fMRIPrep are present under <PATH>, and skips the anatomical processing in full if fMRIPrep's expectations are met. Because now functional processing of many sessions and runs can be efficiently split into more digestible computational units (i.e., cluster job) while guaranteeing the exact same anatomical results are being used, this can significantly speed up longitudinal study preprocessing, and it is a fundamental optimization to process databases of densely scanned individuals such as My Connectome. This option is not recommended for single-session processing.
A change in output CIFTI2 subcortical volume orientation to be compatible with HCP Pipeline tools and data.

Thanks

With thanks to Basile Pinsard, Joe B. Wexler, Noah Benson, and Marc Bue for contributions.

New Paper!

This release comes after our latest protocol paper "Analysis of task-based functional MRI data preprocessed with fMRIPrep" has been accepted. The protocol describes how to use fMRIPrep on high-performance clusters to preprocess fMRI data for task-based analyses. Please check out the latest version on Nature Protocols or the preprint.

Caution!

As with all minor version increments, working directories from previous versions should not be reused.

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

A full list of changes can be found below.

FIX: MultiLabel interpolations should not use float=True (#2147)
FIX: Generate proper LTA transform prior BOLD sampling on surfaces (#2146)
FIX: Temporary config file in work directory gets clobbered in parallel jobs (#2138)
FIX: Dismiss echo entity on several derivatives and figures outputs (#2133)
FIX: Correct summary report when using previously run recon-all (#2124)
FIX: Ensure correct WM and CSF masks are picked in confounds workflow (#2128)
FIX: Explicitly add default native resolution to volumetric outputs (nipreps/niworkflows#494)
ENH: Finish the upstreaming of NiTransforms interfaces to NiWorkflows (#2132)
ENH: Enable filtering for ANY or NONE in --bids-filter-file (#2123)
ENH: Use new DerivativesDataSink from NiWorkflows 1.2.0 (#2114)
ENH: Config module (#2018)
ENH: Add option to ignore T2w / FLAIR images (#2015)
ENH: Ensure subcortical volume in CIFTI is in LAS orientation (nipreps/niworkflows#484)
ENH: Add option to skip brain extraction (#2039)
ENH: Use CIFTI sampling for carpetplot when available (#2055)
MAINT: Stop printing full boilerplate, black fmriprep/cli (#2119)
MAINT: Ensure YAML loader is specified (#2125)
MAINT: PIN tedana version (#2117)
MAINT: Bump minimum Python to 3.7 (#2017)
MAINT: Remove unused console scripts (#2048)
MAINT: Reduce the overall size of outputs (nipreps/niworkflows#492)
DOC: Update parallel subject neurostars link in FAQ (#2104)
DOC: Add FAQ about reusing work directory (#2045)

Author list for papers based on fMRIPrep v20.1.x series

As described in the Contributor Guidelines, anyone listed as developer or contributor may write and submit manuscripts regarding fMRIPrep. To do so, please move the author(s) name(s) to the front of the following list.

Markiewicz, Christopher J. ¹; Goncalves, Mathias ¹; DuPre, Elizabeth ²; Kent, James D. ³; Ciric, Rastko ¹; Salo, Taylor ⁴; de la Vega, Alejandro ⁵; Finc, Karolina ⁶; Feingold, Franklin ¹; Tooley, Ursula A. ⁷; Benson, Noah C. ⁸; Urchs, Sebastian ²; Blair, Ross W. ¹; Erramuzpe, Asier ⁹; Lurie, Daniel J. ¹⁰; Basile Pinsard ¹¹; Heinsfeld, Anibal S. ¹²; Jacoby, Nir ¹³; Frederick, Blaise B. ^{14, 15}; Valabregue, Romain ¹⁶; Sneve, Markus H. ¹⁷; Liem, Franz ¹⁸; Adebimpe, Azeez ¹⁹; Velasco, Pablo ²⁰; Wexler, Joseph B. ¹; Groen, Iris I. A. ²¹; Ma, Feilong ²²; Rivera-Dompenciel, Adriana ³; Amlien, Inge K. ¹⁷; Cieslak, Matthew ¹⁹; Devenyi, Grabriel A. ²³; Ghosh, Satrajit S. ^{24, 25}; Gomez, Daniel E. P. ²⁶; Halchenko, Yaroslav O. ²²; Isik, Ayse Ilkay ²⁷; Moodie, Craig A. ¹; Naveau, Mikaël ²⁸; Satterthwaite, Theodore D. ¹⁹; Sitek, Kevin R. ²⁹; Stojić, Hrvoje ³⁰; Thompson, William H. ¹; Wright, Jessey ¹; Ye, Zhifang ³¹; Gorgolewski, Krzysztof J. ¹; Poldrack, Russell A. ¹; Esteban, Oscar ¹.

Affiliations:

Department of Psychology, Stanford University

Montreal Neurological Institute, McGill University

Neuroscience Program, University of Iowa

Department of Psychology, Florida International University

University of Texas at Austin

Centre for Modern Interdisciplinary Technologies, Nicolaus Copernicus University in Toruń

Department of Neuroscience, University of Pennsylvania, PA, USA

Department of Psychology, New York University

Computational Neuroimaging Lab, BioCruces Health Research Institute

Department of Psychology, Columbia University

Department of Psychology, University of California, Berkeley

SIMEXP Lab, CRIUGM, University of Montréal, Montréal, Canada

Child Mind Institute

CENIR, INSERM U1127, CNRS UMR 7225, UPMC Univ Paris 06 UMR S 1127, Institut du Cerveau et de la Moelle épinière, ICM, F-75013, Paris, France

McLean Hospital Brain Imaging Center, MA, USA

Consolidated Department of Psychiatry, Harvard Medical School, MA, USA

Center for Lifespan Changes in Brain and Cognition, University of Oslo

URPP Dynamics of Healthy Aging, University of Zurich

Perelman School of Medicine, University of Pennsylvania, PA, USA

Center for Brain Imaging, New York University

Department of Psychology, New York University, NY, USA

Dartmouth College: Hanover, NH, United States

Department of Psychiatry, McGill University

McGovern Institute for Brain Research, MIT, MA, USA

Department of Otolaryngology, Harvard Medical School, MA, USA

Donders Institute for Brain, Cognition and Behaviour, Radboud University Nijmegen

Max Planck Institute for Empirical Aesthetics

Cyceron, UMS 3408 (CNRS - UCBN), France

Speech & Hearing Bioscience & Technology Program, Harvard University

Max Planck UCL Centre for Computational Psychiatry and Ageing Research, University College London

State Key Laboratory of Cognitive Neuroscience and Learning, Beijing Normal University

20.0.x series (February 2020)

20.0.7 (May 5, 2020)

Bug-fix release in the 20.0.x series.

This release includes a new, portable version of the templateflow python client. This includes an automatic check to fetch the latest templateflow templates every time.

MAINT: Bump templateflow to auto-update template skeleton

20.0.6 (April 16, 2020)

Bug-fix release in the 20.0.x series.

This release fixes a bug for phase-difference fieldmaps that are not in RAS+ orientation. The bug presented as an error if the orientation was reordered relative to RAS+ (for example, AIL+) and the swapped dimensions were not of the same size. Otherwise, the bug introduced a poor masking of the phase difference map, and could be quite subtle if the original orientation was LAS+. Runs of fMRIPrep that used other susceptibility distortion correction (SDC) methods are not currently considered problematic.

This bug affects all earlier versions of fMRIPrep, except for 1.5.10 and any future releases in the 1.5.x series.

FIX: Do not reorient magnitude images (nipreps/sdcflows#98)

20.0.5 (March 19, 2020)

Bug-fix release in 20.0.x series.

With thanks to James Kent for the fix and Blaise Frederick for the report and testing.

FIX: Add CE agent to output figure filename templates (nipreps/niworkflows#482)

20.0.4 (March 17, 2020)

A bug-fix release improving documentation for filtering BIDS files and standardizing CIFTI volume orientation.

With thanks to Ursula Tooley for the contribution.

DOC: FAQ section for BIDS filter (#2028)

FIX: Ensure BOLD and label orientations are equal (nipreps/niworkflows#477).

20.0.3 (March 12, 2020)

A bug-fix release for CIFTI surfaces.

This release remedies a resampling error when generating fsLR surfaces that was producing erroneous CIFTI files. We strongly recommend all users who have generated CIFTI output with previous 20.0.x releases to upgrade and rerun.

FIX: Remedy fsLR surface resampling (#2032)

20.0.2 (March 6, 2020)

A bug squashing release in the 20.0.x series.

This release fixes the use of custom templates within the docker wrapper, remedies crashes when FreeSurfer HOME was not set, and improves the documentation for local installations.

With thanks to Blaise Frederick for the contribution.

DOC: Update standalone installation requirements (#2009)

FIX: Crashes whenever FREESURFER_HOME is not set (#2014)

FIX: Local template mounting (wrapper) (#2020)

MAINT: Pin minor series of nipype, major series of nibabel (#2021)

20.0.1 (February 27, 2020)

Bug-fix release in 20.0.x series.

This release includes fixes for rare images with invalid qform matrices and some minor improvements in report readability and inclusion of common templates in the Docker image.

FIX: Handle qforms with invalid quaternions (nipreps/niworkflows#466)

FIX: update niworkflows location (#2005)

ENH: Display errors as summary/details elements in reports (nipreps/niworkflows#464)

DOC: Add --fs-subjects-dir usage to slurm example (#2003)

CI: Test that Docker image can run a common set of output spaces without network access (#1997)

20.0.0 (February 24, 2020)

The major release of 2020 is here!

fMRIPrep is transitioning to a calendar version system (#1912). The CalVer system reflects fMRIPrep's nature as an evolving workflow and does not impose any artificial incentive for "big-change" releases. It also permits to quickly see how out-of-date someone's version is. As of now, the default version increment is the minor release number. Hence, when the minor release number changes the work directory of fMRIPrep will presumably break. Micro releases only include bug-fixes that can reuse exiting working directories.

The major highlight of this release entails CIFTI generation to match :abbr:`HCP (Human Connectome Project)` grayordinates. In addition, the new fMRIPrep 20.0.0 has gone through a major overhaul in the handling of standard spaces (spatial normalizations, fusion of prior knowledge from corresponding atlases) and imaging outputs. In particular, the new series almost completely implements the new syntax for --output-spaces to describe the (non)standard spatial references that shall be used for generating outputs (#1604).

This release includes contributions from Azeez Adebimpe and Basile Pinsard - very much appreciated.

ENH: Warn when existing output version does not match current pipeline version (#1967)

ENH: Add --clean-workdir argument (#1966)

ENH: Refactor of how spatial normalization targets and --output-spaces are maintained (#1955) (#1983)

ENH: Add --bids-filter-file argument for more controlled data querying (#1770)

FIX: Ensure subject ID is used when selecting BIDS data (#1982)

FIX: Display a log message when processing completes successfully (#1977)

DOC: Clean up surface outputs (#1993)

DOC: Integrate intersphinx, drop external module wrapping (#1989)

DOC: Improve custom template usage description (#1969)

MAINT: Use local docker registry (#1990)

MAINT: Pin connectome-workbench 1.3.2, add to documented dependencies (#1958)

MAINT: Pin NiBabel, NiWorkflows, sMRIPrep (#1971)

MAINT: CI build error fixes (#1976)

Author list for papers based on fMRIPrep v20.0.0

As described in the Contributor Guidelines, anyone listed as developer or contributor may write and submit manuscripts regarding fMRIPrep. To do so, please move the author(s) name(s) to the front of the following list.

Markiewicz, Christopher J.¹; DuPre, Elizabeth²; Goncalves, Mathias¹; Kent, James D.³; Ciric, Rastko¹; Salo, Taylor⁴; de la Vega, Alejandro⁵; Finc, Karolina⁶; Feingold, Franklin¹; Urchs, Sebastian²; Blair, Ross W.¹; Erramuzpe, Asier⁷; Valabregue, Romain⁸; Jacoby, Nir⁹; Lurie, Daniel J.¹⁰; Heinsfeld, Anibal S.¹¹; Halchenko, Yaroslav O.¹²; Sneve, Markus H.¹³; Devenyi, Grabriel A.¹⁴; Liem, Franz¹⁵; Gomez, Daniel E. P.¹⁶; Adebimpe, Azeez¹⁷; Velasco, Pablo¹⁸; Groen, Iris I. A.¹⁹; Ma, Feilong¹²; Rivera-Dompenciel, Adriana³; Amlien, Inge K.¹³; Cieslak, Matthew¹⁷; Ghosh, Satrajit S.^{20, 21}; Isik, Ayse Ilkay²²; Moodie, Craig A.¹; Naveau, Mikaël²³; Satterthwaite, Theodore D.¹⁷; Sitek, Kevin R.²⁴; Stojić, Hrvoje²⁵; Thompson, William H¹; Tooley, Ursula A.²⁶; Wright, Jessey¹; Ye, Zhifang²⁷; Gorgolewski, Krzysztof J.¹; Poldrack, Russell A.¹; Esteban, Oscar¹.

Affiliations:

Department of Psychology, Stanford University

Montreal Neurological Institute, McGill University

Neuroscience Program, University of Iowa

Department of Psychology, Florida International University

University of Texas at Austin

Centre for Modern Interdisciplinary Technologies, Nicolaus Copernicus University in Toruń

Computational Neuroimaging Lab, BioCruces Health Research Institute

CENIR, INSERM U1127, CNRS UMR 7225, UPMC Univ Paris 06 UMR S 1127, Institut du Cerveau et de la Moelle épinière, ICM, F-75013, Paris, France

Department of Psychology, Columbia University

Department of Psychology, University of California, Berkeley

Child Mind Institute

Dartmouth College: Hanover, NH, United States

Center for Lifespan Changes in Brain and Cognition, University of Oslo

Department of Psychiatry, McGill University

URPP Dynamics of Healthy Aging, University of Zurich

Donders Institute for Brain, Cognition and Behaviour, Radboud University Nijmegen

Perelman School of Medicine, University of Pennsylvania, PA, USA

Center for Brain Imaging, New York University

Department of Psychology, New York University, NY, USA

McGovern Institute for Brain Research, MIT, MA, USA

Department of Otolaryngology, Harvard Medical School, MA, USA

Max Planck Institute for Empirical Aesthetics

Cyceron, UMS 3408 (CNRS - UCBN), France

Speech & Hearing Bioscience & Technology Program, Harvard University

Max Planck UCL Centre for Computational Psychiatry and Ageing Research, University College London

Department of Neuroscience, University of Pennsylvania, PA, USA

State Key Laboratory of Cognitive Neuroscience and Learning, Beijing Normal University