arrscope 0.1.0__py3-none-any.whl

arrscope/__init__.py

@@ -0,0 +1,4 @@
+from arrscope._api import scope
+from arrscope._config import config
+
+__all__ = ["scope", "config"]

arrscope/__main__.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+
+import numpy as np
+
+from arrscope import scope
+
+SHAPES: dict[str, tuple] = {
+    "1d": (6,),
+    "2d": (6, 6),
+    "3d": (3, 4, 5),
+    "4d": (2, 3, 4, 5),
+    "5d": (2, 2, 3, 4, 5),
+    "eye": (5, 5),
+    "trunc": (20, 4, 5),
+}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="arrscope",
+        description="Visualize n-dimensional arrays in the terminal.",
+    )
+    parser.add_argument(
+        "shape",
+        nargs="?",
+        default="4d",
+        help=f"Shape preset or custom dims like 3x4x5. Presets: {', '.join(SHAPES)}",
+    )
+    parser.add_argument("--axes", "-a", nargs="*", help="Axis names")
+    parser.add_argument(
+        "--grid", "-g", nargs="*", default=None, help="Grid axis names"
+    )
+    parser.add_argument(
+        "--title", "-t", default=None, help="Title for the visualization"
+    )
+    parser.add_argument(
+        "--max-height", type=int, default=None, help="Max rows before truncation"
+    )
+    parser.add_argument("--no-color", action="store_true", help="Disable color")
+    parser.add_argument(
+        "--mode", "-m",
+        default="dtype",
+        choices=["dtype", "heatmap", "sparsity"],
+        help="Color mode: dtype (default), heatmap (diverging), sparsity (highlight non-zero)",
+    )
+    parser.add_argument(
+        "--no-stats", action="store_true", help="Hide stats overlay"
+    )
+
+    args = parser.parse_args()
+
+    if args.shape in SHAPES:
+        shape = SHAPES[args.shape]
+    else:
+        shape = tuple(int(d) for d in args.shape.split("x"))
+
+    arr = np.random.rand(*shape)
+
+    kw = {}
+    if args.axes:
+        kw["axes"] = args.axes
+    if args.grid:
+        kw["grid"] = args.grid
+    if args.title:
+        kw["title"] = args.title
+    if args.max_height:
+        kw["max_height"] = args.max_height
+    if args.no_color:
+        kw["color"] = False
+    kw["mode"] = args.mode
+    kw["stats"] = not args.no_stats
+
+    output = scope(arr, **kw)
+    print(output)
+
+
+if __name__ == "__main__":
+    main()

arrscope/_api.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from arrscope._config import config
+from arrscope._format import format_value
+from arrscope._layout import build_layout, compute_stats
+from arrscope._types import VizOutput
+from arrscope.adapters import to_numpy
+from arrscope.renderers import render_html, render_terminal
+
+
+def scope(
+    arr,
+    *,
+    axes: list[str] | None = None,
+    grid: list[str | int] | None = None,
+    title: str | None = None,
+    max_width: int | None = None,
+    max_height: int | None = None,
+    fmt: str | None = None,
+    color: bool | None = None,
+    style: str = "auto",
+    mode: str | None = None,
+    stats: bool | None = None,
+) -> VizOutput:
+    arr_np = to_numpy(arr)
+
+    color = config.color if color is None else color
+    max_width = max_width or config.max_width
+    max_height = max_height or config.max_height
+    mode = mode or config.mode
+    show_stats = config.stats if stats is None else stats
+
+    if mode not in ("dtype", "heatmap", "sparsity"):
+        raise ValueError(f"Unknown mode '{mode}'. Expected one of: dtype, heatmap, sparsity")
+
+    grid_dims = _resolve_grid_dims(arr_np, axes, grid)
+
+    node = build_layout(
+        arr_np,
+        grid_dims=grid_dims,
+        max_height=max_height,
+    )
+
+    global_stats = compute_stats(arr_np) if (show_stats or mode == "heatmap") else None
+    if global_stats and show_stats:
+        node.stats = global_stats
+
+    use_html = _use_html(style)
+    use_terminal = _use_terminal(style)
+
+    output = VizOutput()
+
+    if use_html:
+        output.html = _wrap_html(
+            render_html(node, color=color, mode=mode, global_stats=global_stats), title
+        )
+
+    if use_terminal:
+        output.ansi = _wrap_ansi(
+            render_terminal(node, color=color, mode=mode, global_stats=global_stats), title
+        )
+
+    return output
+
+
+def _resolve_grid_dims(
+    arr: np.ndarray,
+    axes: list[str] | None,
+    grid: list[str | int] | None,
+) -> list[int] | None:
+    if grid is None:
+        return None
+
+    if axes is None:
+        return [g if isinstance(g, int) else arr.ndim - 2 + (list(axes or []).index(g))
+                for g in grid]
+
+    name_to_idx = {name: i for i, name in enumerate(axes)}
+    resolved: list[int] = []
+    for g in grid:
+        if isinstance(g, str):
+            if g not in name_to_idx:
+                raise ValueError(
+                    f"Axis '{g}' not found in axes={axes}. "
+                    f"Available axes: {list(name_to_idx.keys())}"
+                )
+            resolved.append(name_to_idx[g])
+        else:
+            resolved.append(g)
+    return resolved
+
+
+def _use_html(style: str) -> bool:
+    if style == "html":
+        return True
+    if style == "terminal":
+        return False
+    return _in_jupyter()
+
+
+def _use_terminal(style: str) -> bool:
+    if style == "terminal":
+        return True
+    if style == "html":
+        return False
+    return True
+
+
+def _in_jupyter() -> bool:
+    try:
+        from IPython import get_ipython
+
+        shell = get_ipython()
+        return shell is not None and "IPKernelApp" in shell.config
+    except (ImportError, AttributeError):
+        return False
+
+
+def _wrap_html(body: str, title: str | None) -> str:
+    if title:
+        return f'<h3 style="font-family: sans-serif; margin: 4px 0;">{title}</h3>\n{body}'
+    return body
+
+
+def _wrap_ansi(body: str, title: str | None) -> str:
+    if title:
+        from rich.text import Text
+
+        t = Text(title, style="bold")
+        return f"{t}\n{body}"
+    return body

arrscope/_config.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Config:
+    max_width: int | None = None
+    max_height: int | None = None
+    color: bool = True
+    precision: int | None = None
+    mode: str = "dtype"
+    stats: bool = True
+
+
+config: Config = Config()

arrscope/_format.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+
+def format_value(val, fmt: str | None = None) -> str:
+    if isinstance(val, np.floating):
+        return _format_float(float(val), fmt)
+    if isinstance(val, float):
+        return _format_float(val, fmt)
+    if isinstance(val, np.integer):
+        return str(int(val))
+    if isinstance(val, np.bool_):
+        return "T" if val else "F"
+    if isinstance(val, bool):
+        return "T" if val else "F"
+    if isinstance(val, np.complexfloating):
+        return _format_complex(val, fmt)
+    if val is None or (isinstance(val, float) and np.isnan(val)):
+        return "NaN"
+    return str(val)
+
+
+def _format_float(val: float, fmt: str | None) -> str:
+    if fmt is not None:
+        return f"{val:{fmt}}"
+    if val == 0.0:
+        return "0"
+    if math.isnan(val):
+        return "NaN"
+    if math.isinf(val):
+        return "inf" if val > 0 else "-inf"
+    abs_val = abs(val)
+    if abs_val >= 1e4 or abs_val < 1e-4:
+        return f"{val:.4e}"
+    if abs_val >= 1:
+        return f"{val:.4f}".rstrip("0").rstrip(".")
+    return f"{val:.4f}".rstrip("0").rstrip(".")
+
+
+def _format_complex(val: complex, fmt: str | None) -> str:
+    real = _format_float(val.real, fmt)
+    imag = _format_float(abs(val.imag), fmt)
+    sign = "+" if val.imag >= 0 else "-"
+    return f"{real}{sign}{imag}j"
+
+
+def auto_precision(arr: np.ndarray) -> int:
+    flat = arr.ravel()
+    flat = flat[np.isfinite(flat)]
+    if len(flat) == 0:
+        return 2
+    log_range = np.log10(np.max(np.abs(flat))) - np.log10(np.min(np.abs(flat[flat != 0]))) if np.any(flat != 0) else 2
+    if np.isnan(log_range) or np.isinf(log_range):
+        return 4
+    return min(max(int(log_range) + 2, 2), 8)

arrscope/_layout.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from arrscope._types import VizNode
+
+
+def build_layout(
+    arr: np.ndarray,
+    *,
+    grid_dims: list[int] | None = None,
+    max_height: int | None = None,
+) -> VizNode:
+    shape = arr.shape
+    ndim = len(shape)
+
+    if grid_dims is None:
+        grid_dims = list(range(max(0, ndim - 2), ndim))
+
+    non_grid = [d for d in range(ndim) if d not in grid_dims]
+
+    root = _build_tree(arr, non_grid, grid_dims, (), max_height)
+    root.shape = shape
+    root.label = _shape_label(shape, arr.dtype)
+    return root
+
+
+def compute_stats(arr: np.ndarray) -> dict:
+    flat = arr.ravel()
+    stats: dict = {}
+
+    if np.issubdtype(arr.dtype, np.floating) or np.issubdtype(arr.dtype, np.integer):
+        finite = flat[np.isfinite(flat)]
+        if len(finite) > 0:
+            stats["min"] = float(finite.min())
+            stats["max"] = float(finite.max())
+            stats["mean"] = float(finite.mean())
+            stats["std"] = float(finite.std())
+        else:
+            stats["min"] = stats["max"] = stats["mean"] = stats["std"] = float("nan")
+    elif np.issubdtype(arr.dtype, np.bool_):
+        stats["min"] = int(flat.min())
+        stats["max"] = int(flat.max())
+        stats["mean"] = float(flat.mean())
+        stats["std"] = float(flat.std())
+
+    nan_count = int(np.isnan(flat).sum()) if np.issubdtype(arr.dtype, np.floating) else 0
+    zero_count = int((flat == 0).sum())
+    total = flat.size
+    stats["nan_count"] = nan_count
+    stats["zero_count"] = zero_count
+    stats["total"] = total
+    stats["sparsity"] = zero_count / total if total > 0 else 0.0
+    stats["dtype"] = str(arr.dtype)
+
+    return stats
+
+
+def _build_tree(
+    arr: np.ndarray,
+    non_grid: list[int],
+    grid_dims: list[int],
+    indices: tuple[int, ...],
+    max_height: int | None,
+) -> VizNode:
+    if not non_grid:
+        return VizNode(
+            indices=indices,
+            label=_indices_label(indices),
+            shape=arr.shape,
+            grid_data=arr,
+        )
+
+    current_dim = non_grid[0]
+    size = arr.shape[current_dim]
+    remaining = non_grid[1:]
+
+    children: list[VizNode] = []
+    head_count, tail_count = _truncation_limits(size, max_height)
+
+    for i in range(size):
+        is_truncated_region = (
+            max_height is not None
+            and size > head_count + tail_count
+            and head_count <= i < size - tail_count
+        )
+        if is_truncated_region:
+            if i == head_count:
+                children.append(
+                    VizNode(
+                        indices=(),
+                        label=f"... ({size - head_count - tail_count} more)",
+                        truncated=True,
+                    )
+                )
+            continue
+
+        child_indices = indices + (i,)
+        child_arr = _slice_dim(arr, current_dim, i)
+
+        new_remaining = _adjust_indices(remaining, current_dim)
+        child = _build_tree(
+            child_arr, new_remaining, grid_dims, child_indices, max_height
+        )
+        children.append(child)
+
+    return VizNode(
+        indices=indices,
+        label=_indices_label(indices),
+        shape=(size,) + arr.shape[current_dim + 1 :],
+        children=children,
+        truncated=len(children) < size and size > 0,
+        truncated_head=head_count,
+        truncated_tail=tail_count if len(children) < size else 0,
+    )
+
+
+def _slice_dim(arr: np.ndarray, dim: int, index: int) -> np.ndarray:
+    slices = [slice(None)] * arr.ndim
+    slices[dim] = index
+    return arr[tuple(slices)]
+
+
+def _adjust_indices(
+    remaining: list[int], removed_dim: int
+) -> list[int]:
+    return [d - 1 if d > removed_dim else d for d in remaining]
+
+
+def _indices_label(indices: tuple[int, ...]) -> str:
+    if not indices:
+        return ""
+    return "[" + ", ".join(str(i) for i in indices) + "]"
+
+
+def _shape_label(shape: tuple[int, ...], dtype: np.dtype) -> str:
+    return f"({', '.join(str(s) for s in shape)}) {dtype}"
+
+
+def _truncation_limits(
+    size: int, max_height: int | None
+) -> tuple[int, int]:
+    if max_height is None:
+        return size, 0
+    if size <= max_height:
+        return size, 0
+    head = math.ceil(max_height / 2)
+    tail = max_height // 2
+    return head, tail

arrscope/_types.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+
+@dataclass
+class VizNode:
+    indices: tuple[int, ...] = ()
+    label: str = ""
+    shape: tuple[int, ...] = ()
+    children: list[VizNode] = field(default_factory=list)
+    grid_data: np.ndarray | None = None
+    truncated: bool = False
+    truncated_head: int = 0
+    truncated_tail: int = 0
+    stats: dict | None = None
+
+
+@dataclass
+class VizOutput:
+    html: str = ""
+    ansi: str = ""
+    metadata: dict = field(default_factory=dict)
+
+    def _repr_html_(self) -> str:
+        return self.html
+
+    def __rich_console__(self, console, options):
+        from rich.text import Text
+
+        yield Text.from_ansi(self.ansi)
+
+    def __str__(self) -> str:
+        return self.ansi
+
+    def __repr__(self) -> str:
+        return self.ansi

arrscope/adapters/__init__.py

@@ -0,0 +1,3 @@
+from arrscope.adapters._core import to_numpy
+
+__all__ = ["to_numpy"]

arrscope/adapters/_core.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import numpy as np
+
+
+def to_numpy(arr) -> np.ndarray:
+    if isinstance(arr, np.ndarray):
+        return arr
+
+    if hasattr(arr, "__array__"):
+        return np.asarray(arr)
+
+    module = type(arr).__module__ if hasattr(type(arr), "__module__") else ""
+
+    if "torch" in module:
+        import torch
+
+        return arr.detach().cpu().numpy()
+
+    if "tensorflow" in module or "keras" in module:
+        return arr.numpy()
+
+    if "jax" in module:
+        return np.asarray(arr)
+
+    try:
+        return np.asarray(arr)
+    except (TypeError, ValueError) as e:
+        raise TypeError(
+            f"Cannot convert {type(arr).__name__} to numpy array. "
+            f"Supported types: np.ndarray, torch.Tensor, tf.Tensor, jax.Array, "
+            f"and objects implementing __array__."
+        ) from e

arrscope/renderers/__init__.py

@@ -0,0 +1,4 @@
+from arrscope.renderers.terminal import render_terminal
+from arrscope.renderers.html import render_html
+
+__all__ = ["render_terminal", "render_html"]

arrscope/renderers/html.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import html as html_mod
+
+import numpy as np
+
+from arrscope._format import format_value
+from arrscope._types import VizNode
+
+
+def render_html(
+    node: VizNode,
+    color: bool = True,
+    mode: str = "dtype",
+    global_stats: dict | None = None,
+) -> str:
+    css = _css()
+    body = _render_node_html(node, 0, mode, global_stats)
+
+    stats_html = ""
+    if global_stats and node.stats:
+        stats_html = _stats_html(global_stats)
+
+    return f"""<div class="arrscope-wrapper">
+<style>{css}</style>
+{body}
+{stats_html}
+</div>"""
+
+
+def _css() -> str:
+    return """
+.arrscope-wrapper {
+    font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+    font-size: 13px;
+    line-height: 1.5;
+    margin: 8px 0;
+}
+.arrscope-wrapper table {
+    border-collapse: collapse;
+    margin: 4px 0;
+}
+.arrscope-wrapper td, .arrscope-th {
+    padding: 2px 6px;
+    text-align: right;
+    white-space: pre;
+    border: 1px solid #d0d0d0;
+}
+.arrscope-th {
+    font-weight: 600;
+    background: #f5f5f5;
+    text-align: center;
+}
+.arrscope-label {
+    font-weight: 600;
+    margin: 4px 0 2px;
+    color: #333;
+}
+.arrscope-shape {
+    color: #888;
+    font-size: 12px;
+    margin-left: 8px;
+}
+.arrscope-row { display: flex; flex-wrap: wrap; gap: 12px; }
+.arrscope-tree { margin-left: 16px; }
+.arrscope-ellipsis { color: #999; font-style: italic; margin: 2px 0; }
+.arrscope-header {
+    font-weight: 600;
+    padding: 4px 0;
+    border-bottom: 1px solid #e0e0e0;
+    margin-bottom: 4px;
+}
+.arrscope-stats {
+    font-size: 12px;
+    color: #666;
+    margin: 2px 0 4px;
+}
+details.arrscope-details > summary {
+    cursor: pointer;
+    list-style: '⊞ ';
+}
+details.arrscope-details[open] > summary {
+    list-style: '⊟ ';
+}
+
+@media (prefers-color-scheme: dark) {
+    .arrscope-wrapper td {
+        border-color: #444;
+    }
+    .arrscope-th {
+        background: #2a2a2a;
+        color: #ddd;
+    }
+    .arrscope-label { color: #ccc; }
+    .arrscope-shape { color: #777; }
+    .arrscope-stats { color: #999; }
+    .arrscope-header { border-bottom-color: #444; }
+}
+"""
+
+
+def _stats_html(stats: dict) -> str:
+    items = []
+    for key in ("min", "max", "mean", "std"):
+        if key in stats:
+            v = stats[key]
+            if isinstance(v, float):
+                items.append(f"{key}={format_value(v)}")
+            else:
+                items.append(f"{key}={v}")
+    if "zero_count" in stats and "total" in stats:
+        pct = stats["zero_count"] / stats["total"] * 100
+        items.append(f"zeros={pct:.1f}%")
+    if "nan_count" in stats and stats["nan_count"] > 0:
+        items.append(f"NaN={stats['nan_count']}")
+    return f'<div class="arrscope-stats">{" &middot; ".join(items)}</div>'
+
+
+def _render_node_html(
+    node: VizNode, depth: int, mode: str, global_stats: dict | None
+) -> str:
+    if node.grid_data is not None:
+        return _render_grid_html(node.grid_data, node.label, mode, global_stats)
+
+    if not node.children and node.truncated:
+        return f'<div class="arrscope-ellipsis">{html_mod.escape(node.label)}</div>'
+
+    is_large_tree = depth > 0 and len(node.children) > 4
+
+    parts: list[str] = []
+    if depth == 0:
+        parts.append(
+            f'<div class="arrscope-header">{html_mod.escape(_format_header(node))}</div>'
+        )
+
+    if is_large_tree:
+        parts.append(
+            f'<details class="arrscope-details" {"open" if depth == 0 else ""}>'
+        )
+        parts.append(
+            f"<summary>{html_mod.escape(node.label or _format_header(node))}</summary>"
+        )
+        parts.append('<div class="arrscope-tree">')
+
+    for child in node.children:
+        parts.append(_render_node_html(child, depth + 1, mode, global_stats))
+
+    if is_large_tree:
+        parts.append("</div></details>")
+
+    return "".join(parts)
+
+
+def _format_header(node: VizNode) -> str:
+    label = node.label or ""
+    shape = " × ".join(str(s) for s in node.shape)
+    if shape:
+        return f"{label} ({shape})"
+    return label
+
+
+def _render_grid_html(
+    data: np.ndarray, label: str, mode: str, global_stats: dict | None
+) -> str:
+    if data.ndim == 0:
+        return f"<span>{html_mod.escape(format_value(data.item()))}</span>"
+
+    if data.ndim == 1:
+        return _render_1d_html(data, mode, global_stats)
+
+    return _render_2d_html(data, label, mode, global_stats)
+
+
+def _render_1d_html(
+    data: np.ndarray, mode: str, global_stats: dict | None
+) -> str:
+    cells = [
+        f"<td style=\"{_style_html(v, mode, global_stats)}\">"
+        f"{html_mod.escape(_format_cell_html(v, mode))}</td>"
+        for v in data
+    ]
+    return f"<table><tr>{''.join(cells)}</tr></table>"
+
+
+def _render_2d_html(
+    data: np.ndarray, label: str, mode: str, global_stats: dict | None
+) -> str:
+    nrows, ncols = data.shape
+    rows: list[str] = []
+    if label:
+        rows.append(
+            f'<div class="arrscope-label">{html_mod.escape(label)} '
+            f'<span class="arrscope-shape">{nrows}×{ncols}</span></div>'
+        )
+    rows.append("<table>")
+    for row_idx in range(nrows):
+        rows.append("<tr>")
+        for col_idx in range(ncols):
+            val = data[row_idx, col_idx]
+            text = html_mod.escape(_format_cell_html(val, mode))
+            style = _style_html(val, mode, global_stats)
+            rows.append(f"<td style=\"{style}\">{text}</td>")
+        rows.append("</tr>")
+    rows.append("</table>")
+    return "".join(rows)
+
+
+def _format_cell_html(val, mode: str) -> str:
+    if mode == "sparsity" and _is_zero(val):
+        return "·"
+    return format_value(val)
+
+
+def _is_zero(val) -> bool:
+    if isinstance(val, (np.floating, float)):
+        return val == 0.0 or abs(val) < 1e-15
+    if isinstance(val, (np.integer, int)):
+        return val == 0
+    if isinstance(val, (np.bool_, bool)):
+        return not val
+    return val == 0
+
+
+def _style_html(val, mode: str, global_stats: dict | None) -> str:
+    if mode == "heatmap":
+        return _heatmap_style(val, global_stats)
+    if mode == "sparsity":
+        return _sparsity_style(val)
+    return _dtype_style(val)
+
+
+def _heatmap_style(val, global_stats: dict | None) -> str:
+    if not global_stats:
+        return ""
+    if isinstance(val, (np.floating, float)) and (np.isnan(val) or np.isinf(val)):
+        return "color: #e74c3c; font-weight: bold;"
+    if not isinstance(val, (np.floating, float, np.integer, int)):
+        return _dtype_style(val)
+
+    vmin = global_stats.get("min", 0.0)
+    vmax = global_stats.get("max", 1.0)
+    if vmax == vmin:
+        return "color: #999;"
+
+    t = (float(val) - vmin) / (vmax - vmin)
+    t = max(0.0, min(1.0, t))
+
+    if t < 0.5:
+        t2 = t / 0.5
+        r = int(180 - 140 * t2)
+        g = int(30 + 210 * t2)
+        b = int(30 + 100 * t2)
+    else:
+        t2 = (t - 0.5) / 0.5
+        r = int(40 - 10 * t2)
+        g = int(240 - 200 * t2)
+        b = int(130 + 130 * t2)
+
+    return f"color: rgb({r},{g},{b});"
+
+
+def _sparsity_style(val) -> str:
+    if _is_zero(val):
+        return "color: #999; opacity: 0.4;"
+    if isinstance(val, (np.integer, int)):
+        return "color: #27ae60; font-weight: bold;"
+    if isinstance(val, (np.floating, float)):
+        return "color: #2980b9; font-weight: bold;"
+    if isinstance(val, (np.bool_, bool)):
+        return "color: #8e44ad; font-weight: bold;"
+    return _dtype_style(val)
+
+
+def _dtype_style(val) -> str:
+    if isinstance(val, (np.floating, float)):
+        if np.isnan(val) or np.isinf(val):
+            return "color: #e74c3c; font-weight: bold;"
+        if val > 0:
+            intensity = min(abs(val) / 10, 1.0)
+            b = int(180 + 75 * intensity)
+            return f"color: rgb(40, 40, {b});"
+        if val < 0:
+            intensity = min(abs(val) / 10, 1.0)
+            r = int(180 + 75 * intensity)
+            return f"color: rgb({r}, 40, 40);"
+        return "color: #2980b9;"
+    if isinstance(val, (np.integer, int)):
+        return "color: #27ae60;"
+    if isinstance(val, (np.bool_, bool)):
+        return "color: #8e44ad;" if val else "color: #8e44ad; opacity: 0.5;"
+    if isinstance(val, str):
+        return "color: #f39c12;"
+    if isinstance(val, (np.complexfloating, complex)):
+        return "color: #c0392b;"
+    return ""

arrscope/renderers/terminal.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import numpy as np
+from rich.box import SQUARE
+from rich.color import Color
+from rich.style import Style
+from rich.table import Table
+from rich.text import Text
+from rich.tree import Tree
+
+from arrscope._format import format_value
+from arrscope._types import VizNode
+
+
+def render_terminal(
+    node: VizNode,
+    color: bool = True,
+    mode: str = "dtype",
+    global_stats: dict | None = None,
+) -> str:
+    from rich.console import Console
+
+    console = Console(width=120, color_system="truecolor" if color else None)
+    parts: list = []
+
+    body = _render_node(node, 0, color, mode, global_stats)
+    parts.append(body)
+
+    if global_stats and node.stats:
+        parts.append(_stats_text(global_stats, color))
+
+    with console.capture() as capture:
+        for p in parts:
+            console.print(p)
+    return capture.get()
+
+
+def _stats_text(stats: dict, color: bool) -> Text:
+    dim = Style(dim=True, color="grey50") if color else Style(dim=True)
+    t = Text()
+    fmt = ".4f" if stats.get("dtype", "").startswith(("float", "int")) else ".4f"
+
+    def fmt_val(v):
+        if isinstance(v, float):
+            return format_value(v, fmt)
+        return str(v)
+
+    items = []
+    for key in ("min", "max", "mean", "std"):
+        if key in stats:
+            items.append(f"{key}={fmt_val(stats[key])}")
+
+    if "zero_count" in stats and "total" in stats:
+        pct = stats["zero_count"] / stats["total"] * 100
+        items.append(f"zeros={pct:.1f}%")
+
+    if "nan_count" in stats and stats["nan_count"] > 0:
+        items.append(f"NaN={stats['nan_count']}")
+
+    t.append("  " + "  ".join(items), style=dim)
+    return t
+
+
+def _render_node(
+    node: VizNode,
+    depth: int,
+    color: bool,
+    mode: str,
+    global_stats: dict | None,
+) -> Tree | Table | Text:
+    if node.grid_data is not None:
+        return _render_grid(node.grid_data, node.label, color, mode, global_stats)
+
+    if not node.children and node.truncated:
+        t = Text(f"  {node.label}")
+        t.stylize(Style(dim=True))
+        return t
+
+    tree = Tree(
+        _make_header(node, color),
+        guide_style=Style(dim=True, color="grey50") if color else Style(dim=True),
+    )
+    for child in node.children:
+        child_renderable = _render_node(child, depth + 1, color, mode, global_stats)
+        tree.add(child_renderable)
+    return tree
+
+
+def _make_header(node: VizNode, color: bool) -> Text:
+    parts = []
+    if node.label:
+        parts.append((node.label, "bold" if color else ""))
+    shape_str = " × ".join(str(s) for s in node.shape)
+    if shape_str:
+        dim_style = Style(dim=True, color="grey50") if color else Style(dim=True)
+        parts.append((f" ({shape_str})", dim_style))
+    t = Text()
+    for text, style in parts:
+        t.append(text, style=style)
+    return t
+
+
+def _render_grid(
+    data: np.ndarray,
+    label: str,
+    color: bool,
+    mode: str,
+    global_stats: dict | None,
+) -> Text | Table:
+    if data.ndim == 0:
+        return Text(format_value(data.item()))
+
+    if data.ndim == 1:
+        return _render_1d(data, color, mode, global_stats)
+
+    return _render_2d(data, label, color, mode, global_stats)
+
+
+def _render_1d(
+    data: np.ndarray,
+    color: bool,
+    mode: str,
+    global_stats: dict | None,
+) -> Text:
+    items = []
+    for v in data:
+        text = _format_cell(v, mode)
+        items.append(_style_value(text, v, color, mode, global_stats))
+
+    t = Text("[")
+    for i, item in enumerate(items):
+        if i > 0:
+            t.append(", ", Style(dim=True))
+        t.append(item)
+    t.append("]")
+    return t
+
+
+def _render_2d(
+    data: np.ndarray,
+    label: str,
+    color: bool,
+    mode: str,
+    global_stats: dict | None,
+) -> Table:
+    nrows, ncols = data.shape
+    table = Table(
+        show_header=False,
+        show_edge=True,
+        pad_edge=False,
+        box=SQUARE,
+        title=label if label else None,
+        min_width=min(ncols * 8 + 4, 120),
+    )
+
+    for _ in range(ncols):
+        table.add_column()
+
+    for row_idx in range(nrows):
+        row_cells = [
+            _style_value(
+                _format_cell(data[row_idx, col_idx], mode),
+                data[row_idx, col_idx],
+                color,
+                mode,
+                global_stats,
+            )
+            for col_idx in range(ncols)
+        ]
+        table.add_row(*row_cells)
+
+    return table
+
+
+def _format_cell(val, mode: str) -> str:
+    if mode == "sparsity" and _is_zero(val):
+        return "·"
+    return format_value(val)
+
+
+def _is_zero(val) -> bool:
+    if isinstance(val, (np.floating, float)):
+        return val == 0.0 or np.abs(val) < 1e-15
+    if isinstance(val, (np.integer, int)):
+        return val == 0
+    if isinstance(val, (np.bool_, bool)):
+        return not val
+    return val == 0
+
+
+def _style_value(
+    text: str,
+    val,
+    color: bool,
+    mode: str,
+    global_stats: dict | None,
+) -> Text:
+    if not color:
+        return Text(text)
+
+    if mode == "heatmap":
+        cell_style = _heatmap_color(val, global_stats)
+    elif mode == "sparsity":
+        cell_style = _sparsity_color(val)
+    else:
+        cell_style = _dtype_color(val)
+
+    return Text(text, style=cell_style)
+
+
+def _heatmap_color(val, global_stats: dict | None) -> Style:
+    if not global_stats:
+        return Style()
+
+    if isinstance(val, (np.floating, float)):
+        if np.isnan(val) or np.isinf(val):
+            return Style(color="red", bold=True)
+    if not isinstance(val, (np.floating, float, np.integer, int)):
+        return _dtype_color(val)
+
+    vmin = global_stats.get("min", 0.0)
+    vmax = global_stats.get("max", 1.0)
+    if vmax == vmin:
+        return Style(color="grey50")
+
+    t = (float(val) - vmin) / (vmax - vmin)
+    t = max(0.0, min(1.0, t))
+
+    # diverging colormap: dark red -> light -> dark blue
+    if t < 0.5:
+        t2 = t / 0.5  # 0..1
+        r = int(180 - 140 * t2)
+        g = int(30 + 210 * t2)
+        b = int(30 + 100 * t2)
+    else:
+        t2 = (t - 0.5) / 0.5  # 0..1
+        r = int(40 - 10 * t2)
+        g = int(240 - 200 * t2)
+        b = int(130 + 130 * t2)
+
+    return Style(color=Color.from_rgb(r, g, b))
+
+
+def _sparsity_color(val) -> Style:
+    if _is_zero(val):
+        return Style(dim=True, color="grey50")
+    if isinstance(val, (np.integer, int)):
+        return Style(color="green", bold=True)
+    if isinstance(val, (np.floating, float)):
+        return Style(color="cyan", bold=True)
+    if isinstance(val, (np.bool_, bool)):
+        return Style(color="magenta", bold=True)
+    return _dtype_color(val)
+
+
+def _dtype_color(val) -> Style:
+    if isinstance(val, (np.floating, float)):
+        if np.isnan(val) or np.isinf(val):
+            return Style(color="red", bold=True)
+        if val > 0:
+            intensity = min(abs(val) / 10, 1.0)
+            b = int(180 + 75 * intensity)
+            return Style(color=f"rgb(40,40,{b})")
+        if val < 0:
+            intensity = min(abs(val) / 10, 1.0)
+            r = int(180 + 75 * intensity)
+            return Style(color=f"rgb({r},40,40)")
+        return Style(color="cyan")
+    if isinstance(val, (np.integer, int)):
+        return Style(color="green")
+    if isinstance(val, (np.bool_, bool)):
+        return Style(color="magenta") if val else Style(color="magenta", dim=True)
+    if isinstance(val, str):
+        return Style(color="yellow")
+    if isinstance(val, (np.complexfloating, complex)):
+        return Style(color="red")
+    return Style()

arrscope-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: arrscope
+Version: 0.1.0
+Summary: Beautiful n-dimensional array visualization for Python
+Project-URL: Homepage, https://github.com/vizarray/arrscope
+Project-URL: Repository, https://github.com/vizarray/arrscope
+Author: arrscope contributors
+License: MIT
+Keywords: arrays,data-science,machine-learning,numpy,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: rich>=13.0
+Provides-Extra: jax
+Requires-Dist: jax>=0.4; extra == 'jax'
+Provides-Extra: tf
+Requires-Dist: tensorflow>=2.12; extra == 'tf'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# arrscope
+
+Beautiful n-dimensional array visualization for Python — in the terminal and Jupyter.
+
+```python
+from arrscope import scope
+import numpy as np
+
+scope(np.random.rand(2, 3, 8, 8), axes=['batch', 'heads', 'h', 'w'])
+```
+
+```
+├── [0] (3, 8, 8)
+│   ├── [0,0]: 8×8 grid
+│   ├── [0,1]: 8×8 grid
+│   └── [0,2]: 8×8 grid
+└── [1] (3, 8, 8)
+    ...
+  min=0.001  max=0.999  mean=0.5  std=0.29  zeros=0.0%
+```
+
+## Features
+
+- **1D → 6D+**: Tiered visual grammar — lists, grids, trees, collapsed hierarchies
+- **Named axes**: Attach semantics to dimensions (`batch`, `heads`, `h`, `w`)
+- **Configurable grid**: Pick which axes form the leaf 2D matrix
+- **Three color modes**:
+  - `dtype` — semantic colors by data type (float=blue, int=green, bool=magenta, …)
+  - `heatmap` — diverging colormap (red→light→blue) by value magnitude
+  - `sparsity` — zeros as `·`, non-zeros highlighted in bold
+- **Stats overlay**: min, max, mean, std, zero%, NaN count
+- **Head/tail truncation**: large dimensions show first/last N slices with `…`
+- **Smart precision**: auto-detects significant figures for floats
+- **Terminal + Jupyter**: Rich ANSI output + static HTML/CSS with dark mode
+- **Multi-framework**: NumPy, PyTorch, TensorFlow, JAX (lazy imports, no hard deps)
+
+## Install
+
+```bash
+pip install arrscope
+```
+
+Only requires `numpy` + `rich`. Torch/TF/JAX are optional — pass any array type, it just works.
+
+## Quick start
+
+```python
+from arrscope import scope
+import numpy as np
+
+# Auto-detect — last 2 dims form the grid
+scope(np.random.rand(3, 4, 5))
+
+# Named axes for clarity
+scope(
+    np.random.rand(2, 8, 32, 32),
+    axes=['batch', 'heads', 'h', 'w'],
+    grid=['h', 'w'],
+    title='Attention heads',
+)
+
+# Pick any dims as the leaf grid
+scope(data, axes=['a', 'b', 'c', 'd'], grid=['a', 'b'])
+```
+
+## Color modes
+
+```python
+scope(arr, mode='dtype')        # default — blue floats, green ints, etc.
+scope(arr, mode='heatmap')      # diverging colormap by value
+scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros
+```
+
+## Stats overlay
+
+Stats are shown by default. Hide with:
+
+```python
+scope(arr, stats=False)
+```
+
+Shows: `min=0.0  max=1.0  mean=0.5  std=0.29  zeros=12.5%`
+
+## Truncation
+
+```python
+scope(np.random.rand(100, 32, 32), max_height=8)
+```
+
+Shows first 4 + last 4 slices with `… (92 more)` in between.
+
+## Custom formatting
+
+```python
+scope(arr, fmt='.2f')          # fixed precision
+scope(arr, color=False)        # monochrome
+scope(arr, style='html')       # force HTML output in terminal
+```
+
+## CLI
+
+```bash
+# Install globally (ships with the library)
+pip install arrscope
+
+# Use from anywhere
+arrscope 3x4x5
+arrscope 2x3x32x32 --axes batch heads h w --grid h w --mode heatmap
+arrscope 20x4x5 --max-height 6 --no-stats
+```
+
+## Framework support
+
+Pass any array-like — conversion is automatic:
+
+```python
+import torch
+scope(torch.randn(2, 3, 4))          # PyTorch
+
+import tensorflow as tf
+scope(tf.random.uniform((2, 3, 4)))  # TensorFlow
+
+import jax.numpy as jnp
+scope(jnp.array([[1, 2], [3, 4]]))  # JAX
+```
+
+## API
+
+```python
+scope(
+    arr,                          # np.ndarray | torch.Tensor | tf.Tensor | jax.Array
+    axes=None,                    # list[str] — name each dimension
+    grid=None,                    # list[str | int] — which dims form the leaf grid
+    title=None,                   # str — heading above the visualization
+    max_width=None,               # int — max characters wide
+    max_height=None,              # int — max rows before truncation
+    fmt=None,                     # str — format spec like '.4f'
+    color=True,                   # bool — enable/disable color
+    mode='dtype',                 # 'dtype' | 'heatmap' | 'sparsity'
+    stats=True,                   # bool — show min/max/mean/std/zeros
+    style='auto',                 # 'auto' | 'terminal' | 'html'
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/vizarray/arrscope
+cd arrscope
+uv sync
+uv run pytest
+uv run python main.py          # demo script
+uv run jupyter notebook test.ipynb  # notebook demo
+```
+
+## License
+
+MIT

arrscope-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+arrscope/__init__.py,sha256=WxxdMd9gq_DC4AoZ5PMJLtVVBcrcUCsHJRQ5F1qZunc,99
+arrscope/__main__.py,sha256=oLxjmmAXtsPmhHO6SBSAu0Z3J3wmGScHyACOqTUL1K4,2051
+arrscope/_api.py,sha256=d75HggCQr8HhXMsJFn7-ARUw8Zv0NVL00DUiRzjoPAo,3521
+arrscope/_config.py,sha256=ZuaKcIqXbxRhikceYV5zM41OVV83js4O3mlbHd5ECTk,266
+arrscope/_format.py,sha256=fEnOuu_Q1jKJcivMiMX7Lt1I3IWYKE2KUSJwvmBnHGg,1741
+arrscope/_layout.py,sha256=EGnArvkslIRBBw_4RUSafgYnxHLtyRHnlkLwXmnEjvg,4270
+arrscope/_types.py,sha256=0ASV_Tlo6cKIdDX2L9deCYTxVS26VqTKDexesoYtyIE,840
+arrscope/adapters/__init__.py,sha256=y1WQxJmvO4rrIjqCFYgQLvnYcVwoHMEWSU8eIP9v1fU,69
+arrscope/adapters/_core.py,sha256=Q-zonVPFlWunNn_kIreFQPl_ePk2eLbeOyK5FxfsfdQ,841
+arrscope/renderers/__init__.py,sha256=he1exAHx6e375HpLPJ7kAq6AXC7Vi3lVmPyl_Hko32M,150
+arrscope/renderers/html.py,sha256=vEfai1eDOPDavAMn6Oeq2AMIKeI56J8Jt40SPaC945I,8251
+arrscope/renderers/terminal.py,sha256=lfhgYJfD8QGehwy65SAOmiD1cvCayFF8sWJnp4W20ZA,7493
+arrscope-0.1.0.dist-info/METADATA,sha256=lxSNw9gchfuuvJRO-cnkK5VZ9x4gYy8iqtAvz2wItDg,5177
+arrscope-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+arrscope-0.1.0.dist-info/entry_points.txt,sha256=PD1xqmqsAS6HwUKGcU6lCI-kifhDhsSW_gajRG-2pjM,52
+arrscope-0.1.0.dist-info/RECORD,,

arrscope-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

arrscope-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+arrscope = arrscope.__main__:main