:py:mod:`tonic.utils`
=====================

.. py:module:: tonic.utils


Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   tonic.utils.plot_event_grid
   tonic.utils.plot_animation



.. py:function:: plot_event_grid(events: numpy.ndarray, axis_array: tuple[int, int] = (1, 3), plot_frame_number: bool = False)

   Plot events accumulated as frames equal to the product of axes for visual inspection.

   :param events: Structured numpy array of shape [num_events, num_event_channels].
   :param axis_array: dimensions of plotting grid. The larger the grid,
                      the more fine-grained the events will be sliced in time.
   :param plot_frame_number: optional index of frame when plotting

   .. rubric:: Example

   >>> import tonic
   >>> dataset = tonic.datasets.NMNIST(save_to='./data')
   >>> events, target = dataset[100]
   >>> tonic.utils.plot_event_grid(events)

   :returns: None


.. py:function:: plot_animation(frames: numpy.ndarray, figsize: tuple[int, int] = (5, 5))

   Helper function that animates a tensor of frames of shape (TCHW). If you run this in a
   Jupyter notebook, you can display the animation inline like shown in the example below.

   :param frames: numpy array or tensor of shape (TCHW)

   .. rubric:: Example

   >>> import tonic
   >>> nmnist = tonic.datasets.NMNIST(save_to='./data', train=False)
   >>> events, label = nmnist[0]
   >>>
   >>> transform = tonic.transforms.ToFrame(
   >>>     sensor_size=nmnist.sensor_size,
   >>>     time_window=10000,
   >>> )
   >>>
   >>> frames = transform(events)
   >>> animation = tonic.utils.plot_animation(frames)
   >>>
   >>> # Display the animation inline in a Jupyter notebook
   >>> from IPython.display import HTML
   >>> HTML(animation.to_jshtml())

   :returns: The animation object. Store this in a variable to keep it from being garbage collected until displayed.