Metadata-Version: 2.4
Name: zadu
Version: 0.5.4
Summary: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections
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://hyeonword.com/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[jupyter]==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://hyeonword.com/zadu/"><img alt="Documentation" src="https://img.shields.io/badge/docs-GitHub%20Pages-4051b5"></a>
</p>

ZADU evaluates how faithfully a dimensionality-reduction projection preserves
its original data. It provides 22 local, cluster-level, global, and gap-based
distortion measures through a Python interface. Evaluate one projection,
compare several projections of the same samples, or inspect pointwise scores.

**[Documentation](https://hyeonword.com/zadu/)** ·
**[Measure reference](https://hyeonword.com/zadu/measures/)** ·
**[Performance report](https://hyeonword.com/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://hyeonword.com/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))
projection = 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(projection)
print(scores)
```

Results follow the order of `specs`. T&C reports `trustworthiness` and
`continuity`; MRRE reports `mrre_false` and `mrre_missing`. For all four outputs,
1 is best. Keep sample rows aligned between `original` and `projection`.

Read the [quickstart](https://hyeonword.com/zadu/getting-started/quickstart/),
[choose measures](https://hyeonword.com/zadu/guides/choosing-measures/), or
browse the complete [measure reference](https://hyeonword.com/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).
See [CONTRIBUTING.md](CONTRIBUTING.md) for development and correctness
requirements.

<details>
<summary><strong>Citation</strong></summary>

Please cite both the original paper and the exact ZADU software version used in
your work.

### Original paper

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

### Software releases

Choose a release below and copy its BibTeX entry. Each software citation
retains the original ZADU authors and cumulatively adds major contributors
whose work is included in that or an earlier release.

<!-- zadu-citation-latest: 0.5.4 -->

<details>
<summary><strong>ZADU 0.5.4</strong></summary>

```bibtex
@software{zadu_0_5_4,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas and Gunaratne, Kaviru and Ros, Jaume},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.5.4},
  year = {2026},
  month = sep,
  url = {https://github.com/hj-n/zadu/releases/tag/v0.5.4}
}
```

</details>

<details>
<summary><strong>ZADU 0.5.3</strong></summary>

```bibtex
@software{zadu_0_5_3,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas and Gunaratne, Kaviru and Ros, Jaume},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.5.3},
  year = {2026},
  month = aug,
  url = {https://github.com/hj-n/zadu/releases/tag/v0.5.3}
}
```

</details>

<details>
<summary><strong>ZADU 0.5.2</strong></summary>

```bibtex
@software{zadu_0_5_2,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas and Gunaratne, Kaviru and Ros, Jaume},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.5.2},
  year = {2026},
  month = aug,
  url = {https://github.com/hj-n/zadu/releases/tag/v0.5.2}
}
```

</details>

<details>
<summary><strong>ZADU 0.5.1</strong></summary>

```bibtex
@software{zadu_0_5_1,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas and Gunaratne, Kaviru and Ros, Jaume},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.5.1},
  year = {2026},
  month = aug,
  url = {https://github.com/hj-n/zadu/releases/tag/v0.5.1}
}
```

</details>

<details>
<summary><strong>ZADU 0.5.0</strong></summary>

```bibtex
@software{zadu_0_5_0,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas and Gunaratne, Kaviru and Ros, Jaume},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.5.0},
  year = {2026},
  month = aug,
  url = {https://github.com/hj-n/zadu/releases/tag/v0.5.0}
}
```

</details>

<details>
<summary><strong>Earlier releases (0.1.0-0.4.2)</strong></summary>

<details>
<summary><strong>ZADU 0.4.2</strong></summary>

```bibtex
@software{zadu_0_4_2,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas and Gunaratne, Kaviru},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.4.2},
  year = {2026},
  month = may,
  url = {https://github.com/hj-n/zadu/releases/tag/v0.4.2}
}
```

</details>

<details>
<summary><strong>ZADU 0.4.1</strong></summary>

```bibtex
@software{zadu_0_4_1,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas and Gunaratne, Kaviru},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.4.1},
  year = {2026},
  month = feb,
  url = {https://github.com/hj-n/zadu/releases/tag/v0.4.1}
}
```

</details>

<details>
<summary><strong>ZADU 0.3.1</strong></summary>

```bibtex
@software{zadu_0_3_1,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.3.1},
  year = {2025},
  month = nov,
  url = {https://pypi.org/project/zadu/0.3.1/}
}
```

</details>

<details>
<summary><strong>ZADU 0.3.0</strong></summary>

```bibtex
@software{zadu_0_3_0,
  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 and Kim, Minhyeong and Miller, Jacob L. and Heine, Lukas},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.3.0},
  year = {2025},
  month = aug,
  url = {https://github.com/hj-n/zadu/releases/tag/v0.3.0}
}
```

</details>

<details>
<summary><strong>ZADU 0.2.1</strong></summary>

```bibtex
@software{zadu_0_2_1,
  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 and Kim, Minhyeong and Miller, Jacob L.},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.2.1},
  year = {2025},
  month = may,
  url = {https://pypi.org/project/zadu/0.2.1/}
}
```

</details>

<details>
<summary><strong>ZADU 0.2.0</strong></summary>

```bibtex
@software{zadu_0_2_0,
  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 and Kim, Minhyeong},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.2.0},
  year = {2024},
  month = jul,
  url = {https://pypi.org/project/zadu/0.2.0/}
}
```

</details>

<details>
<summary><strong>ZADU 0.1.1</strong></summary>

```bibtex
@software{zadu_0_1_1,
  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},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.1.1},
  year = {2023},
  month = oct,
  url = {https://pypi.org/project/zadu/0.1.1/}
}
```

</details>

<details>
<summary><strong>ZADU 0.1.0</strong></summary>

```bibtex
@software{zadu_0_1_0,
  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},
  title = {{ZADU: A Python Toolkit for Evaluating the Reliability of Dimensionality Reduction Projections}},
  version = {0.1.0},
  year = {2023},
  month = may,
  url = {https://pypi.org/project/zadu/0.1.0/}
}
```

</details>

</details>

Each metric's original literature and later additions are credited in the
[measure reference](https://hyeonword.com/zadu/measures/).

</details>
