zadu

A-to-Z Python library for evalUating Dimensionality reduction

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 · Measure reference · Performance report · ZADU paper

Installation

python -m pip install zadu

Visualization is optional:

python -m pip install "zadu[vis]"

See the installation guide for optional MLX and PyTorch backends.

Quick start

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, choose measures, or browse the complete measure reference.

Contributing

To propose a distortion measure, provide its name, paper, and an optional reference implementation through the metric proposal form. See CONTRIBUTING.md for development and correctness requirements.

Citation

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

Original paper

@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 0.5.4

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

ZADU 0.5.3

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

ZADU 0.5.2

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

ZADU 0.5.1

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

ZADU 0.5.0

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

Earlier releases (0.1.0-0.4.2)

ZADU 0.4.2

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

ZADU 0.4.1

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

ZADU 0.3.1

@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/}
}

ZADU 0.3.0

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

ZADU 0.2.1

@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/}
}

ZADU 0.2.0

@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/}
}

ZADU 0.1.1

@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/}
}

ZADU 0.1.0

@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/}
}

Each metric's original literature and later additions are credited in the measure reference.

Metadata

Release files for zadu 0.5.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zadu 0.5.4
File	Size	Uploaded
zadu-0.5.4.tar.gz	118.2 kB	Sep 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for zadu 0.5.4
File	Interpreter	ABI	Platform	Reset
zadu-0.5.4-py3-none-any.whl 114.0 kB Sep 13, 2026	Python 3	none	any	Details

Total release size: 232.2 kB

Release files / zadu-0.5.4.tar.gz

Download URL	zadu-0.5.4.tar.gz
Size	118.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`7bd85412608ae8e0693bfe06e992063f72343818727962dc285183b723c0c61e`
BLAKE2b-256 checksum How to use checksums	`ce89983fa5128e72547622cacf027ccc5a760a78bb4542c893de552ccef1c909`
Upload date	Sep 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/hj-n/zadu
Publishing commit: github.com/hj-n/zadu/tree/1ec9dcec05954d50d01b9a97bb45e39d3a54206b

Workflow

Publishing configuration: github.com/hj-n/zadu/blob/1ec9dcec05954d50d01b9a97bb45e39d3a54206b/.github/workflows/publish-pypi.yml
Publishing logs: github.com/hj-n/zadu/actions/runs/34790954054/attempts/1

Artifact

Subject: zadu-0.5.4.tar.gz
SHA-256 checksum: 7bd85412608ae8e0693bfe06e992063f72343818727962dc285183b723c0c61e Verifying attestations

Release files / zadu-0.5.4-py3-none-any.whl

Download URL	zadu-0.5.4-py3-none-any.whl
Size	114.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b7ba635fb9571c5376b2e37116607f04b92c7e0f907f75b628b2d28759d0b0ce`
BLAKE2b-256 checksum How to use checksums	`fd16f2d460cbc0c8e6fa67361f9dd77c5732fe692f1fce2dc112a1abf9095566`
Upload date	Sep 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/hj-n/zadu
Publishing commit: github.com/hj-n/zadu/tree/1ec9dcec05954d50d01b9a97bb45e39d3a54206b

Workflow

Publishing configuration: github.com/hj-n/zadu/blob/1ec9dcec05954d50d01b9a97bb45e39d3a54206b/.github/workflows/publish-pypi.yml
Publishing logs: github.com/hj-n/zadu/actions/runs/34790954054/attempts/1

Artifact

Subject: zadu-0.5.4-py3-none-any.whl
SHA-256 checksum: b7ba635fb9571c5376b2e37116607f04b92c7e0f907f75b628b2d28759d0b0ce Verifying attestations