arrscope 0.5.0

Beautiful n-dimensional array visualization for Python

arrscope

Visualize n-dimensional arrays in the terminal and Jupyter — with structural trees, tiled mosaics, array diffing, and distribution sparklines.

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
• Source-expression labels: like icecream's ic(), scope(np.ones((4, 5))) auto-labels the output with np.ones((4, 5)) when you don't pass title=
• 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

pip install arrscope

Only requires numpy + rich + executing. Torch/TF/JAX/tinygrad are optional.

Quick start

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())

Source-expression labels

When you don't pass title=, arrscope inspects the call site and labels the output with the expression you passed in — the same trick icecream.ic() uses:

scope(np.ones((4, 5, 6, 3)))   # labeled "np.ones((4, 5, 6, 3))"
scope(weights)                  # labeled "weights"
scope(x, title="Custom")        # explicit title always wins

Falls back to no label (never raises) when the source isn't available, e.g. in a plain REPL or python -c.

Color modes

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:

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

scope(arr)                        # tree (default) — click-to-expand layers
scope(arr, render_style='mosaic') # all sub-slices tiled side by side

CLI

arrscope 3x4x5
arrscope 2x3x32x32 --axes batch heads h w --grid h w --mode heatmap
arrscope 20x4x5 --max-height 6

Framework support

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

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

git clone https://github.com/vizarray/arrscope
cd arrscope
uv sync
uv run pytest
uv run python main.py

License

MIT