Metadata-Version: 2.4
Name: dr-diagnostics
Version: 0.3.3
Summary: Diagnostics for dimensionality reduction methods such as t-SNE and UMAP
Author: Kasra Amirani
License-Expression: MIT
Project-URL: Tutorial, https://colab.research.google.com/drive/1BQqQumvkz3Qsq-JmlRioWxPJjePpQkcz?usp=sharing
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.

## Tutorial

A hands-on tutorial notebook walks through the package on a synthetic dataset
(two clusters of different density plus a lone outlier) and shows how the
diagnostics reveal density equalisation and outlier absorption:

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1BQqQumvkz3Qsq-JmlRioWxPJjePpQkcz?usp=sharing)

## Installation

Install from PyPI:

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

Inside a Jupyter notebook or Google Colab cell, prefix the command with `!`:

```python
!pip install dr-diagnostics
```

## 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).

## License

This project is licensed under the MIT License.
