canns 0.13.1__py3-none-any.whl → 0.14.0__py3-none-any.whl

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,21 @@
-"""
-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
+
+try:
+    from .asa_gui import ASAGuiApp
+except Exception:  # PySide6 may be missing
+    ASAGuiApp = None  # type: ignore
 
 __all__ = [
-    "Pipeline",
     "ASAApp",
     "asa_main",
+    "GalleryApp",
+    "gallery_main",
+    "launcher_main",
+    "ASAGuiApp",
 ]

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/runner.py

@@ -496,6 +496,7 @@ class PipelineRunner:
             do_shuffle=params.get("do_shuffle", False),
             num_shuffles=params.get("num_shuffles", 1000),
             progress_bar=False,
+            standardize=False,
         )
 
         log_callback("Computing persistent homology...")
@@ -682,9 +683,11 @@ class PipelineRunner:
     ) -> dict[str, Path]:
         """Run path comparison visualization."""
         from canns.analyzer.data.asa import (
-            align_coords_to_position,
+            align_coords_to_position_1d,
+            align_coords_to_position_2d,
             apply_angle_scale,
-            plot_path_compare,
+            plot_path_compare_1d,
+            plot_path_compare_2d,
         )
         from canns.analyzer.data.asa.path import (
             find_coords_matrix,
@@ -731,7 +734,7 @@ class PipelineRunner:
             idx = max(0, dim - 1)
             if idx >= coords_raw.shape[1]:
                 raise ProcessingError(f"dim out of range for coords shape {coords_raw.shape}")
-            coords2 = coords_raw[:, [idx]]
+            coords1 = coords_raw[:, idx]
         else:
             idx1 = max(0, dim1 - 1)
             idx2 = max(0, dim2 - 1)
@@ -753,15 +756,26 @@ class PipelineRunner:
             times_box = None
 
         log_callback("Aligning decoded coordinates to position...")
-        t_use, x_use, y_use, coords_use, _ = align_coords_to_position(
-            t_full=t_full,
-            x_full=x_full,
-            y_full=y_full,
-            coords2=coords2,
-            use_box=use_box,
-            times_box=times_box,
-            interp_to_full=interp_full,
-        )
+        if dim_mode == "1d":
+            t_use, x_use, y_use, coords_use, _ = align_coords_to_position_1d(
+                t_full=t_full,
+                x_full=x_full,
+                y_full=y_full,
+                coords1=coords1,
+                use_box=use_box,
+                times_box=times_box,
+                interp_to_full=interp_full,
+            )
+        else:
+            t_use, x_use, y_use, coords_use, _ = align_coords_to_position_2d(
+                t_full=t_full,
+                x_full=x_full,
+                y_full=y_full,
+                coords2=coords2,
+                use_box=use_box,
+                times_box=times_box,
+                interp_to_full=interp_full,
+            )
         scale = str(angle_scale) if str(angle_scale) in {"rad", "deg", "unit", "auto"} else "rad"
         coords_use = apply_angle_scale(coords_use, scale)
 
@@ -809,8 +823,12 @@ class PipelineRunner:
             return {"path_compare": out_path}
 
         log_callback("Generating path comparison...")
-        config = PlotConfigs.path_compare(show=False, save_path=str(out_path))
-        plot_path_compare(x_use, y_use, coords_use, config=config)
+        if dim_mode == "1d":
+            config = PlotConfigs.path_compare_1d(show=False, save_path=str(out_path))
+            plot_path_compare_1d(x_use, y_use, coords_use, config=config)
+        else:
+            config = PlotConfigs.path_compare_2d(show=False, save_path=str(out_path))
+            plot_path_compare_2d(x_use, y_use, coords_use, config=config)
 
         self._write_cache_meta(self._stage_cache_path(out_dir), {"hash": stage_hash})
         return {"path_compare": out_path}
@@ -820,9 +838,12 @@ class PipelineRunner:
     ) -> dict[str, Path]:
         """Run cohomology space visualization."""
         from canns.analyzer.data.asa import (
-            plot_cohospace_neuron,
-            plot_cohospace_population,
-            plot_cohospace_trajectory,
+            plot_cohospace_neuron_1d,
+            plot_cohospace_neuron_2d,
+            plot_cohospace_population_1d,
+            plot_cohospace_population_2d,
+            plot_cohospace_trajectory_1d,
+            plot_cohospace_trajectory_2d,
         )
         from canns.analyzer.data.asa.cohospace import (
             plot_cohospace_neuron_skewed,
@@ -865,8 +886,7 @@ class PipelineRunner:
                 idx = max(0, dim - 1)
                 if idx >= arr.shape[1]:
                     raise ProcessingError(f"dim out of range for coords shape {arr.shape}")
-                one = arr[:, [idx]]
-                return np.hstack([one, np.zeros_like(one)])
+                return arr[:, idx]
             idx1 = max(0, dim1 - 1)
             idx2 = max(0, dim2 - 1)
             if idx1 >= arr.shape[1] or idx2 >= arr.shape[1]:
@@ -915,15 +935,29 @@ class PipelineRunner:
 
         log_callback("Plotting cohomology space trajectory...")
         traj_path = out_dir / "cohospace_trajectory.png"
-        traj_cfg = PlotConfigs.cohospace_trajectory(show=False, save_path=str(traj_path))
-        plot_cohospace_trajectory(coords=coords2, times=None, subsample=subsample, config=traj_cfg)
+        if dim_mode == "1d":
+            traj_cfg = PlotConfigs.cohospace_trajectory_1d(show=False, save_path=str(traj_path))
+            plot_cohospace_trajectory_1d(
+                coords=coords2,
+                times=None,
+                subsample=subsample,
+                config=traj_cfg,
+            )
+        else:
+            traj_cfg = PlotConfigs.cohospace_trajectory_2d(show=False, save_path=str(traj_path))
+            plot_cohospace_trajectory_2d(
+                coords=coords2,
+                times=None,
+                subsample=subsample,
+                config=traj_cfg,
+            )
         artifacts["trajectory"] = traj_path
 
         neuron_id = params.get("neuron_id", None)
         if neuron_id is not None and view in {"both", "single"}:
             log_callback(f"Plotting neuron {neuron_id}...")
             neuron_path = out_dir / f"cohospace_neuron_{neuron_id}.png"
-            if unfold == "skew":
+            if unfold == "skew" and dim_mode != "1d":
                 plot_cohospace_neuron_skewed(
                     coords=coordsbox2,
                     activity=activity,
@@ -936,22 +970,37 @@ class PipelineRunner:
                     n_tiles=skew_tiles,
                 )
             else:
-                neuron_cfg = PlotConfigs.cohospace_neuron(show=False, save_path=str(neuron_path))
-                plot_cohospace_neuron(
-                    coords=coordsbox2,
-                    activity=activity,
-                    neuron_id=int(neuron_id),
-                    mode=mode,
-                    top_percent=top_percent,
-                    config=neuron_cfg,
-                )
+                if dim_mode == "1d":
+                    neuron_cfg = PlotConfigs.cohospace_neuron_1d(
+                        show=False, save_path=str(neuron_path)
+                    )
+                    plot_cohospace_neuron_1d(
+                        coords=coordsbox2,
+                        activity=activity,
+                        neuron_id=int(neuron_id),
+                        mode=mode,
+                        top_percent=top_percent,
+                        config=neuron_cfg,
+                    )
+                else:
+                    neuron_cfg = PlotConfigs.cohospace_neuron_2d(
+                        show=False, save_path=str(neuron_path)
+                    )
+                    plot_cohospace_neuron_2d(
+                        coords=coordsbox2,
+                        activity=activity,
+                        neuron_id=int(neuron_id),
+                        mode=mode,
+                        top_percent=top_percent,
+                        config=neuron_cfg,
+                    )
             artifacts["neuron"] = neuron_path
 
         if view in {"both", "population"}:
             log_callback("Plotting population activity...")
             pop_path = out_dir / "cohospace_population.png"
             neuron_ids = list(range(activity.shape[1]))
-            if unfold == "skew":
+            if unfold == "skew" and dim_mode != "1d":
                 plot_cohospace_population_skewed(
                     coords=coords2,
                     activity=activity,
@@ -964,15 +1013,30 @@ class PipelineRunner:
                     n_tiles=skew_tiles,
                 )
             else:
-                pop_cfg = PlotConfigs.cohospace_population(show=False, save_path=str(pop_path))
-                plot_cohospace_population(
-                    coords=coords2,
-                    activity=activity,
-                    neuron_ids=neuron_ids,
-                    mode=mode,
-                    top_percent=top_percent,
-                    config=pop_cfg,
-                )
+                if dim_mode == "1d":
+                    pop_cfg = PlotConfigs.cohospace_population_1d(
+                        show=False, save_path=str(pop_path)
+                    )
+                    plot_cohospace_population_1d(
+                        coords=coords2,
+                        activity=activity,
+                        neuron_ids=neuron_ids,
+                        mode=mode,
+                        top_percent=top_percent,
+                        config=pop_cfg,
+                    )
+                else:
+                    pop_cfg = PlotConfigs.cohospace_population_2d(
+                        show=False, save_path=str(pop_path)
+                    )
+                    plot_cohospace_population_2d(
+                        coords=coords2,
+                        activity=activity,
+                        neuron_ids=neuron_ids,
+                        mode=mode,
+                        top_percent=top_percent,
+                        config=pop_cfg,
+                    )
             artifacts["population"] = pop_path
 
         self._write_cache_meta(meta_path, {"hash": stage_hash})

canns/pipeline/asa_gui/__init__.py

@@ -0,0 +1,68 @@
+"""ASA GUI - PySide6-based graphical interface for Attractor Structure Analyzer."""
+
+from __future__ import annotations
+
+import sys
+import os
+import importlib.util
+
+__all__ = ["main", "ASAGuiApp"]
+
+_pyside6_missing = importlib.util.find_spec("PySide6") is None
+if _pyside6_missing:
+    if "pytest" in sys.modules or "PYTEST_CURRENT_TEST" in os.environ:
+        try:  # pragma: no cover - only used in CI/test runs
+            import pytest
+
+            pytest.skip("PySide6 is not installed; skipping asa_gui module.", allow_module_level=True)
+        except Exception:
+            pass
+
+
+def main() -> int:
+    """Entry point for canns-gui command."""
+    try:
+        from PySide6.QtWidgets import QApplication
+    except ImportError as e:
+        print(
+            "PySide6 is not installed. Please install with: pip install canns[gui]",
+            file=sys.stderr,
+        )
+        raise SystemExit(1) from e
+
+    from pathlib import Path
+
+    from PySide6.QtGui import QGuiApplication, QIcon
+
+    from .app import ASAGuiApp
+
+    app = QApplication(sys.argv)
+    app.setOrganizationName("canns")
+    app.setApplicationName("ASA GUI")
+    app.setApplicationDisplayName("ASA GUI")
+    QGuiApplication.setApplicationDisplayName("ASA GUI")
+
+    base = Path(__file__).resolve().parents[4] / "images"
+    logo_path = base / "logo_256.png"
+    if not logo_path.exists():
+        logo_path = base / "logo.svg"
+    if not logo_path.exists():
+        logo_path = base / "logo.ico"
+    icon = QIcon(str(logo_path)) if logo_path.exists() else QIcon()
+    if not icon.isNull():
+        app.setWindowIcon(icon)
+
+    window = ASAGuiApp()
+    if not icon.isNull():
+        window.setWindowIcon(icon)
+    window.show()
+    return app.exec()
+
+
+# Lazy import for ASAGuiApp
+def __getattr__(name: str):
+    if name == "ASAGuiApp":
+        from .app import ASAGuiApp
+
+        return ASAGuiApp
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

canns/pipeline/asa_gui/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m canns.pipeline.asa_gui."""
+
+from . import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

canns/pipeline/asa_gui/analysis_modes/__init__.py

@@ -0,0 +1,42 @@
+"""Analysis modes for ASA GUI."""
+
+from .base import AbstractAnalysisMode
+from .batch_mode import BatchMode
+from .cohomap_mode import CohoMapMode
+from .cohospace_mode import CohoSpaceMode
+from .decode_mode import DecodeMode
+from .fr_mode import FRMode
+from .frm_mode import FRMMode
+from .gridscore_mode import GridScoreInspectMode, GridScoreMode
+from .pathcompare_mode import PathCompareMode
+from .tda_mode import TDAMode
+
+__all__ = [
+    "AbstractAnalysisMode",
+    "BatchMode",
+    "CohoMapMode",
+    "CohoSpaceMode",
+    "DecodeMode",
+    "FRMode",
+    "FRMMode",
+    "GridScoreMode",
+    "GridScoreInspectMode",
+    "PathCompareMode",
+    "TDAMode",
+    "get_analysis_modes",
+]
+
+
+def get_analysis_modes() -> list[AbstractAnalysisMode]:
+    return [
+        TDAMode(),
+        DecodeMode(),
+        CohoMapMode(),
+        PathCompareMode(),
+        CohoSpaceMode(),
+        FRMode(),
+        FRMMode(),
+        GridScoreMode(),
+        GridScoreInspectMode(),
+        BatchMode(),
+    ]

canns/pipeline/asa_gui/analysis_modes/base.py

@@ -0,0 +1,39 @@
+"""Base classes for analysis modes."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QFormLayout, QWidget
+
+
+class AbstractAnalysisMode(ABC):
+    name: str
+    display_name: str
+
+    @abstractmethod
+    def create_params_widget(self) -> QWidget:
+        """Create and return the parameter editor widget."""
+
+    @abstractmethod
+    def collect_params(self) -> dict[str, Any]:
+        """Collect parameters from the widget into a dict."""
+
+    def apply_preset(self, preset: str) -> None:
+        """Apply preset hints (grid/hd) to parameters."""
+        return None
+
+    def apply_ranges(self, neuron_count: int | None, total_steps: int | None) -> None:
+        """Apply neuron/time ranges based on loaded data."""
+        return None
+
+
+def configure_form_layout(form: QFormLayout) -> None:
+    """Apply consistent spacing/alignment for analysis parameter forms."""
+    form.setLabelAlignment(Qt.AlignRight | Qt.AlignVCenter)
+    form.setFormAlignment(Qt.AlignTop | Qt.AlignLeft)
+    form.setHorizontalSpacing(12)
+    form.setVerticalSpacing(6)
+    form.setFieldGrowthPolicy(QFormLayout.AllNonFixedFieldsGrow)

canns/pipeline/asa_gui/analysis_modes/batch_mode.py

@@ -0,0 +1,21 @@
+"""Batch analysis mode placeholder."""
+
+from __future__ import annotations
+
+from PySide6.QtWidgets import QLabel, QVBoxLayout, QWidget
+
+from .base import AbstractAnalysisMode
+
+
+class BatchMode(AbstractAnalysisMode):
+    name = "batch"
+    display_name = "Batch"
+
+    def create_params_widget(self) -> QWidget:
+        widget = QWidget()
+        layout = QVBoxLayout(widget)
+        layout.addWidget(QLabel("Batch mode parameters will be added here."))
+        return widget
+
+    def collect_params(self) -> dict:
+        return {}