arrscope 0.2.0__tar.gz → 0.4.0__tar.gz

arrscope-0.4.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: arrscope
+Version: 0.4.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, array diffing, and distribution sparklines.
+
+```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`)
+- **Four 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
+  - `diff` — compare with a reference array (red=increased, blue=decreased, grey=unchanged)
+- **Two render styles**:
+  - `tree` (default) — hierarchical branch view with colored guide lines
+  - `mosaic` — all 2D sub-slices tiled side by side as numeric tables
+- **Distribution sparkline**: every output shows a unicode histogram (`▁▂▃▄▅▆▇█`) of value distribution — replaces text stats
+- **Array diffing**: pass `reference=` to compare any two arrays. Color-coded per-cell changes + aggregate metrics (MSE, % changed)
+- **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'])
+
+# Method chaining
+r = scope(arr, mode='heatmap')
+print(r.tree())
+print(r.mosaic())
+```
+
+## Color modes
+
+```python
+scope(arr, mode='dtype')          # default — blue floats, green ints, ...
+scope(arr, mode='heatmap')        # diverging colormap by value
+scope(arr, mode='sparsity')       # · for zeros, bold for non-zeros
+scope(arr, mode='diff',           # red/blue by change direction
+      reference=original_array)   # Δ -0.5  ▁▂▃▄▅▆▇█  +0.5  mse=0.02  12% changed
+```
+
+## Array diffing
+
+Compare any two arrays of the same shape. Values show the current array; color encodes the change:
+
+```python
+before = np.random.rand(3, 4, 5)
+after  = before + np.random.normal(0, 0.1, before.shape)
+
+scope(after, reference=before, mode="diff")
+```
+
+Diff stats replace the sparkline: range of deltas, MSE, and percentage of elements that changed.
+
+## Render styles
+
+```python
+scope(arr)                        # tree (default) — click-to-expand layers
+scope(arr, render_style='mosaic') # all sub-slices tiled side by side
+```
+
+## 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' | 'diff'
+    render_style='tree',  # 'tree' | 'mosaic'
+    reference=None,       # array-like — reference for diff mode
+)
+```
+
+## 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.4.0/README.md

@@ -0,0 +1,141 @@
+# arrscope
+
+Visualize n-dimensional arrays in the terminal and Jupyter — with structural trees, tiled mosaics, array diffing, and distribution sparklines.
+
+```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`)
+- **Four 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
+  - `diff` — compare with a reference array (red=increased, blue=decreased, grey=unchanged)
+- **Two render styles**:
+  - `tree` (default) — hierarchical branch view with colored guide lines
+  - `mosaic` — all 2D sub-slices tiled side by side as numeric tables
+- **Distribution sparkline**: every output shows a unicode histogram (`▁▂▃▄▅▆▇█`) of value distribution — replaces text stats
+- **Array diffing**: pass `reference=` to compare any two arrays. Color-coded per-cell changes + aggregate metrics (MSE, % changed)
+- **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'])
+
+# Method chaining
+r = scope(arr, mode='heatmap')
+print(r.tree())
+print(r.mosaic())
+```
+
+## Color modes
+
+```python
+scope(arr, mode='dtype')          # default — blue floats, green ints, ...
+scope(arr, mode='heatmap')        # diverging colormap by value
+scope(arr, mode='sparsity')       # · for zeros, bold for non-zeros
+scope(arr, mode='diff',           # red/blue by change direction
+      reference=original_array)   # Δ -0.5  ▁▂▃▄▅▆▇█  +0.5  mse=0.02  12% changed
+```
+
+## Array diffing
+
+Compare any two arrays of the same shape. Values show the current array; color encodes the change:
+
+```python
+before = np.random.rand(3, 4, 5)
+after  = before + np.random.normal(0, 0.1, before.shape)
+
+scope(after, reference=before, mode="diff")
+```
+
+Diff stats replace the sparkline: range of deltas, MSE, and percentage of elements that changed.
+
+## Render styles
+
+```python
+scope(arr)                        # tree (default) — click-to-expand layers
+scope(arr, render_style='mosaic') # all sub-slices tiled side by side
+```
+
+## 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' | 'diff'
+    render_style='tree',  # 'tree' | 'mosaic'
+    reference=None,       # array-like — reference for diff mode
+)
+```
+
+## 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.4.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.2.0 → arrscope-0.4.0}/main.py

@@ -62,8 +62,8 @@ 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)
@@ -89,4 +89,9 @@ print(
     )
 )
 
+print("\n1️⃣6️⃣  DIFF — compare two arrays (value = current, color = change)")
+a = np.random.rand(4, 5)
+b = a + np.random.normal(0, 0.1, a.shape)
+print(scope(a, reference=b, mode="diff"))
+
 print("\n Done!")

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

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

{arrscope-0.2.0 → arrscope-0.4.0}/src/arrscope/_api.py

@@ -1,15 +1,11 @@
-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"]
+Mode = Literal["dtype", "heatmap", "sparsity", "diff"]
 RenderStyle = Literal["tree", "mosaic"]
 
 
@@ -19,14 +15,11 @@ def scope(
     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,
+    max_height: int | None = 20,
     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,
+    reference=None,
 ) -> VizOutput:
     """Visualize an n-dimensional array in the terminal and/or Jupyter.
 
@@ -45,41 +38,36 @@ def scope(
         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.
+            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.
-        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).
+            - ``"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. Best for
-              spotting value patterns.
+              scaled to the array's global min/max range.
             - ``"sparsity"`` — Zeros rendered as dim ``·``, non-zero
-              values in bold. Best for inspecting sparse or masked arrays.
+              values in bold.
+            - ``"diff"`` — Compare with a reference array. Values
+              colored red/blue by how much they increased/decreased.
+              Requires ``reference``.
 
-        render_style: Visual layout style:
+        render_style: Visual layout:
 
-            - ``"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).
+            - ``"tree"`` (default) — Hierarchical branch view with
+              click-to-expand nested layers.
+            - ``"mosaic"`` — All 2D sub-slices tiled side by side as
+              numeric tables.
 
-        stats: Show summary statistics below the tree (min, max, mean,
-            std, zeros %, NaN count). Defaults to ``True``.
+        reference: A reference array to compare against. Must have
+            the same shape as ``arr``. When provided, ``mode`` defaults
+            to ``"diff"`` and stats show difference metrics.
 
     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.
+        A ``VizOutput`` with ``.tree()`` and ``.mosaic()`` methods.
+        Renders as ANSI in the terminal and as HTML in Jupyter.
 
     Examples:
         >>> import numpy as np
@@ -88,59 +76,53 @@ def scope(
 
         >>> scope(np.eye(5), title="Identity", mode="sparsity")
 
-        >>> scope(
-        ...     np.random.rand(2, 8, 32, 32),
-        ...     axes=["batch", "heads", "h", "w"],
-        ...     mode="heatmap",
-        ... )
+        >>> a = np.random.rand(3, 4, 5)
+        >>> b = a + np.random.normal(0, 0.1, a.shape)
+        >>> scope(a, reference=b, mode="diff")
     """
     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 reference is not None:
+        ref_np = to_numpy(reference)
+        if ref_np.shape != arr_np.shape:
+            raise ValueError(
+                f"reference shape {ref_np.shape} does not match arr shape {arr_np.shape}"
+            )
+    else:
+        ref_np = None
+
+    mode = mode or ("diff" if ref_np is not None else "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 mode not in ("dtype", "heatmap", "sparsity", "diff"):
+        raise ValueError(f"Unknown mode '{mode}'. Expected: dtype, heatmap, sparsity, diff")
+
+    if mode == "diff" and ref_np is None:
+        raise ValueError("mode='diff' requires a reference array via the `reference` parameter")
 
     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()
 
-    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
-        )
+    def _render(style: str) -> VizOutput:
+        node = build_layout(arr_np, grid_dims=grid_dims, max_height=max_height, reference=ref_np)
+        gs = compute_stats(arr_np, reference=ref_np)
+        if gs:
+            node.stats = gs
 
-    if use_terminal:
-        output.ansi = _wrap_ansi(
-            render_terminal(node, color=color, mode=mode, global_stats=global_stats, render_style=rs), title
-        )
+        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 output
+    return _render(rs)
 
 
 def _resolve_grid_dims(
-    arr: np.ndarray,
+    arr,
     axes: list[str] | None,
     grid: list[str | int] | None,
 ) -> list[int] | None:
@@ -166,22 +148,6 @@ def _resolve_grid_dims(
     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

arrscope-0.4.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.2.0 → arrscope-0.4.0}/src/arrscope/_format.py

@@ -23,6 +23,18 @@ def format_value(val, fmt: str | None = None) -> str:
     return str(val)
 
 
+def sparkline(stats: dict) -> str:
+    """Return a unicode histogram sparkline from pre-computed bins."""
+    bins = stats.get("histogram")
+    if not bins:
+        return ""
+    mx = max(bins)
+    if mx == 0:
+        return "▁" * len(bins)
+    chars = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+    return "".join(chars[min(int(b / mx * 7), 7)] for b in bins)
+
+
 def _format_float(val: float, fmt: str | None) -> str:
     if fmt is not None:
         return f"{val:{fmt}}"