openTSNE

1.0.4 verified Fri May 01 auth: no python

Extensible, parallel implementations of t-SNE for visualizing high-dimensional data. Supports multiple affinity models (e.g., multiscale mixture), optimization via Barnes-Hut or FIt-SNE, and out-of-sample embedding. Current version 1.0.4, requires Python >=3.9, with low release cadence (major/minor every few years).

pip install opentsne

Common errors

error AttributeError: module 'openTSNE' has no attribute 'TSNE' ↓

cause Importing with wrong case; the package name is 'openTSNE' but the module is also 'openTSNE', so `import openTSNE` works, but `from openTSNE import TSNE` is needed. Common mistake: using `import opentsne` (lowercase) which is not a standard alias.

fix

Use from openTSNE import TSNE or import openTSNE as tsne.

error ImportError: cannot import name 'TSNEEmbedding' from 'openTSNE' ↓

cause TSNEEmbedding is not directly importable from the top-level openTSNE; it resides in the `openTSNE.embedding` submodule in older versions, but in v1.x it is available from `openTSNE` directly. This error occurs when using an older version and trying the new import path.

fix

For openTSNE >=1.0.0: from openTSNE import TSNEEmbedding. For older versions (0.x): from openTSNE.embedding import TSNEEmbedding.

error ValueError: The 'perplexity' parameter must be an integer or a list of integers. ↓

cause openTSNE v0.6.2+ expects multiscale perplexity as a list (default [50, 500]) but passing a single float or integer incorrectly can trigger this error.

fix

Pass perplexity=30 for single perplexity, or perplexity=[50, 500] for multiscale.

Warnings

breaking In openTSNE v0.6.0, the API changed: affinities are no longer passed to TSNE constructor; use `affinities` parameter in `.fit()` method instead. Also, `TSNE` no longer accepts `affinities` at construction; custom affinities must be passed to `.fit()`. ↓

fix Pass affinities via `tsne.fit(X, affinities=my_affinity)` instead of `TSNE(affinities=...)`.

breaking The default affinity model changed from `PerplexityBasedNN` with a single perplexity to `MultiscaleMixture` with two perplexities (50 and 500) in v0.6.2. Results may differ from previous versions if not explicitly specifying perplexity. ↓

fix To replicate old behavior, use `TSNE(perplexity=30, affinities='perplexity')`.

breaking Python 3.6 support dropped in v1.0.1, and Python 3.9+ required starting v1.0.2. Older Python versions will fail to install. ↓

fix Use Python >=3.9 for openTSNE >=1.0.2.

Install

pip install opentsne[gpu]

Imports

TSNE
wrong
```
from opentsne import TSNE
```
correct
```
from openTSNE import TSNE
```
Library uses camelCase 'openTSNE' as package name, not lowercase.
TSNEEmbedding
```
from openTSNE import TSNEEmbedding
```
Affinity
```
from openTSNE.affinity import Affinity
```
MultiscaleMixture
```
from openTSNE.affinity import MultiscaleMixture
```
Default affinity model since v0.6.2.

Quickstart

Basic t-SNE embedding using default multiscale mixture affinity.

from openTSNE import TSNE
from sklearn.datasets import load_iris
import numpy as np

iris = load_iris()
X = iris.data
y = iris.target

# Initialize with default parameters (multiscale perplexity = [50, 500])
tsne = TSNE(random_state=42, verbose=False)
embedding = tsne.fit(X)

print(embedding.shape)  # (150, 2)