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

canns/analyzer/visualization/core/backend.py

@@ -43,32 +43,21 @@ def select_animation_backend(
     requested_backend: str | None = None,
     check_imageio_plugins: bool = True,
 ) -> BackendSelection:
-    """
-    Select the optimal animation rendering backend.
-
-    This function implements smart backend selection logic:
-    1. If user explicitly requests a backend, validate and use it
-    2. Otherwise, auto-select based on file format and available dependencies
-    3. For GIF: prefer imageio (parallel rendering)
-    4. For MP4: prefer imageio if plugins available, else matplotlib
-    5. Always fallback gracefully with helpful warnings
+    """Select the optimal animation rendering backend.
 
     Args:
-        save_path: Output file path (determines format)
-        requested_backend: User's backend preference ('imageio', 'matplotlib', 'auto', or None)
-        check_imageio_plugins: Whether to verify imageio can write the format
+        save_path: Output file path (determines format).
+        requested_backend: Backend preference ('imageio', 'matplotlib', 'auto', or None).
+        check_imageio_plugins: Whether to verify imageio can write the format.
 
     Returns:
-        BackendSelection with backend choice and metadata
+        BackendSelection with backend choice and metadata.
 
-    Example:
+    Examples:
+        >>> from canns.analyzer.visualization.core.backend import select_animation_backend
         >>> selection = select_animation_backend("output.mp4")
-        >>> print(f"Using {selection.backend}: {selection.reason}")
-        Using imageio: Parallel rendering available for MP4
-
-        >>> selection = select_animation_backend("output.gif", "matplotlib")
-        >>> print(selection.warnings)
-        ['Consider using imageio backend for faster GIF rendering']
+        >>> print(selection.backend in {"imageio", "matplotlib"})
+        True
     """
     warnings_list = []
 
@@ -110,7 +99,7 @@ def select_animation_backend(
             return BackendSelection(
                 backend="imageio",
                 supports_parallel=True,
-                reason=f"User explicitly requested imageio backend",
+                reason="User explicitly requested imageio backend",
                 warnings=[],
             )
 
@@ -277,7 +266,7 @@ def get_multiprocessing_context(prefer_fork: bool = False):
         prefer_fork: Whether to prefer 'fork' over 'spawn' (Linux only)
 
     Returns:
-        Multiprocessing context or None if unavailable
+        Tuple of (multiprocessing context, method name) or (None, None) if unavailable
     """
     import multiprocessing as mp
 
@@ -293,16 +282,16 @@ def get_multiprocessing_context(prefer_fork: bool = False):
                     RuntimeWarning,
                     stacklevel=3,
                 )
-                return mp.get_context("spawn")
-            return mp.get_context("fork")
+                return mp.get_context("spawn"), "spawn"
+            return mp.get_context("fork"), "fork"
         except (RuntimeError, ValueError):
             pass
 
     # Default to spawn (works everywhere)
     try:
-        return mp.get_context("spawn")
+        return mp.get_context("spawn"), "spawn"
     except (RuntimeError, ValueError):
-        return None
+        return None, None
 
 
 def emit_backend_warnings(warnings_list: list[str], stacklevel: int = 2):

canns/analyzer/visualization/core/config.py

@@ -13,13 +13,19 @@ __all__ = ["PlotConfig", "PlotConfigs", "AnimationConfig", "finalize_figure"]
 
 @dataclass
 class PlotConfig:
-    """Unified configuration class for all plotting helpers in ``canns.analyzer``.
+    """Unified configuration class for 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.
+    Examples:
+        >>> import numpy as np
+        >>> from canns.analyzer.visualization import PlotConfig, energy_landscape_1d_static
+        >>>
+        >>> # Dummy input (matches test-style energy_landscape usage)
+        >>> x = np.linspace(0, 1, 5)
+        >>> data_sets = {"u": (x, np.sin(x))}
+        >>> config = PlotConfig(title="Demo", show=False)
+        >>> fig, ax = energy_landscape_1d_static(data_sets, config=config)
+        >>> print(fig is not None)
+        True
     """
 
     title: str = ""
@@ -109,6 +115,21 @@ def finalize_figure(
         rasterize_artists: Optional list of artists to rasterize before saving.
         savefig_kwargs: Extra kwargs merged into ``savefig`` (wins over config).
         always_close: If True, close the figure even when ``config.show`` is True.
+
+    Examples:
+        >>> import numpy as np
+        >>> from matplotlib import pyplot as plt
+        >>> from canns.analyzer.visualization import PlotConfig
+        >>> from canns.analyzer.visualization.core.config import finalize_figure
+        >>>
+        >>> x = np.linspace(0, 1, 5)
+        >>> y = np.sin(x)
+        >>> fig, ax = plt.subplots()
+        >>> _ = ax.plot(x, y)
+        >>> config = PlotConfig(title="Finalize Demo", show=False)
+        >>> finalized = finalize_figure(fig, config)
+        >>> print(finalized is not None)
+        True
     """
 
     from matplotlib import pyplot as plt
@@ -156,14 +177,13 @@ class AnimationConfig:
                                 more than this many frames
 
     Example:
-        >>> # High-quality animation (default)
-        >>> config = AnimationConfig(fps=30, quality='high')
-        >>>
-        >>> # Fast draft mode for quick iteration
-        >>> draft_config = AnimationConfig(quality='draft')  # Auto: 15 FPS, 0.5x resolution
+        >>> from canns.analyzer.visualization import AnimationConfig
         >>>
-        >>> # Force parallel rendering
-        >>> parallel_config = AnimationConfig(use_parallel=True, num_workers=8)
+        >>> # Dummy input representing total frames
+        >>> total_frames = 120
+        >>> config = AnimationConfig(fps=30, quality="high")
+        >>> print(config.fps, total_frames)
+        30 120
     """
 
     fps: int = 30
@@ -186,8 +206,16 @@ class AnimationConfig:
 class PlotConfigs:
     """Collection of commonly used plot configurations.
 
-    These helpers mirror the presets that existed in ``canns.analyzer.visualize``
-    so that callers relying on them continue to receive the exact same defaults.
+    Examples:
+        >>> import numpy as np
+        >>> from canns.analyzer.visualization import PlotConfigs, energy_landscape_1d_static
+        >>>
+        >>> x = np.linspace(0, 1, 5)
+        >>> data_sets = {"u": (x, np.sin(x))}
+        >>> config = PlotConfigs.energy_landscape_1d_static(show=False)
+        >>> fig, ax = energy_landscape_1d_static(data_sets, config=config)
+        >>> print(fig is not None)
+        True
     """
 
     @staticmethod
@@ -240,6 +268,83 @@ class PlotConfigs:
         defaults.update(kwargs)
         return PlotConfig.for_animation(time_steps, **defaults)
 
+    @staticmethod
+    def cohomap(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "CohoMap",
+            "xlabel": "",
+            "ylabel": "",
+            "figsize": (10, 4),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
+    @staticmethod
+    def cohospace_trajectory(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "CohoSpace trajectory",
+            "xlabel": "theta1 (deg)",
+            "ylabel": "theta2 (deg)",
+            "figsize": (6, 6),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
+    @staticmethod
+    def cohospace_neuron(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Neuron activity on coho-space",
+            "xlabel": "Theta 1 (deg)",
+            "ylabel": "Theta 2 (deg)",
+            "figsize": (6, 6),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
+    @staticmethod
+    def cohospace_population(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Population activity on coho-space",
+            "xlabel": "Theta 1 (deg)",
+            "ylabel": "Theta 2 (deg)",
+            "figsize": (6, 6),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
+    @staticmethod
+    def fr_heatmap(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Firing Rate Heatmap",
+            "xlabel": "Time",
+            "ylabel": "Neuron",
+            "figsize": (10, 5),
+            "clabel": "Value",
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
+    @staticmethod
+    def frm(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Firing Rate Map",
+            "xlabel": "X bin",
+            "ylabel": "Y bin",
+            "figsize": (6, 5),
+            "clabel": "Rate",
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
+    @staticmethod
+    def path_compare(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Path Compare",
+            "figsize": (12, 5),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
     @staticmethod
     def raster_plot(mode: str = "block", **kwargs: Any) -> PlotConfig:
         defaults: dict[str, Any] = {

canns/analyzer/visualization/core/jupyter_utils.py

@@ -4,11 +4,15 @@ from __future__ import annotations
 
 
 def is_jupyter_environment() -> bool:
-    """
-    Detect if code is running in a Jupyter notebook environment.
+    """Detect if code is running in a Jupyter notebook environment.
 
     Returns:
-        bool: True if running in Jupyter/IPython notebook, False otherwise.
+        bool: True if running in a Jupyter notebook, False otherwise.
+
+    Examples:
+        >>> from canns.analyzer.visualization.core.jupyter_utils import is_jupyter_environment
+        >>> print(is_jupyter_environment() in {True, False})
+        True
     """
     try:
         # Check if IPython is available and we're in a notebook
@@ -28,23 +32,37 @@ def is_jupyter_environment() -> bool:
 
 
 def display_animation_in_jupyter(animation, format: str = "html5"):
-    """
-    Display a matplotlib animation in Jupyter notebook.
-
-    Performance comparison (100 frames):
-        - html5 (default): 1.3s, 134 KB - Fast encoding, small size, smooth playback
-        - jshtml: 2.6s, 4837 KB - Slower, 36x larger, but works without FFmpeg
+    """Display a matplotlib animation in a Jupyter notebook.
 
     Args:
-        animation: matplotlib.animation.FuncAnimation object
-        format: Display format - 'html5' (default, MP4 video) or 'jshtml' (JS animation)
+        animation: ``matplotlib.animation.FuncAnimation`` instance.
+        format: Display format - ``"html5"`` (default) or ``"jshtml"``.
 
     Returns:
-        IPython.display.HTML object if successful, None otherwise
-
-    Note:
-        'html5' format requires FFmpeg to be installed. If FFmpeg is not available,
-        it will automatically fall back to 'jshtml'.
+        ``IPython.display.HTML`` object if successful, otherwise ``None``.
+
+    Examples:
+        >>> import numpy as np
+        >>> from matplotlib import pyplot as plt
+        >>> from matplotlib.animation import FuncAnimation
+        >>> from canns.analyzer.visualization.core.jupyter_utils import (
+        ...     display_animation_in_jupyter,
+        ...     is_jupyter_environment,
+        ... )
+        >>>
+        >>> x = np.linspace(0, 2 * np.pi, 50)
+        >>> fig, ax = plt.subplots()
+        >>> (line,) = ax.plot([], [])
+        >>>
+        >>> def update(i):
+        ...     line.set_data(x[: i + 1], np.sin(x[: i + 1]))
+        ...     return (line,)
+        >>>
+        >>> anim = FuncAnimation(fig, update, frames=5, interval=50, blit=True)
+        >>> if is_jupyter_environment():
+        ...     _ = display_animation_in_jupyter(anim, format="jshtml")
+        ... print(anim is not None)
+        True
     """
     try:
         from IPython.display import HTML, display

canns/analyzer/visualization/core/rendering.py

@@ -286,51 +286,48 @@ def render_animation_parallel(
     show_progress: bool = True,
     file_format: str | None = None,
 ):
-    """Universal parallel animation renderer for all CANNS animation functions.
-
-    This function provides a unified interface for parallel frame rendering that can be
-    used by ANY animation function in the codebase. It handles:
-    - Format detection (GIF vs MP4)
-    - Parallel vs sequential rendering
-    - Progress bars
-    - Optimal writer selection
+    """Universal parallel animation renderer for analyzer animations.
 
     Args:
         render_frame_func: Callable that renders a single frame:
-                          func(frame_idx, frame_data) -> np.ndarray (H, W, 3 or 4)
-        frame_data: Data needed by render_frame_func (will be passed to workers)
-        num_frames: Total number of frames to render
-        save_path: Output file path (extension determines format)
-        fps: Frames per second
-        num_workers: Number of parallel workers (None = auto-detect)
-        show_progress: Whether to show progress bar (default: True)
-        file_format: Override file format detection ('gif', 'mp4', etc.)
+            ``func(frame_idx, frame_data) -> np.ndarray (H, W, 3 or 4)``.
+        frame_data: Data needed by ``render_frame_func`` (passed to workers).
+        num_frames: Total number of frames to render.
+        save_path: Output file path (extension determines format).
+        fps: Frames per second.
+        num_workers: Number of parallel workers (None = auto-detect).
+        show_progress: Whether to show progress bar.
+        file_format: Override file format detection ('gif', 'mp4', etc.).
 
     Returns:
-        None (saves animation to file)
-
-    Example:
-        >>> def render_my_frame(idx, data):
-        ...     # Your frame rendering logic here
-        ...     return frame_array  # shape (H, W, 3)
+        None (saves animation to file).
+
+    Examples:
+        >>> import numpy as np
+        >>> import tempfile
+        >>> from pathlib import Path
+        >>> from canns.analyzer.visualization.core.rendering import render_animation_parallel
+        >>> from canns.analyzer.visualization.core import rendering
+        >>>
+        >>> def render_frame(idx, data):
+        ...     frame = data[idx]
+        ...     return frame  # (H, W, 3)
         >>>
-        >>> render_animation_parallel(
-        ...     render_my_frame,
-        ...     my_data,
-        ...     num_frames=200,
-        ...     save_path="output.mp4",
-        ...     fps=10
-        ... )
-
-    Performance:
-        - GIF: 3-4x speedup with parallel rendering
-        - MP4: 2-3x speedup (rendering parallel, encoding sequential)
-        - Automatically falls back to sequential for short animations (<50 frames)
+        >>> frames = [np.zeros((10, 10, 3), dtype=np.uint8) for _ in range(2)]
+        >>> # Save a tiny animation if imageio is available
+        >>> if rendering.IMAGEIO_AVAILABLE:
+        ...     with tempfile.TemporaryDirectory() as tmpdir:
+        ...         save_path = Path(tmpdir) / "demo.gif"
+        ...         render_animation_parallel(
+        ...             render_frame, frames, num_frames=2, save_path=str(save_path), fps=2
+        ...         )
+        ...         print("saved")
+        ... else:
+        ...     print("imageio not available")
     """
-    import os
     import multiprocessing as mp
-    import platform
-    from concurrent.futures import ProcessPoolExecutor
+    import os
+
     from tqdm import tqdm
 
     # Detect file format
@@ -489,7 +486,12 @@ def _render_mp4_parallel(
     if IMAGEIO_AVAILABLE:
         # Try imageio first (simpler, more reliable if ffmpeg plugin available)
         try:
-            writer_kwargs = {"fps": fps, "codec": "libx264", "pixelformat": "yuv420p", "bitrate": "5000k"}
+            writer_kwargs = {
+                "fps": fps,
+                "codec": "libx264",
+                "pixelformat": "yuv420p",
+                "bitrate": "5000k",
+            }
             with imageio.get_writer(save_path, **writer_kwargs) as writer:
                 for frame in frames:
                     # Ensure RGB format
@@ -514,14 +516,14 @@ def _render_mp4_parallel(
     h, w = frames[0].shape[:2]
     fig = plt.figure(figsize=(w / 100, h / 100), dpi=100, frameon=False)
     ax = fig.add_axes([0, 0, 1, 1])
-    ax.axis('off')
+    ax.axis("off")
 
     writer = FFMpegWriter(fps=fps, codec="h264", bitrate=5000)
     with writer.saving(fig, save_path, dpi=100):
         for frame in frames:
             ax.clear()
             ax.imshow(frame)
-            ax.axis('off')
+            ax.axis("off")
             writer.grab_frame()
 
     plt.close(fig)

canns/analyzer/visualization/core/writers.py

@@ -439,31 +439,21 @@ def warn_gif_format(*, stacklevel: int = 2) -> None:
 
 
 def get_matplotlib_writer(save_path: str, fps: int = 10, **kwargs):
-    """
-    Create appropriate matplotlib animation writer based on file extension.
-
-    This function automatically selects the correct writer:
-    - .mp4 → FFMpegWriter (H.264 codec, high quality, fast encoding)
-    - .gif → PillowWriter (universal compatibility)
-    - others → FFMpegWriter (default)
+    """Create a Matplotlib animation writer based on file extension.
 
     Args:
-        save_path: Output file path (extension determines format)
-        fps: Frames per second
-        **kwargs: Additional arguments passed to the writer
-            For FFMpegWriter: codec, bitrate, extra_args
-            For PillowWriter: codec (ignored)
+        save_path: Output file path (extension determines format).
+        fps: Frames per second.
+        **kwargs: Additional arguments passed to the writer.
 
     Returns:
-        Matplotlib animation writer instance
+        Matplotlib animation writer instance.
 
-    Example:
-        >>> from matplotlib import animation
-        >>> writer = get_matplotlib_writer('output.mp4', fps=20)
-        >>> ani.save('output.mp4', writer=writer)
-
-        >>> # With custom codec
-        >>> writer = get_matplotlib_writer('output.mp4', fps=30, bitrate=8000)
+    Examples:
+        >>> from canns.analyzer.visualization.core.writers import get_matplotlib_writer
+        >>> writer = get_matplotlib_writer("output.gif", fps=5)
+        >>> print(writer is not None)
+        True
     """
     import os