========================
The *SDCFlows* 2.0.x series are released after a comprehensive overhaul of the software's API.
This overhaul has the vision of converting *SDCFlows* into some sort of subordinate pipeline
to other *d/fMRIPrep*, inline with *sMRIPrep*'s approach.
The idea is to consider fieldmaps a first-citizen input, for which derivatives are generated
at the output (on the same vein of, and effectively implementing `26
<https://github.com/nipreps/sdcflows/issues/26>`__).
A bids's-eye view of this new release follows:
* Two new base objects (:py:class:`~sdcflows.fieldmaps.FieldmapFile` and
:py:class:`~sdcflows.fieldmaps.FieldmapEstimation`) for the validation
and representation of fieldmap estimation strategies.
Validation of metadata and checking the sufficiency of imaging files
and necessary parameters is now done with these two objects.
:py:class:`~sdcflows.fieldmaps.FieldmapEstimation` also generates the
appropriate estimation workflow for the input data.
* Moved estimation workflows under the :py:mod:`sdcflows.workflows.fit` module.
* New outputs submodule :py:mod:`sdcflows.workflows.outputs` that writes out reportlets and
derivatives, following suit with higher-level *NiPreps* (*s/f/dMRIPrep*).
The two workflows are exercised in the CircleCI tests, and the artifacts are generated
this way.
Derivatives are populated with relevant pieces of metadata (for instance, they forward
the ``IntendedFor`` fields).
* A new :py:func:`~sdcflows.workflows.base.init_fmap_preproc_wf`, leveraging
:py:class:`~sdcflows.fieldmaps.FieldmapEstimation` objects.
* Separated out a new utilities module :py:mod:`sdcflows.utils` for the manipulation of
phase information and :abbr:`EPI (echo-planar imaging)` data.
* New :py:mod:`sdcflows.workflows.apply.registration` module, which aligns the reference map
of the fieldmap of choice (e.g., a magnitude image) to the reference EPI
(e.g., an SBRef, a *b=0* DWI, or a *fMRIPrep*'s *BOLDRef*) with ANTs.
The workflow resamples the fieldmap reference into the reference EPI's space for
reporting/visualization objectives.
* New :py:mod:`sdcflows.interfaces.bspline` set of utilities for the filtering and
extrapolation of fieldmaps with B-Splines.
Accordingly, all workflows have been updated to correctly handle (and better use) B-Spline
coefficients.
* A new PEPOLAR implementation based on TOPUP (see
:py:func:`sdcflows.workflows.fit.pepolar.init_topup_wf`).
* Pushed the code coverage with tests, along with a deep code cleanup.
.. attention::
*SDCFlows* drops Python 3.6 starting with 1.4.x series.
Some of the most prominent pull-requests conducive to this release are:
* FIX: Fast & accurate brain extraction of magnitude images without FSL BET (174)
* FIX: svgutils 0.3.2 breaks our reportlets (175)
* FIX: Misconfigured test of unwarping workflow (170)
* FIX: Cleanup annoying isolated dots in reportlets + new tests (168)
* FIX: Make images "plumb" before running ANTs-SyN (and roll-back afterwards) (165)
* FIX: Convert SEI fieldmaps given in rad/s into Hz (127)
* FIX: Limit ``3dQwarp`` to maximum 4 CPUs for stability reasons (128)
* ENH: Adopt new brain extraction algorithm in magnitude preparation workflow (176)
* ENH: Add "*fieldmap-less*" estimations to default heuristics (166)
* ENH: Add one test for the SDC-SyN workflow (164)
* ENH: Generate a simple mask after correction (161)
* ENH: Increase unit-tests coverage of ``sdcflows.fieldmaps`` (159)
* ENH: Optimize tensor-product B-Spline kernel evaluation (157)
* ENH: Add a memory check to dynamically limit interpolation blocksize (156)
* ENH: Massage TOPUP's fieldcoeff files to be compatible with ours (154)
* ENH: Add a simplistic EPI masking algorithm (152)
* ENH: Utility that returns the ``B0FieldSource`` of a given potential EPI target (151)
* ENH: Write ``fmapid-`` entity in Derivatives (150)
* ENH: Multiplex fieldmap estimation outputs into a single ``outputnode`` (149)
* ENH: Putting the new API together on a base workflow (143)
* ENH: Autogenerate ``B0FieldIdentifiers`` from ``IntendedFor`` (142)
* ENH: Finalizing the API overhaul (132)
* ENH: Keep a registry of already-used identifiers (and auto-generate new) (130)
* ENH: New objects for better representation of fieldmap estimation (114)
* ENH: Show FieldmapReportlet oriented aligned with cardinal axes (120)
* ENH: New estimation API (featuring a TOPUP implementation!) (115)
* DOC: Minor improvements to the literate workflows descriptions. (162)
* DOC: Fix typo in docstring (155)
* DOC: Enable NiPype's sphinx-extension to better render Interfaces (131)
* MAINT: Docker - Update base Ubuntu image & ANTs, makefile (173)
* MAINT: Retouch several tests and improve ANTs version handling of SyN workflow (172)
* MAINT: Drop Python 3.6 (160)
* MAINT: Enable Git-archive protocol with setuptools-scm-archive (153)
* MAINT: Migrate TravisCI -> GH Actions (completion) (138)
* MAINT: Migrate TravisCI -> GH Actions (137)
* MAINT: Minimal unit test and refactor of pepolar workflow node (133)
* MAINT: Collect code coverage from tests on Circle (122)
* MAINT: Test minimum dependencies with TravisCI (96)
* MAINT: Add FLIRT config files to prepare for TOPUP integration (116)
A complete list of issues addressed by the release is found `in the GitHub repo
<https://github.com/nipreps/sdcflows/milestone/2?closed=1>`__.
.. admonition:: Author list for papers based on *SDCFlows* 2.0.x series
As described in the `Contributor Guidelines
<https://www.nipreps.org/community/CONTRIBUTING/#recognizing-contributions>`__,
anyone listed as developer or contributor may write and submit manuscripts
about *SDCFlows*.
To do so, please move the author(s) name(s) to the front of the following list:
Markiewicz, Christopher J. \ :sup:`1`\ ; Goncalves, Mathias \ :sup:`1`\ ; MacNicol, Eilidh \ :sup:`2`\ ; Adebimpe, Azeez \ :sup:`3`\ ; Blair, Ross W. \ :sup:`1`\ ; Cieslak, Matthew \ :sup:`3`\ ; Naveau, Mikaël \ :sup:`4`\ ; Sitek, Kevin R. \ :sup:`5`\ ; Sneve, Markus H. \ :sup:`6`\ ; Gorgolewski, Krzysztof J. \ :sup:`1`\ ; Satterthwaite, Theodore D. \ :sup:`3`\ ; Poldrack, Russell A. \ :sup:`1`\ ; Esteban, Oscar \ :sup:`7`\ .
Affiliations:
1. Department of Psychology, Stanford University
2. Department of Neuroimaging, King's College London
3. Perelman School of Medicine, University of Pennsylvania, PA, USA
4. Cyceron, UMS 3408 (CNRS - UCBN), France
5. Speech & Hearing Bioscience & Technology Program, Harvard University
6. Center for Lifespan Changes in Brain and Cognition, University of Oslo
7. Dept. of Radiology, Lausanne University Hospital, University of Lausanne
1.3.x series
============