[ENH] BEP 16: Diffusion modeling derivatives

[arokem]

This transfers work that so far has been done in a separate repository: https://github.com/bids-standard/bids-bep016.

I believe this is not too far from ready to be reviewed by the community, but also seeking input from @Lestropie, @francopestilli, @oesteban, @PeerHerholz.

[arokem]

Forgot to tag @mattcieslak, whose input here also useful. And probably others, please tag and add to this discussion.

[francopestilli]

@effigies @dorahermes @jdtournier @frheault @mattcieslak We are trying to merge the current status of the DWI BEP 16. Would you guys take a look, please? @PeerHerholz

[arokem]

Looking at the required deliverables for BEPs, I see that we might be at the stage to discuss whether we have 1 (the markdown component), and that discussion can lead to work on 2 and 3 (examples, relatively easy; schema, relatively hard, and where we might need some guidance/examples to follow).

[PeerHerholz]

Hey @arokem and everyone,

thx @arokem! Yeah, I think once it's decided that the current markdown and respective information/proposals are in a good status we would create a couple of example datasets (I can update the conversion software respectively). I do agree that the examples should be relatively easy, especially considering that we would provide empty imaging files and focus on the metadata. The schema appears to be a different beast and having someone from the maintainers/developers involved would be great.

[arokem]

One general question: does the validator currently look into the content of data files to validate that their content is sensible? The BEP proposes that data be organized in a particular way within the files (e.g., a particular order of tensor components), and I am wondering whether there is any way that this is currently being validated. If not, maybe that's fine. Ultimately, it is up to users of the spec to produce data that makes sense, but I still wonder whether we can help enforce that.

[codecov[bot]]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 82.83%. Comparing base (373da35) to head (064a7b3).

Additional details and impacted files

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

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

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

[effigies]

One general question: does the validator currently look into the content of data files to validate that their content is sensible?

It validates tsv contents and NIfTI headers.

Validating NIfTI data blocks is likely to be significantly slower, and would probably make sense for a separate tool like miniQC.

What kind of check are you thinking?

[arokem]

One thing that comes to mind is to validate the shape of the data. For example, the tensor should have six elements on the last dimension; CSD coefficients would also have a certain dimensionality that can be checked. This can be done without reading the data. So, if there is precedent for this kind of check, that's good.

[arokem]

Should I be using the macros___make_sidecar_table for the tables that are raising remark linting issues?

[effigies]

Yes, checking NIfTI shapes is doable:

https://github.com/bids-standard/bids-specification/blob/b9a66732e67de7bc51402b7ed0a73a1e58ce85d6/src/schema/rules/checks/func.yaml#L57-L67

You'll want to use make_sidecar_table if it corresponds to a sidecar schema rule, but for describing deeper models, you'll probably want make_metadata_table, e.g.,

https://github.com/bids-standard/bids-specification/blob/b9a66732e67de7bc51402b7ed0a73a1e58ce85d6/src/common-principles.md?plain=1#L539-L561

[arokem]

By all means, please jump in! Good catch, that's an error fixed in 337bc06d

On Thu, Nov 6, 2025 at 6:16 AM Anthony Gagnon @.***> wrote:

@.**** commented on this pull request.

In src/derivatives/diffusion-derivatives.md https://github.com/bids-standard/bids-specification/pull/2211#discussion_r2499129460 :

•        <source_keywords>[_space-<space>]_desc-preproc_dwi.bvals
  

•        <source_keywords>[_space-<space>]_desc-preproc_dwi.bvecs
  

Sorry to jump in here, but would it be better for consistency to keep the extension identical to the raw data files (e.g., .bval and .bvec, here for reference https://bids-specification.readthedocs.io/en/stable/glossary.html#bval-extensions )?

— Reply to this email directly, view it on GitHub https://github.com/bids-standard/bids-specification/pull/2211#pullrequestreview-3428410067, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAA46NQEM5ENMXLF2GJ7HET33NJ4LAVCNFSM6AAAAACGSIMDTCVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTIMRYGQYTAMBWG4 . You are receiving this because you were mentioned.Message ID: @.***>

[PeerHerholz]

Hey @arokem,

I'm very sorry if I missed it but should I add some examples in the next couple of days?

[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]

Replaced by #2258. I will follow up to copy comments made here to that PR, but let me know if I miss anything.

CC: team @bids-standard/bep016