arrscope 0.3.0__tar.gz → 0.4.0__tar.gz

{arrscope-0.3.0 → arrscope-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrscope
-Version: 0.3.0
+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
@@ -27,7 +27,7 @@ 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.
+Visualize n-dimensional arrays in the terminal and Jupyter — with structural trees, tiled mosaics, array diffing, and distribution sparklines.
 
 ```python
 from arrscope import scope
@@ -40,15 +40,16 @@ scope(np.random.rand(3, 4, 5))
 
 - **1D → 6D+**: Tiered visual grammar — lists, grids, trees, nested layers
 - **Named axes**: Attach semantics (`batch`, `heads`, `h`, `w`)
-- **Three color modes**:
+- **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
-- **Method chaining**: `scope(arr, mode="heatmap").tree().mosaic()` — switch styles without re-specifying
-- **Stats overlay**: min, max, mean, std, zero%, NaN count (always shown)
+- **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
@@ -82,26 +83,41 @@ scope(
 
 # 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
-scope(arr, mode='heatmap')      # diverging colormap
-scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros
+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
-
-# Method chaining for switching styles
-r = scope(arr, mode='heatmap')
-print(r.tree())
-print(r.mosaic())
 ```
 
 ## CLI
@@ -115,17 +131,10 @@ 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))
+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
@@ -138,8 +147,9 @@ scope(
     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'
+    mode='dtype',         # 'dtype' | 'heatmap' | 'sparsity' | 'diff'
     render_style='tree',  # 'tree' | 'mosaic'
+    reference=None,       # array-like — reference for diff mode
 )
 ```
 

{arrscope-0.3.0 → arrscope-0.4.0}/README.md

@@ -1,6 +1,6 @@
 # arrscope
 
-Visualize n-dimensional arrays in the terminal and Jupyter — with structural trees, tiled mosaics, and color-coded value maps.
+Visualize n-dimensional arrays in the terminal and Jupyter — with structural trees, tiled mosaics, array diffing, and distribution sparklines.
 
 ```python
 from arrscope import scope
@@ -13,15 +13,16 @@ scope(np.random.rand(3, 4, 5))
 
 - **1D → 6D+**: Tiered visual grammar — lists, grids, trees, nested layers
 - **Named axes**: Attach semantics (`batch`, `heads`, `h`, `w`)
-- **Three color modes**:
+- **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
-- **Method chaining**: `scope(arr, mode="heatmap").tree().mosaic()` — switch styles without re-specifying
-- **Stats overlay**: min, max, mean, std, zero%, NaN count (always shown)
+- **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
@@ -55,26 +56,41 @@ scope(
 
 # 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
-scope(arr, mode='heatmap')      # diverging colormap
-scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros
+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
-
-# Method chaining for switching styles
-r = scope(arr, mode='heatmap')
-print(r.tree())
-print(r.mosaic())
 ```
 
 ## CLI
@@ -88,17 +104,10 @@ 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))
+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
@@ -111,8 +120,9 @@ scope(
     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'
+    mode='dtype',         # 'dtype' | 'heatmap' | 'sparsity' | 'diff'
     render_style='tree',  # 'tree' | 'mosaic'
+    reference=None,       # array-like — reference for diff mode
 )
 ```
 

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

@@ -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.3.0 → arrscope-0.4.0}/pyproject.toml

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

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

@@ -1,12 +1,11 @@
 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"]
+Mode = Literal["dtype", "heatmap", "sparsity", "diff"]
 RenderStyle = Literal["tree", "mosaic"]
 
 
@@ -20,6 +19,7 @@ def scope(
     fmt: str | None = None,
     mode: Mode | None = None,
     render_style: RenderStyle | None = None,
+    reference=None,
 ) -> VizOutput:
     """Visualize an n-dimensional array in the terminal and/or Jupyter.
 
@@ -50,6 +50,9 @@ def scope(
               scaled to the array's global min/max range.
             - ``"sparsity"`` — Zeros rendered as dim ``·``, non-zero
               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:
 
@@ -58,10 +61,13 @@ def scope(
             - ``"mosaic"`` — All 2D sub-slices tiled side by side as
               numeric tables.
 
+        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`` with ``.ansi`` and ``.html`` attributes.
-        Use ``.tree()`` or ``.mosaic()`` to switch render styles
-        without re-specifying parameters.
+        A ``VizOutput`` with ``.tree()`` and ``.mosaic()`` methods.
+        Renders as ANSI in the terminal and as HTML in Jupyter.
 
     Examples:
         >>> import numpy as np
@@ -70,19 +76,29 @@ 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)
 
-    mode = mode or "dtype"
+    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")
@@ -91,15 +107,15 @@ def scope(
     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)
+        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
 
         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)
+            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)

{arrscope-0.3.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}}"

{arrscope-0.3.0 → arrscope-0.4.0}/src/arrscope/_layout.py

@@ -12,6 +12,7 @@ def build_layout(
     *,
     grid_dims: list[int] | None = None,
     max_height: int | None = None,
+    reference: np.ndarray | None = None,
 ) -> VizNode:
     shape = arr.shape
     ndim = len(shape)
@@ -21,16 +22,31 @@ def build_layout(
 
     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 = _build_tree(arr, non_grid, grid_dims, (), max_height, reference)
     root.shape = shape
     root.label = _shape_label(shape, arr.dtype)
     return root
 
 
-def compute_stats(arr: np.ndarray) -> dict:
+def compute_stats(arr: np.ndarray, reference: np.ndarray | None = None) -> dict:
     flat = arr.ravel()
     stats: dict = {}
 
+    if reference is not None:
+        ref_flat = reference.ravel()
+        diff = flat.astype(float) - ref_flat.astype(float)
+        finite_diff = diff[np.isfinite(diff)]
+        if len(finite_diff) > 0:
+            stats["max_abs_diff"] = float(np.max(np.abs(finite_diff)))
+            stats["mse"] = float(np.mean(finite_diff ** 2))
+            stats["pct_changed"] = float(np.mean(np.abs(diff) > 1e-15) * 100)
+            hist, edges = np.histogram(finite_diff, bins=10)
+            stats["histogram"] = hist.tolist()
+            stats["hist_min"] = float(edges[0])
+            stats["hist_max"] = float(edges[-1])
+        stats["dtype"] = str(arr.dtype)
+        return stats
+
     if np.issubdtype(arr.dtype, np.floating) or np.issubdtype(arr.dtype, np.integer):
         finite = flat[np.isfinite(flat)]
         if len(finite) > 0:
@@ -38,6 +54,10 @@ def compute_stats(arr: np.ndarray) -> dict:
             stats["max"] = float(finite.max())
             stats["mean"] = float(finite.mean())
             stats["std"] = float(finite.std())
+            hist, edges = np.histogram(finite, bins=10)
+            stats["histogram"] = hist.tolist()
+            stats["hist_min"] = float(edges[0])
+            stats["hist_max"] = float(edges[-1])
         else:
             stats["min"] = stats["max"] = stats["mean"] = stats["std"] = float("nan")
     elif np.issubdtype(arr.dtype, np.bool_):
@@ -64,13 +84,18 @@ def _build_tree(
     grid_dims: list[int],
     indices: tuple[int, ...],
     max_height: int | None,
+    reference: np.ndarray | None = None,
 ) -> VizNode:
     if not non_grid:
+        ref = None
+        if reference is not None:
+            ref = reference
         return VizNode(
             indices=indices,
             label=_indices_label(indices),
             shape=arr.shape,
             grid_data=arr,
+            ref_data=ref,
         )
 
     current_dim = non_grid[0]
@@ -99,10 +124,11 @@ def _build_tree(
 
         child_indices = indices + (i,)
         child_arr = _slice_dim(arr, current_dim, i)
+        child_ref = _slice_dim(reference, current_dim, i) if reference is not None else None
 
         new_remaining = _adjust_indices(remaining, current_dim)
         child = _build_tree(
-            child_arr, new_remaining, grid_dims, child_indices, max_height
+            child_arr, new_remaining, grid_dims, child_indices, max_height, child_ref
         )
         children.append(child)
 

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

@@ -13,6 +13,7 @@ class VizNode:
     shape: tuple[int, ...] = ()
     children: list[VizNode] = field(default_factory=list)
     grid_data: np.ndarray | None = None
+    ref_data: np.ndarray | None = None
     truncated: bool = False
     truncated_head: int = 0
     truncated_tail: int = 0
@@ -24,24 +25,26 @@ _RerenderFn = Callable[[str], "VizOutput"]
 
 @dataclass
 class VizOutput:
-    html: str = ""
-    ansi: str = ""
-    metadata: dict = field(default_factory=dict)
+    _html: str = ""
+    _ansi: str = ""
     _rerender: _RerenderFn | None = None
 
     def _repr_html_(self) -> str:
-        return self.html
+        return self._html
 
     def __rich_console__(self, console, options):
         from rich.text import Text
 
-        yield Text.from_ansi(self.ansi)
+        yield Text.from_ansi(self._ansi)
 
     def __str__(self) -> str:
-        return self.ansi
+        return self._ansi
 
     def __repr__(self) -> str:
-        return self.ansi
+        return self._ansi
+
+    def __dir__(self) -> list[str]:
+        return ["tree", "mosaic"]
 
     def tree(self) -> VizOutput:
         return self._rerender("tree") if self._rerender else self

{arrscope-0.3.0 → arrscope-0.4.0}/src/arrscope/renderers/html.py

@@ -4,7 +4,7 @@ import html as html_mod
 
 import numpy as np
 
-from arrscope._format import format_value
+from arrscope._format import format_value, sparkline
 from arrscope._types import VizNode
 
 
@@ -23,7 +23,7 @@ def render_html(
 
     stats_html = ""
     if global_stats and node.stats:
-        stats_html = _stats_html(global_stats)
+        stats_html = _stats_sparkline_html(global_stats, mode)
 
     return f"""<div class="arrscope-wrapper">
 <style>{css}</style>
@@ -53,7 +53,7 @@ def _render_mosaic_html(
     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))
+            tiles.append(_render_grid_html(leaf.grid_data, leaf.label, mode, global_stats, leaf.ref_data))
 
     return '<div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: flex-start;">' + "".join(tiles) + "</div>"
 
@@ -104,6 +104,7 @@ def _css() -> str:
     font-size: 12px;
     color: #666;
     margin: 2px 0 4px;
+    white-space: pre;
 }
 details.arrscope-details > summary {
     cursor: pointer;
@@ -129,28 +130,42 @@ details.arrscope-details[open] > summary {
 """
 
 
-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 _stats_sparkline_html(stats: dict, mode: str) -> str:
+    sp = sparkline(stats)
+    parts = []
+
+    if mode == "diff":
+        lo = stats.get("hist_min")
+        hi = stats.get("hist_max")
+        if lo is not None and hi is not None and sp:
+            parts.append(f"Δ {format_value(lo)}  {sp}  {format_value(hi)}")
+        mse = stats.get("mse")
+        pct = stats.get("pct_changed")
+        if mse is not None:
+            parts.append(f"mse={format_value(mse)}")
+        if pct is not None:
+            parts.append(f"{pct:.1f}% changed")
+    else:
+        lo = stats.get("hist_min")
+        hi = stats.get("hist_max")
+        if lo is not None and hi is not None and sp:
+            parts.append(f"{format_value(lo)}  {sp}  {format_value(hi)}")
+        if "zero_count" in stats and "total" in stats:
+            pct = stats["zero_count"] / stats["total"] * 100
+            parts.append(f"zeros={pct:.1f}%")
+        if "nan_count" in stats and stats["nan_count"] > 0:
+            parts.append(f"NaN={stats['nan_count']}")
+
+    if not parts:
+        return ""
+    return f'<div class="arrscope-stats">{" &middot; ".join(html_mod.escape(p) for p in parts)}</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)
+        return _render_grid_html(node.grid_data, node.label, mode, global_stats, node.ref_data)
 
     if not node.children and node.truncated:
         return f'<div class="arrscope-ellipsis">{html_mod.escape(node.label)}</div>'
@@ -190,30 +205,35 @@ def _format_header(node: VizNode) -> str:
 
 
 def _render_grid_html(
-    data: np.ndarray, label: str, mode: str, global_stats: dict | None
+    data: np.ndarray, label: str, mode: str, global_stats: dict | None,
+    ref_data: np.ndarray | None = 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_1d_html(data, mode, global_stats, ref_data)
 
-    return _render_2d_html(data, label, mode, global_stats)
+    return _render_2d_html(data, label, mode, global_stats, ref_data)
 
 
 def _render_1d_html(
-    data: np.ndarray, mode: str, global_stats: dict | None
+    data: np.ndarray, mode: str, global_stats: dict | None,
+    ref_data: np.ndarray | None = 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
-    ]
+    cells = []
+    for i, v in enumerate(data):
+        ref = ref_data[i] if ref_data is not None else None
+        cells.append(
+            f"<td style=\"{_style_html(v, mode, global_stats, ref)}\">"
+            f"{html_mod.escape(_format_cell_html(v, mode))}</td>"
+        )
     return f"<table><tr>{''.join(cells)}</tr></table>"
 
 
 def _render_2d_html(
-    data: np.ndarray, label: str, mode: str, global_stats: dict | None
+    data: np.ndarray, label: str, mode: str, global_stats: dict | None,
+    ref_data: np.ndarray | None = None,
 ) -> str:
     nrows, ncols = data.shape
     rows: list[str] = []
@@ -227,8 +247,9 @@ def _render_2d_html(
         rows.append("<tr>")
         for col_idx in range(ncols):
             val = data[row_idx, col_idx]
+            ref = ref_data[row_idx, col_idx] if ref_data is not None else None
             text = html_mod.escape(_format_cell_html(val, mode))
-            style = _style_html(val, mode, global_stats)
+            style = _style_html(val, mode, global_stats, ref)
             rows.append(f"<td style=\"{style}\">{text}</td>")
         rows.append("</tr>")
     rows.append("</table>")
@@ -251,7 +272,9 @@ def _is_zero(val) -> bool:
     return val == 0
 
 
-def _style_html(val, mode: str, global_stats: dict | None) -> str:
+def _style_html(val, mode: str, global_stats: dict | None, ref_val=None) -> str:
+    if mode == "diff":
+        return _diff_style(val, ref_val, global_stats)
     if mode == "heatmap":
         return _heatmap_style(val, global_stats)
     if mode == "sparsity":
@@ -259,6 +282,35 @@ def _style_html(val, mode: str, global_stats: dict | None) -> str:
     return _dtype_style(val)
 
 
+def _diff_style(val, ref_val, global_stats: dict | None) -> str:
+    if ref_val is None:
+        return ""
+    if not isinstance(val, (np.floating, float, np.integer, int)):
+        return _dtype_style(val)
+    if not isinstance(ref_val, (np.floating, float, np.integer, int)):
+        return ""
+
+    diff = float(val) - float(ref_val)
+    if abs(diff) < 1e-15:
+        return "color: #999; opacity: 0.4;"
+
+    max_abs = global_stats.get("max_abs_diff", 1.0) if global_stats else 1.0
+    if max_abs == 0:
+        max_abs = 1.0
+    t = min(abs(diff) / max_abs, 1.0)
+
+    if diff > 0:
+        r = int(180 + 75 * t)
+        g = int(40 * (1 - t))
+        b = int(40 * (1 - t))
+    else:
+        r = int(40 * (1 - t))
+        g = int(40 * (1 - t))
+        b = int(180 + 75 * t)
+
+    return f"color: rgb({r},{g},{b}); font-weight: bold;"
+
+
 def _heatmap_style(val, global_stats: dict | None) -> str:
     if not global_stats:
         return ""

{arrscope-0.3.0 → arrscope-0.4.0}/src/arrscope/renderers/terminal.py

@@ -9,7 +9,7 @@ from rich.table import Table
 from rich.text import Text
 from rich.tree import Tree
 
-from arrscope._format import format_value
+from arrscope._format import format_value, sparkline
 from arrscope._types import VizNode
 
 BRANCH_COLORS = ["grey50", "cyan", "green", "yellow", "magenta", "blue"]
@@ -33,7 +33,7 @@ def render_terminal(
     parts.append(body)
 
     if global_stats and node.stats:
-        parts.append(_stats_text(global_stats))
+        parts.append(_stats_sparkline(global_stats, mode))
 
     with console.capture() as capture:
         for p in parts:
@@ -62,35 +62,47 @@ def _render_mosaic(
     tables: list[Table] = []
     for leaf in leaves:
         if leaf.grid_data is not None:
-            t = _render_grid(leaf.grid_data, leaf.label, mode, global_stats)
+            t = _render_grid(leaf.grid_data, leaf.label, mode, global_stats, leaf.ref_data)
             tables.append(t)
 
     return Columns(tables, equal=True, expand=False)
 
 
-def _stats_text(stats: dict) -> Text:
+def _stats_sparkline(stats: dict, mode: str) -> Text:
     dim = Style(dim=True, color="grey50")
     t = Text()
-    fmt = ".4f" if stats.get("dtype", "").startswith(("float", "int")) else ".4f"
+    sp = sparkline(stats)
+
+    if mode == "diff":
+        lo = stats.get("hist_min")
+        hi = stats.get("hist_max")
+        if lo is not None and hi is not None and sp:
+            t.append(f"Δ {format_value(lo)}  {sp}  {format_value(hi)}", style=dim)
+        mse = stats.get("mse")
+        pct = stats.get("pct_changed")
+        parts = []
+        if mse is not None:
+            parts.append(f"mse={format_value(mse)}")
+        if pct is not None:
+            parts.append(f"{pct:.1f}% changed")
+        if parts:
+            t.append("  " + "  ".join(parts), style=dim)
+        return t
 
-    def fmt_val(v):
-        if isinstance(v, float):
-            return format_value(v, fmt)
-        return str(v)
+    lo = stats.get("hist_min")
+    hi = stats.get("hist_max")
+    if lo is not None and hi is not None and sp:
+        t.append(f"{format_value(lo)}  {sp}  {format_value(hi)}", style=dim)
 
     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']}")
+    if items:
+        t.append("  " + "  ".join(items), style=dim)
 
-    t.append("  " + "  ".join(items), style=dim)
     return t
 
 
@@ -101,7 +113,7 @@ def _render_node(
     global_stats: dict | None,
 ) -> Tree | Table | Text:
     if node.grid_data is not None:
-        return _render_grid(node.grid_data, node.label, mode, global_stats)
+        return _render_grid(node.grid_data, node.label, mode, global_stats, node.ref_data)
 
     if not node.children and node.truncated:
         t = Text(f"  {node.label}")
@@ -137,25 +149,28 @@ def _render_grid(
     label: str,
     mode: str,
     global_stats: dict | None,
+    ref_data: np.ndarray | None = None,
 ) -> Text | Table:
     if data.ndim == 0:
         return Text(format_value(data.item()))
 
     if data.ndim == 1:
-        return _render_1d(data, mode, global_stats)
+        return _render_1d(data, mode, global_stats, ref_data)
 
-    return _render_2d(data, label, mode, global_stats)
+    return _render_2d(data, label, mode, global_stats, ref_data)
 
 
 def _render_1d(
     data: np.ndarray,
     mode: str,
     global_stats: dict | None,
+    ref_data: np.ndarray | None = None,
 ) -> Text:
     items = []
-    for v in data:
+    for i, v in enumerate(data):
         text = _format_cell(v, mode)
-        items.append(_style_value(text, v, mode, global_stats))
+        ref = ref_data[i] if ref_data is not None else None
+        items.append(_style_value(text, v, mode, global_stats, ref))
 
     t = Text("[")
     for i, item in enumerate(items):
@@ -171,6 +186,7 @@ def _render_2d(
     label: str,
     mode: str,
     global_stats: dict | None,
+    ref_data: np.ndarray | None = None,
 ) -> Table:
     nrows, ncols = data.shape
     table = Table(
@@ -186,15 +202,19 @@ def _render_2d(
         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],
-                mode,
-                global_stats,
+        row_cells = []
+        for col_idx in range(ncols):
+            val = data[row_idx, col_idx]
+            ref = ref_data[row_idx, col_idx] if ref_data is not None else None
+            row_cells.append(
+                _style_value(
+                    _format_cell(val, mode),
+                    val,
+                    mode,
+                    global_stats,
+                    ref,
+                )
             )
-            for col_idx in range(ncols)
-        ]
         table.add_row(*row_cells)
 
     return table
@@ -221,8 +241,11 @@ def _style_value(
     val,
     mode: str,
     global_stats: dict | None,
+    ref_val=None,
 ) -> Text:
-    if mode == "heatmap":
+    if mode == "diff":
+        cell_style = _diff_color(val, ref_val, global_stats)
+    elif mode == "heatmap":
         cell_style = _heatmap_color(val, global_stats)
     elif mode == "sparsity":
         cell_style = _sparsity_color(val)
@@ -232,6 +255,35 @@ def _style_value(
     return Text(text, style=cell_style)
 
 
+def _diff_color(val, ref_val, global_stats: dict | None) -> Style:
+    if ref_val is None:
+        return Style()
+    if not isinstance(val, (np.floating, float, np.integer, int)):
+        return _dtype_color(val)
+    if not isinstance(ref_val, (np.floating, float, np.integer, int)):
+        return Style()
+
+    diff = float(val) - float(ref_val)
+    if abs(diff) < 1e-15:
+        return Style(dim=True, color="grey50")
+
+    max_abs = global_stats.get("max_abs_diff", 1.0) if global_stats else 1.0
+    if max_abs == 0:
+        max_abs = 1.0
+    t = min(abs(diff) / max_abs, 1.0)
+
+    if diff > 0:
+        r = int(180 + 75 * t)
+        g = int(40 * (1 - t))
+        b = int(40 * (1 - t))
+    else:
+        r = int(40 * (1 - t))
+        g = int(40 * (1 - t))
+        b = int(180 + 75 * t)
+
+    return Style(color=Color.from_rgb(r, g, b))
+
+
 def _heatmap_color(val, global_stats: dict | None) -> Style:
     if not global_stats:
         return Style()
@@ -250,14 +302,13 @@ def _heatmap_color(val, global_stats: dict | None) -> Style:
     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
+        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  # 0..1
+        t2 = (t - 0.5) / 0.5
         r = int(40 - 10 * t2)
         g = int(240 - 200 * t2)
         b = int(130 + 130 * t2)

{arrscope-0.3.0 → arrscope-0.4.0}/uv.lock

@@ -18,7 +18,7 @@ wheels = [
 
 [[package]]
 name = "arrscope"
-version = "0.2.0"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },