[ENH] BEP 16: Diffusion modeling derivatives

[arokem]

Introduces specifications for diffusion modeling derivatives.

This PR replaces #2211 so that maintainers can push changes into the PR during its development.

Note

At this point, the best way to communicate about this BEP is through this GitHub pull request.

[HTML preview of this BEP](XXX - will add when available)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.83%. Comparing base (373da35) to head (016c398).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2258   +/-   ##
=======================================
  Coverage   82.83%   82.83%           
=======================================
  Files          20       20           
  Lines        1672     1672           
=======================================
  Hits         1385     1385           
  Misses        287      287           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[arokem]

Surfacing some comments that were embedded in the document, but that are probably better addressed here (with small edits, for clarity):

• TODO: For bedpostx results, confirm whether we want to enforce specific axes for direction encoding and bootstrap realizations, or leave that to be encoded separately in a metadata field.

I think that we should leave this as it is now. That is, enforce specific axes.

• TODO DISCUSS
  The example presented here [of bedpostx, L637 and on] is not necessarily a unique solution
  for the storage of the outcomes of the FSL bedpostx command as BIDS Derivatives:

  • WOULD SPLITTING STICK COMPONENTS ACROSS NIFTIS
    REQUIRE A NEW ENTITY BY WHICH TO INDEX THEM?
    OR JUST GIVE THEM EG. _param-spherical1, _param-spherical2?

I don't think that we want a new entity for this. I think that adding indices is fine.

-   While the FSL `bedpostx` command yields the fibre orientation for each individual stick
    as polar angles within separate NIfTI images,
    for BIDS it is RECOMMENDED that such orientation information be encoded
    either as [spherical coordinates](#encoding-spherical) or [3-vectors](#encoding-3vector). 
-   Given that it is possible to encode a scalar parameter
    into either `spherical coordinates or `3-vectors` encodings,
    it is possible to store an image that encodes,
    for each stick component,
    both volume fraction and orientation.
    It is however RECOMMENDED to encode this information in separate files,
    given that in the more general case there may be multiple scalar parameters
    individually attributed to each component.

I agree. I think that this should be handled by providing some "canonical" conversion software. @PeerHerholz : does the software that you wrote cover these issues?

[arokem]

@PeerHerholz : there was some discussion of examples on #2211. Have you made any progress on that?

[PeerHerholz]

@PeerHerholz : there was some discussion of examples on #2211. Have you made any progress on that?

Sorry, I missed this in the other PR. Thanks for bringing it up again here.
So far, the software focused on DTI and CSD based on the status of the BEP a while back. However, I can try to add bedpostx support and the respective conversion.

[tsalo]

I am having trouble figuring out how to validate subobjects' field values. In this case, if "OrientationEncoding"["Type"] is "amplitudes", "OrientationEncoding"["AmplitudesDirections"] MUST be defined.