ENH: Add improved motion plotting capabilities

[jhlegarreta]

Add improved motion plotting capabilities: an interactive head motion correction plot with animated before/after correction frames and optional framewise displacement lineplot.

Add the corresponding interface.

Add tests covering the plotting capabilities.

Add imageio as an additional dependency and update the uv.lock file.

This feature was originally contributed to the PETPrep project by Martin Norgaard:
nipreps/petprep#171

This PR transfers and refactors that work so it can be reused across the NiPreps projects.

Co-Authored-By: Martin Norgaard martin.noergaard@nru.dk

[jhlegarreta]

@mnoergaard Can you please paste here what this looked like in PETPrep so that I can have a reference to work with?

Also, I am wondering whether this can be generalized to any other parameter that we are willing to plot after a pre-processing step.

[codecov]

Codecov Report

❌ Patch coverage is 92.88889% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.62%. Comparing base (40b1fdb) to head (cf72829).

Files with missing lines	Patch %	Lines
nireports/reportlets/utils.py	89.18%	8 Missing and 4 partials ⚠️
nireports/interfaces/nuisance.py	92.85%	1 Missing and 1 partial ⚠️
nireports/reportlets/nuisance.py	97.67%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #257      +/-   ##
==========================================
+ Coverage   66.56%   68.62%   +2.05%     
==========================================
  Files          27       27              
  Lines        3030     3254     +224     
  Branches      401      428      +27     
==========================================
+ Hits         2017     2233     +216     
- Misses        897      902       +5     
- Partials      116      119       +3     

Flag	Coverage Δ
unittests	64.81% <92.88%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mnoergaard]

@jhlegarreta

Example here https://petprep.readthedocs.io/en/latest/_images/sub-01_ses-baseline_desc-hmc_pet.svg

[jhlegarreta]

Example here https://petprep.readthedocs.io/en/latest/_images/sub-01_ses-baseline_desc-hmc_pet.svg

Thanks @mnoergaard. Can you please share the necessary data so that I can try reproducing it?

[jhlegarreta]

This is ready on my end. Thanks @mnoergaard for the original work and for your help behind the scenes.

Some notes:

• Contrary to most other plot function implementation, plot_motion receives the actual volumes to be plot (rather than the paths from which the data is read), and returns the figure that has been plot. IMO it makes most sense that we pass the actual data rather than the files, and same goes for passing the destination path (output_file) vs the function returning the figure handle.

• render_comparison_frames writes temporarily the frames to disk and reads them back immediately. If we believe this round-trip can be avoided and doing everything on the fly is better, e.g.

def display_to_array(display):
    fig = display.frame_axes.figure
    buf = BytesIO()
    fig.savefig(buf, format="png", bbox_inches="tight")
    plt.close(fig)
    buf.seek(0)
    return np.asarray(iio.imread(buf))


def render_comparison_frames(...):
    (...)
    uncorr_display = plot_epi(...)
    uncorr_arr = display_to_array(uncorr_display)

please let me know.

• Re ENH: Add improved motion plotting capabilities #257 (comment)

generalized to any other parameter that we are willing to plot after a pre-processing step.

This can be left for a separate PR/for whenever the need surfaces; the bottom lineplot could be parameterized to display another parameter.

[jhlegarreta]

By the way, is th SVG supposed to be animated or interactive (i.e. triggered by hovering) @mnoergaard? The original documentation says it is interactive but I'd say that it is animated.