dr-diagnostics 0.3.2

Diagnostics for dimensionality reduction methods such as t-SNE and UMAP

dr-diagnostics

dr-diagnostics is a Python package for visual diagnostics of dimensionality reduction embeddings.

It helps users inspect how well a low-dimensional embedding preserves structure from the original high-dimensional data. The package supports user-provided embeddings, as well as built-in workflows for t-SNE and UMAP.

Installation

Install from PyPI:

pip install dr-diagnostics

Or, for development, from the project root in editable mode:

pip install -e .

Features

• Visualize original data and low-dimensional embeddings, with optional named class legends.
• Compare high-dimensional and low-dimensional Euclidean distances (distance-fit plots).
• Approximate geodesic distances using a k-nearest-neighbour graph and compare them against low-dimensional Euclidean distances.
• Compute rank matrices from pairwise distance matrices and compare high-dimensional ranks with low-dimensional ranks.
• Trustworthiness and continuity curves over a range of neighbourhood sizes.
• Compare t-SNE similarity matrices P and Q, and UMAP similarity matrices V and W.
• Generate a six-panel dashboard combining the diagnostics in one figure.
• Inspect a single selected point and its k-nearest neighbours across all panels, or a specific pair of points (with automatic detection of the most distorted pairs).
• Show the true 3D scatter of the original data when it is three-dimensional (e.g. the Swiss Roll).

Quick start

from sklearn.datasets import load_iris
from dr_diagnostics import run_diagnostics

iris = load_iris()
class_labels = {i: name for i, name in enumerate(iris.target_names)}

fig, results = run_diagnostics(
    X_original=iris.data,
    method="tsne",            # or "umap"
    color_values=iris.target,
    class_labels=class_labels,
    compute_geodesic=True,
)
fig.savefig("iris_diagnostics.png", dpi=300, bbox_inches="tight")

run_diagnostics returns the dashboard figure and a results dictionary containing the embedding, distance and rank matrices, and similarity matrices. These can be passed to selected_point_dashboard or selected_pair_dashboard for local inspection.

License

This project is licensed under the MIT License.