Metadata-Version: 2.4
Name: ferrum-viz
Version: 0.9.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Dist: polars>=1.0
Requires-Dist: pyarrow>=15.0
Requires-Dist: narwhals>=1.0,<2
Requires-Dist: numpy>=1.20
Requires-Dist: scikit-learn>=1.3 ; extra == 'all'
Requires-Dist: shap>=0.42 ; extra == 'all'
Requires-Dist: anywidget>=0.9 ; extra == 'all'
Requires-Dist: anywidget>=0.9 ; extra == 'jupyter'
Requires-Dist: scikit-learn>=1.3 ; extra == 'models'
Requires-Dist: scikit-learn>=1.3 ; extra == 'shap'
Requires-Dist: shap>=0.42 ; extra == 'shap'
Provides-Extra: all
Provides-Extra: jupyter
Provides-Extra: models
Provides-Extra: shap
License-File: LICENSE
License-File: NOTICE
Summary: Ferrum is a statistical visualization library for Python: a grammar-first charting system that unifies exploratory plots, statistical graphics, interactive views, and model diagnostics, backed by a Rust engine.
Keywords: visualization,plotting,grammar-of-graphics,charts,rust,statistics,diagnostics
Author-email: chris-santiago <cjsantiago@gatech.edu>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://ferrumviz.com
Project-URL: Homepage, https://ferrumviz.com
Project-URL: Issues, https://github.com/chris-santiago/ferrum/issues
Project-URL: Repository, https://github.com/chris-santiago/ferrum

# Ferrum

Grammar-of-graphics statistical visualization for Python, with a Rust core.

Ferrum builds every chart — scatter plot, faceted histogram, ROC curve, SHAP beeswarm — from the same grammar of data, encodings, marks, scales, and statistical transforms. The declaration layer is Python; the computation engine is Rust compiled via PyO3.

## Install

```bash
pip install ferrum-viz
```

Install with all optional extras (scikit-learn, SHAP, Jupyter interactive rendering):

```bash
pip install ferrum-viz[all]
```

## Quickstart

```python
import ferrum as fm
import polars as pl

df = pl.DataFrame({"x": [1, 2, 3, 4], "y": [2, 4, 3, 5], "group": ["a", "a", "b", "b"]})

chart = fm.Chart(df).mark_point().encode(x="x", y="y", color="group:N")
chart.save("scatter.svg")
chart.show_png()  # raster output, no display server needed
```

## Key features

- **One chart model** — scatter plots, statistical graphics, and ML diagnostics share the same grammar and compose with `+`, `|`, `&`.
- **Stat transforms in the pipeline** — KDE, LOESS, bootstrap CIs, binning, and aggregations are declared in the chart spec and computed in Rust.
- **Model diagnostics as charts** — `fm.roc_chart(model, X, y)`, `fm.confusion_matrix_chart(...)`, `fm.shap_chart(...)` return regular `Chart` objects.
- **Zero system dependencies** — no Cairo, no X11, no display server. Renders anywhere `pip install` works.
- **DataFrame pluralism** — polars, pandas, modin, cuDF, dask, ibis, and pyarrow all work through `Chart(data)`.
- **Interactive rendering** — `chart.interactive()` switches to a GPU-backed WASM renderer with selections, zoom/pan, linked views, and tooltips. Backed by `anywidget` for Jupyter.
- **12 built-in themes** — from Paper Ink (warm cream default) to dark, publication, and editorial styles.

## Examples

```python
# Layer a LOESS trend on a scatter plot
points = fm.Chart(df).mark_point(opacity=0.6).encode(x="x", y="y", color="group:N")
trend = fm.Chart(df).mark_smooth(method="loess").encode(x="x", y="y", color="group:N")
chart = points + trend

# Compose diagnostics into a model report
source = fm.ModelSource(model, X_test, y_test)
report = (fm.roc_chart(source) | fm.confusion_matrix_chart(source)) & fm.importance_chart(source)
report.save("model_report.svg")

# Figure-level helpers
fm.displot(df, x="value", hue="group", kind="kde")
fm.catplot(df, x="species", y="measurement", kind="violin")
fm.pairplot(df, vars=["a", "b", "c"], hue="label")
```

## Architecture

| Layer | Role |
|---|---|
| `src/ferrum/` | Python declaration API — Chart, encodings, marks, themes, plots |
| `crates/ferrum-core/` | Rust computation engine — transforms, scales, rendering |
| Arrow CDI | Zero-copy data transport between Python and Rust via `pyo3-arrow` |

## Development

Requires Python 3.10+, Rust toolchain, and [maturin](https://www.maturin.rs/).

```bash
uv sync
unset CONDA_PREFIX && uv run --no-sync maturin develop   # build Rust extension
uv run pytest                                            # run tests
```

## How this was built

Ferrum was designed and implemented in 9 days by one human and an agentic Claude framework — 918 commits, ~97k lines of source, 3,358 tests. The project uses a six-layer automation architecture with language-specific coding agents, commit-level review gates, and repeatable quality campaigns. See [design-docs/development-meta-analysis.md](design-docs/development-meta-analysis.md) for the full retrospective.

## Documentation

Full docs at [ferrumviz.com](https://ferrumviz.com).

## License

See [LICENSE](LICENSE) for details.

