scitex 2.7.3__py3-none-any.whl → 2.10.0__py3-none-any.whl

scitex/diagram/_schema.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-15
+# Author: ywatanabe / Claude
+# File: scitex/diagram/_schema.py
+
+"""
+Schema definitions for SciTeX Diagram.
+
+The schema defines paper-specific constraints that Mermaid/Graphviz don't know:
+- Paper layout (single/double column, max width)
+- Reading direction preferences
+- Node emphasis for scientific communication
+- Semantic layer grouping
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Dict, Optional, Literal
+
+
+class DiagramType(Enum):
+    """Semantic type of diagram - affects layout strategy."""
+    WORKFLOW = "workflow"       # Sequential process, prefer LR/TB flow
+    DECISION = "decision"       # Decision tree, prefer TB with branches
+    PIPELINE = "pipeline"       # Data pipeline, strict LR with stages
+    HIERARCHY = "hierarchy"     # Tree structure, TB with levels
+    COMPARISON = "comparison"   # Side-by-side, two columns
+
+
+class ColumnLayout(Enum):
+    """Paper column layout."""
+    SINGLE = "single"   # Full width (~170mm)
+    DOUBLE = "double"   # Half width (~85mm)
+
+
+class SpacingLevel(Enum):
+    """Abstract spacing levels - mapped to backend-specific values."""
+    TIGHT = "tight"       # Publication: minimal whitespace
+    COMPACT = "compact"
+    MEDIUM = "medium"
+    LARGE = "large"
+
+
+class PaperMode(Enum):
+    """Paper mode affects layout density and edge visibility."""
+    DRAFT = "draft"           # Full arrows, visible bidirectional, medium spacing
+    PUBLICATION = "publication"  # Compact, return edges hidden/dotted
+
+
+@dataclass
+class PaperConstraints:
+    """Paper-specific constraints that affect layout."""
+    column: ColumnLayout = ColumnLayout.SINGLE
+    max_width_mm: int = 170
+    reading_direction: Literal["left_to_right", "top_to_bottom"] = "left_to_right"
+    mode: PaperMode = PaperMode.DRAFT  # draft: full details, publication: compact
+    emphasize: List[str] = field(default_factory=list)  # Node IDs to highlight
+
+    # Scientific communication hints
+    main_flow: List[str] = field(default_factory=list)  # Critical path nodes
+    secondary_flow: List[str] = field(default_factory=list)  # Supporting elements
+    return_edges: List[tuple] = field(default_factory=list)  # Edges to hide in publication
+
+
+@dataclass
+class LayoutHints:
+    """Abstract layout hints - compiled to backend directives."""
+    layers: List[List[str]] = field(default_factory=list)  # Nodes grouped by rank
+    alignment: Dict[str, str] = field(default_factory=dict)  # Node alignment hints
+    layer_gap: SpacingLevel = SpacingLevel.MEDIUM
+    node_gap: SpacingLevel = SpacingLevel.MEDIUM
+
+    # Subgraph organization
+    groups: Dict[str, List[str]] = field(default_factory=dict)  # Named groups
+
+
+@dataclass
+class NodeSpec:
+    """Specification for a single node."""
+    id: str
+    label: str
+    shape: Literal["box", "rounded", "diamond", "circle", "stadium"] = "box"
+    emphasis: Literal["normal", "primary", "success", "warning", "muted"] = "normal"
+
+    def short_label(self, max_chars: int = 20) -> str:
+        """Return truncated label for compact layouts."""
+        if len(self.label) <= max_chars:
+            return self.label
+        return self.label[:max_chars-3] + "..."
+
+
+@dataclass
+class EdgeSpec:
+    """Specification for an edge between nodes."""
+    source: str
+    target: str
+    label: Optional[str] = None
+    style: Literal["solid", "dashed", "dotted"] = "solid"
+    arrow: Literal["normal", "none", "open"] = "normal"
+
+
+@dataclass
+class DiagramSpec:
+    """Complete diagram specification - the semantic layer."""
+
+    # Metadata
+    type: DiagramType = DiagramType.WORKFLOW
+    title: str = ""
+
+    # Paper constraints
+    paper: PaperConstraints = field(default_factory=PaperConstraints)
+
+    # Layout hints
+    layout: LayoutHints = field(default_factory=LayoutHints)
+
+    # Content
+    nodes: List[NodeSpec] = field(default_factory=list)
+    edges: List[EdgeSpec] = field(default_factory=list)
+
+    # Theme
+    theme: Dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "DiagramSpec":
+        """Create DiagramSpec from dictionary (parsed YAML)."""
+        spec = cls()
+
+        # Parse type
+        if "type" in data:
+            spec.type = DiagramType(data["type"])
+
+        spec.title = data.get("title", "")
+
+        # Parse paper constraints
+        if "paper" in data:
+            p = data["paper"]
+            spec.paper = PaperConstraints(
+                column=ColumnLayout(p.get("column", "single")),
+                max_width_mm=p.get("max_width_mm", 170),
+                reading_direction=p.get("reading_direction", "left_to_right"),
+                mode=PaperMode(p.get("mode", "draft")),
+                emphasize=p.get("emphasize", []),
+                main_flow=p.get("main_flow", []),
+                secondary_flow=p.get("secondary_flow", []),
+                return_edges=[tuple(e) for e in p.get("return_edges", [])],
+            )
+
+        # Parse layout hints
+        if "layout" in data:
+            lt = data["layout"]
+            spec.layout = LayoutHints(
+                layers=lt.get("layers", []),
+                alignment=lt.get("alignment", {}),
+                layer_gap=SpacingLevel(lt.get("layer_gap", "medium")),
+                node_gap=SpacingLevel(lt.get("node_gap", "medium")),
+                groups=lt.get("groups", {}),
+            )
+
+        # Parse nodes
+        for n in data.get("nodes", []):
+            spec.nodes.append(NodeSpec(
+                id=n["id"],
+                label=n.get("label", n["id"]),
+                shape=n.get("shape", "box"),
+                emphasis=n.get("emphasis", "normal"),
+            ))
+
+        # Parse edges
+        for e in data.get("edges", []):
+            spec.edges.append(EdgeSpec(
+                source=e["from"] if "from" in e else e["source"],
+                target=e["to"] if "to" in e else e["target"],
+                label=e.get("label"),
+                style=e.get("style", "solid"),
+                arrow=e.get("arrow", "normal"),
+            ))
+
+        # Theme
+        spec.theme = data.get("theme", {})
+
+        return spec

scitex/diagram/_split.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-15
+# Author: ywatanabe / Claude
+# File: scitex/diagram/_split.py
+
+"""
+Auto-split large diagrams into multiple figures.
+
+Strategies:
+- by_groups: Split by existing layout.groups (deterministic, paper-friendly)
+- by_articulation: Split at hub nodes (graph-theoretic)
+
+The split preserves "ghost nodes" at boundaries for visual continuity.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Set, Optional, Tuple
+from copy import deepcopy
+from enum import Enum
+
+from scitex.diagram._schema import DiagramSpec, NodeSpec, EdgeSpec
+
+
+class SplitStrategy(Enum):
+    BY_GROUPS = "by_groups"           # Split by layout.groups
+    BY_ARTICULATION = "by_articulation"  # Split at hub nodes
+
+
+@dataclass
+class SplitConfig:
+    """Configuration for auto-splitting."""
+    enabled: bool = False
+    max_nodes: int = 12               # Split if more nodes than this
+    strategy: SplitStrategy = SplitStrategy.BY_GROUPS
+    keep_hubs: bool = True            # Show hub nodes in both parts
+    ghost_style: str = "muted"        # Style for ghost nodes
+
+
+@dataclass
+class SplitResult:
+    """Result of splitting a diagram."""
+    figures: List[DiagramSpec]
+    labels: List[str]                  # Figure labels (A, B, C, ...)
+    cut_nodes: Set[str]               # Nodes that appear in multiple figures
+
+
+def split_diagram(
+    spec: DiagramSpec,
+    config: Optional[SplitConfig] = None,
+    group_assignments: Optional[List[List[str]]] = None,
+) -> SplitResult:
+    """
+    Split a diagram into multiple figures.
+
+    Parameters
+    ----------
+    spec : DiagramSpec
+        Original diagram specification.
+    config : SplitConfig, optional
+        Split configuration.
+    group_assignments : List[List[str]], optional
+        Manual group assignments for splitting.
+        If provided, overrides automatic detection.
+
+    Returns
+    -------
+    SplitResult
+        List of split diagram specifications.
+    """
+    if config is None:
+        config = SplitConfig(enabled=True)
+
+    # Check if split is needed
+    if not config.enabled or len(spec.nodes) <= config.max_nodes:
+        return SplitResult(figures=[spec], labels=[""], cut_nodes=set())
+
+    # Determine groups to split by
+    if group_assignments:
+        groups = group_assignments
+    elif config.strategy == SplitStrategy.BY_GROUPS:
+        groups = _split_by_groups(spec, max_nodes=config.max_nodes)
+    else:  # BY_ARTICULATION
+        groups = _split_by_articulation(spec)
+
+    # Create split figures
+    figures = []
+    labels = []
+    cut_nodes = set()
+
+    for i, group_nodes in enumerate(groups):
+        fig, cuts = _create_split_figure(spec, group_nodes, config)
+        figures.append(fig)
+        labels.append(chr(ord('A') + i))
+        cut_nodes.update(cuts)
+
+    return SplitResult(figures=figures, labels=labels, cut_nodes=cut_nodes)
+
+
+def _split_by_groups(spec: DiagramSpec, max_nodes: int = 12) -> List[List[str]]:
+    """
+    Split by existing layout.groups using greedy packing.
+
+    Packs groups into figures until max_nodes is exceeded,
+    then starts a new figure.
+
+    Returns list of node ID lists, one per split figure.
+    """
+    if not spec.layout.groups:
+        # No groups defined - try to split in half
+        node_ids = [n.id for n in spec.nodes]
+        mid = len(node_ids) // 2
+        return [node_ids[:mid], node_ids[mid:]]
+
+    # Group keys in order
+    group_names = list(spec.layout.groups.keys())
+
+    # Greedy packing: add groups until max_nodes exceeded
+    figures = []
+    current_figure = []
+    current_count = 0
+
+    for group_name in group_names:
+        group_nodes = spec.layout.groups[group_name]
+        group_size = len(group_nodes)
+
+        # If adding this group exceeds max and we have something, start new figure
+        if current_count + group_size > max_nodes and current_figure:
+            figures.append(current_figure)
+            current_figure = []
+            current_count = 0
+
+        # Add group to current figure
+        current_figure.extend(group_nodes)
+        current_count += group_size
+
+    # Don't forget the last figure
+    if current_figure:
+        figures.append(current_figure)
+
+    # Add ungrouped nodes to first figure
+    grouped = set()
+    for fig in figures:
+        grouped.update(fig)
+    for n in spec.nodes:
+        if n.id not in grouped:
+            if figures:
+                figures[0].append(n.id)
+            else:
+                figures.append([n.id])
+
+    # Ensure at least 2 figures if we have enough nodes
+    if len(figures) == 1 and len(figures[0]) > max_nodes:
+        # Force split in half
+        nodes = figures[0]
+        mid = len(nodes) // 2
+        figures = [nodes[:mid], nodes[mid:]]
+
+    return figures
+
+
+def _split_by_articulation(spec: DiagramSpec) -> List[List[str]]:
+    """
+    Split at articulation points (hub nodes).
+
+    This finds nodes that, if removed, would disconnect the graph.
+    These are natural split points for large diagrams.
+    """
+    # Build adjacency
+    adj: Dict[str, Set[str]] = {n.id: set() for n in spec.nodes}
+    for e in spec.edges:
+        adj[e.source].add(e.target)
+        adj[e.target].add(e.source)
+
+    # Find node with most connections (hub)
+    hub = max(adj.keys(), key=lambda x: len(adj[x]))
+
+    # BFS from first node, stopping at hub
+    visited = {hub}  # Block the hub
+    node_ids = [n.id for n in spec.nodes if n.id != hub]
+
+    if not node_ids:
+        return [[hub]]
+
+    # Find components when hub is removed
+    components = []
+    for start in node_ids:
+        if start in visited:
+            continue
+        component = []
+        queue = [start]
+        while queue:
+            curr = queue.pop(0)
+            if curr in visited:
+                continue
+            visited.add(curr)
+            component.append(curr)
+            for neighbor in adj[curr]:
+                if neighbor not in visited:
+                    queue.append(neighbor)
+        if component:
+            components.append(component)
+
+    # Add hub to each component (as ghost)
+    for comp in components:
+        comp.append(hub)
+
+    return components if components else [[n.id for n in spec.nodes]]
+
+
+def _create_split_figure(
+    spec: DiagramSpec,
+    node_ids: List[str],
+    config: SplitConfig,
+) -> Tuple[DiagramSpec, Set[str]]:
+    """
+    Create a split figure containing specified nodes.
+
+    Returns (figure_spec, ghost_node_ids).
+    """
+    node_id_set = set(node_ids)
+
+    # Find edges that cross the boundary
+    boundary_nodes = set()
+    for edge in spec.edges:
+        src_in = edge.source in node_id_set
+        tgt_in = edge.target in node_id_set
+        if src_in and not tgt_in:
+            if config.keep_hubs:
+                boundary_nodes.add(edge.target)
+        elif tgt_in and not src_in:
+            if config.keep_hubs:
+                boundary_nodes.add(edge.source)
+
+    # Create new spec
+    new_spec = DiagramSpec(
+        type=spec.type,
+        title=spec.title,
+        paper=deepcopy(spec.paper),
+        layout=deepcopy(spec.layout),
+        theme=dict(spec.theme),
+    )
+
+    # Filter nodes
+    node_map = {n.id: n for n in spec.nodes}
+    for node_id in node_ids:
+        if node_id in node_map:
+            new_spec.nodes.append(deepcopy(node_map[node_id]))
+
+    # Add ghost nodes (boundary nodes not in this split)
+    for ghost_id in boundary_nodes:
+        if ghost_id in node_map and ghost_id not in node_id_set:
+            ghost = deepcopy(node_map[ghost_id])
+            ghost.emphasis = config.ghost_style
+            ghost.label = f"→ {ghost.label}"  # Mark as continuation
+            new_spec.nodes.append(ghost)
+
+    # Filter edges
+    all_ids = node_id_set | boundary_nodes
+    for edge in spec.edges:
+        if edge.source in all_ids and edge.target in all_ids:
+            new_spec.edges.append(deepcopy(edge))
+
+    # Filter groups
+    new_spec.layout.groups = {}
+    for group_name, group_nodes in spec.layout.groups.items():
+        filtered = [n for n in group_nodes if n in all_ids]
+        if filtered:
+            new_spec.layout.groups[group_name] = filtered
+
+    # Filter layers
+    new_spec.layout.layers = []
+    for layer in spec.layout.layers:
+        filtered = [n for n in layer if n in all_ids]
+        if filtered:
+            new_spec.layout.layers.append(filtered)
+
+    return new_spec, boundary_nodes

scitex/dict/_pop_keys.py

@@ -1,11 +1,7 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: "2025-11-10 22:40:16 (ywatanabe)"
 
 
-import numpy as np
-
-
 def pop_keys(keys_list, keys_to_pop):
     """Remove specified keys from a list of keys.
 
@@ -28,9 +24,7 @@ def pop_keys(keys_list, keys_to_pop):
     >>> pop_keys(keys_list, keys_to_pop)
     ['a', 'c', 'e', 'bde']
     """
-    indi_to_remain = [k not in keys_to_pop for k in keys_list]
-    keys_remainded_list = list(np.array(keys_list)[list(indi_to_remain)])
-    return keys_remainded_list
+    return [k for k in keys_list if k not in keys_to_pop]
 
 
 # EOF

scitex/dsp/__init__.py

@@ -3,20 +3,23 @@
 
 import warnings
 
+# Import example, params, norm, reference, filt, and add_noise modules as submodules
+from . import add_noise, example, filt, norm, params, reference
+
 # Core imports that should always work
 from ._crop import crop
 from ._demo_sig import demo_sig
 from ._detect_ripples import (
-    detect_ripples,
-    _preprocess,
-    _find_events,
-    _drop_ripples_at_edges,
     _calc_relative_peak_position,
+    _drop_ripples_at_edges,
+    _find_events,
+    _preprocess,
     _sort_columns,
+    detect_ripples,
 )
 from ._ensure_3d import ensure_3d
 from ._hilbert import hilbert
-from ._modulation_index import modulation_index, _reshape
+from ._modulation_index import _reshape, modulation_index
 from ._pac import pac
 from ._psd import band_powers, psd
 from ._resample import resample
@@ -24,16 +27,12 @@ from ._time import time
 from ._transform import to_segments, to_sktime_df
 from ._wavelet import wavelet
 
-# Import example and params modules as submodules
-from . import example
-from . import params
-
 # Try to import audio-related functions that require PortAudio
 try:
     from ._listen import list_and_select_device
 
     _audio_available = True
-except (ImportError, OSError) as e:
+except (ImportError, OSError):
     warnings.warn(
         "Audio functionality unavailable: PortAudio library not found. "
         "Install PortAudio to use audio features (e.g., sudo apt-get install portaudio19-dev)",
@@ -62,17 +61,23 @@ __all__ = [
     "_preprocess",
     "_reshape",
     "_sort_columns",
+    "add_noise",
     "band_powers",
     "crop",
     "demo_sig",
     "detect_ripples",
     "ensure_3d",
+    "example",
+    "filt",
     "get_eeg_pos",
     "hilbert",
     "list_and_select_device",
     "modulation_index",
+    "norm",
     "pac",
+    "params",
     "psd",
+    "reference",
     "resample",
     "time",
     "to_segments",

scitex/dsp/add_noise.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Time-stamp: "ywatanabe (2024-11-02 23:09:49)"
 # File: ./scitex_repo/src/scitex/dsp/add_noise.py
 
 import torch
+
 from scitex.decorators import signal_fn
 
 
@@ -50,9 +50,11 @@ def pink(x, amp=1.0, dim=-1):
 
 @signal_fn
 def brown(x, amp=1.0, dim=-1):
+    from scitex.dsp import norm
+
     noise = _uniform(x.shape, amp=amp)
     noise = torch.cumsum(noise, dim=dim)
-    noise = scitex.dsp.norm.minmax(noise, amp=amp, dim=dim)
+    noise = norm.minmax(noise, amp=amp, dim=dim)
     return x + noise.to(x.device)
 
 
@@ -60,6 +62,7 @@ if __name__ == "__main__":
     import sys
 
     import matplotlib.pyplot as plt
+
     import scitex
 
     # Start

scitex/dsp/example.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Time-stamp: "2024-04-06 01:36:18 (ywatanabe)"
 
 import matplotlib
@@ -9,6 +8,17 @@ import matplotlib.pyplot as plt
 import pandas as pd
 import scitex
 
+import scitex
+
+# Module-level constants (defaults for example functions)
+TGT_FS = 512
+LOW_HZ = 20
+HIGH_HZ = 50
+SIGMA = 10
+
+# Default color cycle
+CC = {"blue": "#1f77b4", "red": "#d62728", "green": "#2ca02c"}
+
 
 # Functions
 def calc_norm_resample_filt_hilbert(xx, tt, fs, sig_type, verbose=True):
@@ -17,18 +27,19 @@ def calc_norm_resample_filt_hilbert(xx, tt, fs, sig_type, verbose=True):
     if sig_type == "tensorpac":
         xx = xx[:, :, 0]
 
-    sigs[f"orig"] = (xx, tt, fs)
+    sigs["orig"] = (xx, tt, fs)
 
     # Normalization
     sigs["z_normed"] = (scitex.dsp.norm.z(xx), tt, fs)
     sigs["minmax_normed"] = (scitex.dsp.norm.minmax(xx), tt, fs)
 
     # Resampling
-    sigs["resampled"] = (
-        scitex.dsp.resample(xx, fs, TGT_FS),
-        tt[:: int(fs / TGT_FS)],
-        TGT_FS,
-    )
+    resampled_xx = scitex.dsp.resample(xx, fs, TGT_FS)
+    # Create proper time vector for resampled signal
+    import numpy as np
+
+    resampled_tt = np.linspace(tt[0], tt[-1], resampled_xx.shape[-1])
+    sigs["resampled"] = (resampled_xx, resampled_tt, TGT_FS)
 
     # Noise injection
     sigs["gaussian_noise_added"] = (scitex.dsp.add_noise.gauss(xx), tt, fs)
@@ -36,15 +47,16 @@ def calc_norm_resample_filt_hilbert(xx, tt, fs, sig_type, verbose=True):
     sigs["pink_noise_added"] = (scitex.dsp.add_noise.pink(xx), tt, fs)
     sigs["brown_noise_added"] = (scitex.dsp.add_noise.brown(xx), tt, fs)
 
-    # Filtering
+    # Filtering (bands format is [[low_hz, high_hz]])
+    bands = [[LOW_HZ, HIGH_HZ]]
     sigs[f"bandpass_filted ({LOW_HZ} - {HIGH_HZ} Hz)"] = (
-        scitex.dsp.filt.bandpass(xx, fs, low_hz=LOW_HZ, high_hz=HIGH_HZ),
+        scitex.dsp.filt.bandpass(xx, fs, bands),
         tt,
         fs,
     )
 
     sigs[f"bandstop_filted ({LOW_HZ} - {HIGH_HZ} Hz)"] = (
-        scitex.dsp.filt.bandstop(xx, fs, low_hz=LOW_HZ, high_hz=HIGH_HZ),
+        scitex.dsp.filt.bandstop(xx, fs, bands),
         tt,
         fs,
     )
@@ -88,18 +100,19 @@ def plot_signals(plt, sigs, sig_type):
         # if sig_type == "tensorpac":
         #     xx = xx[:, :, 0]
 
-        try:
-            ax.plot(
-                tt,
-                xx[i_batch, i_ch],
-                label=col,
-                c=CC["red"] if col == "hilbert_amp" else CC["blue"],
-            )
-        except Exception as e:
-            print(e)
-            import ipdb
-
-            ipdb.set_trace()
+        # Handle potential shape mismatches from filter operations
+        signal = xx[i_batch, i_ch]
+        if hasattr(signal, "squeeze"):
+            signal = signal.squeeze()
+        if hasattr(signal, "numpy"):
+            signal = signal.numpy()
+
+        ax.plot(
+            tt,
+            signal,
+            label=col,
+            c=CC["red"] if col == "hilbert_amp" else CC["blue"],
+        )
 
         # Adjustments
         ax.legend(loc="upper left")