Scikit-Learn · Class

SpectralClustering

Clusters samples by embedding an affinity matrix through the normalized Laplacian and then labeling points in the embedded space. It is particularly useful for small, non-convex clusters where center-and-spread descriptions are inadequate.

How it works

SpectralClustering creates an affinity-based spectral embedding, then assigns samples to clusters in that lower-dimensional representation. The affinity can be learned from features with a kernel or nearest-neighbor graph, or supplied directly as a precomputed matrix.

Syntax

class sklearn.cluster.SpectralClustering(n_clusters=8, *, eigen_solver=None, n_components=None, random_state=None, n_init=10, gamma=1.0, affinity='rbf', n_neighbors=10, eigen_tol='auto', assign_labels='kmeans', degree=3, coef0=1, kernel_params=None, verbose=False)

Parameters

Name	Type	Description
`n_clusters`	`int`	Number of clusters to extract; default 8.
`eigen_solver`	`{'arpack', 'lobpcg', 'amg'} or None`	Eigenvalue decomposition strategy: 'arpack', 'lobpcg', or 'amg'; default None.
`n_components`	`int or None`	Number of eigenvectors used for the spectral embedding; default None.
`gamma`	`float`	Kernel coefficient for rbf, poly, sigmoid, laplacian, and chi2 kernels; default 1.0.
`affinity`	`str or callable`	Affinity construction method, such as 'rbf', 'nearest_neighbors', 'precomputed', or a callable; default 'rbf'.
`eigen_tol`	`float`	Tolerance for eigenvalue decomposition; default 'auto'.
`n_init`	`int`	Number of KMeans initializations when assign_labels='kmeans'; default 10.
`random_state`	`int, RandomState instance, or None`	Random seed or random generator controlling randomized behavior; default None.
`assign_labels`	`{'kmeans', 'discretize', 'cluster_qr'}`	Label-assignment method: 'kmeans', 'discretize', or 'cluster_qr'; default 'kmeans'.
`verbose`	`bool`	Whether to enable verbose output; default False.

Returns

fit_predict returns an ndarray of cluster labels for each sample; fit returns the fitted estimator.

Key points

The estimator clusters a spectral projection derived from the normalized Laplacian.
n_clusters sets the requested number of output groups and defaults to 8.
n_components controls the dimensionality of the spectral embedding.
eigen_solver selects the eigendecomposition method: ARPACK, LOBPCG, or AMG.

Common mistakes

You must set n_clusters before fitting; the estimator does not infer the number of clusters.
Prefer it for a small cluster count rather than a high-cardinality clustering problem.

Example: Cluster non-convex samples

from sklearn.cluster import SpectralClustering
from sklearn.datasets import make_moons

X, _ = make_moons(n_samples=200, noise=0.06, random_state=0)
model = SpectralClustering(
    n_clusters=2,
    affinity="nearest_neighbors",
    assign_labels="kmeans",
    random_state=0,
)
labels = model.fit_predict(X)
print(labels[:10])

Builds a two-cluster model for non-convex moon-shaped data and returns a cluster label for each sample.

When to use it

Non-convex feature clusters

Data forms curved, nested, or otherwise non-convex groups.

Graph-based clustering

Relationships are represented by a sparse graph rather than useful Euclidean centers.

Precomputed affinities

A similarity matrix is already available from domain-specific measurements.

Interview questions

QHow does SpectralClustering handle non-convex clusters?

It embeds the affinity matrix into a low-dimensional space using eigenvectors of the normalized Laplacian, then clusters the embedded samples, commonly with KMeans. This lets it represent non-convex cluster structure better than methods based on cluster centers.

Follow-up: When is it computationally attractive? It is especially efficient when the affinity matrix is sparse and the AMG solver is used for the eigenvalue problem.

QWhat does the affinity parameter control?

The default affinity is "rbf", which constructs an affinity matrix from pairwise similarities. Other choices include "nearest_neighbors", "precomputed", or a callable kernel; with "precomputed", X must be an affinity matrix.

Follow-up: What shape must a precomputed affinity have? It must be a square matrix with one row and column per sample.

QWhat are n_clusters and n_components used for?

n_clusters specifies how many clusters to extract and defaults to 8. n_components controls the number of eigenvectors used for the spectral embedding; when it is None, the implementation uses n_clusters eigenvectors.

Follow-up: Why can a large n_clusters be problematic? The documentation advises SpectralClustering for a small number of clusters, not many clusters.

sklearn.cluster.spectral_clustering
sklearn.cluster.KMeans
sklearn.cluster.AgglomerativeClustering
sklearn.cluster.DBSCAN

Source: SpectralClustering — scikit-learn 1.9.1 documentation. Checked 2026-10-15.