src.canns.analyzer.experimental_data.cann2d

Attributes

HAS_NUMBA
data

Exceptions

CANN2DError	Base exception for CANN2D analysis errors.
DataLoadError	Raised when data loading fails.
ProcessingError	Raised when data processing fails.

Classes

CANN2DPlotConfig	Specialized PlotConfig for CANN2D visualizations.
Constants	Constants used throughout CANN2D analysis.
SpikeEmbeddingConfig	Configuration for spike train embedding.
TDAConfig	Configuration for Topological Data Analysis.

Functions

decode_circular_coordinates(persistence_result, spike_data)	Decode circular coordinates (bump positions) from cohomology.
embed_spike_trains(spike_trains[, config])	Load and preprocess spike train data from npz file.
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(decoding_result, position_data[, ...])	Visualize CohoMap 1.0: decoded circular coordinates mapped onto spatial trajectory.
plot_projection(reduce_func, embed_data[, config, ...])	Plot a 3D projection of the embedded data.
tda_vis(embed_data[, config])	Topological Data Analysis visualization with optional shuffle testing.

Module Contents

exception src.canns.analyzer.experimental_data.cann2d.CANN2DError

Bases: Exception

Base exception for CANN2D analysis errors.

Initialize self. See help(type(self)) for accurate signature.

exception src.canns.analyzer.experimental_data.cann2d.DataLoadError

Bases: CANN2DError

Raised when data loading fails.

Initialize self. See help(type(self)) for accurate signature.

exception src.canns.analyzer.experimental_data.cann2d.ProcessingError

Bases: CANN2DError

Raised when data processing fails.

Initialize self. See help(type(self)) for accurate signature.

class src.canns.analyzer.experimental_data.cann2d.CANN2DPlotConfig

Bases: src.canns.analyzer.plotting.PlotConfig

Specialized PlotConfig for CANN2D visualizations.

classmethod for_projection_3d(**kwargs)

Create configuration for 3D projection plots.

classmethod for_torus_animation(**kwargs)

Create configuration for 3D torus bump animations.

dpi: int = 300

frame_step: int = 5

n_frames: int = 20

numangsint: int = 51

r1: float = 1.5

r2: float = 1.0

window_size: int = 300

zlabel: str = 'Component 3'

class src.canns.analyzer.experimental_data.cann2d.Constants

Constants used throughout CANN2D analysis.

DEFAULT_DPI = 300

DEFAULT_FIGSIZE = (10, 8)

GAUSSIAN_SIGMA_FACTOR = 100

MULTIPROCESSING_CORES = 4

SPEED_CONVERSION_FACTOR = 100

TIME_CONVERSION_FACTOR = 0.01

class src.canns.analyzer.experimental_data.cann2d.SpikeEmbeddingConfig

Configuration for spike train embedding.

dt: int = 1000

min_speed: float = 2.5

res: int = 100000

sigma: int = 5000

smooth: bool = True

speed_filter: bool = True

class src.canns.analyzer.experimental_data.cann2d.TDAConfig

Configuration for Topological Data Analysis.

active_times: int = 15000

coeff: int = 47

dim: int = 6

do_shuffle: bool = False

k: int = 1000

maxdim: int = 1

metric: str = 'cosine'

n_points: int = 1200

nbs: int = 800

num_shuffles: int = 1000

num_times: int = 5

progress_bar: bool = True

show: bool = True

src.canns.analyzer.experimental_data.cann2d.decode_circular_coordinates(persistence_result, spike_data, real_ground=True, real_of=True, save_path=None)

Decode circular coordinates (bump positions) from cohomology.

Parameters:

• persistence_result (dict[str, Any]) – dict containing persistence analysis results with keys: - ‘persistence’: persistent homology result - ‘indstemp’: indices of sampled points - ‘movetimes’: selected time points - ‘n_points’: number of sampled points

• spike_data (dict[str, Any]) – dict, optional Spike data dictionary containing ‘spike’, ‘t’, and optionally ‘x’, ‘y’

• real_ground (bool) – bool Whether x, y, t ground truth exists

• real_of (bool) – bool Whether experiment was performed in open field

• save_path (str | None) – str, optional Path to save decoding results. If None, saves to ‘Results/spikes_decoding.npz’

Returns:

Dictionary containing decoding results with keys:

• ’coords’: decoded coordinates for all timepoints

• ’coordsbox’: decoded coordinates for box timepoints

• ’times’: time indices for coords

• ’times_box’: time indices for coordsbox

• ’centcosall’: cosine centroids

• ’centsinall’: sine centroids

Return type:

dict

src.canns.analyzer.experimental_data.cann2d.embed_spike_trains(spike_trains, config=None, **kwargs)

Load and preprocess spike train data from npz file.

This function converts raw spike times into a time-binned spike matrix, optionally applying Gaussian smoothing and filtering based on animal movement speed.

Parameters:

• spike_trains – dict containing ‘spike’, ‘t’, and optionally ‘x’, ‘y’.

• config (SpikeEmbeddingConfig | None) – SpikeEmbeddingConfig, optional configuration object

• **kwargs – backward compatibility parameters

Returns:

Binned and optionally smoothed spike matrix of shape (T, N). xx (ndarray, optional): X coordinates (if speed_filter=True). yy (ndarray, optional): Y coordinates (if speed_filter=True). tt (ndarray, optional): Time points (if speed_filter=True).

Return type:

spikes_bin (ndarray)

src.canns.analyzer.experimental_data.cann2d.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), **kwargs)

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 (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

Return type:

matplotlib.animation.FuncAnimation

src.canns.analyzer.experimental_data.cann2d.plot_cohomap(decoding_result, position_data, save_path=None, show=False, figsize=(10, 4), dpi=300, subsample=10)

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:

The matplotlib figure object

Return type:

plt.Figure

Raises:

• KeyError – If required keys are missing from input dictionaries

• ValueError – If data dimensions are inconsistent

• IndexError – If time indices are out of bounds

Examples

>>> # Decode coordinates
>>> decoding = decode_circular_coordinates(persistence_result, spike_data)
>>> # Visualize with trajectory data
>>> fig = plot_cohomap(
...     decoding,
...     position_data={'x': xx, 'y': yy},
...     save_path='cohomap.png',
...     show=True
... )

src.canns.analyzer.experimental_data.cann2d.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)

Plot a 3D projection of the embedded data.

Parameters:

• reduce_func (callable) – Function to reduce the dimensionality of the data.

• embed_data (ndarray) – Data to be projected.

• config (PlotConfig, optional) – Configuration object for unified plotting parameters

• **kwargs – backward compatibility parameters

• title (str) – Title of the plot.

• xlabel (str) – Label for the x-axis.

• ylabel (str) – Label for the y-axis.

• zlabel (str) – Label for the z-axis.

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

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

• dpi (int) – Dots per inch for saving the figure.

• figsize (tuple) – Size of the figure.

Returns:

The created figure object.

Return type:

fig

src.canns.analyzer.experimental_data.cann2d.tda_vis(embed_data, config=None, **kwargs)

Topological Data Analysis visualization with optional shuffle testing.

Parameters:

• embed_data (numpy.ndarray) – ndarray Embedded spike train data.

• config (TDAConfig | None) – TDAConfig, optional Configuration object with all TDA parameters

• **kwargs – backward compatibility parameters

Returns:

Dictionary containing:

• persistence: persistence diagrams from real data

• indstemp: indices of sampled points

• movetimes: selected time points

• n_points: number of sampled points

• shuffle_max: shuffle analysis results (if do_shuffle=True, otherwise None)

Return type:

dict

src.canns.analyzer.experimental_data.cann2d.HAS_NUMBA = True

src.canns.analyzer.experimental_data.cann2d.data = None