Metadata-Version: 2.4
Name: zadu
Version: 0.5.2
Summary: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Embeddings
Author-email: Hyeon Jeon <hj@hcil.snu.ac.kr>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hj-n/zadu
Project-URL: Documentation, https://hj-n.github.io/zadu/
Project-URL: Repository, https://github.com/hj-n/zadu
Project-URL: Issues, https://github.com/hj-n/zadu/issues
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 :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES/gap-index-MIT.txt
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: numpy>=1.23
Requires-Dist: scikit-learn>=1.2
Requires-Dist: threadpoolctl>=3.1
Requires-Dist: scipy>=1.9
Requires-Dist: hdbscan>=0.8.33
Requires-Dist: numba>=0.57
Provides-Extra: vis
Requires-Dist: matplotlib>=3.7; extra == "vis"
Provides-Extra: mlx
Requires-Dist: mlx<0.33,>=0.32; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "mlx"
Provides-Extra: torch
Requires-Dist: torch>=2.6; extra == "torch"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.7; extra == "docs"
Requires-Dist: mkdocstrings[python]<1,>=0.30; extra == "docs"
Provides-Extra: dev
Requires-Dist: black==26.5.1; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff==0.16.4; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: bayesian-optimization; extra == "benchmark"
Requires-Dist: pandas; extra == "benchmark"
Requires-Dist: tqdm; extra == "benchmark"
Requires-Dist: umap-learn; extra == "benchmark"
Dynamic: license-file

<p align="center">
  <h2 align="center">ZADU</h2>
  <p align="center"><b>A</b>-to-<b>Z</b> Python library for eval<b>U</b>ating <b>D</b>imensionality reduction</p>
</p>

<p align="center">
  <a href="https://pypi.org/project/zadu/"><img alt="PyPI" src="https://img.shields.io/pypi/v/zadu"></a>
  <a href="https://github.com/hj-n/zadu/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/hj-n/zadu/actions/workflows/test.yml/badge.svg"></a>
  <a href="https://hj-n.github.io/zadu/"><img alt="Documentation" src="https://img.shields.io/badge/docs-GitHub%20Pages-4051b5"></a>
</p>

ZADU evaluates how faithfully a dimensionality-reduction embedding preserves
its original data. It provides 22 local, cluster-level, global, and gap-based
distortion measures through one consistent Python interface, with exact shared
execution, bounded-memory strategies, repeated-embedding evaluation, and
optional MLX and PyTorch backends.

**[Documentation](https://hj-n.github.io/zadu/)** ·
**[Measure reference](https://hj-n.github.io/zadu/measures/)** ·
**[Performance report](https://hj-n.github.io/zadu/performance/0.5.1-acceleration-report/)** ·
**[ZADU paper](https://doi.org/10.1109/VIS54172.2023.00048)**

## Installation

```bash
python -m pip install zadu
```

Visualization is optional:

```bash
python -m pip install "zadu[vis]"
```

See the [installation guide](https://hj-n.github.io/zadu/getting-started/installation/)
for optional MLX and PyTorch backends.

## Quick start

```python
import numpy as np
from zadu import ZADU

rng = np.random.default_rng(0)
original = rng.normal(size=(200, 16))
embedding = original[:, :2] + 0.05 * rng.normal(size=(200, 2))

specs = [
    {"id": "tnc", "params": {"k": 20}},
    {"id": "mrre", "params": {"k": 20}},
]

scores = ZADU(specs, original).measure(embedding)
print(scores)
```

ZADU's execution DAG shares compatible exact distances, neighbors, ranks,
densities, and pair reductions across measures. Scientific scores remain
separate from backend, timing, and memory diagnostics in `last_run_info`.

Read the [quickstart](https://hj-n.github.io/zadu/getting-started/quickstart/),
[choose measures](https://hj-n.github.io/zadu/guides/choosing-measures/), or
browse the complete [measure reference](https://hj-n.github.io/zadu/measures/).

## Contributing

To propose a distortion measure, provide its name, paper, and an optional
reference implementation through the
[metric proposal form](https://github.com/hj-n/zadu/issues/new?template=metric-proposal.yml).
You do not need to learn ZADU's internals or prepare repository files. See
[CONTRIBUTING.md](CONTRIBUTING.md) for development and correctness requirements.

## Citation

```bibtex
@INPROCEEDINGS{jeon23vis,
  author={Jeon, Hyeon and Cho, Aeri and Jang, Jinhwa and Lee, Soohyun and Hyun, Jake and Ko, Hyung-Kwon and Jo, Jaemin and Seo, Jinwook},
  booktitle={2023 IEEE Visualization and Visual Analytics (VIS)},
  title={ZADU: A Python Library for Evaluating the Reliability of Dimensionality Reduction Embeddings},
  year={2023},
  pages={196--200},
  doi={10.1109/VIS54172.2023.00048}
}
```

Each metric's original literature and later additions are credited in the
[measure reference](https://hj-n.github.io/zadu/measures/).
