MRtrix3 provides a set of tools to perform various advanced diffusion MRI analyses, including constrained spherical deconvolution (CSD), probabilistic tractography, track-density imaging, and apparent fibre density
To have any kind of confidence around robust encoding of the outcomes of diffusion model fits on the filesystem, in my mind there are two requirements:
Prove that the purported coordinate system is correct.
This necessitates a broader set of data. Showing that for one data instance, the purported coordinate system seems reasonable, is not evidence that in some other use case the interpretation will be incorrect.
Have the capability to convert data between different encodings or reference frames.
Here I've created two new commands, that are requisite for later parts of this validation tool.
peaksconvert converts both between different reference frames, and between 3-vector versus spherical coordinate encodings. This for instance should allow loading the outcomes of diffusion model fits from FSL and MRtrix in the converse software.
peakscheck does something similar to dwigradcheck, just using peaks images and tckgen -algorithm fact. Similar to #2902 (which happened during the course of generating this changeset) the set of possible errors in encoding that are evaluated can be more complex than just axis permutations and flips.
Outstanding TODOs, many of which are plucked from code comments:
[ ] Deep in the spherical coordinates handling, the prospect of a triplet of spherical coefficients appears, where the third element is inferred to be a radius. This is however contrary to ISO convention, where the first element should be the radius. Would need to audit what code uses it, but I would like to consider changing that behaviour. Potentially to avoid unexpected errors, revert those functions to only consider unit spherical coordinates, and have newly named functions that deal with the prospect of triplets?
[ ] For spherical coordinates, should support for both physics and mathematics conventions be implemented?
peakscheck tests for the prospect of swapping the order of the two angles; but permitting explicit specification of which of the two is in use may be preferable (relates to https://github.com/bids-standard/bids-bep016/issues/96).
[ ] Give peaksconvert ability to change fill value of absent fixels
[ ] Give peaksconvert ability to reduce maximal number of fixels
Hypothetically, this could be done either by culling volumes, or by first sorting by the value per fixel (as 3-vector norm or spherical radius) and then removing
[ ] Multi-thread peaksconvert
[ ] Check whether peaksconvert works across bootstrap realisations, if those realisations appear along the fifth image axis
(In BEP016 I want to define explicitly if an image axis is used to encode orientation information vs. if an image axis is used to encode bootstrap realisations; see https://github.com/bids-standard/bids-bep016/issues/38. But that may not necessarily propagate to MRtrix)
[ ] peakscheck: Try to catch case where upstream there has been an erroneous transformation; eg. someone has orientations in IJK, they erroneously applied an XYZ2IJK transformation, and so now they need to apply the IJK2XYZ transformation twice to get their orientations in MRtrix's expected XYZ
[ ] peakscheck: Reduce doubling-up between ijk and bvec reference frames.
Ideally evaluate each unique transformation only once; there may however be multiple interpretations to a unique transformation.
[ ] peakscheck: Add -in_reference option; the variant that includes the corresponding transformation to XYZ should then be considered the "expected" interpretation of the input data, used to determine whether the return code should be non-zero.
[ ] Add ability to disable internal transform realignment on image load via environment variable; make use of this in peakscheck
Draft PR.
Depends on #2917 (uses that as base branch).
This is work that I deemed necessary for BIDS BEP016 DWI models (https://github.com/bids-standard/bids-bep016/pull/24).
To have any kind of confidence around robust encoding of the outcomes of diffusion model fits on the filesystem, in my mind there are two requirements:
Here I've created two new commands, that are requisite for later parts of this validation tool.
peaksconvertconverts both between different reference frames, and between 3-vector versus spherical coordinate encodings. This for instance should allow loading the outcomes of diffusion model fits from FSL and MRtrix in the converse software.peakscheckdoes something similar todwigradcheck, just usingpeaksimages andtckgen -algorithm fact. Similar to #2902 (which happened during the course of generating this changeset) the set of possible errors in encoding that are evaluated can be more complex than just axis permutations and flips.Outstanding TODOs, many of which are plucked from code comments:
[ ] Deep in the spherical coordinates handling, the prospect of a triplet of spherical coefficients appears, where the third element is inferred to be a radius. This is however contrary to ISO convention, where the first element should be the radius. Would need to audit what code uses it, but I would like to consider changing that behaviour. Potentially to avoid unexpected errors, revert those functions to only consider unit spherical coordinates, and have newly named functions that deal with the prospect of triplets?
[ ] For spherical coordinates, should support for both physics and mathematics conventions be implemented?
peakschecktests for the prospect of swapping the order of the two angles; but permitting explicit specification of which of the two is in use may be preferable (relates to https://github.com/bids-standard/bids-bep016/issues/96).[ ] Give
peaksconvertability to change fill value of absent fixels[ ] Give
peaksconvertability to reduce maximal number of fixels Hypothetically, this could be done either by culling volumes, or by first sorting by the value per fixel (as 3-vector norm or spherical radius) and then removing[ ] Multi-thread
peaksconvert[ ] Check whether
peaksconvertworks across bootstrap realisations, if those realisations appear along the fifth image axis (In BEP016 I want to define explicitly if an image axis is used to encode orientation information vs. if an image axis is used to encode bootstrap realisations; see https://github.com/bids-standard/bids-bep016/issues/38. But that may not necessarily propagate to MRtrix)[ ]
peakscheck: Try to catch case where upstream there has been an erroneous transformation; eg. someone has orientations in IJK, they erroneously applied an XYZ2IJK transformation, and so now they need to apply the IJK2XYZ transformation twice to get their orientations in MRtrix's expected XYZ[ ]
peakscheck: Reduce doubling-up between ijk and bvec reference frames. Ideally evaluate each unique transformation only once; there may however be multiple interpretations to a unique transformation.[ ]
peakscheck: Add-in_referenceoption; the variant that includes the corresponding transformation to XYZ should then be considered the "expected" interpretation of the input data, used to determine whether the return code should be non-zero.[ ] Add ability to disable internal transform realignment on image load via environment variable; make use of this in
peakscheck