arrscope 0.3.0

Beautiful n-dimensional array visualization for Python

arrscope

Visualize n-dimensional arrays in the terminal and Jupyter — with structural trees, tiled mosaics, and color-coded value maps.

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

pip install arrscope

Only requires numpy + rich. 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'])

Color modes

scope(arr, mode='dtype')        # default
scope(arr, mode='heatmap')      # diverging colormap
scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros

Render styles

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

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'
    render_style='tree',  # 'tree' | 'mosaic'
)

Development

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

License

MIT