canns.analyzer.data.asa.plotting

Functions

plot_2d_bump_on_manifold(decoding_result, spike_data)

Create 2D projection animation of CANN2D bump activity with full blitting support.

plot_3d_bump_on_torus(decoding_result, spike_data[, ...])

Visualize the movement of the neural activity bump on a torus using matplotlib animation.

plot_cohomap_scatter(decoding_result, position_data[, ...])

Visualize CohoMap 1.0: decoded circular coordinates mapped onto spatial trajectory.

plot_cohomap_scatter_multi(decoding_result, position_data)

Visualize CohoMap with N-dimensional decoded coordinates.

plot_path_compare_1d(x, y, coords[, config, title, ...])

Plot physical path vs decoded coho-space path (1D) side-by-side.

plot_path_compare_2d(x, y, coords[, config, title, ...])

Plot physical path vs decoded coho-space path (2D) side-by-side.

plot_projection(reduce_func, embed_data[, config, ...])

Plot a 3D projection of the embedded data.

Module Contents

canns.analyzer.data.asa.plotting.plot_2d_bump_on_manifold(decoding_result, spike_data, save_path=None, fps=20, show=True, mode='fast', window_size=10, frame_step=5, numangsint=20, figsize=(8, 6), show_progress=False, config=None, render_backend='auto', output_dpi=150, render_workers=None)[source]

Create 2D projection animation of CANN2D bump activity with full blitting support.

This function provides a fast 2D heatmap visualization as an alternative to the 3D torus animation. It achieves 10-20x speedup using matplotlib blitting optimization, making it ideal for rapid prototyping and daily analysis.

Parameters:

  • decoding_result (dict[str, Any] | str) – Decoding results containing coords and times (dict or file path)

  • spike_data (dict[str, Any]) – Dictionary containing spike train data

  • save_path (str | None) – Path to save animation (None to skip saving)

  • fps (int) – Frames per second

  • show (bool) – Whether to display the animation

  • mode (str) – Visualization mode - ‘fast’ for 2D heatmap (default), ‘3d’ falls back to 3D

  • window_size (int) – Time window for activity aggregation

  • frame_step (int) – Time step between frames

  • numangsint (int) – Number of angular bins for spatial discretization

  • figsize (tuple[int, int]) – Figure size (width, height) in inches

  • show_progress (bool) – Show progress bar during processing

Returns:

  • matplotlib.animation.FuncAnimation | None – Animation object (or None in Jupyter when showing).

  • Raises – ProcessingError: If mode is invalid or animation generation fails

Return type:

matplotlib.animation.FuncAnimation | None

Examples

>>> # Fast 2D visualization (recommended for daily use)
>>> ani = plot_2d_bump_on_manifold(
...     decoding_result, spike_data,
...     save_path='bump_2d.mp4', mode='fast'
... )
>>> # For publication-ready 3D visualization, use mode='3d'
>>> ani = plot_2d_bump_on_manifold(
...     decoding_result, spike_data, mode='3d'
... )
canns.analyzer.data.asa.plotting.plot_3d_bump_on_torus(decoding_result, spike_data, config=None, save_path=None, numangsint=51, r1=1.5, r2=1.0, window_size=300, frame_step=5, n_frames=20, fps=5, show_progress=True, show=True, figsize=(8, 8), render_backend='auto', output_dpi=150, render_workers=None, **kwargs)[source]

Visualize the movement of the neural activity bump on a torus using matplotlib animation.

This function follows the canns.analyzer.plotting patterns for animation generation with progress tracking and proper resource cleanup.

Parameters:

  • decoding_result (dict[str, Any] | str) – dict or str Dictionary containing decoding results with ‘coordsbox’ and ‘times_box’ keys, or path to .npz file containing these results

  • spike_data (dict[str, Any]) – dict, optional Spike data dictionary containing spike information

  • config (canns.analyzer.data.asa.config.CANN2DPlotConfig | None) – PlotConfig, optional Configuration object for unified plotting parameters

  • **kwargs – backward compatibility parameters

  • save_path (str | None) – str, optional Path to save the animation (e.g., ‘animation.gif’ or ‘animation.mp4’)

  • numangsint (int) – int Grid resolution for the torus surface

  • r1 (float) – float Major radius of the torus

  • r2 (float) – float Minor radius of the torus

  • window_size (int) – int Time window (in number of time points) for each frame

  • frame_step (int) – int Step size to slide the time window between frames

  • n_frames (int) – int Total number of frames in the animation

  • fps (int) – int Frames per second for the output animation

  • show_progress (bool) – bool Whether to show progress bar during generation

  • show (bool) – bool Whether to display the animation

  • figsize (tuple[int, int]) – tuple[int, int] Figure size for the animation

Returns:

The animation object, or None when shown in Jupyter.

Return type:

matplotlib.animation.FuncAnimation | None

Examples

>>> ani = plot_3d_bump_on_torus(decoding, spike_data, show=False)
canns.analyzer.data.asa.plotting.plot_cohomap_scatter(decoding_result, position_data, config=None, save_path=None, show=False, figsize=(10, 4), dpi=300, subsample=10)[source]

Visualize CohoMap 1.0: decoded circular coordinates mapped onto spatial trajectory.

Creates a two-panel visualization showing how the two decoded circular coordinates vary across the animal’s spatial trajectory. Each panel displays the spatial path colored by the cosine of one circular coordinate dimension.

Parameters:

  • decoding_result (dict[str, Any]) – dict Dictionary from decode_circular_coordinates() containing: - ‘coordsbox’: decoded coordinates for box timepoints (n_times x n_dims) - ‘times_box’: time indices for coordsbox

  • position_data (dict[str, Any]) – dict Position data containing ‘x’ and ‘y’ arrays for spatial coordinates

  • save_path (str | None) – str, optional Path to save the visualization. If None, no save performed

  • show (bool) – bool, default=False Whether to display the visualization

  • figsize (tuple[int, int]) – tuple[int, int], default=(10, 4) Figure size (width, height) in inches

  • dpi (int) – int, default=300 Resolution for saved figure

  • subsample (int) – int, default=10 Subsampling interval for plotting (plot every Nth timepoint)

Returns:

  • matplotlib.figure.Figure – The matplotlib figure object.

  • Raises – KeyError : If required keys are missing from input dictionaries ValueError : If data dimensions are inconsistent IndexError : If time indices are out of bounds

Return type:

matplotlib.pyplot.Figure

Examples

>>> # Decode coordinates
>>> decoding = decode_circular_coordinates(persistence_result, spike_data)
>>> # Visualize with trajectory data
>>> fig = plot_cohomap_scatter(
...     decoding,
...     position_data={'x': xx, 'y': yy},
...     save_path='cohomap.png',
...     show=True
... )
canns.analyzer.data.asa.plotting.plot_cohomap_scatter_multi(decoding_result, position_data, config=None, save_path=None, show=False, figsize=(10, 4), dpi=300, subsample=10)[source]

Visualize CohoMap with N-dimensional decoded coordinates.

Each subplot shows the spatial trajectory colored by cos(coord_i) for a single circular coordinate.

Parameters:

  • decoding_result (dict) – Dictionary containing coordsbox and times_box.

  • position_data (dict) – Position data containing x and y arrays.

  • config (PlotConfig, optional) – Plot configuration for styling, saving, and showing.

  • save_path (str, optional) – Path to save the figure.

  • show (bool) – Whether to show the figure.

  • figsize (tuple[int, int]) – Figure size in inches.

  • dpi (int) – Save DPI.

  • subsample (int) – Subsample stride for plotting.

Returns:

The created figure.

Return type:

matplotlib.figure.Figure

Examples

>>> fig = plot_cohomap_scatter_multi(decoding, {"x": xx, "y": yy}, show=False)
canns.analyzer.data.asa.plotting.plot_path_compare_1d(x, y, coords, config=None, *, title='Path Compare (1D)', figsize=(12, 5), show=True, save_path=None)[source]

Plot physical path vs decoded coho-space path (1D) side-by-side.

canns.analyzer.data.asa.plotting.plot_path_compare_2d(x, y, coords, config=None, *, title='Path Compare', figsize=(12, 5), show=True, save_path=None)[source]

Plot physical path vs decoded coho-space path (2D) side-by-side.

Parameters:

  • x (np.ndarray) – Physical position arrays of shape (T,).

  • y (np.ndarray) – Physical position arrays of shape (T,).

  • coords (np.ndarray) – Decoded circular coordinates, shape (T, 2) or (T, 2+).

  • config (PlotConfig, optional) – Plot configuration. If None, a default config is created.

  • title (optional) – Backward-compatibility parameters.

  • figsize (optional) – Backward-compatibility parameters.

  • show (optional) – Backward-compatibility parameters.

  • save_path (optional) – Backward-compatibility parameters.

Returns:

Figure and axes array.

Return type:

(Figure, ndarray)

Examples

>>> fig, axes = plot_path_compare_2d(x, y, coords, show=False)
canns.analyzer.data.asa.plotting.plot_projection(reduce_func, embed_data, config=None, title='Projection (3D)', xlabel='Component 1', ylabel='Component 2', zlabel='Component 3', save_path=None, show=True, dpi=300, figsize=(10, 8), **kwargs)[source]

Plot a 3D projection of the embedded data.

Parameters:

  • (callable) (reduce_func)

  • (ndarray) (embed_data)

  • (PlotConfig (config)

  • optional) (Path to save the plot. If None, plot will not be saved.)

  • **kwargs (backward compatibility parameters)

  • (str) (zlabel)

  • (str)

  • (str)

  • (str)

  • (str (save_path)

  • optional)

  • (bool) (show)

  • (int) (dpi)

  • (tuple) (figsize)

Returns:

The created figure.

Return type:

matplotlib.figure.Figure

Examples

>>> fig = plot_projection(reduce_func, embed_data, show=False)