ENH: Add gradient plot method

[jhlegarreta]

Add gradient plot method.

[jhlegarreta]

Notes:

• Following https://github.com/nipreps/mriqc/issues/1216#issuecomment-2056452871.
• Test data is missing. I have used some local data. Suggestions on where a pair of bvals/bvecs should be fetched are welcome.
• This has been transferred/adapted (return object docstring added to plot_gradients) from eddymotion. IMO eddymotion should import plot capabilities from either here, nireports or elsewhere. As the mentioned issue was opened here, adding the code here.
• Eventually, the entire eddymotion.viz module will need to be relocated, and the documentation be adjusted:
• https://github.com/nipreps/eddymotion/pull/169/files#diff-c4b284a0e8c330264ebefb4d3d14dd5bb68fe3b72c2ae656f49132e2c134b84fR90
• Not sure whether the module where I added the data is the most appropriate one (e.g. instrumentation has a viz module).
• The current code provides this plot: are we OK with it?

• Or do we prefer each shell in a different sphere, e.g.?

[oesteban]

I would prefer the first plot, but with a twist: it should render both the original b-vectors and where they land after head motion correction, possibly showing the glyph through which they rotate.

The original b-vector could be just a point (not to overcrowd the plot) and then the rotated b-vector should take the color scale.

Why this?

First, because the plot would allow assessing head motion at the same time (we have some metrics summarizing the angles between original and rotated b-vectors). Second, because MRIQC cannot assume the dataset is "shelled" -- the input can be DSI or some hybrid sampling. IMHO, plots with 3 or more spheres are almost impossible to interpret. Having a single sphere can feel crowdy, but gives a good sense of the coverage of the b-vectors and shells.

WDYT?

[oesteban]

• This has been transferred/adapted (return object docstring added to plot_gradients) from eddymotion. IMO eddymotion should import plot capabilities from either here, nireports or elsewhere. As the mentioned issue was opened here, adding the code here.

I think eddymotion's viz module could be outsourced into nireports, so all nipreps can use it naturally without forcing the dependency.

[oesteban]

• Not sure whether the module where I added the data is the most appropriate one (e.g. instrumentation has a viz module).

mriqc.instrumentation is basically a resource monitoring tool, and the plotting is just for it. mriqc.viz is the right location for this (actually somewhere under nireports.reportlets)

[jhlegarreta]

I would prefer the first plot, but with a twist: it should render both the original b-vectors and where they land after head motion correction, possibly showing the glyph through which they rotate. First, because the plot would allow assessing head motion at the same time (we have some metrics summarizing the angles between original and rotated b-vectors).

Agreed. But I would leave that for a separate PR. See below.

because MRIQC cannot assume the dataset is "shelled" -- the input can be DSI or some hybrid sampling. IMHO, plots with 3 or more spheres are almost impossible to interpret. Having a single sphere can feel crowdy, but gives a good sense of the coverage of the b-vectors and shells.

OK, I see. For now, I would prefer to go forward with the code as I extracted from eddymotion: it is already a useful tool. Identifying the relevant data (conventional shelled DWI data or DSI acq data) is already missing, and I fear that it may take some time until everything is in place. Same goes to the corrected bvecs.

After quickly looking to the code: should we directly outsource this from eddymotion into nireports?

OK. So I will close this PR and move the code nireports.