Metadata-Version: 2.4
Name: manylatents
Version: 0.1.6
Summary: Unified dimensionality reduction and neural network analysis framework
Project-URL: Homepage, https://github.com/latent-reasoning-works/manylatents
Project-URL: Documentation, https://latent-reasoning-works.github.io/manylatents/
Project-URL: Repository, https://github.com/latent-reasoning-works/manylatents
Project-URL: Issues, https://github.com/latent-reasoning-works/manylatents/issues
Project-URL: Changelog, https://github.com/latent-reasoning-works/manylatents/blob/main/CHANGELOG.md
Author-email: César Miguel Valdez Córdova <cesar.valdez@mila.quebec>, Matthew Scicluna <matthew.scicluna@mila.quebec>, Shuang Ni <shuang.ni@mila.quebec>
License-Expression: MIT
License-File: LICENSE
Keywords: dimensionality-reduction,embeddings,hydra,manifold-learning,pytorch-lightning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.11
Requires-Dist: archetypes>=0.6
Requires-Dist: deprecated>=1.2
Requires-Dist: graphtools>=2.0
Requires-Dist: gudhi>=3.0
Requires-Dist: hydra-core>=1.3
Requires-Dist: hydra-submitit-launcher>=1.2
Requires-Dist: hydra-zen>=0.13
Requires-Dist: leidenalg>=0.10
Requires-Dist: lightning>=2.5
Requires-Dist: matplotlib>=3.8
Requires-Dist: multiscale-phate
Requires-Dist: numpy>=1.25
Requires-Dist: opentsne>=1.0
Requires-Dist: pandas>=2.0
Requires-Dist: phate>=2.0
Requires-Dist: pot>=0.9
Requires-Dist: python-igraph>=1.0
Requires-Dist: rich>=13.9
Requires-Dist: ripser>=0.6
Requires-Dist: scikit-learn>=1.2
Requires-Dist: scipy<1.15,>=1.8
Requires-Dist: torch<3.0,>=2.3
Requires-Dist: torchdiffeq>=0.2
Requires-Dist: torchmetrics>=1.6
Requires-Dist: torchsde>=0.2
Requires-Dist: tqdm>=4.67
Requires-Dist: umap-learn>=0.5
Requires-Dist: wandb>=0.25.0
Provides-Extra: all
Requires-Dist: datasets>=3.0; extra == 'all'
Requires-Dist: diffrax>=0.6; extra == 'all'
Requires-Dist: faiss-cpu; extra == 'all'
Requires-Dist: jax; extra == 'all'
Requires-Dist: manylatents-omics; extra == 'all'
Requires-Dist: optax>=0.2; extra == 'all'
Requires-Dist: ott-jax>=0.4; extra == 'all'
Requires-Dist: torchdr<0.4,>=0.3; extra == 'all'
Requires-Dist: transformers>=4.40; extra == 'all'
Provides-Extra: docs
Requires-Dist: mkdocs-macros-plugin>=1.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.6; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Provides-Extra: hf
Requires-Dist: datasets>=3.0; extra == 'hf'
Requires-Dist: transformers>=4.40; extra == 'hf'
Provides-Extra: jax
Requires-Dist: diffrax>=0.6; extra == 'jax'
Requires-Dist: jax; extra == 'jax'
Requires-Dist: optax>=0.2; extra == 'jax'
Requires-Dist: ott-jax>=0.4; extra == 'jax'
Provides-Extra: omics
Requires-Dist: manylatents-omics; extra == 'omics'
Provides-Extra: torchdr
Requires-Dist: faiss-cpu; extra == 'torchdr'
Requires-Dist: torchdr<0.4,>=0.3; extra == 'torchdr'
Description-Content-Type: text/markdown

<div align="center">

<pre>
     .  . .
  .  .. . . ..       .  . .
 . . .  . .. . . -->  . .. .  -->  λ(·)
  . ..  . .  .       .  . .
    .  . .

        m a n y l a t e n t s

  one geometry, learned through many latents
</pre>

[![license](https://img.shields.io/badge/license-MIT-2DD4BF.svg)](LICENSE)
[![python](https://img.shields.io/badge/python-3.11+-2DD4BF.svg)](https://www.python.org)
[![uv](https://img.shields.io/badge/pkg-uv-2DD4BF.svg)](https://docs.astral.sh/uv/)
[![PyPI](https://img.shields.io/badge/PyPI-manylatents-2DD4BF.svg)](https://pypi.org/project/manylatents/)

</div>

---

## install

```bash
uv add manylatents
```

Optional extras:

```bash
uv add manylatents[hf]         # HuggingFace trainer
uv add manylatents[torchdr]    # GPU-accelerated DR via TorchDR
uv add manylatents[jax]        # JAX backend (diffrax)
uv add manylatents[all]        # everything
```

<details>
<summary>pip also works</summary>

```bash
pip install manylatents
```

</details>

## quickstart

```bash
# embed a swiss roll with UMAP
manylatents algorithms/latent=umap data=swissroll

# add metrics
manylatents algorithms/latent=umap data=swissroll \
  metrics=trustworthiness

# sweep algorithms
manylatents --multirun \
  algorithms/latent=umap,phate,tsne \
  data=swissroll metrics=trustworthiness
```

<details>
<summary>development install</summary>

```bash
git clone https://github.com/latent-reasoning-works/manylatents.git
cd manylatents && uv sync
```

</details>

```python
from manylatents.api import run

result = run(data="swissroll", algorithm="pca", metrics=["trustworthiness"])

embeddings = result["embeddings"]   # (n, d) ndarray
scores     = result["scores"]       # {"trustworthiness": 0.95}

# chain: PCA 50d -> PHATE 2d
result2 = run(input_data=result["embeddings"], algorithm="phate")
```

---

## architecture

```
  CLI                         API
  manylatents ...             run(data=, algorithm=, ...)
       │                           │
       ▼                           ▼
  ┌─────────┐               ┌───────────┐
  │ main.py │               │  api.py   │
  │ Hydra   │               │ registries│
  └────┬────┘               └─────┬─────┘
       │    instantiate objects    │
       └──────────┬───────────────┘
                  ▼
        ┌──────────────────┐      ┌────────────────┐
        │  experiment.py   │─────►│  evaluate.py   │
        │  run_experiment()│      │  evaluate()    │
        │                  │      │  prewarm_cache │
        │  LatentModule    │      │  compute_knn   │
        │    fit/transform │      │  metric_fn(    │
        │  LightningModule │      │   cache=cache) │
        │    trainer.fit   │      └────────────────┘
        └──────────────────┘
```

Two base classes, one decision rule:

| if the algorithm... | use | interface |
|---|---|---|
| has no training loop | `LatentModule` | `fit(x)` / `transform(x)` |
| trains with backprop | `LightningModule` | `trainer.fit()` / `encode(x)` |

Both produce `LatentOutputs` — a dict keyed by `"embeddings"`. All metrics receive a shared `cache` dict for deduplicated kNN and eigenvalue computation.

---

## [algorithms](https://latent-reasoning-works.github.io/manylatents/algorithms/)

> 17 algorithms -- 12 latent modules, 5 lightning modules

PCA, t-SNE, UMAP, PHATE, DiffusionMap, MDS, MultiscalePHATE, Merging,
Classifier, Leiden, ReebGraph, SelectiveCorrection,
Autoencoder, AANet, LatentODE, HF Trainer, Reconstruction AE.

`neighborhood_size=k` sweeps kNN uniformly across algorithms.

---

## [metrics](https://latent-reasoning-works.github.io/manylatents/metrics/)

> 20+ metrics across three evaluation contexts

Embedding fidelity (trustworthiness, continuity, kNN preservation), spectral
analysis (affinity spectrum, spectral decay rate), topological features
(persistent homology), and dataset properties (stratification).

All metrics share a `cache` dict for deduplicated kNN computation.
List-valued parameters expand via `flatten_and_unroll_metrics()` --
one kNN computation covers the entire sweep.

Config pattern: `metrics=<name>` (each metric config has an `at:` field for evaluation context)

---

## [data](https://latent-reasoning-works.github.io/manylatents/data/)

> 6 synthetic manifolds + precomputed loader

Swiss roll, torus, saddle surface, gaussian blobs, DLA tree, and custom `.npy`/`.npz` files.
Domain-specific datasets (genomics, single-cell) available via extensions.

---

## citing

If manylatents was useful in your research, a citation goes a long way:

```bibtex
@software{manylatents2026,
  title     = {manyLatents: Unified Dimensionality Reduction and Neural Network Analysis},
  author    = {Valdez C{\'o}rdova, C{\'e}sar Miguel and Scicluna, Matthew and Ni, Shuang},
  year      = {2026},
  url       = {https://github.com/latent-reasoning-works/manylatents},
  license   = {MIT}
}
```

---

<br><br>

<p align="center">
<sub>MIT License &middot; <a href="https://github.com/latent-reasoning-works">Latent Reasoning Works</a></sub>
</p>
