src.canns.analyzer.plotting

High-level plotting helpers for analyzer functionality.

Submodules

• src.canns.analyzer.plotting.config
• src.canns.analyzer.plotting.energy
• src.canns.analyzer.plotting.jupyter_utils
• src.canns.analyzer.plotting.spatial
• src.canns.analyzer.plotting.spikes
• src.canns.analyzer.plotting.tuning

Classes

PlotConfig	Unified configuration class for all plotting helpers in canns.analyzer.
PlotConfigs	Collection of commonly used plot configurations.

Functions

average_firing_rate_plot(spike_train, dt[, config, ...])	Calculate and plot average neural activity from a spike train.
energy_landscape_1d_animation(data_sets[, ...])	Create an animation of an evolving 1D energy landscape.
energy_landscape_1d_static(data_sets[, config, title, ...])	Plot a 1D static energy landscape using Matplotlib.
energy_landscape_2d_animation(zs_data[, config, ...])	Create an animation of an evolving 2D landscape.
energy_landscape_2d_static(z_data[, config, title, ...])	Plot a static 2D landscape from a 2D array as a heatmap.
plot_firing_field_heatmap(heatmap[, config, figsize, ...])	Plot a single spatial firing field heatmap.
raster_plot(spike_train[, config, mode, title, ...])	Generate a raster plot from a spike train matrix.
tuning_curve(stimulus, firing_rates, neuron_indices[, ...])	Plot the tuning curve for one or more neurons.

Package Contents

class src.canns.analyzer.plotting.PlotConfig

Unified configuration class for all plotting helpers in canns.analyzer.

This mirrors the behaviour of the previous visualize module so that reorganising the files does not affect the public API. The attributes map directly to keyword arguments exposed by the high-level plotting functions, allowing users to keep existing configuration objects unchanged after the reorganisation.

__post_init__()

classmethod for_animation(time_steps_per_second, **kwargs)

Return configuration tailored for animations.

classmethod for_static_plot(**kwargs)

Return configuration tailored for static plots.

to_matplotlib_kwargs()

Materialize matplotlib keyword arguments from the config.

clabel: str = 'Value'

color: str = 'black'

figsize: tuple[int, int] = (10, 6)

fps: int = 30

grid: bool = False

kwargs: dict[str, Any] | None = None

repeat: bool = True

save_path: str | None = None

show: bool = True

show_legend: bool = True

show_progress_bar: bool = True

time_steps_per_second: int | None = None

title: str = ''

xlabel: str = ''

ylabel: str = ''

class src.canns.analyzer.plotting.PlotConfigs

Collection of commonly used plot configurations.

These helpers mirror the presets that existed in canns.analyzer.visualize so that callers relying on them continue to receive the exact same defaults.

static average_firing_rate_plot(mode='per_neuron', **kwargs)

static energy_landscape_1d_animation(**kwargs)

static energy_landscape_1d_static(**kwargs)

static energy_landscape_2d_animation(**kwargs)

static energy_landscape_2d_static(**kwargs)

static grid_cell_manifold_static(**kwargs)

static raster_plot(mode='block', **kwargs)

static theta_population_activity_static(**kwargs)

static theta_sweep_animation(**kwargs)

static tuning_curve(num_bins=50, pref_stim=None, **kwargs)

src.canns.analyzer.plotting.average_firing_rate_plot(spike_train, dt, config=None, *, mode='population', weights=None, title='Average Firing Rate', figsize=(12, 5), save_path=None, show=True, **kwargs)

Calculate and plot average neural activity from a spike train.

Parameters:

• spike_train (numpy.ndarray) – Boolean/integer array of shape (timesteps, neurons).

• dt (float) – Simulation time step in seconds.

• config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig with styling overrides.

• mode (str) – One of "per_neuron", "population" or "weighted_average".

• weights (numpy.ndarray | None) – Neuron-wise weights required for "weighted_average".

• title (str) – Plot title when config is not provided.

• figsize (tuple[int, int]) – Figure size forwarded to Matplotlib when creating the axes.

• save_path (str | None) – Optional path used to persist the plot.

• show (bool) – Whether to display the plot interactively.

• **kwargs (Any) – Additional keyword arguments forwarded to Matplotlib.

src.canns.analyzer.plotting.energy_landscape_1d_animation(data_sets, time_steps_per_second=None, config=None, *, fps=30, title='Evolving 1D Energy Landscape', xlabel='Collective Variable / State', ylabel='Energy', figsize=(10, 6), grid=False, repeat=True, save_path=None, show=True, show_progress_bar=True, **kwargs)

Create an animation of an evolving 1D energy landscape.

The docstring intentionally preserves the guidance from the previous implementation so existing callers can rely on the same parameter explanations.

Parameters:

• data_sets (dict[str, tuple[numpy.ndarray, numpy.ndarray]]) – Dictionary whose keys are legend labels and values are (x_data, y_data) tuples where y_data is shaped as (time, state).

• time_steps_per_second (int | None) – Number of simulation time steps per second of wall-clock time (e.g., 1/dt).

• config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig with shared styling overrides.

• fps (int) – Frames per second to render in the resulting animation.

• title (str) – Title used when config is not provided.

• xlabel (str) – X-axis label used when config is not provided.

• ylabel (str) – Y-axis label used when config is not provided.

• figsize (tuple[int, int]) – Figure size passed to Matplotlib when building the canvas.

• grid (bool) – Whether to overlay a grid on the animation axes.

• repeat (bool) – Whether the animation should loop once it finishes.

• save_path (str | None) – Optional path to persist the animation (.gif / .mp4).

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

• show_progress_bar (bool) – Whether to show a tqdm progress bar when saving.

• **kwargs (Any) – Further keyword arguments passed through to ax.plot.

Returns:

The constructed animation.

Return type:

matplotlib.animation.FuncAnimation

src.canns.analyzer.plotting.energy_landscape_1d_static(data_sets, config=None, *, title='1D Energy Landscape', xlabel='Collective Variable / State', ylabel='Energy', show_legend=True, figsize=(10, 6), grid=False, save_path=None, show=True, **kwargs)

Plot a 1D static energy landscape using Matplotlib.

This mirrors the long-form description from the pre-reorganisation module so existing documentation references stay accurate. The function accepts a dictionary of datasets, plotting each curve on the same set of axes while honouring the PlotConfig defaults callers relied on previously.

Parameters:

• data_sets (dict[str, tuple[numpy.ndarray, numpy.ndarray]]) – Mapping of series labels to (x, y) tuples representing the energy curve to draw.

• config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig carrying shared styling.

• title (str) – Plot title when no config override is supplied.

• xlabel (str) – X-axis label when no config override is supplied.

• ylabel (str) – Y-axis label when no config override is supplied.

• show_legend (bool) – Whether to display the legend for labelled curves.

• figsize (tuple[int, int]) – Figure size forwarded to Matplotlib when creating the axes.

• grid (bool) – Whether to enable a grid background.

• save_path (str | None) – Optional path for persisting the plot to disk.

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

• **kwargs (Any) – Additional keyword arguments forwarded to ax.plot.

Returns:

The created figure and axes handles.

Return type:

Tuple[plt.Figure, plt.Axes]

src.canns.analyzer.plotting.energy_landscape_2d_animation(zs_data, config=None, *, time_steps_per_second=None, fps=30, title='Evolving 2D Landscape', xlabel='X-Index', ylabel='Y-Index', clabel='Value', figsize=(8, 7), grid=False, repeat=True, save_path=None, show=True, show_progress_bar=True, **kwargs)

Create an animation of an evolving 2D landscape.

The long-form description mirrors the previous implementation to maintain backwards-compatible documentation for downstream users.

Parameters:

• zs_data (numpy.ndarray) – Array of shape (timesteps, dim_y, dim_x) describing the landscape at each simulation step.

• config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig carrying display preferences.

• time_steps_per_second (int | None) – Number of simulation steps per second of simulated time; required unless encoded in config.

• fps (int) – Frames per second in the generated animation.

• title (str) – Title used when config is not provided.

• xlabel (str) – X-axis label used when config is not provided.

• ylabel (str) – Y-axis label used when config is not provided.

• clabel (str) – Colorbar label used when config is not provided.

• figsize (tuple[int, int]) – Figure size passed to Matplotlib.

• grid (bool) – Whether to overlay a grid on the heatmap.

• repeat (bool) – Whether the animation should loop.

• save_path (str | None) – Optional output path (.gif / .mp4).

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

• show_progress_bar (bool) – Whether to render a tqdm progress bar during save.

• **kwargs (Any) – Additional keyword arguments forwarded to ax.imshow.

Returns:

The constructed animation.

Return type:

matplotlib.animation.FuncAnimation

src.canns.analyzer.plotting.energy_landscape_2d_static(z_data, config=None, *, title='2D Static Landscape', xlabel='X-Index', ylabel='Y-Index', clabel='Value', figsize=(8, 7), grid=False, save_path=None, show=True, **kwargs)

Plot a static 2D landscape from a 2D array as a heatmap.

Parameters:

• z_data (numpy.ndarray) – 2D array (dim_y, dim_x) representing the landscape.

• config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig with pre-set styling.

• title (str) – Plot title when config is not provided.

• xlabel (str) – X-axis label when config is not provided.

• ylabel (str) – Y-axis label when config is not provided.

• clabel (str) – Colorbar label when config is not provided.

• figsize (tuple[int, int]) – Figure size forwarded to Matplotlib when allocating the canvas.

• grid (bool) – Whether to draw a grid overlay.

• save_path (str | None) – Optional path that triggers saving the figure to disk.

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

• **kwargs (Any) – Additional keyword arguments passed through to ax.imshow.

Returns:

The Matplotlib figure and axes objects.

Return type:

Tuple[plt.Figure, plt.Axes]

src.canns.analyzer.plotting.plot_firing_field_heatmap(heatmap, config=None, figsize=(5, 5), cmap='jet', interpolation='nearest', origin='lower', show=True, save_path=None, **kwargs)

Plot a single spatial firing field heatmap.

This function creates a publication-quality heatmap visualization of neural spatial firing patterns. It supports both modern PlotConfig-based configuration and legacy keyword arguments for backward compatibility.

Parameters:

• heatmap (np.ndarray) – 2D array of shape (M, K) representing spatial firing rates in each bin.

• config (PlotConfig | None) – Unified configuration object. If None, uses backward compatibility parameters.

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

• cmap (str) – Colormap name for the heatmap. Defaults to ‘jet’.

• interpolation (str) – Interpolation method for imshow. Defaults to ‘nearest’.

• origin (str) – Origin position for imshow (‘lower’ or ‘upper’). Defaults to ‘lower’.

• show (bool) – Whether to display the plot. Defaults to True.

• save_path (str | None) – Path to save the figure. If None, figure is not saved.

• **kwargs – Additional keyword arguments passed to plt.imshow().

Returns:

The figure and axis objects for further customization.

Return type:

tuple[plt.Figure, plt.Axes]

Example

>>> from canns.analyzer.spatial import compute_firing_field
>>> from canns.analyzer.plotting import plot_firing_field_heatmap, PlotConfig
>>> # Compute firing field
>>> heatmaps = compute_firing_field(activity, positions, 5.0, 5.0, 50, 50)
>>> # Plot single neuron with PlotConfig
>>> config = PlotConfig(figsize=(6, 6), save_path='neuron_0.png', show=False)
>>> fig, ax = plot_firing_field_heatmap(heatmaps[0], config=config)
>>> # Plot with legacy parameters
>>> fig, ax = plot_firing_field_heatmap(heatmaps[1], cmap='viridis', save_path='neuron_1.png')

src.canns.analyzer.plotting.raster_plot(spike_train, config=None, *, mode='block', title='Raster Plot', xlabel='Time Step', ylabel='Neuron Index', figsize=(12, 6), color='black', save_path=None, show=True, **kwargs)

Generate a raster plot from a spike train matrix.

The explanatory text mirrors the former visualize module so callers see the same guidance after the reorganisation.

Parameters:

• spike_train (numpy.ndarray) – Boolean/integer array of shape (timesteps, neurons).

• config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig with shared styling options.

• mode (str) – Either "scatter" or "block" to pick the rendering style.

• title (str) – Plot title when config is not provided.

• xlabel (str) – X-axis label when config is not provided.

• ylabel (str) – Y-axis label when config is not provided.

• figsize (tuple[int, int]) – Figure size forwarded to Matplotlib when creating the axes.

• color (str) – Spike colour (or “on” colour for block mode).

• save_path (str | None) – Optional path used to persist the plot.

• show (bool) – Whether to display the plot interactively.

• **kwargs (Any) – Additional keyword arguments passed through to Matplotlib.

src.canns.analyzer.plotting.tuning_curve(stimulus, firing_rates, neuron_indices, config=None, *, pref_stim=None, num_bins=50, title='Tuning Curve', xlabel='Stimulus Value', ylabel='Average Firing Rate', figsize=(10, 6), save_path=None, show=True, **kwargs)

Plot the tuning curve for one or more neurons.

The wording mirrors the original visualize module to avoid API drift and to keep existing references valid.

Parameters:

• stimulus (numpy.ndarray) – 1D array with the stimulus value at each time step.

• firing_rates (numpy.ndarray) – 2D array of firing rates shaped (timesteps, neurons).

• neuron_indices (numpy.ndarray | int) – Integer or iterable of neuron indices to analyse.

• config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig containing styling overrides.

• pref_stim (numpy.ndarray | None) – Optional 1D array of preferred stimuli used in legend text.

• num_bins (int) – Number of bins when mapping stimulus to mean activity.

• title (str) – Plot title when config is not provided.

• xlabel (str) – X-axis label when config is not provided.

• ylabel (str) – Y-axis label when config is not provided.

• figsize (tuple[int, int]) – Figure size forwarded to Matplotlib when creating the axes.

• save_path (str | None) – Optional location where the figure should be stored.

• show (bool) – Whether to display the plot interactively.

• **kwargs (Any) – Additional keyword arguments passed through to ax.plot.