Metadata-Version: 2.4
Name: arrscope
Version: 0.4.1
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
