canns 0.13.0__py3-none-any.whl → 0.13.2__py3-none-any.whl

canns/analyzer/data/asa/__init__.py

@@ -18,6 +18,12 @@ from .config import (
 )
 from .decode import decode_circular_coordinates, decode_circular_coordinates_multi
 from .embedding import embed_spike_trains
+from .fly_roi import (
+    BumpFitsConfig,
+    CANN1DPlotConfig,
+    create_1d_bump_animation,
+    roi_bump_fits,
+)
 from .fr import (
     FRMResult,
     compute_fr_heatmap_matrix,
@@ -60,6 +66,10 @@ __all__ = [
     "plot_cohomap_multi",
     "plot_3d_bump_on_torus",
     "plot_2d_bump_on_manifold",
+    "BumpFitsConfig",
+    "CANN1DPlotConfig",
+    "create_1d_bump_animation",
+    "roi_bump_fits",
     "compute_fr_heatmap_matrix",
     "save_fr_heatmap_png",
     "FRMResult",

canns/analyzer/data/asa/decode.py

@@ -33,7 +33,7 @@ def decode_circular_coordinates(
     real_of : bool
         Whether the experiment is open-field (controls box coordinate handling).
     save_path : str, optional
-        Path to save decoding results. Defaults to ``Results/spikes_decoding.npz``.
+        Path to save decoding results. If ``None``, results are not saved.
 
     Returns
     -------
@@ -174,13 +174,12 @@ def decode_circular_coordinates(
         "centsinall": centsinall,
     }
 
-    # Save results
-    if save_path is None:
-        os.makedirs("Results", exist_ok=True)
-        save_path = "Results/spikes_decoding.npz"
-
-    os.makedirs(os.path.dirname(save_path), exist_ok=True)
-    np.savez_compressed(save_path, **results)
+    # Save results (only when requested)
+    if save_path is not None:
+        save_dir = os.path.dirname(save_path)
+        if save_dir:
+            os.makedirs(save_dir, exist_ok=True)
+        np.savez_compressed(save_path, **results)
 
     return results
 
@@ -264,13 +263,12 @@ def decode_circular_coordinates1(
         "centsinall": centsinall,
     }
 
-    # Save results
-    if save_path is None:
-        os.makedirs("Results", exist_ok=True)
-        save_path = "Results/spikes_decoding.npz"
-
-    os.makedirs(os.path.dirname(save_path), exist_ok=True)
-    np.savez_compressed(save_path, **results)
+    # Save results (only when requested)
+    if save_path is not None:
+        save_dir = os.path.dirname(save_path)
+        if save_dir:
+            os.makedirs(save_dir, exist_ok=True)
+        np.savez_compressed(save_path, **results)
 
     return results
 
@@ -291,7 +289,7 @@ def decode_circular_coordinates_multi(
     spike_data : dict
         Spike data dictionary containing ``'spike'``, ``'t'`` and optionally ``'x'``/``'y'``.
     save_path : str, optional
-        Path to save decoding results. Defaults to ``Results/spikes_decoding.npz``.
+        Path to save decoding results. If ``None``, results are not saved.
     num_circ : int
         Number of H1 cocycles/circular coordinates to decode.
 
@@ -383,11 +381,10 @@ def decode_circular_coordinates_multi(
         "centsinall": centsinall,
     }
 
-    if save_path is None:
-        os.makedirs("Results", exist_ok=True)
-        save_path = "Results/spikes_decoding.npz"
-
-        os.makedirs(os.path.dirname(save_path), exist_ok=True)
+    if save_path is not None:
+        save_dir = os.path.dirname(save_path)
+        if save_dir:
+            os.makedirs(save_dir, exist_ok=True)
         np.savez_compressed(save_path, **results)
     return results
 

canns/analyzer/data/{legacy/cann1d.py → asa/fly_roi.py}

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 
 import numpy as np
 from matplotlib import pyplot as plt
-from matplotlib.animation import FuncAnimation, PillowWriter
+from matplotlib.animation import FuncAnimation
 from scipy.optimize import linear_sum_assignment
 from scipy.special import i0
 from tqdm import tqdm
@@ -66,22 +66,6 @@ class BumpFitsConfig:
     random_seed: int | None = None
 
 
-@dataclass
-class AnimationConfig:
-    """Configuration for 1D CANN bump animation."""
-
-    show: bool = False
-    max_height_value: float = 0.5
-    max_width_range: int = 40
-    npoints: int = 300
-    nframes: int | None = None
-    fps: int = 5
-    bump_selection: str = "strongest"
-    show_progress_bar: bool = True
-    repeat: bool = False
-    title: str = "1D CANN Bump Animation"
-
-
 @dataclass
 class CANN1DPlotConfig(PlotConfig):
     """Specialized PlotConfig for CANN1D visualizations."""
@@ -141,9 +125,9 @@ class AnimationError(CANN1DError):
     pass
 
 
-def bump_fits(data, config: BumpFitsConfig | None = None, save_path=None, **kwargs):
+def roi_bump_fits(data, config: BumpFitsConfig | None = None, save_path=None, **kwargs):
     """
-    Fit CANN1D bumps to data using MCMC optimization.
+    Fit CANN1D bumps to ROI data using MCMC optimization.
 
     Parameters:
         data : numpy.ndarray
@@ -318,10 +302,10 @@ def create_1d_bump_animation(
     Parameters:
         fits_data : numpy.ndarray
             Shape (n_fits, 4) array with columns [time, position, amplitude, kappa]
-        config : AnimationConfig, optional
+        config : CANN1DPlotConfig, optional
             Configuration object with all animation parameters
         save_path : str, optional
-            Output path for the generated GIF
+            Output path for the generated animation (e.g. .gif or .mp4)
         **kwargs : backward compatibility parameters
 
     Returns:
@@ -336,6 +320,8 @@ def create_1d_bump_animation(
     for key, value in kwargs.items():
         if hasattr(config, key):
             setattr(config, key, value)
+    if save_path is not None:
+        config.save_path = save_path
 
     try:
         # ==== Smoothing functions ====
@@ -520,7 +506,10 @@ def create_1d_bump_animation(
             fig, update, frames=nframes, init_func=init, blit=use_blitting, repeat=config.repeat
         )
 
-        # Save animation with progress tracking
+        ani = None
+        progress_bar_enabled = getattr(config, "show_progress_bar", True)
+
+        # Save animation with unified backend selection
         if config.save_path:
             # Warn if both saving and showing (causes double rendering)
             if config.show and nframes > 50:
@@ -528,31 +517,95 @@ def create_1d_bump_animation(
 
                 warn_double_rendering(nframes, config.save_path, stacklevel=2)
 
-            if config.show_progress_bar:
-                pbar = tqdm(total=nframes, desc=f"Saving animation to {config.save_path}")
+            from ...visualization.core import (
+                emit_backend_warnings,
+                get_imageio_writer_kwargs,
+                get_matplotlib_writer,
+                select_animation_backend,
+            )
 
-                def progress_callback(current_frame, total_frames):
-                    pbar.update(1)
+            backend_selection = select_animation_backend(
+                save_path=config.save_path,
+                requested_backend=getattr(config, "render_backend", None),
+                check_imageio_plugins=True,
+            )
+            emit_backend_warnings(backend_selection.warnings, stacklevel=2)
+            backend = backend_selection.backend
 
+            if backend == "imageio":
                 try:
-                    ani.save(
-                        config.save_path,
-                        writer=PillowWriter(fps=config.fps),
-                        progress_callback=progress_callback,
-                    )
-                    pbar.close()
-                    print(f"\nAnimation successfully saved to: {config.save_path}")
-                except Exception as e:
-                    pbar.close()
-                    print(f"\nError saving animation: {e}")
-                    raise
-            else:
-                try:
-                    ani.save(config.save_path, writer=PillowWriter(fps=config.fps))
+                    import imageio
+
+                    writer_kwargs, mode = get_imageio_writer_kwargs(config.save_path, config.fps)
+                    with imageio.get_writer(config.save_path, mode=mode, **writer_kwargs) as writer:
+                        frames_iter = range(nframes)
+                        if progress_bar_enabled:
+                            frames_iter = tqdm(
+                                frames_iter,
+                                desc=f"Rendering {config.save_path}",
+                            )
+
+                        init()
+                        for frame_idx in frames_iter:
+                            update(frame_idx)
+                            fig.canvas.draw()
+                            frame = np.asarray(fig.canvas.buffer_rgba())
+                            if frame.shape[-1] == 4:
+                                frame = frame[:, :, :3]
+                            writer.append_data(frame)
+
                     print(f"Animation saved to: {config.save_path}")
                 except Exception as e:
-                    print(f"Error saving animation: {e}")
-                    raise
+                    import warnings
+
+                    warnings.warn(
+                        f"imageio rendering failed: {e}. Falling back to matplotlib.",
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
+                    backend = "matplotlib"
+
+            if backend == "matplotlib":
+                ani = FuncAnimation(
+                    fig,
+                    update,
+                    frames=nframes,
+                    init_func=init,
+                    blit=use_blitting,
+                    repeat=config.repeat,
+                )
+
+                writer = get_matplotlib_writer(config.save_path, fps=config.fps)
+
+                if progress_bar_enabled:
+                    pbar = tqdm(total=nframes, desc=f"Saving to {config.save_path}")
+
+                    def progress_callback(current_frame, total_frames):
+                        pbar.update(1)
+
+                    try:
+                        ani.save(
+                            config.save_path,
+                            writer=writer,
+                            progress_callback=progress_callback,
+                        )
+                        print(f"Animation saved to: {config.save_path}")
+                    finally:
+                        pbar.close()
+                else:
+                    ani.save(config.save_path, writer=writer)
+                    print(f"Animation saved to: {config.save_path}")
+
+        # Create animation object for showing (if not already created)
+        if config.show and ani is None:
+            ani = FuncAnimation(
+                fig,
+                update,
+                frames=nframes,
+                init_func=init,
+                blit=use_blitting,
+                repeat=config.repeat,
+            )
 
         if config.show:
             # Automatically detect Jupyter and display as HTML/JS
@@ -1043,7 +1096,7 @@ def _mcmc(
 
 if __name__ == "__main__":
     data = load_roi_data()
-    bumps, fits, nbump, centrbump = bump_fits(
+    bumps, fits, nbump, centrbump = roi_bump_fits(
         data, n_steps=5000, n_roi=16, save_path=os.path.join(os.getcwd(), "test.npz")
     )
 

canns/analyzer/data/asa/fr.py

@@ -135,7 +135,8 @@ def save_fr_heatmap_png(
         Plot configuration. Use ``config.save_path`` to specify output file.
     **kwargs : Any
         Additional ``imshow`` keyword arguments. ``save_path`` may be provided here
-        as a fallback if not set in ``config``.
+        as a fallback if not set in ``config``. If ``save_path`` is omitted, the
+        figure is only displayed when ``show=True``.
 
     Notes
     -----
@@ -172,11 +173,6 @@ def save_fr_heatmap_png(
         if not config.ylabel:
             config.ylabel = ylabel
 
-    if config.save_path is None:
-        raise ValueError(
-            "save_path must be provided via config.save_path or as a keyword argument."
-        )
-
     config.save_dpi = dpi
 
     M = np.asarray(M)
@@ -391,7 +387,8 @@ def plot_frm(
         Plot configuration. Use ``config.save_path`` to specify output file.
     **kwargs : Any
         Additional ``imshow`` keyword arguments. ``save_path`` may be provided here
-        as a fallback if not set in ``config``.
+        as a fallback if not set in ``config``. If ``save_path`` is omitted, the
+        figure is only displayed when ``show=True``.
 
     Examples
     --------
@@ -423,11 +420,6 @@ def plot_frm(
         if not config.ylabel:
             config.ylabel = "Y bin"
 
-    if config.save_path is None:
-        raise ValueError(
-            "save_path must be provided via config.save_path or as a keyword argument."
-        )
-
     config.save_dpi = dpi
 
     frm = np.asarray(frm)

canns/analyzer/data/asa/plotting.py

@@ -295,8 +295,19 @@ def plot_path_compare(
     ax0 = axes[0]
     ax0.set_title("Physical path (x,y)")
     ax0.set_aspect("equal", "box")
-    ax0.axis("off")
     ax0.plot(x, y, lw=0.9, alpha=0.8)
+    # Keep a visible frame while hiding ticks for a clean path outline.
+    ax0.set_xticks([])
+    ax0.set_yticks([])
+    for spine in ax0.spines.values():
+        spine.set_visible(True)
+    # Add a small padding so the frame doesn't touch the path.
+    x_min, x_max = np.min(x), np.max(x)
+    y_min, y_max = np.min(y), np.max(y)
+    pad_x = (x_max - x_min) * 0.03 if x_max > x_min else 1.0
+    pad_y = (y_max - y_min) * 0.03 if y_max > y_min else 1.0
+    ax0.set_xlim(x_min - pad_x, x_max + pad_x)
+    ax0.set_ylim(y_min - pad_y, y_max + pad_y)
 
     ax1 = axes[1]
     ax1.set_title("Decoded coho path")

canns/data/__init__.py

@@ -16,11 +16,13 @@ from .datasets import (
     get_data_dir,
     get_dataset_path,
     get_huggingface_upload_guide,
+    get_left_right_data_session,
+    get_left_right_npz,
     list_datasets,
     load,
     quick_setup,
 )
-from .loaders import load_grid_data, load_roi_data
+from .loaders import load_grid_data, load_left_right_npz, load_roi_data
 
 __all__ = [
     # Dataset registry and management
@@ -31,6 +33,8 @@ __all__ = [
     "list_datasets",
     "download_dataset",
     "get_dataset_path",
+    "get_left_right_data_session",
+    "get_left_right_npz",
     "quick_setup",
     "get_huggingface_upload_guide",
     # Generic loading
@@ -38,4 +42,5 @@ __all__ = [
     # Specialized loaders
     "load_roi_data",
     "load_grid_data",
+    "load_left_right_npz",
 ]

canns/data/datasets.py

@@ -38,6 +38,7 @@ DEFAULT_DATA_DIR = Path.home() / ".canns" / "data"
 # URLs for datasets on Hugging Face
 HUGGINGFACE_REPO = "canns-team/data-analysis-datasets"
 BASE_URL = f"https://huggingface.co/datasets/{HUGGINGFACE_REPO}/resolve/main/"
+LEFT_RIGHT_DATASET_DIR = "Left_Right_data_of"
 
 # Dataset registry with metadata
 DATASETS = {
@@ -68,6 +69,16 @@ DATASETS = {
         "sha256": None,
         "url": f"{BASE_URL}grid_2.npz",
     },
+    "left_right_data_of": {
+        "filename": LEFT_RIGHT_DATASET_DIR,
+        "description": "ASA type data from Left-Right sweep paper",
+        "size_mb": 604.0,
+        "format": "directory",
+        "usage": "ASA analysis, left-right sweep sessions",
+        "sha256": None,
+        "url": f"{BASE_URL}{LEFT_RIGHT_DATASET_DIR}/",
+        "is_collection": True,
+    },
 }
 
 
@@ -130,7 +141,10 @@ def list_datasets() -> None:
     print("=" * 60)
 
     for key, info in DATASETS.items():
-        status = "Available" if info["url"] else "Setup required"
+        if info.get("is_collection"):
+            status = "Collection (use session getter)"
+        else:
+            status = "Available" if info["url"] else "Setup required"
         print(f"\nDataset: {key}")
         print(f"  File: {info['filename']}")
         print(f"  Size: {info['size_mb']} MB")
@@ -162,6 +176,11 @@ def download_dataset(dataset_key: str, force: bool = False) -> Path | None:
 
     info = DATASETS[dataset_key]
 
+    if info.get("is_collection"):
+        print(f"{dataset_key} is a dataset collection.")
+        print("Use get_left_right_data_session(session_id) to download a session.")
+        return None
+
     if not info["url"]:
         print(f"{dataset_key} not yet available for download")
         print("Please use setup_local_datasets() to copy from local repository")
@@ -213,6 +232,10 @@ def get_dataset_path(dataset_key: str, auto_setup: bool = True) -> Path | None:
     if dataset_key not in DATASETS:
         print(f"Unknown dataset: {dataset_key}")
         return None
+    if DATASETS[dataset_key].get("is_collection"):
+        print(f"{dataset_key} is a dataset collection.")
+        print("Use get_left_right_data_session(session_id) to access session files.")
+        return None
 
     data_dir = get_data_dir()
     filepath = data_dir / DATASETS[dataset_key]["filename"]
@@ -236,6 +259,136 @@ def get_dataset_path(dataset_key: str, auto_setup: bool = True) -> Path | None:
     return None
 
 
+def get_left_right_data_session(
+    session_id: str, auto_download: bool = True, force: bool = False
+) -> dict[str, Path | list[Path] | None] | None:
+    """
+    Download and return files for a Left_Right_data_of session.
+
+    Parameters
+    ----------
+    session_id : str
+        Session folder name, e.g. "24365_2".
+    auto_download : bool
+        Whether to download missing files automatically.
+    force : bool
+        Whether to force re-download of existing files.
+
+    Returns
+    -------
+    dict or None
+        Mapping with keys: "manifest", "full_file", "module_files".
+    """
+    if not session_id:
+        raise ValueError("session_id must be non-empty")
+
+    session_dir = get_data_dir() / LEFT_RIGHT_DATASET_DIR / session_id
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    manifest_filename = f"{session_id}_ASA_manifest.json"
+    manifest_url = f"{BASE_URL}{LEFT_RIGHT_DATASET_DIR}/{session_id}/{manifest_filename}"
+    manifest_path = session_dir / manifest_filename
+
+    if auto_download and (force or not manifest_path.exists()):
+        if not download_file_with_progress(manifest_url, manifest_path):
+            print(f"Failed to download manifest for session {session_id}")
+            return None
+
+    if not manifest_path.exists():
+        print(f"Manifest not found for session {session_id}")
+        return None
+
+    import json
+
+    with open(manifest_path) as f:
+        manifest = json.load(f)
+
+    full_file = manifest.get("full_file")
+    module_files = manifest.get("module_files", [])
+    requested_files: list[str] = []
+
+    if isinstance(full_file, str):
+        requested_files.append(Path(full_file).name)
+
+    if isinstance(module_files, list):
+        for module_file in module_files:
+            if isinstance(module_file, str):
+                requested_files.append(Path(module_file).name)
+
+    # De-duplicate while preserving order
+    seen: set[str] = set()
+    unique_files: list[str] = []
+    for filename in requested_files:
+        if filename and filename not in seen:
+            seen.add(filename)
+            unique_files.append(filename)
+
+    for filename in unique_files:
+        file_path = session_dir / filename
+        if auto_download and (force or not file_path.exists()):
+            file_url = f"{BASE_URL}{LEFT_RIGHT_DATASET_DIR}/{session_id}/{filename}"
+            if not download_file_with_progress(file_url, file_path):
+                print(f"Failed to download {filename} for session {session_id}")
+                return None
+
+    return {
+        "manifest": manifest_path,
+        "full_file": session_dir / Path(full_file).name if isinstance(full_file, str) else None,
+        "module_files": [
+            session_dir / Path(module_file).name
+            for module_file in module_files
+            if isinstance(module_file, str)
+        ],
+    }
+
+
+def get_left_right_npz(
+    session_id: str, filename: str, auto_download: bool = True, force: bool = False
+) -> Path | None:
+    """
+    Download and return a specific Left_Right_data_of NPZ file.
+
+    Parameters
+    ----------
+    session_id : str
+        Session folder name, e.g. "26034_3".
+    filename : str
+        File name inside the session folder, e.g.
+        "26034_3_ASA_mec_gridModule02_n104_cm.npz".
+    auto_download : bool
+        Whether to download the file if missing.
+    force : bool
+        Whether to force re-download of existing files.
+
+    Returns
+    -------
+    Path or None
+        Path to the requested file if available, None otherwise.
+    """
+    if not session_id:
+        raise ValueError("session_id must be non-empty")
+    if not filename:
+        raise ValueError("filename must be non-empty")
+
+    safe_name = Path(filename).name
+    session_dir = get_data_dir() / LEFT_RIGHT_DATASET_DIR / session_id
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    file_path = session_dir / safe_name
+    if file_path.exists() and not force:
+        return file_path
+
+    if not auto_download:
+        return None
+
+    file_url = f"{BASE_URL}{LEFT_RIGHT_DATASET_DIR}/{session_id}/{safe_name}"
+    if not download_file_with_progress(file_url, file_path):
+        print(f"Failed to download {safe_name} for session {session_id}")
+        return None
+
+    return file_path
+
+
 def detect_file_type(filepath: Path) -> str:
     """Detect file type based on extension."""
     suffix = filepath.suffix.lower()

canns/data/loaders.py

@@ -211,6 +211,43 @@ def load_grid_data(
             return None
 
 
+def load_left_right_npz(
+    session_id: str, filename: str, auto_download: bool = True, force: bool = False
+) -> dict[str, Any] | None:
+    """
+    Load a Left_Right_data_of NPZ file.
+
+    Parameters
+    ----------
+    session_id : str
+        Session folder name, e.g. "26034_3".
+    filename : str
+        File name inside the session folder.
+    auto_download : bool
+        Whether to download the file if missing.
+    force : bool
+        Whether to force re-download of existing files.
+
+    Returns
+    -------
+    dict or None
+        Dictionary of npz arrays if successful, None otherwise.
+    """
+    try:
+        path = _datasets.get_left_right_npz(
+            session_id=session_id,
+            filename=filename,
+            auto_download=auto_download,
+            force=force,
+        )
+        if path is None:
+            return None
+        return dict(np.load(path, allow_pickle=True))
+    except Exception as e:
+        print(f"Failed to load Left-Right npz {session_id}/{filename}: {e}")
+        return None
+
+
 def validate_roi_data(data: np.ndarray) -> bool:
     """
     Validate ROI data format for 1D CANN analysis.

canns/pipeline/__init__.py

@@ -1,17 +1,9 @@
-"""
-CANNs Pipeline Module
+"""CANNs pipeline entrypoints."""
 
-High-level pipelines for common analysis workflows, designed to make CANN models
-accessible to experimental researchers without requiring detailed knowledge of
-the underlying implementations.
-"""
-
-from ._base import Pipeline
 from .asa import ASAApp
 from .asa import main as asa_main
+from .gallery import GalleryApp
+from .gallery import main as gallery_main
+from .launcher import main as launcher_main
 
-__all__ = [
-    "Pipeline",
-    "ASAApp",
-    "asa_main",
-]
+__all__ = ["ASAApp", "asa_main", "GalleryApp", "gallery_main", "launcher_main"]

canns/pipeline/__main__.py

@@ -0,0 +1,6 @@
+"""Run the canns TUI launcher as a module."""
+
+from .launcher import main
+
+if __name__ == "__main__":
+    main()

canns/pipeline/asa/widgets.py

@@ -3,10 +3,10 @@
 This module provides reusable UI components for the ASA analysis interface.
 """
 
-from pathlib import Path
 import os
 import subprocess
 import sys
+from pathlib import Path
 
 from rich.ansi import AnsiDecoder
 from rich.text import Text