psne-poisson-neighbor-python 0.1.0__py3-none-any.whl

psne_poisson_neighbor_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.1
+Name: psne-poisson-neighbor-python
+Version: 0.1.0
+Summary: p-SNE: Poisson Stochastic Neighbor Embedding. Nonlinear dimensionality reduction for sparse count data (neural spike counts, scRNA-seq, text corpora).
+Author: Noga Mudrik, Adam S. Charles
+License: MIT
+Project-URL: Homepage, https://github.com/NogaMudrik/PSNE-Poisson-Stochastic-Neighbor-Embedding
+Project-URL: Paper, https://arxiv.org/abs/2604.16932
+Project-URL: Issues, https://github.com/NogaMudrik/PSNE-Poisson-Stochastic-Neighbor-Embedding/issues
+Keywords: dimensionality-reduction,t-SNE,Poisson,count-data,sparse-data,visualization,embedding,neuroscience,scRNA-seq,spike-counts
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: numpy >=1.21
+Requires-Dist: scipy >=1.7
+Requires-Dist: scikit-learn >=1.0
+Requires-Dist: matplotlib >=3.5
+Requires-Dist: seaborn >=0.11
+
+# p-SNE: Poisson Stochastic Neighbor Embedding
+
+[![arXiv](https://img.shields.io/badge/arXiv-2604.16932-b31b1b.svg)](https://arxiv.org/abs/2604.16932)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+**A nonlinear dimensionality reduction method for sparse count data.**
+
+p-SNE embeds high-dimensional count matrices (neural spike counts, text corpora) into 2D or 3D, using Poisson KL divergence to measure pairwise dissimilarity and Hellinger distance to optimize the embedding. It follows the same API conventions as scikit-learn's t-SNE.
+
+📄 **Paper:** [Neighbor Embedding for High-Dimensional Sparse Poisson Data](https://arxiv.org/abs/2604.16932) (arXiv 2604.16932)
+
+💻 **Code:** [github.com/NogaMudrik/PSNE-Poisson-Stochastic-Neighbor-Embedding](https://github.com/NogaMudrik/PSNE-Poisson-Stochastic-Neighbor-Embedding)
+
+📝 **Blog post:** [Life Is Too Short for Wrong Metrics](https://pub.aimind.so/life-is-too-short-for-wrong-metrics-visualizing-sparse-count-data-with-p-sne-0c6ae0a191c9)
+
+---
+
+## Why p-SNE?
+
+Standard dimensionality reduction methods (t-SNE, UMAP, PCA) assume continuous, Gaussian-distributed features. When applied to sparse count data, they treat zeros as informative distances and ignore the mean-variance coupling inherent in Poisson observations. This leads to distorted embeddings where structure is lost or fabricated.
+
+p-SNE replaces the Euclidean distance in t-SNE with a Poisson KL divergence that respects the discrete, non-negative nature of count data. On sparse neural recordings, text word counts, and single-cell RNA-seq data, p-SNE recovers cluster structure that t-SNE, UMAP, and PCA miss.
+
+---
+
+## Installation
+
+```bash
+pip install p-sne
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/NogaMudrik/PSNE-Poisson-Stochastic-Neighbor-Embedding.git
+cd PSNE-Poisson-Stochastic-Neighbor-Embedding
+pip install -r requirements.txt
+```
+
+Core dependencies: `numpy`, `scipy`, `scikit-learn`, `matplotlib`, `seaborn`.
+
+---
+
+## Quick start
+
+```python
+import numpy as np
+from psne.psne_core import PSNE
+
+X = np.random.poisson(5, size=(50, 30)).astype(float)
+model = PSNE(n_components=2, max_iter=500, eta=100.0, verbose=True)
+embedding = model.fit_transform(X)
+```
+
+With your own data:
+
+```python
+import numpy as np
+from psne.psne_core import PSNE
+
+X = np.load('my_data.npy').astype(float)
+assert np.all(X >= 0), 'p-SNE requires non-negative input'
+
+model = PSNE(
+    n_components=3,
+    s_mode='weight_exp',
+    weight_exp=1.0,
+    eta=200.0,
+    max_iter=1000,
+    gamma=0.0,
+    use_momentum=True,
+    use_early_exaggeration=True,
+    verbose=True,
+)
+embedding = model.fit_transform(X)
+```
+
+Plotting:
+
+```python
+import matplotlib.pyplot as plt
+
+labels = np.load('my_labels.npy')
+
+fig, ax = plt.subplots()
+ax.scatter(embedding[:, 0], embedding[:, 1], c=labels, cmap='tab10', s=30)
+ax.set_xlabel('$y_1$')
+ax.set_ylabel('$y_2$')
+plt.show()
+```
+
+For 3D:
+
+```python
+fig = plt.figure()
+ax = fig.add_subplot(111, projection='3d')
+ax.scatter(embedding[:, 0], embedding[:, 1], embedding[:, 2], c=labels, cmap='tab10', s=30)
+plt.show()
+```
+
+---
+
+## Method
+
+1. **Poisson KL distance matrix.** Asymmetric divergence between all sample pairs:
+
+$$D_{ij} = \frac{1}{N}\sum_n \left[ x_{n,i} \log\frac{x_{n,i}+\epsilon}{x_{n,j}+\epsilon} + x_{n,j} - x_{n,i} \right]$$
+
+2. **High-dimensional joint probabilities** $S$: convert $D$ into a symmetric probability matrix via a global weight exponent or adaptive per-point perplexity.
+3. **Low-dimensional joint probabilities** $Q$: Cauchy kernel over the embedding coordinates, as in t-SNE.
+4. **Hellinger cost:** minimize $H(S, Q)$ instead of KL divergence.
+5. **Optional group-lasso penalty:** $\gamma \sum_n \|y_n\|_2$ promotes sparsity across embedding dimensions.
+6. **Optimizer:** gradient descent with momentum and early exaggeration.
+
+---
+
+## Data format
+
+- Shape: $(N, T)$ where $N$ is features (neurons, genes, words) and $T$ is samples (conditions, cells, documents).
+- Type: `float` or `int` numpy array.
+- Values: non-negative.
+
+Samples are columns, features are rows. The output embedding has shape `(T, n_components)` with samples as rows. Remove all-zero samples before fitting.
+
+---
+
+## Parameters
+
+**Model:**
+
+| Parameter | Default | Description |
+|---|---|---|
+| `n_components` | 3 | Embedding dimensionality. |
+| `s_mode` | `'weight_exp'` | How to build $S$: `'weight_exp'` (global) or `'perplexity'` (adaptive). |
+| `weight_exp` | 1.0 | Weight exponent for `s_mode='weight_exp'`. Higher sharpens neighborhoods. |
+| `perplexity` | 30.0 | Target perplexity for `s_mode='perplexity'`. Must be < number of samples. |
+| `epsilon` | 1e-2 | Smoothing constant for Poisson KL. |
+| `gamma` | 0.0 | Group-lasso regularization weight ($\gamma > 0$ enforces sparsity). |
+| `random_state` | 42 | Random seed for initialization. |
+
+**Optimizer:**
+
+| Parameter | Default | Description |
+|---|---|---|
+| `eta` | 200.0 | Learning rate. |
+| `max_iter` | 1000 | Maximum iterations. |
+| `tol` | 1e-8 | Convergence tolerance on cost change. |
+| `use_momentum` | True | Enable momentum. |
+| `momentum_alpha` | 0.5 | Initial momentum coefficient. |
+| `momentum_alpha_final` | 0.8 | Final momentum coefficient. |
+| `momentum_switch_iter` | 250 | Iteration at which momentum switches. |
+| `use_early_exaggeration` | True | Multiply $S$ by `exaggeration_factor` for the first iterations. |
+| `exaggeration_factor` | 12.0 | Exaggeration multiplier. |
+| `exaggeration_iters` | 250 | Number of exaggeration iterations. |
+
+---
+
+## Attributes (after fitting)
+
+| Attribute | Shape | Description |
+|---|---|---|
+| `embedding_` | `(n_components, T)` | Learned embedding. `fit_transform` returns the transpose. |
+| `cost_history_` | list | Total cost at each iteration. |
+| `hellinger_history_` | list | Hellinger distance at each iteration. |
+| `D_` | $(T, T)$ | Poisson KL distance matrix. |
+| `S_` | $(T, T)$ | High-dimensional joint probabilities. |
+| `Q_` | $(T, T)$ | Final low-dimensional joint probabilities. |
+| `n_iter_` | int | Number of iterations run. |
+
+---
+
+## Demo
+
+```bash
+python psne_demo_nonlinear.py
+```
+
+Runs two synthetic datasets (3-group and 4-group XOR), compares p-SNE against baselines (t-SNE, UMAP, PCA, ZIFA, scVI, GLM-PCA, Poisson GPFA), and saves embedding plots, cost curves, and `.npy` files.
+
+---
+
+## File structure
+
+```
+PSNE-Poisson-Stochastic-Neighbor-Embedding/
+├── psne/
+│   ├── __init__.py
+│   ├── psne_core.py
+│   ├── psne_config.py
+│   └── psne_utils.py
+├── psne_demo_nonlinear.py
+├── pyproject.toml
+├── requirements.txt
+├── LICENSE
+└── README.md
+```
+
+---
+
+## Citation
+
+If you use p-SNE, please cite:
+
+```bibtex
+@article{mudrik2026neighbor,
+  title={Neighbor Embedding for High-Dimensional Sparse Poisson Data},
+  author={Mudrik, Noga and Charles, Adam S},
+  journal={arXiv preprint arXiv:2604.16932},
+  year={2026}
+}
+```

psne_poisson_neighbor_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+psne_poisson_neighbor_python-0.1.0.dist-info/METADATA,sha256=eIHSaq90_SMXP4r2vTjCY8S76yZ-x6S62uy4_s6EE6o,8726
+psne_poisson_neighbor_python-0.1.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+psne_poisson_neighbor_python-0.1.0.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+psne_poisson_neighbor_python-0.1.0.dist-info/RECORD,,

psne_poisson_neighbor_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.42.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

psne_poisson_neighbor_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+