Spherical coordinates convention

[Lestropie]

Currently the BEP enforces the mathematical convention of (radius, azimuth, inclination). But the physics convention of (radius, inclination, azimuth) is equally valid. Need to decide whether to enforce one, or use a metadata field to allow utilization of either.

[arokem]

My personal opinion is that it would be best to stick to one of these conventions. Hopefully, the one that the community already tends to use. DIPY tends to use the physics convention in ordering of arguments (e.g., here). What convention does mrtrix use? Do you know about any other software?

[Lestropie]

MRtrix3 code reference
For unit spherical coordinates, MRtrix3 uses mathematical convention. However throughout the code I see references to "elevation" in variable names, whereas the underlying calculations suggest that it's actually inclination that is used. This is in need of an audit of our code in case there's any inconsistency in interpretation: MRtrix3/mrtrix3#2630.

Where a radius is included, MRtrix3 includes that as the third element, which doesn't seem to conform to any convention. It is probably not particularly consequential; I'm not sure if there is actually any code that uses non-unit spherical polar coordinates, and even if there were to be, it's likely to be entirely internal data handling and not involving any writes to disk. Dates back to 2014; no documentation in the commit message on how / why. @jdtournier any recollection?

[Lestropie]

So the first two softwares we've looked at have opposing conventions. Admittedly for MRtrix3 we don't export fibre orientations using spherical coordinates; we use it for dense sampling sets, eg. A2SH conversions or non-negativity constraints. Nevertheless, given the clash at first port of call, would it be better to support multiple? I've been thinking a lot about conversion of software outputs to BIDS derivative compliance, and wanting the scope of manipulation of data to be minimal where possible.

There's also the issue that one could equivalently use elevation rather than inclination.

So the option space might look something like:

1. Enforce one and only one convention
   Explicit conversion of data (whether image intensities or metadata) may be necessary for outputs from some softwares; ideally this is something we'd need to provide.

2. Permit mathematical or physical notation
   Physics convention would be (inclination, azimuth) for unit spherical and (radius, inclination, azimuth) otherwise; mathematics convention would be (azimuth, inclination) for unit spherical and (radius, azimuth, inclination) otherwise (the fact that MRtrix3 has an internal conflict with this shouldn't be an issue).
   In addition to the metadata field "OrientationEncoding" to indicate unit spherical vs. spherical vs. something else, would need a second metadata field eg. "SphericalConvention" to distinguish between physics and mathematics conventions.

3. Permit any encoding
   Azimuth, inclination or elevation, and optionally radius, could be placed in any order, with some metadata field stating which fields are present and their relative order.

There may be other options I'm not immediately seeing.
Given the two conventions have both persisted in the global community, and both are in use by existing DWI softwares, I think I'd choose 2. Open to thought though.

[Lestropie]

@arokem What's the scope of utilisation of spherical coordinates in dipy? What matters here is not what is used for any internal calculations, but specifically interactions with the file system. For MRtrix3, dir* commands can take unit spherical coordinates; this is to do with direction sets used for diffusion gradient schemes, constraints, or numerical integration. While I'm not sure if it works out of the box currently, the "amplitudes" type needs the corresponding direction set, and sometimes that might be provided in spherical coordinates rather than euclidean. If dipy also has features that interface with spherical coordinates at the filesystem level, then it may be preferable to support both.