Convenience functions for common plots?

[sfmig]

Is your feature request related to a problem? Please describe. A few times we have discussed whether it would be useful to include convenience functions to produce plots that are common or cumbersome to write.

For example we could have plot_trajectory or plot_trajectory_with_velocity_vectors.

One implementation @niksirbi liked a while ago is the one in pyrat

Describe the solution you'd like A plotting module that is part of movement, with helper functions for plotting and/or utils for producing common plots.

Describe alternatives you've considered We may just use xarray's plot method and matplotlib directly as we do now.

It may be that our users end up doing their own custom plots anyways, and aiming to cover them all is quite ambitious. Right now our examples are a good showcase of how to make informative plots with a movement dataset.

We may also end up delegating these things to napari-matplotlib.

[willGraham01]

Following the discussion with Sepi on 2025-01-23, she identified 3 plots that she would like "convenient" wrapper functions for. These are listed below, along with the existing examples that movement has for creating these plots.

• Head trajectory
• Occupancy heatmap
• Body part orientation / head direction polar histogram - note that the relevant sections for this wrapper function actually start from this section. For body part orientation, we can generalise the already existing example: it currently uses the head_vector, but this of course could be any kind of vector derived from two keypoints on the mouse (EG left_leg and right_leg for the body instead of the ears).

As a first step, I suggest creating a plotting (or fast_plotting) submodule, in which a wrapper function for each of these use cases should exist. At first pass, these wrappers can just borrow the code in the examples, and suitably generalise it for the this:

def plot_wrapper(
   data,
   # other required arguments for assembling the plot, EG the left/right keypoints
) -> matplotlib.pyplot.Figure
"""Generate a figure corresponding to <wrapped plot type>."""

Each wrapper should return the matplotlib.pyplot.Figure object that contains the "fast made" plot. This will allow the user to show() the plot if they wish, but also to edit the figure for use in a paper, without needing to reassemble the computed data. At the same time as creating a wrapper, we should also update the corresponding example to use the new convenience wrapper function.

Would recommend breaking out a sub-issue for each of the bullet points given above.