Metadata-Version: 2.4
Name: pysgtsnepi
Version: 0.3.1
Summary: Pure Python implementation of SG-t-SNE-Π: Swift Neighbor Embedding of Sparse Stochastic Graphs
Project-URL: Homepage, https://t-sne-pi.cs.duke.edu
Project-URL: Documentation, https://qqgjyx.com/pysgtsnepi/
Project-URL: Repository, https://github.com/qqgjyx/sgtsnepi
Project-URL: Issues, https://github.com/qqgjyx/sgtsnepi/issues
Author-email: Juntang Wang <jw853@duke.edu>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: numba>=0.61
Requires-Dist: numpy>=1.23
Requires-Dist: pynndescent>=0.5
Requires-Dist: scikit-learn>=1.2
Requires-Dist: scipy>=1.9
Provides-Extra: dev
Requires-Dist: ipykernel>=6.29; extra == 'dev'
Requires-Dist: matplotlib>=3.5; extra == 'dev'
Requires-Dist: nbclient>=0.10; extra == 'dev'
Requires-Dist: nbformat>=5.10; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: scikit-image>=0.20; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-awesome-pages-plugin; extra == 'docs'
Requires-Dist: mkdocs-jupyter; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Provides-Extra: examples
Requires-Dist: matplotlib>=3.5; extra == 'examples'
Requires-Dist: scikit-image>=0.20; extra == 'examples'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == 'viz'
Requires-Dist: seaborn>=0.12; extra == 'viz'
Description-Content-Type: text/markdown

# <img src="docs/assets/sgtsne.png" width="40px" align="center" alt="SG-t-SNE-Pi logo"> PySGtSNEpi

<img src="docs/assets/logo.png" width="800px" align="center" alt="SG-t-SNE-Pi embedding demo">

[![PyPI version](https://badge.fury.io/py/pysgtsnepi.svg)](https://pypi.org/project/pysgtsnepi/)
[![Python 3.10–3.13](https://img.shields.io/pypi/pyversions/pysgtsnepi)](https://pypi.org/project/pysgtsnepi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/qqgjyx/sgtsnepi/actions/workflows/ci.yml/badge.svg)](https://github.com/qqgjyx/sgtsnepi/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-qqgjyx.com%2Fpysgtsnepi-blue)](https://qqgjyx.com/pysgtsnepi/)

> Embed sparse graphs into 2D/3D — pure Python, pip-installable, sklearn-compatible.

PySGtSNEpi is a pure Python port of the
[SG-t-SNE-Pi](https://t-sne-pi.cs.duke.edu) algorithm, translated from the
original [C++](https://github.com/fcdimitr/sgtsnepi) and
[Julia](https://github.com/fcdimitr/SGtSNEpi.jl) implementations.
Unlike standard t-SNE, SG-t-SNE-Pi works on **any sparse stochastic graph**,
not just kNN graphs derived from point clouds.
No C/C++ compiler needed — `pip install` and go.

## Features

- **1D / 2D / 3D embedding** of sparse stochastic graphs
- **Arbitrary sparse graph input** — not limited to kNN graphs
- **Point cloud input** with automatic kNN graph construction via [PyNNDescent](https://github.com/lmcinnes/pynndescent)
- **Lambda rescaling** to equalize effective node degrees
- **Scikit-learn compatible** API (`fit` / `transform` / `fit_transform`)
- **Pure Python** — runs on Windows, macOS (including Apple Silicon), and Linux
- **Numba JIT** compiled hot loops for near-native speed
- **FFT-accelerated** repulsive force computation

## Quick Start

```bash
pip install pysgtsnepi
```

### Scikit-learn API (point cloud)

```python
from pysgtsnepi import SGtSNEpi

model = SGtSNEpi(d=2, lambda_=10)
Y = model.fit_transform(X)   # X is (n_samples, n_features)
```

### Functional API (sparse graph)

```python
from scipy.io import mmread
from pysgtsnepi import sgtsnepi

P = mmread("graph.mtx")       # sparse stochastic graph
Y = sgtsnepi(P, d=3, lambda_=10)
```

## Roadmap

- [x] Lambda equalization
- [x] kNN graph construction (via PyNNDescent)
- [x] Core SG-t-SNE-Pi embedding (attractive + repulsive forces)
- [x] FFT-accelerated repulsive forces
- [x] Numba JIT for interpolation and gradient kernels
- [x] 1D / 3D embedding support
- [x] `SGtSNEpi` sklearn estimator class
- [x] `sgtsnepi()` functional API

## Citation

If you use this package in your research, please cite:

```bibtex
@article{pitsianis2019joss,
  title     = {{SG-t-SNE-$\Pi$}: Swift Neighbor Embedding of Sparse Stochastic Graphs},
  author    = {Pitsianis, Nikos and Floros, Dimitris and Iliopoulos, Alexandros-Stavros and Sun, Xiaobai},
  journal   = {Journal of Open Source Software},
  volume    = {4},
  number    = {39},
  pages     = {1577},
  year      = {2019},
  doi       = {10.21105/joss.01577}
}

@inproceedings{pitsianis2019hpec,
  title     = {Spaceland Embedding of Sparse Stochastic Graphs},
  author    = {Pitsianis, Nikos and Iliopoulos, Alexandros-Stavros and Floros, Dimitris and Sun, Xiaobai},
  booktitle = {IEEE High Performance Extreme Computing Conference},
  year      = {2019},
  doi       = {10.1109/HPEC.2019.8916505}
}
```

## Links

- [Algorithm website](https://t-sne-pi.cs.duke.edu)
- [C++ implementation](https://github.com/fcdimitr/sgtsnepi)
- [Julia implementation](https://github.com/fcdimitr/SGtSNEpi.jl)
- [Documentation](https://qqgjyx.com/pysgtsnepi/)

## License

MIT — see [LICENSE](https://github.com/qqgjyx/sgtsnepi/blob/main/LICENSE).
