arrscope 0.1.0__tar.gz → 0.3.0__tar.gz

arrscope-0.3.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: arrscope
+Version: 0.3.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
+
+Visualize n-dimensional arrays in the terminal and Jupyter — with structural trees, tiled mosaics, and color-coded value maps.
+
+```python
+from arrscope import scope
+import numpy as np
+
+scope(np.random.rand(3, 4, 5))
+```
+
+## Features
+
+- **1D → 6D+**: Tiered visual grammar — lists, grids, trees, nested layers
+- **Named axes**: Attach semantics (`batch`, `heads`, `h`, `w`)
+- **Three color modes**:
+  - `dtype` — semantic colors by data type (blue=float, green=int, …)
+  - `heatmap` — diverging colormap (red → light → blue) by value
+  - `sparsity` — zeros as `·`, non-zeros in bold
+- **Two render styles**:
+  - `tree` (default) — hierarchical branch view with colored guide lines
+  - `mosaic` — all 2D sub-slices tiled side by side as numeric tables
+- **Method chaining**: `scope(arr, mode="heatmap").tree().mosaic()` — switch styles without re-specifying
+- **Stats overlay**: min, max, mean, std, zero%, NaN count (always shown)
+- **Head/tail truncation**: large dims show first/last N slices with `…` (default 20)
+- **Smart precision**: auto-detects significant figures for floats
+- **Terminal + Jupyter**: Rich ANSI + static HTML/CSS with dark mode auto-detect
+- **Multi-framework**: NumPy, PyTorch, TensorFlow, JAX, tinygrad (lazy imports)
+- **Zero config**: color always on, stats always on, auto-detect terminal vs notebook
+
+## Install
+
+```bash
+pip install arrscope
+```
+
+Only requires `numpy` + `rich`. Torch/TF/JAX/tinygrad are optional.
+
+## 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
+scope(
+    np.random.rand(2, 8, 32, 32),
+    axes=['batch', 'heads', 'h', 'w'],
+    grid=['h', 'w'],
+    title='Attention heads',
+)
+
+# Custom grid dims
+scope(data, axes=['a', 'b', 'c', 'd'], grid=['a', 'b'])
+```
+
+## Color modes
+
+```python
+scope(arr, mode='dtype')        # default
+scope(arr, mode='heatmap')      # diverging colormap
+scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros
+```
+
+## Render styles
+
+```python
+scope(arr)                        # tree (default) — click-to-expand layers
+scope(arr, render_style='mosaic') # all sub-slices tiled side by side
+
+# Method chaining for switching styles
+r = scope(arr, mode='heatmap')
+print(r.tree())
+print(r.mosaic())
+```
+
+## CLI
+
+```bash
+arrscope 3x4x5
+arrscope 2x3x32x32 --axes batch heads h w --grid h w --mode heatmap
+arrscope 20x4x5 --max-height 6
+```
+
+## Framework support
+
+```python
+import torch
+scope(torch.randn(2, 3, 4))
+
+import tensorflow as tf
+scope(tf.random.uniform((2, 3, 4)))
+
+import jax.numpy as jnp
+scope(jnp.array([[1, 2], [3, 4]]))
+
+from tinygrad import Tensor
+scope(Tensor.randn(3, 4))
+```
+
+## API
+
+```python
+scope(
+    arr,
+    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_height=20,        # int | None — rows before truncation, None disables
+    fmt=None,             # str — format spec like '.4f'
+    mode='dtype',         # 'dtype' | 'heatmap' | 'sparsity'
+    render_style='tree',  # 'tree' | 'mosaic'
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/vizarray/arrscope
+cd arrscope
+uv sync
+uv run pytest
+uv run python main.py
+```
+
+## License
+
+MIT

arrscope-0.3.0/README.md

@@ -0,0 +1,131 @@
+# arrscope
+
+Visualize n-dimensional arrays in the terminal and Jupyter — with structural trees, tiled mosaics, and color-coded value maps.
+
+```python
+from arrscope import scope
+import numpy as np
+
+scope(np.random.rand(3, 4, 5))
+```
+
+## Features
+
+- **1D → 6D+**: Tiered visual grammar — lists, grids, trees, nested layers
+- **Named axes**: Attach semantics (`batch`, `heads`, `h`, `w`)
+- **Three color modes**:
+  - `dtype` — semantic colors by data type (blue=float, green=int, …)
+  - `heatmap` — diverging colormap (red → light → blue) by value
+  - `sparsity` — zeros as `·`, non-zeros in bold
+- **Two render styles**:
+  - `tree` (default) — hierarchical branch view with colored guide lines
+  - `mosaic` — all 2D sub-slices tiled side by side as numeric tables
+- **Method chaining**: `scope(arr, mode="heatmap").tree().mosaic()` — switch styles without re-specifying
+- **Stats overlay**: min, max, mean, std, zero%, NaN count (always shown)
+- **Head/tail truncation**: large dims show first/last N slices with `…` (default 20)
+- **Smart precision**: auto-detects significant figures for floats
+- **Terminal + Jupyter**: Rich ANSI + static HTML/CSS with dark mode auto-detect
+- **Multi-framework**: NumPy, PyTorch, TensorFlow, JAX, tinygrad (lazy imports)
+- **Zero config**: color always on, stats always on, auto-detect terminal vs notebook
+
+## Install
+
+```bash
+pip install arrscope
+```
+
+Only requires `numpy` + `rich`. Torch/TF/JAX/tinygrad are optional.
+
+## 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
+scope(
+    np.random.rand(2, 8, 32, 32),
+    axes=['batch', 'heads', 'h', 'w'],
+    grid=['h', 'w'],
+    title='Attention heads',
+)
+
+# Custom grid dims
+scope(data, axes=['a', 'b', 'c', 'd'], grid=['a', 'b'])
+```
+
+## Color modes
+
+```python
+scope(arr, mode='dtype')        # default
+scope(arr, mode='heatmap')      # diverging colormap
+scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros
+```
+
+## Render styles
+
+```python
+scope(arr)                        # tree (default) — click-to-expand layers
+scope(arr, render_style='mosaic') # all sub-slices tiled side by side
+
+# Method chaining for switching styles
+r = scope(arr, mode='heatmap')
+print(r.tree())
+print(r.mosaic())
+```
+
+## CLI
+
+```bash
+arrscope 3x4x5
+arrscope 2x3x32x32 --axes batch heads h w --grid h w --mode heatmap
+arrscope 20x4x5 --max-height 6
+```
+
+## Framework support
+
+```python
+import torch
+scope(torch.randn(2, 3, 4))
+
+import tensorflow as tf
+scope(tf.random.uniform((2, 3, 4)))
+
+import jax.numpy as jnp
+scope(jnp.array([[1, 2], [3, 4]]))
+
+from tinygrad import Tensor
+scope(Tensor.randn(3, 4))
+```
+
+## API
+
+```python
+scope(
+    arr,
+    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_height=20,        # int | None — rows before truncation, None disables
+    fmt=None,             # str — format spec like '.4f'
+    mode='dtype',         # 'dtype' | 'heatmap' | 'sparsity'
+    render_style='tree',  # 'tree' | 'mosaic'
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/vizarray/arrscope
+cd arrscope
+uv sync
+uv run pytest
+uv run python main.py
+```
+
+## License
+
+MIT

arrscope-0.3.0/examples/renders.py

@@ -0,0 +1,71 @@
+"""arrscope render style examples.
+
+Run this file to see both render styles in action.
+Use method chaining to switch styles without re-specifying params.
+
+Usage:
+    uv run python examples/renders.py
+"""
+
+import numpy as np
+
+from arrscope import scope
+
+# ── data ──────────────────────────────────────────────────────────────
+arr_3d = np.arange(60).reshape(3, 4, 5).astype(float)
+eye = np.eye(8)
+sparse = np.zeros((6, 8), dtype=float)
+sparse[0, 0] = 1.5
+sparse[2, 3] = -2.3
+sparse[4, 5] = 42.0
+sparse[5, 7] = 0.7
+
+
+# ── individual calls ──────────────────────────────────────────────────
+print("=" * 56)
+print("1  tree  — hierarchical branch view (default)")
+print("=" * 56)
+print(scope(arr_3d, render_style="tree"))
+
+print("=" * 56)
+print("2  mosaic  — numeric tables tiled side by side")
+print("=" * 56)
+print(scope(arr_3d, render_style="mosaic"))
+
+
+# ── method chaining ───────────────────────────────────────────────────
+print("=" * 56)
+print("3  method chaining  —  scope().tree() / .mosaic()")
+print("=" * 56)
+
+r = scope(eye, title="Identity", mode="heatmap")
+
+print("--- .tree() ---")
+print(r.tree())
+
+print("--- .mosaic() ---")
+print(r.mosaic())
+
+
+# ── all three modes with mosaic ──────────────────────────────────────
+print("=" * 56)
+print("4  mosaic + all three color modes")
+print("=" * 56)
+
+print("--- dtype ---")
+print(scope(sparse, render_style="mosaic", mode="dtype"))
+
+print("--- heatmap ---")
+print(scope(sparse, render_style="mosaic", mode="heatmap"))
+
+print("--- sparsity ---")
+print(scope(sparse, render_style="mosaic", mode="sparsity"))
+
+
+# ── large array in mosaic ────────────────────────────────────────────
+print("=" * 56)
+print("5  large array —  (8, 8, 8)  as mosaic + heatmap")
+print("=" * 56)
+print(scope(np.random.rand(8, 8, 8), render_style="mosaic", mode="heatmap"))
+
+print("\nDone!")

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

@@ -62,7 +62,31 @@ print(scope(sparse, mode="sparsity"))
 print("\n1️⃣2️⃣  HEATMAP + 3D + global stats")
 print(scope(np.random.rand(2, 3, 4), mode="heatmap"))
 
-print("\n1️⃣3️⃣  STATS OFF")
-print(scope(np.eye(5), stats=False))
+print("\n1️⃣3️⃣  TRUNCATION OFF (max_height=None)")
+print(scope(np.arange(60).reshape(3, 4, 5).astype(float), max_height=None))
+
+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.3.0}/pyproject.toml

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

arrscope-0.3.0/src/arrscope/_api.py

@@ -0,0 +1,157 @@
+from typing import Literal
+
+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_height: int | None = 20,
+    fmt: str | None = None,
+    mode: Mode | None = None,
+    render_style: RenderStyle | 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.
+            Defaults to 20. Set to ``None`` to disable truncation.
+        fmt: Format spec for float values, e.g. ``".4f"``, ``".2e"``.
+            Auto-detected from value range when not set.
+        mode: Colorization strategy:
+
+            - ``"dtype"`` (default) — Semantic colors by data type
+              (blue=float, green=int, magenta=bool, yellow=str).
+              Negative values tinted red, positive tinted blue.
+            - ``"heatmap"`` — Diverging colormap (red → light → blue)
+              scaled to the array's global min/max range.
+            - ``"sparsity"`` — Zeros rendered as dim ``·``, non-zero
+              values in bold.
+
+        render_style: Visual layout:
+
+            - ``"tree"`` (default) — Hierarchical branch view with
+              click-to-expand nested layers.
+            - ``"mosaic"`` — All 2D sub-slices tiled side by side as
+              numeric tables.
+
+    Returns:
+        A ``VizOutput`` with ``.ansi`` and ``.html`` attributes.
+        Use ``.tree()`` or ``.mosaic()`` to switch render styles
+        without re-specifying parameters.
+
+    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)
+
+    mode = mode or "dtype"
+    rs = render_style or "tree"
+
+    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)
+    use_html = _in_jupyter()
+
+    def _render(style: str) -> VizOutput:
+        node = build_layout(arr_np, grid_dims=grid_dims, max_height=max_height)
+        gs = compute_stats(arr_np)
+        if gs:
+            node.stats = gs
+
+        out = VizOutput(_rerender=_render)
+        if use_html:
+            out.html = _wrap_html(render_html(node, mode=mode, global_stats=gs, render_style=style), title)
+        out.ansi = _wrap_ansi(render_terminal(node, mode=mode, global_stats=gs, render_style=style), title)
+        return out
+
+    return _render(rs)
+
+
+def _resolve_grid_dims(
+    arr,
+    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 _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.3.0/src/arrscope/_config.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    mode: str = "dtype"
+    render_style: str = "tree"  # tree | mosaic
+
+
+config: Config = Config()

{arrscope-0.1.0 → arrscope-0.3.0}/src/arrscope/_types.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass, field
 
 import numpy as np
@@ -18,11 +19,15 @@ class VizNode:
     stats: dict | None = None
 
 
+_RerenderFn = Callable[[str], "VizOutput"]
+
+
 @dataclass
 class VizOutput:
     html: str = ""
     ansi: str = ""
     metadata: dict = field(default_factory=dict)
+    _rerender: _RerenderFn | None = None
 
     def _repr_html_(self) -> str:
         return self.html
@@ -37,3 +42,9 @@ class VizOutput:
 
     def __repr__(self) -> str:
         return self.ansi
+
+    def tree(self) -> VizOutput:
+        return self._rerender("tree") if self._rerender else self
+
+    def mosaic(self) -> VizOutput:
+        return self._rerender("mosaic") if self._rerender else self

{arrscope-0.1.0 → arrscope-0.3.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.3.0}/src/arrscope/renderers/html.py

@@ -10,12 +10,16 @@ from arrscope._types import VizNode
 
 def render_html(
     node: VizNode,
-    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 +32,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 {
@@ -125,7 +155,7 @@ def _render_node_html(
     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
+    is_large_tree = depth > 0 and len(node.children) > 0
 
     parts: list[str] = []
     if depth == 0: