arrscope 0.1.0

Beautiful n-dimensional array visualization for Python

arrscope

Beautiful n-dimensional array visualization for Python — in the terminal and Jupyter.

from arrscope import scope
import numpy as np

scope(np.random.rand(2, 3, 8, 8), axes=['batch', 'heads', 'h', 'w'])

├── [0] (3, 8, 8)
│   ├── [0,0]: 8×8 grid
│   ├── [0,1]: 8×8 grid
│   └── [0,2]: 8×8 grid
└── [1] (3, 8, 8)
    ...
  min=0.001  max=0.999  mean=0.5  std=0.29  zeros=0.0%

Features

• 1D → 6D+: Tiered visual grammar — lists, grids, trees, collapsed hierarchies
• Named axes: Attach semantics to dimensions (batch, heads, h, w)
• Configurable grid: Pick which axes form the leaf 2D matrix
• Three color modes:
  • dtype — semantic colors by data type (float=blue, int=green, bool=magenta, …)
  • heatmap — diverging colormap (red→light→blue) by value magnitude
  • sparsity — zeros as ·, non-zeros highlighted in bold
• Stats overlay: min, max, mean, std, zero%, NaN count
• Head/tail truncation: large dimensions show first/last N slices with …
• Smart precision: auto-detects significant figures for floats
• Terminal + Jupyter: Rich ANSI output + static HTML/CSS with dark mode
• Multi-framework: NumPy, PyTorch, TensorFlow, JAX (lazy imports, no hard deps)

Install

pip install arrscope

Only requires numpy + rich. Torch/TF/JAX are optional — pass any array type, it just works.

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 for clarity
scope(
    np.random.rand(2, 8, 32, 32),
    axes=['batch', 'heads', 'h', 'w'],
    grid=['h', 'w'],
    title='Attention heads',
)

# Pick any dims as the leaf grid
scope(data, axes=['a', 'b', 'c', 'd'], grid=['a', 'b'])

Color modes

scope(arr, mode='dtype')        # default — blue floats, green ints, etc.
scope(arr, mode='heatmap')      # diverging colormap by value
scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros

Stats overlay

Stats are shown by default. Hide with:

scope(arr, stats=False)

Shows: min=0.0 max=1.0 mean=0.5 std=0.29 zeros=12.5%

Truncation

scope(np.random.rand(100, 32, 32), max_height=8)

Shows first 4 + last 4 slices with … (92 more) in between.

Custom formatting

scope(arr, fmt='.2f')          # fixed precision
scope(arr, color=False)        # monochrome
scope(arr, style='html')       # force HTML output in terminal

CLI

# Install globally (ships with the library)
pip install arrscope

# Use from anywhere
arrscope 3x4x5
arrscope 2x3x32x32 --axes batch heads h w --grid h w --mode heatmap
arrscope 20x4x5 --max-height 6 --no-stats

Framework support

Pass any array-like — conversion is automatic:

import torch
scope(torch.randn(2, 3, 4))          # PyTorch

import tensorflow as tf
scope(tf.random.uniform((2, 3, 4)))  # TensorFlow

import jax.numpy as jnp
scope(jnp.array([[1, 2], [3, 4]]))  # JAX

API

scope(
    arr,                          # np.ndarray | torch.Tensor | tf.Tensor | jax.Array
    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_width=None,               # int — max characters wide
    max_height=None,              # int — max rows before truncation
    fmt=None,                     # str — format spec like '.4f'
    color=True,                   # bool — enable/disable color
    mode='dtype',                 # 'dtype' | 'heatmap' | 'sparsity'
    stats=True,                   # bool — show min/max/mean/std/zeros
    style='auto',                 # 'auto' | 'terminal' | 'html'
)

Development

git clone https://github.com/vizarray/arrscope
cd arrscope
uv sync
uv run pytest
uv run python main.py          # demo script
uv run jupyter notebook test.ipynb  # notebook demo

License

MIT