Metadata-Version: 2.4
Name: dr-diagnostics
Version: 0.3.2
Summary: Diagnostics for dimensionality reduction methods such as t-SNE and UMAP
Author: Kasra Amirani
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: seaborn
Requires-Dist: umap-learn>=0.5.7
Dynamic: license-file

# 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:

```bash
pip install dr-diagnostics
```

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

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

```python
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.
