Skip to content

Release v0.13.0: ASA Pipeline with Terminal UI and Experimental Data Analysis

Choose a tag to compare

View all tags
@Routhleck Routhleck released this 26 Jan 02:53
· 53 commits to master since this release
v0.13.0
ddc896e

What's New

🔬 Attractor State Analysis (ASA) Pipeline with Interactive Terminal UI

  • Brand new Textual-based terminal user interface for comprehensive ASA analysis
  • Complete experimental data analysis toolkit with cohomological methods, TDA, and advanced decoding
  • Research paper draft documenting the CANNs toolkit design and motivation

📊 Production-Ready Experimental Data Analysis

  • Unified ASA module with cohospace alignment, topological data analysis, and circular coordinate decoding
  • New example scripts for firing field maps, path comparison, and TDA visualization
  • Modern Python type hints and improved error handling throughout

Major Features / Key Changes

🔬 ASA Pipeline with Textual TUI (PR #84)

  • Interactive Terminal Interface: New canns.pipeline.asa module with a full-featured TUI for ASA analysis
  • Advanced Analysis Controls: Granular parameter controls for decode, PathCompare, and CohoSpace operations
  • Smart Result Management: Dataset-specific result directories with image preview and log file handling
  • Easy Access: Install and run with pip install canns then canns-tui
# Install CANNs
pip install canns

# Launch the ASA TUI
canns-tui

# Or use the Python module directly
python -m canns.pipeline.asa

Key TUI Features:

  • File browser with image preview support
  • Real-time analysis progress tracking
  • Configurable preprocessing parameters (speed filter, resolution, etc.)
  • Support for stopping running analyses
  • External image viewer integration

📊 Experimental Data Analysis Module (PR #83)

  • ASA Submodule: New canns.analyzer.data.asa with comprehensive analysis tools
  • Cohomological Analysis: CohoMap and CohoSpace alignment for attractor state analysis
  • Advanced Decoding: Multiple circular coordinate decoding methods with automatic filtering
  • Topological Data Analysis: Persistent homology, Betti curves, and shuffle analysis
  • Embedding Tools: PCA, UMAP, and custom embedding methods for dimensionality reduction
  • Comprehensive Plotting: Specialized plotting functions for all ASA analysis types
from canns.analyzer.data.asa import (
    decode_circular_coordinates_multi,
    plot_cohomap_multi,
    compute_persistent_homology,
    plot_path_compare
)

# Decode circular coordinates from spike data
coords = decode_circular_coordinates_multi(
    spike_data, 
    n_points=1000,
    version=2
)

# Plot cohomological map
plot_cohomap_multi(coords, spike_data, save_path="cohomap.png")

# Compute persistent homology
ph_result = compute_persistent_homology(coords)

New Example Scripts:

  • examples/experimental_data_analysis/cohomap.py - Cohomological map visualization
  • examples/experimental_data_analysis/cohospace.py - CohoSpace alignment analysis
  • examples/experimental_data_analysis/firing_field_map.py - Firing field visualization
  • examples/experimental_data_analysis/path_compare.py - Path comparison analysis
  • examples/experimental_data_analysis/tda_vis.py - TDA visualization

📖 Research Paper and Documentation

  • Paper Draft: Added paper.md describing CANNs toolkit motivation, design, and impact
  • Comprehensive Bibliography: paper.bib with 700+ lines of references
  • Architecture Diagram: Visual representation of software design in images/architecture.png
  • Automated PDF Build: GitHub Actions workflow for draft PDF generation

New Components Added

ASA Analysis Module:

  • src/canns/analyzer/data/asa/cohospace.py - CohoSpace alignment (905 lines)
  • src/canns/analyzer/data/asa/decode.py - Circular coordinate decoding (448 lines)
  • src/canns/analyzer/data/asa/embedding.py - Dimensionality reduction (269 lines)
  • src/canns/analyzer/data/asa/tda.py - Topological data analysis (901 lines)
  • src/canns/analyzer/data/asa/plotting.py - Specialized plotting (1,276 lines)
  • src/canns/analyzer/data/asa/fr.py - Firing rate utilities (439 lines)
  • src/canns/analyzer/data/asa/path.py - Path analysis (389 lines)
  • src/canns/analyzer/data/asa/filters.py - Data filtering (208 lines)
  • src/canns/analyzer/data/asa/config.py - Configuration classes (246 lines)

ASA TUI Application:

  • src/canns/pipeline/asa/app.py - Main TUI application (1,000 lines)
  • src/canns/pipeline/asa/runner.py - Analysis runner (1,095 lines)
  • src/canns/pipeline/asa/screens.py - UI screens (215 lines)
  • src/canns/pipeline/asa/state.py - Application state (248 lines)
  • src/canns/pipeline/asa/widgets.py - Custom widgets (233 lines)
  • src/canns/pipeline/asa/styles.tcss - TUI styling (221 lines)

Legacy Module:

  • src/canns/analyzer/data/legacy/ - Moved CANN1D and CANN2D experimental analysis

Breaking Changes

  • Removed: src/canns/pipeline/theta_sweep.py module
  • Removed: examples/pipeline/advanced_theta_sweep_pipeline.py
  • Removed: examples/pipeline/theta_sweep_from_external_data.py
  • Moved: Legacy experimental analysis scripts to examples/experimental_data_analysis/legacy/

Migration Guide:

  • The theta sweep functionality is still available through the core models and visualization modules
  • For experimental data analysis, use the new canns.analyzer.data.asa module instead of legacy scripts
  • Legacy CANN1D/CANN2D experimental analysis is available in canns.analyzer.data.legacy

Technical Improvements

  • Modern Type Hints: Updated to PEP 604 syntax (dict | None instead of Optional[Dict])
  • Error Handling: Improved validation and error messages in decoding functions
  • Auto-filtering: Automatic activity data filtering when lengths mismatch in cohospace alignment
  • Preprocessing Config: Consistent merging of user and default configuration values
  • Test Coverage: New comprehensive test suite for ASA experimental data analysis

New Dependencies

  • textual: Terminal user interface framework for the ASA TUI
  • Additional dependencies: Updated in uv.lock for ASA functionality

Technical Notes

  • ASA TUI requires a terminal with color support and minimum dimensions for optimal display
  • Results are stored in dataset-specific subdirectories under a Results/ folder
  • Image preview supports common formats (PNG, JPG, etc.) and can open in external viewers
  • Preprocessing parameters include speed filtering, resolution, and spatial binning options
  • TDA analysis uses persistent homology with configurable parameters for robustness

Files Changed Summary

  • 53 files changed: 10,570 insertions(+), 1,637 deletions(-)
  • Major additions: ASA analysis module (~5,000 lines), ASA TUI (~3,000 lines)
  • Documentation: paper.md, paper.bib, architecture.png
  • Examples: 6 new experimental data analysis scripts

Full Changelog: v0.12.7...v0.13.0

Assets 2
Loading