src.canns.analyzer.experimental_data

Submodules

• src.canns.analyzer.experimental_data.cann1d
• src.canns.analyzer.experimental_data.cann2d

Classes

CANN1DPlotConfig	Specialized PlotConfig for CANN1D visualizations.
CANN2DPlotConfig	Specialized PlotConfig for CANN2D visualizations.
PlotConfig	Unified configuration class for all plotting helpers in canns.analyzer.
SpikeEmbeddingConfig	Configuration for spike train embedding.
TDAConfig	Configuration for Topological Data Analysis.

Functions

bump_fits(data[, config, save_path])	Fit CANN1D bumps to data using MCMC optimization.
create_1d_bump_animation(fits_data[, config, save_path])	Create 1D CANN bump animation using vectorized operations.
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.
load_grid_data([source, dataset_key])	Load grid cell data for 2D CANN analysis.
load_roi_data([source])	Load ROI data for 1D CANN analysis.
plot_3d_bump_on_torus(decoding_result, spike_data[, ...])	Visualize the movement of the neural activity bump on a torus using matplotlib animation.
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.
validate_grid_data(data)	Validate grid data format for 2D CANN analysis.
validate_roi_data(data)	Validate ROI data format for 1D CANN analysis.

Package Contents

class src.canns.analyzer.experimental_data.CANN1DPlotConfig

Bases: src.canns.analyzer.plotting.PlotConfig

Specialized PlotConfig for CANN1D visualizations.

classmethod for_bump_animation(**kwargs)

Create configuration for 1D CANN bump animation.

bump_selection: str = 'strongest'

max_height_value: float = 0.5

max_width_range: int = 40

nframes: int | None = None

npoints: int = 300

class src.canns.analyzer.experimental_data.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.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.experimental_data.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.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.bump_fits(data, config=None, save_path=None, **kwargs)

Fit CANN1D bumps to data using MCMC optimization.

Parameters:

• data – numpy.ndarray Input data for bump fitting

• config (BumpFitsConfig | None) – BumpFitsConfig, optional Configuration object with all fitting parameters

• save_path – str, optional Path to save the results

• **kwargs – backward compatibility parameters

Returns:

list

List of fitted bump objects

fits_arraynumpy.ndarray

Array of fitted bump parameters

nbump_arraynumpy.ndarray

Array of bump counts and reconstructed signals

centrbump_arraynumpy.ndarray

Array of centered bump data

Return type:

bumps

src.canns.analyzer.experimental_data.create_1d_bump_animation(fits_data, config=None, save_path=None, **kwargs)

Create 1D CANN bump animation using vectorized operations.

Parameters:

• fits_data – numpy.ndarray Shape (n_fits, 4) array with columns [time, position, amplitude, kappa]

• config (CANN1DPlotConfig | None) – AnimationConfig, optional Configuration object with all animation parameters

• save_path – str, optional Output path for the generated GIF

• **kwargs – backward compatibility parameters

Returns:

matplotlib.animation.FuncAnimation

The animation object

src.canns.analyzer.experimental_data.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.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.load_grid_data(source=None, dataset_key='grid_1')

Load grid cell data for 2D CANN analysis.

Parameters:

• source (str, Path, or None) – Data source. Can be: - URL string: downloads and loads from URL - Path: loads from local file - None: uses default CANNs dataset

• dataset_key (str) – Which default dataset to use (‘grid_1’ or ‘grid_2’) when source is None.

Returns:

Dictionary containing spike data and metadata if successful, None otherwise. Expected keys: ‘spike’, ‘t’, and optionally ‘x’, ‘y’ for position data.

Return type:

dict or None

Examples

>>> # Load default dataset
>>> grid_data = load_grid_data()
>>>
>>> # Load from URL
>>> grid_data = load_grid_data('https://example.com/grid_data.npz')
>>>
>>> # Load specific default dataset
>>> grid_data = load_grid_data(dataset_key='grid_2')

src.canns.analyzer.experimental_data.load_roi_data(source=None)

Load ROI data for 1D CANN analysis.

Parameters:

source (str, Path, or None) – Data source. Can be: - URL string: downloads and loads from URL - Path: loads from local file - None: uses default CANNs dataset

Returns:

ROI data array if successful, None otherwise.

Return type:

ndarray or None

Examples

>>> # Load default dataset
>>> roi_data = load_roi_data()
>>>
>>> # Load from URL
>>> roi_data = load_roi_data('https://example.com/roi_data.txt')
>>>
>>> # Load from local file
>>> roi_data = load_roi_data('./my_roi_data.txt')

src.canns.analyzer.experimental_data.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.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.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.validate_grid_data(data)

Validate grid data format for 2D CANN analysis.

Parameters:

data (dict) – Grid data dictionary.

Returns:

True if data is valid, False otherwise.

Return type:

bool

src.canns.analyzer.experimental_data.validate_roi_data(data)

Validate ROI data format for 1D CANN analysis.

Parameters:

data (ndarray) – ROI data array.

Returns:

True if data is valid, False otherwise.

Return type:

bool