src.canns.analyzer.theta_sweep

Theta sweep specific visualization functions for CANNs models.

This module contains specialized plotting functions for analyzing theta-modulated neural activity, particularly for direction cell and grid cell networks.

Functions

create_theta_sweep_grid_cell_animation(position_data, ...)

Create comprehensive theta sweep animation with 4 panels (optimized for speed):

create_theta_sweep_place_cell_animation(position_data, ...)

Create theta sweep animation for place cell network with 2 panels:

plot_direction_cell_polar(direction_bins, ...[, ...])

Plot direction cell activity in polar coordinates.

plot_grid_cell_manifold(value_grid_twisted, ...[, ...])

Plot grid cell activity on the twisted torus manifold.

plot_population_activity_with_theta(time_steps, ...[, ...])

Plot neural population activity with theta oscillation markers and direction trace.

Module Contents

src.canns.analyzer.theta_sweep.create_theta_sweep_grid_cell_animation(position_data, direction_data, dc_activity_data, gc_activity_data, gc_network, env_size, mapping_ratio, dt=0.001, config=None, n_step=10, fps=10, figsize=(12, 3), save_path=None, show=True, show_progress_bar=True, render_backend='auto', output_dpi=150, render_workers=None, render_start_method=None, **kwargs)[source]

Create comprehensive theta sweep animation with 4 panels (optimized for speed): 1. Animal trajectory 2. Direction cell polar plot 3. Grid cell activity on manifold 4. Grid cell activity in real space

Parameters:

  • position_data (numpy.ndarray) – Animal position data (time, 2)

  • direction_data (numpy.ndarray) – Direction data (time,)

  • dc_activity_data (numpy.ndarray) – Direction cell activity (time, neurons)

  • gc_activity_data (numpy.ndarray) – Grid cell activity (time, neurons)

  • gc_network – GridCellNetwork instance for coordinate transformations

  • env_size (float) – Environment size

  • mapping_ratio (float) – Mapping ratio for grid cells

  • dt (float) – Time step size

  • config (src.canns.analyzer.plotting.PlotConfig | None) – PlotConfig object for unified configuration

  • n_step (int) – Subsample every n_step frames for animation

  • render_backend (str | None) – Rendering backend. Use ‘matplotlib’, ‘imageio’, or ‘auto’/’None’ for auto-detect.

  • output_dpi (int) – Target DPI when rendering frames with non-interactive backends

  • render_workers (int | None) – Worker processes for imageio backend. None auto-selects, 0 disables.

  • render_start_method (str | None) – Multiprocessing start method (‘fork’, ‘spawn’, ‘forkserver’) or None for auto

  • **kwargs – Additional parameters for backward compatibility

Returns:

Matplotlib animation object for interactive backend, otherwise None

Return type:

FuncAnimation | None

src.canns.analyzer.theta_sweep.create_theta_sweep_place_cell_animation(position_data, pc_activity_data, pc_network, navigation_task, dt=0.001, config=None, n_step=10, fps=10, figsize=(12, 4), save_path=None, show=True, show_progress_bar=True, **kwargs)[source]

Create theta sweep animation for place cell network with 2 panels: 1. Environment trajectory with place cell bump overlay 2. Population activity heatmap over time

Parameters:

  • position_data (numpy.ndarray) – Animal position data (time, 2)

  • pc_activity_data (numpy.ndarray) – Place cell activity (time, num_cells)

  • pc_network – PlaceCellNetwork instance

  • navigation_task – BaseNavigationTask instance for environment visualization

  • dt (float) – Time step size

  • config (src.canns.analyzer.plotting.PlotConfig | None) – PlotConfig object for unified configuration

  • n_step (int) – Subsample every n_step frames for animation

  • fps (int) – Frames per second for animation

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

  • save_path (str | None) – Path to save animation (GIF or MP4)

  • show (bool) – Whether to display animation

  • show_progress_bar (bool) – Whether to show progress bar during saving

  • **kwargs – Additional parameters (cmap, alpha, etc.)

Returns:

Matplotlib animation object

Return type:

FuncAnimation

src.canns.analyzer.theta_sweep.plot_direction_cell_polar(direction_bins, direction_activity, true_direction, config=None, title='Direction Cell Activity', figsize=(6, 6), show=True, save_path=None, **kwargs)[source]

Plot direction cell activity in polar coordinates.

Parameters:

  • direction_bins (numpy.ndarray) – Array of direction bins (radians)

  • direction_activity (numpy.ndarray) – Array of activity values for each direction

  • true_direction (float) – True direction value (radians)

  • config (src.canns.analyzer.plotting.PlotConfig | None) – PlotConfig object for unified configuration

  • **kwargs – Additional parameters for backward compatibility

Returns:

(figure, axis) objects

Return type:

tuple

src.canns.analyzer.theta_sweep.plot_grid_cell_manifold(value_grid_twisted, grid_cell_activity, config=None, ax=None, title='Grid Cell Activity on Manifold', figsize=(8, 6), cmap='jet', show=True, save_path=None, **kwargs)[source]

Plot grid cell activity on the twisted torus manifold.

Parameters:

  • value_grid_twisted (numpy.ndarray) – Coordinates on twisted manifold

  • grid_cell_activity (numpy.ndarray) – 2D array of grid cell activities

  • config (src.canns.analyzer.plotting.PlotConfig | None) – PlotConfig object for unified configuration

  • ax (matplotlib.pyplot.Axes | None) – Optional axis to draw on instead of creating a new figure

  • **kwargs – Additional parameters for backward compatibility

Returns:

(figure, axis) objects

Return type:

tuple

src.canns.analyzer.theta_sweep.plot_population_activity_with_theta(time_steps, theta_phase, net_activity, direction, config=None, add_lines=True, atol=0.01, title='Population Activity with Theta', xlabel='Time (s)', ylabel='Direction (°)', figsize=(12, 4), cmap='jet', show=True, save_path=None, **kwargs)[source]

Plot neural population activity with theta oscillation markers and direction trace.

Parameters:

  • time_steps (numpy.ndarray) – Array of time points

  • theta_phase (numpy.ndarray) – Array of theta phase values [-π, π]

  • net_activity (numpy.ndarray) – 2D array of network activity (time, neurons)

  • direction (numpy.ndarray) – Array of direction values

  • config (src.canns.analyzer.plotting.PlotConfig | None) – PlotConfig object for unified configuration

  • add_lines (bool) – Whether to add vertical lines at theta phase zeros

  • atol (float) – Tolerance for detecting theta phase zeros

  • **kwargs – Additional parameters for backward compatibility

Returns:

(figure, axis) objects

Return type:

tuple