DWI directions utilised in model

[Lestropie]

| **Key name**     | **Description**                                                                                                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Gradients        | OPTIONAL. List of 3-vectors. Subset of gradients utilized to fit the model, as a list of three-elements lists. If not present, all gradients were used.                                      |
| Shells           | OPTIONAL. List of floats. Shells that were utilized to fit the model, as a list of b-values. If the key is not present, it should be assumed that all shells were used during model fitting. |

• "Shells" does not apply to data that are not shelled; that's fine, it can simply not be applicable in all circumstances, but nevertheless it's imperfect.
• "Gradients" only applies to either single-shell data, or multi-shell data where the same gradient orientations are used across all shells; and even then, that fails to take into account the prospect of subject motion resulting in those gradient orientations not being precisely equivalent between shells.

The more general solution here is to store the gradient table of the data to which the model was fitted. Applies to non-shelled data, applies to use of a subset of data, and will eventually apply to the case of advanced DWI acquisitions. We already do something akin to this in MRtrix3 MRtrix3/mrtrix3#774.

[francopestilli]

@Lestropie I wonder whether we should try to cover 80-90 percent of the current data and software (for that gradients would work I think) or be more forward-looking and discuss more solutions for future data.

[Lestropie]

I suspect the functional coverage of "Gradients" may be less than 80 percent at the current time.

Utilising only a subset of the diffusion directions is itself uncommon, so does it even need to be part of the spec? I can see that "Shells" could be used more often, e.g. discarding higher b-values to do a tensor fit; but a subset of orientations is unusual.

If the gradient table were already in the IJKb / XYZb format rather than bvecs & bvals, I'd be suggesting just allocating a JSON field where the utilised gradient table can be stored, just as MRtrix3 does it; but being bvecs & bvals makes it a bit hard to do so.

[Lestropie]

Working on #92 highlighted that this was potentially causing more problems than it solved:

• It's already the case that more than 80% of the time, the model will be fit to all DWI data available rather than some subset, in which case such fields are not necessary.
• If one wants more detail about what data the model was fit to, then knowing the provenance of the filesystem path(s) of the input image(s) to the model fitting process should be of greater precedence than nominating whether only a subset of the data within such was used.

So I'm going to close this off as having been removed from the specification. If there's adequate motivation for having the capacity to track such provenance, then it will need more dedicated consideration.