[ENH] BEP 16: Diffusion modeling derivatives #2211
Conversation
This PR splits the tractography section from the diffusion derivatives document, so that #5 is easier to merge. The new ``05-diffusion-derivatives-tractography.md`` file will remain orphaned, but kept there as a base for the time we tackle tractography. It shouldn't be merged into the derivatives branch until it is ready.
[FIX] Split out tractography
- More clarity of distinction between requisite and optional files in output directory. - Try using 3 spaces rather than 4 in non-code indentation; partly to try to get tables within dot point lists to render correctly, partly to improve editor software syntax highlighting.
- Various small re-wordings. - Slightly more use of hyperlinks. - Short introductions to "parameter terminology" and "data representations" sections. - Be more explicit about normalised vs. non-normalised 3-vectors, so that structure more clusely mimics that of description of spherical coordinate representation. - Rename hyperlink names to "parameter terminology" section to better separate from later "intrinsic / extrinsic model parameters" sections.
Based on suggestion in #5. If all model intrinsic parameters are incorporated into a single file, rather than dropping the "_parameter-<param>" field, instead enforce that parameter name "all" be used.
When introducing the file naming convention, give an example of the "_<model>" field.
Re-arranged descriptions of intrinsic and extrinsic model parameters within the file naming section, and corrected a discordance in one dot point that was using an intrinsic model parameter filename path but discussing extrinsic model parameters.
Provide information on specification of orientation data after the various models and model parameters have been explained.
[ENH] Restructuring of DWI derivatives
Revised based on MRtrix3/mrtrix3#1635. Manual merge / cherry-pick of: c6539851, 8b278282, c6539851, ebbf0d3d, d7b4731d, 99e92e0a, 6bfc7849 due to unresolvable conflict in bids-standard/bids-bep016#8.
[FIX] Formatting conformity to pass CI
Conflicts: src/05-derivatives/05-diffusion-derivatives.md
- Provide basic instructions rather than elaborating on rare use cases. - Remove JSON dictionary on preprocessing steps utilised as these relate to provenance and are therefore out of scope. Proposal for addressing bids-standard/bids-bep016#25.
|
By all means, please jump in! Good catch, that's an error fixed in 337bc06
…On Thu, Nov 6, 2025 at 6:16 AM Anthony Gagnon ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In src/derivatives/diffusion-derivatives.md
<#2211 (comment)>
:
> + <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
<#2211 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAA46NQEM5ENMXLF2GJ7HET33NJ4LAVCNFSM6AAAAACGSIMDTCVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTIMRYGQYTAMBWG4>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
…cale. This diverges from the usual recommendation to use SI units, but makes sense in this field, where values of mm^2/s are used to describe diffusivity in many different places.
| } | ||
| ) }} | ||
|
|
||
| Dictionary `"Model["Parameters"]"` has the following reserved keywords that may be applicable to a broad range of models: |
There was a problem hiding this comment.
For "Model["Parameters"]", do we want to restrict keys to the reserved keywords or do we want it to be like column names in some TSVs (i.e., some columns are described in the specification and are automatically validated against that, but if you add your own columns you need to define what they are)?
The tough part is that, since this is already in the JSON, there's no separate place to define the key if you're adding a new one.
As an example, QSIRecon has three parameters for its NODDI interface: "ParallelDiffusivity", "PerpendicularDiffusivity", and "IsExVivo". The first two are proposed, with specific units, in this BEP, but the third one is just a parameter for the AMICO NODDI implementation, and my bet is that it tunes a bunch of knobs internally and QSIRecon doesn't have access to those knobs' values. Therefore, if we wanted to include "IsExVivo", would we need a nested dictionary like the following?
{
"Model":
"Parameters": {
"ParallelDiffusivity": 0.017,
"PerpendicularDiffusivity": 0.025,
"IsExVivo": {
"Value": true,
"Description": "A boolean indicating if the data are ex vivo (true) or in vivo (false)."
"Type": "boolean"
}
}
}There was a problem hiding this comment.
Is there any precedent to this situation (i.e., passing parameters to software to create derivatives)? For example, what does fitlins do with its input parameters in metadata?
There was a problem hiding this comment.
The only thing I can think of is the provenance BEP, but that uses json.ld files instead of BIDS sidecars.
There was a problem hiding this comment.
Sorry for missing this. No, there's no way to describe JSON values in JSON. We could propose a JSON-schema (or JSON Type Definition) format that allows a dataset to declare the schema that its values should be validated against. Something like model-<label>_param-<label>_dwimap.schema.json, that validates sidecars matching those entities.
I don't think it would be worth trying to extend the column definitions in sidecars for TSV files to meet this use case. If you're at the point of describing JSON, using an existing validation technology is probably less surprising to anybody producing or consuming these values.
There was a problem hiding this comment.
OK - let's keep this simple, by using only reserved keywords described in the model parameters table, and specified explicitly in the schema. We can always add more models/parameters through subsequent additions.
|
Hey @arokem, I'm very sorry if I missed it but should I add some examples in the next couple of days? |
I didn't use any references so the glossary links will be broken.
Add metadata fields to schema
Fix yamllint and remark warnings
|
Surfacing some comments that were embedded in the document, but that are probably better addressed here (with small edits, for clarity):
I think that we should leave this as it is now. That is, enforce specific axes.
I don't think that we want a new entity for this. I think that adding indices is fine.
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? |
|
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 |
8 participants
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.