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

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

```python
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

```bash
pip install arrscope
```

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

## 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 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

```python
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:

```python
scope(arr, stats=False)
```

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

## Truncation

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

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

## Custom formatting

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

## CLI

```bash
# 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:

```python
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

```python
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

```bash
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
