Estimators

UMAP

UMAP(
    n_components: int = 2,
    n_neighbors: int = 15,
    metric: str = "euclidean",
    min_dist: float = 0.5,
    spread: float = 1.0,
    n_epochs: int = 500,
    learning_rate: float = 1.0,
    init: str = "spectral",
    ann: str = "kmknn",
    optimiser: str = "adam_parallel",
    randomised: bool = False,
    init_range: float | None = None,
    seed: int = 42,
    verbose: int = 0,
    nn_params: NeighbourParams | None = None,
    graph_params: UmapGraph | None = None,
    optim_params: UmapOptim | None = None,
)

Bases: BaseEmbedding

Uniform manifold approximation and projection.

The default optimiser is the multi-threaded Adam one, which is where most of the speed comes from; "sgd" reproduces the original reference behaviour more closely and is slower. Spectral initialisation is the default and is worth keeping: PCA is the fallback when the Laplacian will not converge, and random init throws away the global structure spectral gives you for free.

Parameters:

Name	Type	Description	Default
n_components	int	Output dimensionality.	2
n_neighbors	int	Neighbours per point. The locality knob: small values chase fine structure, large ones preserve more of the global picture.	15
metric	str	"euclidean"/"l2", "cosine" or "manhattan"/"l1".	'euclidean'
min_dist	float	How tightly points may pack in the embedding. Together with spread it fits the repulsion curve; neither is used for anything else.	0.5
spread	float	Scale of the embedding relative to min_dist.	1.0
n_epochs	int	Optimisation epochs.	500
learning_rate	float	Initial learning rate.	1.0
init	str	"spectral", "pca" or "random".	'spectral'
ann	str	Neighbour backend. "kmknn" is exact and fast up to a few hundred thousand points; "hnsw" or "nndescent" past that.	'kmknn'
optimiser	str	"adam_parallel", "adam" or "sgd".	'adam_parallel'
randomised	bool	Use randomised SVD for the PCA initialisation. No effect under spectral or random init.	False
init_range	float | None	Scale of the initial coordinates. None lets the core pick per initialisation.	None
seed	int	Fixes the initialisation and the negative sampling.	42
verbose	int	0 silent, 1 normal, 2 detailed. Progress goes to the process stdout, not sys.stdout. In Jupyter that lands in the terminal running the kernel.	0
nn_params	NeighbourParams | None	Backend-specific neighbour knobs. See NeighbourParams.	None
graph_params	UmapGraph | None	Fuzzy simplicial set knobs. See UmapGraph.	None
optim_params	UmapOptim | None	Remaining optimiser knobs. See UmapOptim.	None

DensMAP

DensMAP(
    n_components: int = 2,
    n_neighbors: int = 15,
    metric: str = "euclidean",
    min_dist: float = 0.5,
    spread: float = 1.0,
    lambda_: float = 2.0,
    n_epochs: int = 500,
    learning_rate: float = 1.0,
    init: str = "spectral",
    ann: str = "kmknn",
    optimiser: str = "adam_parallel",
    randomised: bool = False,
    init_range: float | None = None,
    seed: int = 42,
    verbose: int = 0,
    nn_params: NeighbourParams | None = None,
    graph_params: UmapGraph | None = None,
    optim_params: UmapOptim | None = None,
    dens_params: DensParams | None = None,
)

Bases: UMAP

UMAP with a density-preservation term.

Plain UMAP is free to stretch a dense region and squash a sparse one, so relative density in the embedding means nothing. densMAP adds a term correlating the local radii of the embedding with those of the original space, switched on only for the last DensParams.frac of the run so it corrects a settled embedding rather than fighting the layout.

Parameters:

Name	Type	Description	Default
lambda_	float	Weight on the density term. 0 recovers plain UMAP.	2.0
dens_params	DensParams | None	Remaining density knobs. See DensParams.	None

Everything else is as UMAP.

TSNE

TSNE(
    n_components: int = 2,
    perplexity: float = 30.0,
    metric: str = "euclidean",
    n_epochs: int = 1000,
    learning_rate: float | None = None,
    init: str = "pca",
    ann: str = "kmknn",
    approx: str = "barnes_hut",
    randomised_init: bool = True,
    init_range: float | None = None,
    seed: int = 42,
    verbose: int = 0,
    nn_params: NeighbourParams | None = None,
    optim_params: TsneOptim | None = None,
)

Bases: BaseEmbedding

t-distributed stochastic neighbour embedding.

Two-dimensional only, which is the core's restriction rather than this layer's. The learning rate defaults to the N-invariant max(N / 12, 200) heuristic rather than a fixed 200, so it does not need retuning when the dataset grows.

Parameters:

Name	Type	Description	Default
n_components	int	Output dimensionality. Must be 2.	2
perplexity	float	Effective neighbourhood size. The kNN search uses 3 * perplexity neighbours, so this also sets the graph width.	30.0
metric	str	"euclidean"/"l2", "cosine" or "manhattan"/"l1".	'euclidean'
n_epochs	int	Optimisation epochs.	1000
learning_rate	float | None	None applies the max(N / 12, 200) heuristic.	None
init	str	"pca", "spectral" or "random". PCA is the default and what makes a t-SNE run reproducible in shape rather than only in seed.	'pca'
ann	str	Neighbour backend.	'kmknn'
approx	str	Repulsion approximation. "barnes_hut" unless the extension was built with the fft_tsne feature, which the published wheel is not: FFTW is a system library no manylinux container carries.	'barnes_hut'
randomised_init	bool	Use randomised SVD for the PCA initialisation.	True
init_range	float | None	Scale of the initial coordinates.	None
seed	int	Fixes the initialisation.	42
verbose	int	0 silent, 1 normal, 2 detailed.	0
nn_params	NeighbourParams | None	See NeighbourParams.	None
optim_params	TsneOptim | None	See TsneOptim.	None

DensNE

DensNE(
    n_components: int = 2,
    perplexity: float = 30.0,
    metric: str = "euclidean",
    lambda_: float = 0.1,
    n_epochs: int = 1000,
    learning_rate: float | None = None,
    init: str = "pca",
    ann: str = "kmknn",
    approx: str = "barnes_hut",
    randomised_init: bool = True,
    init_range: float | None = None,
    seed: int = 42,
    verbose: int = 0,
    nn_params: NeighbourParams | None = None,
    optim_params: TsneOptim | None = None,
    dens_params: DensParams | None = None,
)

Bases: TSNE

t-SNE with a density-preservation term.

The same correction as DensMAP, applied to t-SNE. The default weight is much smaller than densMAP's because t-SNE's gradients are on a different scale, not because the effect is meant to be weaker.

Parameters:

Name	Type	Description	Default
lambda_	float	Weight on the density term. 0 recovers plain t-SNE.	0.1
dens_params	DensParams | None	Remaining density knobs. See DensParams.	None

Everything else is as TSNE.

PHATE

PHATE(
    n_components: int = 2,
    k: int = 5,
    metric: str = "euclidean",
    decay: float | None = 40.0,
    t: int | None = None,
    gamma: float = 1.0,
    mds: str = "sgd_dense",
    mds_iter: int | None = None,
    ann: str = "kmknn",
    randomised: bool = True,
    seed: int = 42,
    verbose: int = 0,
    nn_params: NeighbourParams | None = None,
    diffusion_params: PhateDiffusion | None = None,
)

Bases: BaseEmbedding

Potential of heat diffusion for affinity-based transition embedding.

Built for continuous structure rather than clusters: it powers a diffusion operator to time t, takes the potential distance between the resulting distributions, and lays those out with MDS. Trajectories and branch points survive this that t-SNE and UMAP tear apart.

t defaults to the von Neumann entropy knee, which is the right answer more often than a guess, and is worth pinning once you have looked at it.

Parameters:

Name	Type	Description	Default
n_components	int	Output dimensionality.	2
k	int	Neighbours used to build the affinity graph. Smaller than UMAP's because the diffusion does the smoothing.	5
metric	str	"euclidean"/"l2", "cosine" or "manhattan"/"l1".	'euclidean'
decay	float | None	Alpha-decay exponent of the kernel. None gives a binary connectivity kernel instead.	40.0
t	int | None	Diffusion time. None picks the VNE knee.	None
gamma	float	Informational distance constant, in [-1, 1]. 1 is the log potential, 0 the square-root potential.	1.0
mds	str	"sgd_dense" (also "dense") or "classic".	'sgd_dense'
mds_iter	int | None	MDS iterations. None uses the backend default.	None
ann	str	Neighbour backend.	'kmknn'
randomised	bool	Use randomised SVD for the initialisation.	True
seed	int	Fixes the initialisation and the landmark sampling.	42
verbose	int	0 silent, 1 normal, 2 detailed.	0
nn_params	NeighbourParams | None	See NeighbourParams.	None
diffusion_params	PhateDiffusion | None	Remaining operator knobs, landmarks included. See PhateDiffusion.	None

PaCMAP

PaCMAP(
    n_components: int = 2,
    n_near: int = 10,
    n_mid_near: int = 5,
    n_further: int = 20,
    mn_candidate_start: int = 4,
    mn_candidate_end: int = 50,
    metric: str = "euclidean",
    n_epochs: int = 450,
    learning_rate: float = 0.01,
    init: str = "pca",
    ann: str = "kmknn",
    optimiser: str = "adam_parallel",
    range_: float | None = 0.01,
    seed: int = 42,
    verbose: int = 0,
    nn_params: NeighbourParams | None = None,
    optim_params: PacmapOptim | None = None,
)

Bases: BaseEmbedding

Pairwise-controlled manifold approximation and projection.

Three kinds of pair rather than UMAP's one: near pairs pull, further pairs push, and mid-near pairs hold the global arrangement together while their weight decays over the first two phases. That decay is what lets PaCMAP keep global structure without the spectral initialisation UMAP leans on.

PCA initialisation is the default and close to required: random init costs PaCMAP most of its global-structure advantage.

Parameters:

Name	Type	Description	Default
n_components	int	Output dimensionality.	2
n_near	int	Near (attractive) pairs per point.	10
n_mid_near	int	Mid-near pairs per point.	5
n_further	int	Further (repulsive) pairs per point.	20
mn_candidate_start	int	First kNN slot the mid-near sampler draws from.	4
mn_candidate_end	int	Last such slot, and therefore the width of the kNN search. A precomputed graph must be at least this wide.	50
metric	str	"euclidean"/"l2", "cosine" or "manhattan"/"l1".	'euclidean'
n_epochs	int	Optimisation epochs across all three phases.	450
learning_rate	float	Adam learning rate.	0.01
init	str	"pca", "spectral" or "random".	'pca'
ann	str	Neighbour backend.	'kmknn'
optimiser	str	"adam_parallel" or "adam".	'adam_parallel'
range_	float | None	Scale of the initial coordinates.	0.01
seed	int	Fixes the initialisation and the pair sampling.	42
verbose	int	0 silent, 1 normal, 2 detailed.	0
nn_params	NeighbourParams | None	See NeighbourParams.	None
optim_params	PacmapOptim | None	Phase boundaries and Adam knobs. See PacmapOptim.	None

DiffusionMaps

DiffusionMaps(
    n_components: int = 2,
    k: int = 5,
    metric: str = "euclidean",
    alpha: float = 1.0,
    t: int | None = None,
    bandwidth_scale: float = 1.0,
    thresh: float = 0.0001,
    graph_symmetry: str = "add",
    n_landmarks: int | None = None,
    landmark_method: str = "spectral",
    n_svd: int | None = None,
    ann: str = "kmknn",
    seed: int = 42,
    verbose: int = 0,
    nn_params: NeighbourParams | None = None,
)

Bases: BaseEmbedding

Diffusion maps.

The spectral embedding of a diffusion operator, which is the thing PHATE builds on top of. alpha is the knob worth understanding: 0 gives the normalised graph Laplacian, 0.5 the Fokker-Planck operator, 1 the Laplace-Beltrami operator, which is the one that removes the influence of sampling density.

Parameters:

Name	Type	Description	Default
n_components	int	Output dimensionality, meaning eigenvectors kept.	2
k	int	Neighbours used to build the kernel.	5
metric	str	"euclidean"/"l2", "cosine" or "manhattan"/"l1".	'euclidean'
alpha	float	Anisotropic density-correction exponent in [0, 1].	1.0
t	int | None	Diffusion time. None picks the VNE knee.	None
bandwidth_scale	float	Multiplier on the adaptive kernel bandwidth.	1.0
thresh	float	Kernel entries below this are zeroed.	0.0001
graph_symmetry	str	"add", "multiply", "mnn" or "none".	'add'
n_landmarks	int | None	Landmarks to diffuse on instead of the full graph. None or a value at least n_samples runs the full operator.	None
landmark_method	str	"spectral", "random" or "density".	'spectral'
n_svd	int | None	Components for spectral landmark selection.	None
ann	str	Neighbour backend.	'kmknn'
seed	int	Fixes the landmark sampling.	42
verbose	int	0 silent, 1 normal, 2 detailed.	0
nn_params	NeighbourParams | None	See NeighbourParams.	None