Skip to content

Release v0.14.0: ASA GUI Application and Cell Classification Module

Choose a tag to compare

View all tags
@Routhleck Routhleck released this 28 Jan 05:32
· 41 commits to master since this release
v0.14.0
8aeee47

Release v0.14.0: ASA GUI Application and Cell Classification Module

What's New

🎨 ASA GUI Application - Interactive Desktop Interface for Data Analysis

  • Complete PySide6-based graphical user interface for ASA pipeline with 10+ analysis modes
  • Light/dark theme support with modern, polished UI design
  • Drag-and-drop file loading, real-time progress tracking, and interactive result visualization
  • Comprehensive Chinese tutorial with screenshots for all analysis modes

🔬 Cell Classification Module - Grid Cells and Head Direction Analysis

  • Production-ready algorithms for grid cell and head direction cell classification
  • Gridness score computation, spatial rate map analysis, and autocorrelogram-based features
  • Leiden clustering for grid module identification
  • Complete utilities for circular statistics, correlation, geometry, and image processing

🔧 API Refinements - 1D/2D Separation for Clarity

  • Explicit 1D/2D function variants in cohospace and path analysis modules
  • Improved clarity and type safety for spatial analysis workflows

Major Features / Key Changes

🎨 ASA GUI Application (PR #91)

A complete desktop application for ASA (Attractor State Analysis) pipeline with modern UI and comprehensive analysis capabilities.

Core Features:

  • 10+ Analysis Modes: CohoMap, CohoSpace, Decode, Firing Rate, FRM, Grid Score, Path Compare, TDA, and Batch processing
  • Modern UI: Light/dark theme switching, drop shadows, card-based layouts, and responsive design
  • Interactive Workflow: Drag-and-drop file loading, parameter forms with validation, real-time progress bars
  • Result Visualization: Built-in image viewer, external viewer support, and organized result directories
  • CLI Entry Point: Launch with canns-gui or python -m canns.pipeline.asa_gui

Technical Architecture:

  • MVC pattern with controllers, models, and views
  • Background worker threads for non-blocking analysis
  • State management with caching and job tracking
  • Modular analysis modes with base class abstraction
# Launch the GUI application
from canns.pipeline.asa_gui import run_gui
run_gui()

# Or from command line
# $ canns-gui

New Components:

  • src/canns/pipeline/asa_gui/ - Complete GUI application package
  • docs/zh/3_full_detail_tutorials/04_pipeline/03_asa_gui.rst - Comprehensive tutorial
  • 12 new documentation images showing each analysis mode

🔬 Cell Classification Module (PR #89)

Production-ready algorithms for identifying and analyzing grid cells and head direction cells from neural recordings.

Grid Cell Analysis:

  • Gridness Score: Compute gridness using autocorrelogram rotation analysis
  • Spatial Rate Maps: Generate 2D firing rate maps with Gaussian smoothing
  • Grid Module Clustering: Identify grid modules using Leiden clustering on autocorrelogram features
  • Visualization: Plot rate maps, autocorrelograms, and grid scores
from canns.analyzer.data.cell_classification import (
    compute_gridness_score,
    compute_spatial_rate_map,
    identify_grid_modules_and_stats
)

# Compute gridness score for a neuron
rate_map = compute_spatial_rate_map(spike_times, x_pos, y_pos, arena_size=100)
gridness, rotation_analysis = compute_gridness_score(rate_map)

# Identify grid modules across population
modules = identify_grid_modules_and_stats(
    spike_trains, positions, arena_size=100, resolution=50
)

Head Direction Cell Analysis:

  • Directional Tuning: Compute head direction tuning curves
  • Mean Vector Length: Quantify directional selectivity
  • Rayleigh Test: Statistical test for directional tuning
  • Visualization: Polar plots and tuning curve displays

Utilities:

  • Circular Statistics: Mean direction, vector length, Rayleigh test, circular correlation
  • Correlation: Spatial autocorrelation, cross-correlation with rotation
  • Geometry: Distance calculations, boundary detection, field analysis
  • Image Processing: Gaussian smoothing, peak detection, rotation operations

New Components:

  • src/canns/analyzer/data/cell_classification/ - Complete cell classification package
  • examples/cell_classification/ - Example scripts for grid score and classification
  • docs/zh/examples/02_data_analysis/04_cell_classification.ipynb - Tutorial notebook

🔧 API Refactoring - 1D/2D Separation (PR #89)

Improved API clarity by splitting cohospace and path functions into explicit 1D/2D variants.

Breaking Changes:

  • plot_cohospace_trajectory() → plot_cohospace_trajectory_1d() / plot_cohospace_trajectory_2d()
  • align_coords_to_position() → align_coords_to_position_1d() / align_coords_to_position_2d()
  • compare_paths() → compare_paths_1d() / compare_paths_2d()

Migration Guide:

# Old API (deprecated)
from canns.analyzer.data.asa import plot_cohospace_trajectory
plot_cohospace_trajectory(coords, positions)  # Ambiguous dimensionality

# New API (explicit)
from canns.analyzer.data.asa import plot_cohospace_trajectory_1d, plot_cohospace_trajectory_2d
plot_cohospace_trajectory_1d(coords, positions)  # Clear 1D usage
plot_cohospace_trajectory_2d(coords, positions)  # Clear 2D usage

Benefits:

  • Explicit dimensionality prevents confusion
  • Better type hints and IDE support
  • Clearer documentation and examples

📖 Documentation Enhancements (PR #90)

  • ASA Core References: Added comprehensive references section to ASA documentation
  • GUI Tutorial: Complete Chinese tutorial for ASA GUI with 12 screenshots
  • Cell Classification Tutorial: New notebook demonstrating grid cell and HD cell analysis
  • Updated Examples: Refactored example scripts to use new 1D/2D API

New Dependencies

  • PySide6 (>=6.8.1): Qt6 bindings for GUI application (optional, install with pip install canns[gui])
  • scikit-image (>=0.24.0): Image processing for spatial analysis
  • h5py (>=3.12.1): HDF5 file support for MATLAB data loading
  • igraph (>=0.11.8): Graph algorithms for grid module clustering
  • leidenalg (>=0.10.2): Leiden clustering algorithm

Breaking Changes

ASA API - 1D/2D Function Separation:

  • Functions in canns.analyzer.data.asa.cohospace and canns.analyzer.data.asa.path have been split into explicit 1D/2D variants
  • Old function names are deprecated and will be removed in v0.15.0
  • Update your code to use the new _1d or _2d suffixed functions

Technical Improvements

  • Optimized Embedding: Improved embed_spike_trains binning and smoothing performance
  • TDA Standardization: Added standardize option to TDAConfig for normalized persistence diagrams
  • Code Quality: Modernized type annotations to Python 3.10+ syntax across cell classification modules
  • Import Consistency: Standardized import ordering and usage throughout ASA GUI

Use Cases

  • Experimentalists: Use the GUI application for interactive data analysis without writing code
  • Computational Neuroscientists: Leverage cell classification algorithms for grid cell and HD cell identification
  • Method Developers: Build on the modular GUI architecture for custom analysis modes
  • Students: Learn spatial navigation analysis through comprehensive tutorials and examples

Files Added/Modified

New Packages:

  • src/canns/pipeline/asa_gui/ - Complete GUI application (40+ files)
  • src/canns/analyzer/data/cell_classification/ - Cell classification module (15+ files)

Key Files:

  • pyproject.toml: Added GUI optional dependencies and canns-gui entry point
  • docs/zh/3_full_detail_tutorials/04_pipeline/03_asa_gui.rst: GUI tutorial
  • docs/zh/examples/02_data_analysis/04_cell_classification.ipynb: Cell classification tutorial
  • examples/cell_classification/: New example scripts
  • images/logo.ico: Application icon

Full Changelog: v0.13.2...v0.14.0

Assets 2
Loading