24.0.0 Release Candidate 0

[mgxd]

Release Notes

This major release includes a substantial refactoring of the pipeline.

One key addition is the addition of the --level flag, which 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 was altered to take arguments in the form name=/path/to/dir.
For each directory provided, if a derivative is found - it will be used instead of computing it from scratch. If a derivative is not found, NiBabies will compute it and proceed as usual.

Taken together, these features can allow a dataset provider to run a minimal NiBabies 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 NiBabies behavior, enabling easier workarounds for bugs or experimentation with alternatives.

Another new feature is a dynamic anatomical reference, which is set based on surface reconstruction method or through the --reference-anatomical flag. Previously, T1w was the default output space.

Additionally, minor adjustments have been made to MCRIBS surface reconstruction to address failure rates. This is still an on-going investigation, but preliminary results look promising.

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, add fmap-jacobian to the --ignore argument.

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

Changes

• RF: Move to fit/apply workflow (RF: Move to fit/apply workflow #360)
• FIX: nest pathlib import in fix_multi_source_name (FIX: nest pathlib import in fix_multi_source_name #365)
• FIX: Avoid retrieving multiple templates from latest TF (FIX: Avoid retrieving multiple templates from latest TF #353)
• ENH: better repr for Derivatives class (ENH: better repr for Derivatives class #351)
• FIX: Raise informative error if no t1w or t2w found (FIX: Raise informative error if no t1w or t2w found #347)
• Replace resource_filename with load_data (Replace resource_filename with load_data #345)
• FIX: Easier pyenv usage (FIX: Easier pyenv usage #342)
• Build(deps): Bump urllib3 from 2.0.3 to 2.0.7 (Build(deps): Bump urllib3 from 2.0.3 to 2.0.7 #319)
• Build(deps): Bump pillow from 9.5.0 to 10.0.1 (Build(deps): Bump pillow from 9.5.0 to 10.0.1 #317)
• DOC: Use correct argument flag (DOC: Use correct argument flag #338)
• MAINT: Raise minimum to 3.10, bump actions (MAINT: Raise minimum to 3.10, bump actions #337)
• FIX: Catch nonexistent derivatives, clean up subworkflow logic (FIX: Catch nonexistent derivatives, clean up subworkflow logic #336)
• Use fsLR reg sphere for MCRIBS morphometrics resampling (Use fsLR reg sphere for MCRIBS morphometrics resampling #334)
• FIX: Multiple T2ws, coerce reference to string (FIX: Multiple T2ws, coerce reference to string #333)

---

This discussion was created from the release 24.0.0 Release Candidate 0.