arrscope 0.1.0__tar.gz → 0.2.0__tar.gz

{arrscope-0.1.0 → arrscope-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrscope
-Version: 0.1.0
+Version: 0.2.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

{arrscope-0.1.0 → arrscope-0.2.0}/main.py

@@ -65,4 +65,28 @@ print(scope(np.random.rand(2, 3, 4), mode="heatmap"))
 print("\n1️⃣3️⃣  STATS OFF")
 print(scope(np.eye(5), stats=False))
 
+print("\n1️⃣4️⃣  MOSAIC — 3×4×5 tiled (no tree)")
+arr = np.arange(60).reshape(3, 4, 5).astype(float)
+print(scope(arr, render_style="mosaic"))
+
+print("\n1️⃣5️⃣  MOSAIC — 4D with named axes tiled side by side")
+print(
+    scope(
+        np.random.rand(2, 3, 6, 6),
+        axes=["batch", "heads", "h", "w"],
+        grid=["h", "w"],
+        title="Mosaic: 2×3 attention heads",
+        render_style="mosaic",
+    )
+)
+
+print("\n1️⃣6️⃣  MOSAIC + HEATMAP — tiled grids with diverging colors")
+print(
+    scope(
+        np.random.rand(2, 4, 5, 5),
+        render_style="mosaic",
+        mode="heatmap",
+    )
+)
+
 print("\n Done!")

{arrscope-0.1.0 → arrscope-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrscope"
-version = "0.1.0"
+version = "0.2.0"
 description = "Beautiful n-dimensional array visualization for Python"
 readme = "README.md"
 license = { text = "MIT" }

arrscope-0.2.0/src/arrscope/_api.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from typing import Literal
+
+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
+
+Mode = Literal["dtype", "heatmap", "sparsity"]
+RenderStyle = Literal["tree", "mosaic"]
+
+
+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: Literal["auto", "terminal", "html"] = "auto",
+    mode: Mode | None = None,
+    render_style: RenderStyle | None = None,
+    stats: bool | None = None,
+) -> VizOutput:
+    """Visualize an n-dimensional array in the terminal and/or Jupyter.
+
+    Renders a structural tree view with 2D value grids at the leaves.
+    Works with NumPy, PyTorch, TensorFlow, JAX, and tinygrad arrays.
+
+    Args:
+        arr: The array to visualize. Accepts np.ndarray, torch.Tensor,
+            tf.Tensor, jax.Array, tinygrad.Tensor, or any object
+            implementing ``__array__``.
+        axes: Names for each dimension, e.g. ``["batch", "heads", "h", "w"]``.
+            Used in headers and for ``grid`` axis selection by name.
+        grid: Which dimensions form the leaf 2D grid. Given as axis indices
+            (``[0, 1]``), axis names (``["h", "w"]``), or omitted to
+            default to the last two dimensions.
+        title: Optional heading displayed above the visualization.
+        max_height: Max tree rows before truncation. The first half and
+            last half of children are shown with ``... (N more)`` in between.
+        max_width: Max character width (terminal only). Not yet enforced.
+        fmt: Format spec for float values, e.g. ``".4f"``, ``".2e"``.
+            Auto-detected from value range when not set.
+        color: Enable or disable ANSI / CSS color output.
+            Defaults to ``True``.
+        style: Output target. ``"auto"`` detects Jupyter and renders
+            HTML there, ANSI elsewhere. ``"terminal"`` forces ANSI,
+            ``"html"`` forces HTML.
+        mode: Colorization strategy:
+
+            - ``"dtype"`` — Semantic colors by data type (blue=float,
+              green=int, magenta=bool, yellow=str, red=complex).
+              Negative values tinted red, positive tinted blue.
+            - ``"heatmap"`` — Diverging colormap (red → light → blue)
+              scaled to the array's global min/max range. Best for
+              spotting value patterns.
+            - ``"sparsity"`` — Zeros rendered as dim ``·``, non-zero
+              values in bold. Best for inspecting sparse or masked arrays.
+
+        render_style: Visual layout style:
+
+            - ``"tree"`` (default) — Hierarchical branch view with 2D
+              grids nested at the leaves. Each depth level gets a
+              distinct branch color for readability.
+            - ``"mosaic"`` — All 2D sub-slices tiled side by side in a
+              contact-sheet grid. Best for comparing slices in 3D/4D
+              arrays (batches, attention heads, channels).
+
+        stats: Show summary statistics below the tree (min, max, mean,
+            std, zeros %, NaN count). Defaults to ``True``.
+
+    Returns:
+        A ``VizOutput`` object with ``.ansi`` (str) and ``.html`` (str)
+        attributes. In Jupyter it auto-displays via ``_repr_html_``.
+        In the terminal, ``print()`` or ``str()`` renders the ANSI output.
+
+    Examples:
+        >>> import numpy as np
+        >>> from arrscope import scope
+        >>> scope(np.random.rand(3, 4, 5))
+
+        >>> scope(np.eye(5), title="Identity", mode="sparsity")
+
+        >>> scope(
+        ...     np.random.rand(2, 8, 32, 32),
+        ...     axes=["batch", "heads", "h", "w"],
+        ...     mode="heatmap",
+        ... )
+    """
+    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
+    rs = render_style or config.render_style
+    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")
+
+    if rs not in ("tree", "mosaic"):
+        raise ValueError(f"Unknown render_style '{rs}'. Expected one of: tree, mosaic")
+
+    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, render_style=rs), title
+        )
+
+    if use_terminal:
+        output.ansi = _wrap_ansi(
+            render_terminal(node, color=color, mode=mode, global_stats=global_stats, render_style=rs), 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-0.1.0 → arrscope-0.2.0}/src/arrscope/_config.py

@@ -1,4 +1,4 @@
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 
 
 @dataclass
@@ -8,6 +8,7 @@ class Config:
     color: bool = True
     precision: int | None = None
     mode: str = "dtype"
+    render_style: str = "tree"
     stats: bool = True
 
 

{arrscope-0.1.0 → arrscope-0.2.0}/src/arrscope/adapters/_core.py

@@ -23,11 +23,14 @@ def to_numpy(arr) -> np.ndarray:
     if "jax" in module:
         return np.asarray(arr)
 
+    if "tinygrad" in module:
+        return arr.numpy()
+
     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__."
+            f"tinygrad.Tensor, and objects implementing __array__."
         ) from e

{arrscope-0.1.0 → arrscope-0.2.0}/src/arrscope/renderers/html.py

@@ -13,9 +13,14 @@ def render_html(
     color: bool = True,
     mode: str = "dtype",
     global_stats: dict | None = None,
+    render_style: str = "tree",
 ) -> str:
     css = _css()
-    body = _render_node_html(node, 0, mode, global_stats)
+
+    if render_style == "mosaic":
+        body = _render_mosaic_html(node, mode, global_stats)
+    else:
+        body = _render_node_html(node, 0, mode, global_stats)
 
     stats_html = ""
     if global_stats and node.stats:
@@ -28,6 +33,32 @@ def render_html(
 </div>"""
 
 
+def _collect_leaves(node: VizNode) -> list[VizNode]:
+    if node.grid_data is not None:
+        return [node]
+    leaves: list[VizNode] = []
+    for child in node.children:
+        leaves.extend(_collect_leaves(child))
+    return leaves
+
+
+def _render_mosaic_html(
+    node: VizNode,
+    mode: str,
+    global_stats: dict | None,
+) -> str:
+    leaves = _collect_leaves(node)
+    if not leaves:
+        return "<span>(empty)</span>"
+
+    tiles: list[str] = []
+    for leaf in leaves:
+        if leaf.grid_data is not None:
+            tiles.append(_render_grid_html(leaf.grid_data, leaf.label, mode, global_stats))
+
+    return '<div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: flex-start;">' + "".join(tiles) + "</div>"
+
+
 def _css() -> str:
     return """
 .arrscope-wrapper {
@@ -63,6 +94,13 @@ def _css() -> str:
 }
 .arrscope-row { display: flex; flex-wrap: wrap; gap: 12px; }
 .arrscope-tree { margin-left: 16px; }
+.arrscope-level-0 { }
+.arrscope-level-1 { border-left: 2px solid #00bcd4; padding-left: 8px; }
+.arrscope-level-2 { border-left: 2px solid #4caf50; padding-left: 8px; }
+.arrscope-level-3 { border-left: 2px solid #ffc107; padding-left: 8px; }
+.arrscope-level-4 { border-left: 2px solid #e91e63; padding-left: 8px; }
+.arrscope-level-5 { border-left: 2px solid #9c27b0; padding-left: 8px; }
+.arrscope-level-6 { border-left: 2px solid #2196f3; padding-left: 8px; }
 .arrscope-ellipsis { color: #999; font-style: italic; margin: 2px 0; }
 .arrscope-header {
     font-weight: 600;
@@ -95,6 +133,12 @@ details.arrscope-details[open] > summary {
     .arrscope-shape { color: #777; }
     .arrscope-stats { color: #999; }
     .arrscope-header { border-bottom-color: #444; }
+    .arrscope-level-1 { border-left-color: #26c6da; }
+    .arrscope-level-2 { border-left-color: #66bb6a; }
+    .arrscope-level-3 { border-left-color: #ffd54f; }
+    .arrscope-level-4 { border-left-color: #f06292; }
+    .arrscope-level-5 { border-left-color: #ab47bc; }
+    .arrscope-level-6 { border-left-color: #42a5f5; }
 }
 """
 
@@ -140,7 +184,8 @@ def _render_node_html(
         parts.append(
             f"<summary>{html_mod.escape(node.label or _format_header(node))}</summary>"
         )
-        parts.append('<div class="arrscope-tree">')
+        level_class = f"arrscope-level-{(depth + 1) % 7}"
+        parts.append(f'<div class="arrscope-tree {level_class}">')
 
     for child in node.children:
         parts.append(_render_node_html(child, depth + 1, mode, global_stats))

{arrscope-0.1.0 → arrscope-0.2.0}/src/arrscope/renderers/terminal.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import numpy as np
 from rich.box import SQUARE
 from rich.color import Color
+from rich.columns import Columns
 from rich.style import Style
 from rich.table import Table
 from rich.text import Text
@@ -11,19 +12,25 @@ from rich.tree import Tree
 from arrscope._format import format_value
 from arrscope._types import VizNode
 
+BRANCH_COLORS = ["grey50", "cyan", "green", "yellow", "magenta", "blue"]
+
 
 def render_terminal(
     node: VizNode,
     color: bool = True,
     mode: str = "dtype",
     global_stats: dict | None = None,
+    render_style: str = "tree",
 ) -> 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)
+    if render_style == "mosaic":
+        body = _render_mosaic(node, color, mode, global_stats)
+    else:
+        body = _render_node(node, 0, color, mode, global_stats)
     parts.append(body)
 
     if global_stats and node.stats:
@@ -35,6 +42,34 @@ def render_terminal(
     return capture.get()
 
 
+def _collect_leaves(node: VizNode) -> list[VizNode]:
+    if node.grid_data is not None:
+        return [node]
+    leaves: list[VizNode] = []
+    for child in node.children:
+        leaves.extend(_collect_leaves(child))
+    return leaves
+
+
+def _render_mosaic(
+    node: VizNode,
+    color: bool,
+    mode: str,
+    global_stats: dict | None,
+) -> Columns | Text:
+    leaves = _collect_leaves(node)
+    if not leaves:
+        return Text("(empty)")
+
+    tables: list[Table] = []
+    for leaf in leaves:
+        if leaf.grid_data is not None:
+            t = _render_grid(leaf.grid_data, leaf.label, color, mode, global_stats)
+            tables.append(t)
+
+    return Columns(tables, equal=True, expand=False)
+
+
 def _stats_text(stats: dict, color: bool) -> Text:
     dim = Style(dim=True, color="grey50") if color else Style(dim=True)
     t = Text()
@@ -76,9 +111,12 @@ def _render_node(
         t.stylize(Style(dim=True))
         return t
 
+    guide_color = BRANCH_COLORS[(depth) % len(BRANCH_COLORS)]
+    guide = Style(dim=True, color=guide_color) if color else Style(dim=True)
+
     tree = Tree(
         _make_header(node, color),
-        guide_style=Style(dim=True, color="grey50") if color else Style(dim=True),
+        guide_style=guide,
     )
     for child in node.children:
         child_renderable = _render_node(child, depth + 1, color, mode, global_stats)

arrscope-0.1.0/src/arrscope/_api.py

@@ -1,131 +0,0 @@
-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