phate-manifold-metrics 1.0.0
Manifold-aware semantic and relational affinity metrics using PHATE
License: MIT
Requires Python: >=3.9
Keywords: phate, manifold, metrics, embeddings, semantic-affinity, relational-affinity, NLP

# PHATE Manifold Metrics

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Manifold-aware semantic and relational affinity metrics using PHATE.

## Overview

Compute **Semantic Affinity (SA)** and **Relational Affinity (RA)** metrics that leverage manifold geometry to capture non-Euclidean structure in embedding spaces.

### Key Features

✨ **Multi-scale Analysis**: Compare metrics at t=1 (baseline) vs t=5-6 (manifold)
✨ **Multiple RA Variants**: Euclidean, Geodesic, Diffusion
✨ **Clustering-free SA**: Distribution-based (no labels required)
✨ **Analogy Support**: Specialized 4-word analogy methods
✨ **Optional Loaders**: FastText, LaBSE, Ollama, OpenRouter
✨ **Dataset Utilities**: CSV loading and parsing

## Installation

```bash
# Core metrics only
pip install phate-manifold-metrics

# With embedding loaders
pip install phate-manifold-metrics[embeddings]

# Development (includes pytest, black, mypy)
pip install phate-manifold-metrics[all]
```

## Quick Start

```python
import numpy as np
from phate_manifold_metrics import PhateManifoldMetrics

# Load/generate embeddings
embeddings = np.random.randn(100, 384)

# Initialize & fit
metrics = PhateManifoldMetrics(knn=5, t=6)
metrics.fit(embeddings)

# Define word pairs
pairs = [(0,1), (2,3), (4,5)]

# Compute SA
sa = metrics.compute_semantic_affinity(pairs)
print(f"SA: {sa['sa_score']:.3f}")

# Compute RA variants
ra_euc = metrics.compute_relational_affinity_euc(pairs)
ra_geo = metrics.compute_relational_affinity_geo(pairs)
ra_dif = metrics.compute_relational_affinity_dif(pairs)

print(f"RA_euc: {ra_euc['ra_euc_score']:.3f}")
print(f"RA_geo: {ra_geo['ra_geo_score']:.3f}")
print(f"RA_dif: {ra_dif['ra_dif_score']:.3f}")
```

## CLI Usage

```bash
# Basic test
phate-metrics --knn 5 --t 6

# Dual-scale analysis
phate-metrics --dual-scale

# Euclidean metric
phate-metrics --metric euclidean
```

## Metrics Explained

### Semantic Affinity (SA)
Clustering quality in manifold space:
```
SA = 1 / (1 + CV)
where CV = std(distances) / mean(distances)
```
- Range: [0, 1], higher = better clustering
- No labels required

### Relational Affinity (RA)
Directional alignment of relational vectors:

**Statistical RA** (word pairs):
- `RA_euc`: Euclidean (flat space baseline)
- `RA_geo`: Geodesic (k-NN graph shortest paths)
- `RA_dif`: Diffusion (PHATE manifold)
- Range: [-1, 1], higher = stronger alignment

**Analogy RA** (4-word test cases a:b::c:d):
- `RA_euc_analogy`: Euclidean parallelogram
- `RA_geo_analogy`: Geodesic parallelogram
- Range: [0, 1], higher = stronger analogy

## Parameters

| Parameter | Description | Recommendation |
|-----------|-------------|----------------|
| `knn` | k-Nearest neighbors | 5-10 (start with 5) |
| `t` | Diffusion time | 1 (baseline), 6 (manifold) |
| `metric` | Distance metric | 'cosine' (normalized), 'euclidean' |

## Optional: Embedding Loaders

### FastText
```python
from phate_manifold_metrics.embeddings import load_fasttext_from_extracted

embeddings = load_fasttext_from_extracted(["cat", "dog"], lang='en')
```

### LaBSE
```python
from phate_manifold_metrics.embeddings import load_labse_embeddings

embeddings = load_labse_embeddings(["hello", "你好", "hola"])
```

### Ollama
```python
from phate_manifold_metrics.embeddings.ollama import get_ollama_embeddings_fixed

embeddings = get_ollama_embeddings_fixed(
    ["cat", "dog"],
    model_name="snowflake-arctic-embed2"
)
```

### OpenRouter API
```python
import os
from phate_manifold_metrics.embeddings.openrouter import load_openrouter_embeddings

os.environ['OPENROUTER_API_KEY'] = 'your-key'
embeddings = load_openrouter_embeddings(
    ["hello", "world"],
    model_path="qwen/qwen3-embedding-8b",
    model_name="Qwen3-8B"
)
```

## Documentation

Full API documentation available in docstrings:
```python
from phate_manifold_metrics import PhateManifoldMetrics
help(PhateManifoldMetrics)
```

## Citation

```bibtex
@software{phate_manifold_metrics,
  title = {PHATE Manifold Metrics},
  author = {Digital Duck},
  year = {2026},
  url = {https://github.com/digital-duck/phate-manifold-metrics}
}
```

## References

- **PHATE**: Moon et al., Nature Biotechnology 2019
- **Diffusion Distance**: Coifman & Lafon, Applied and Computational Harmonic Analysis 2006

## License

MIT License - Copyright (c) 2026 Digital Duck

## Authors

Digital Duck (Wen + Claude Sonnet 4.5 + Google Gemini 2.5)