python-som

Implementation of Kohonen's 2-D self-organizing map. NumPy is the only dependency. Accepts NumPy arrays, pandas DataFrames, polars, pyarrow, and anything else implementing the __array__ protocol.

Documentation · Changelog

Install

pip install python-som                  # requires Python 3.10+; NumPy is the only dependency
pip install "python-som[cli]"           # adds tqdm progress bars
pip install "python-som[sklearn]"       # adds the scikit-learn estimator adapter
pip install "python-som[examples]"      # adds matplotlib and seaborn, for the plots

Training can also use a compiled kernel, worth up to 2.4x on batch training. It is a separate package rather than an extra, and it is picked up automatically once present:

pip install numba                       # note: numba currently requires numpy<2.5

Confirm it is active with python_som.accelerated(). See Speed up training.

Quick start

import numpy as np
import python_som

rng = np.random.default_rng(0)
data = rng.normal(size=(150, 4))

som = python_som.SOM(x=20, y=None, input_len=4, data=data, random_seed=42)
som.weight_initialization(mode="linear", data=data)
error = som.train(data, n_iteration=len(data), mode="batch")

umatrix = som.distance_matrix()
winner = som.winner(data[0])

The same map through the estimator interface, which Pipeline and GridSearchCV also understand:

som.fit(data, n_iteration=len(data), mode="batch")
labels = som.predict(data)  # (n_samples,) flat node index
distances = som.transform(data)  # (n_samples, x*y)

som.save_npz("map.npz")  # models plus provenance, no pickle
som = python_som.SOM.load_npz("map.npz")

A full worked example with plots is in examples/iris.py and in the getting-started guide.

Features

• NumPy is the only runtime dependency; a fresh install is 69 MB across one package
• Batch training 23x to 31x faster than MiniSom and 26x to 94x faster than SOMPY, measured
• Optional compiled kernel via numba, used automatically when installed; accelerated() reports it
• Stepwise and batch training
• Random, random-sampling and linear (PCA) weight initialization
• Automatic selection of the map size ratio, from PCA
• Cyclic arrays, for toroidal maps
• Gaussian, bubble and Mexican hat neighborhood functions
• Custom decay functions
• Save and load a trained map without pickle, so loading one cannot execute code
• Provenance: every run records its seed, iteration count, error and library versions
• Works as a scikit-learn estimator: fit, transform, predict, and an adapter for Pipeline, GridSearchCV and cross_val_score
• Options accepted as plain strings or enums, with typos caught by a type checker
• Visualization support: U-matrix, activation matrix
• Supervised labelling, via the label map
• Fully type-annotated, with a py.typed marker

Neighborhood functions

All three are functions of the distance between two nodes in the grid, sqdist(c, i) in Eq. (5) of Kohonen (2013).

Name	Shape	Notes
'gaussian'	exp(-r² / 2σ²)	Strictly positive, monotonically decreasing. The default.
'bubble'	1 for max(dx, dy) ≤ σ, else 0	The truncated inner lobe of the Mexican hat. Uses the Chebyshev metric, so the region is a square.
'mexicanhat'	(1 - u)·exp(-u), u = r² / 2σ²	Excitatory near the winner, inhibitory beyond it. Zero at r = √2·σ, minimum -e⁻² at r = 2σ.

The Mexican hat takes negative values, so it cannot be used with mode='batch': the batch update of Kohonen Eq. (8) is a weighted mean whose denominator is not sign-definite for a signed neighborhood function. Use mode='random' or mode='sequential'; mode='batch' raises a ValueError.

See Neighborhood functions for the derivations, including why the Mexican hat is not an outer product of two 1-D wavelets.

Upgrading

Two releases change numerical results. If you are reproducing a figure, pin the version that made it.

0.3.0 corrects several methodology defects, so results are not comparable with earlier versions. In particular random_seed no longer reproduces pre-0.3.0 maps: the generator is now per-instance rather than a call to np.random.seed on NumPy's global state. To reproduce older figures, pin python-som==0.2.0.

0.4.0 corrects linear initialization for data far from the origin. Its PCA previously went through scikit-learn's auto solver, which forms a covariance matrix and loses precision when the mean is large relative to the spread. On data offset by 1e7 the second explained variance was wrong by 5.8%. Near the origin the difference is floating-point noise. Timestamps, coordinates and absolute sensor readings are the cases that were affected.

0.4.0 also removed pandas and scikit-learn as runtime dependencies. If you imported either transitively through this package, depend on them directly, or install python-som[examples].

0.5.0 briefly made plain-string options emit a DeprecationWarning. 0.6.0 withdrew that: strings are permanent and 1.0.0 will not remove them. If you saw that warning, you can stop migrating.

0.7.0 makes batch training 20x to 40x faster by reorganising the same arithmetic. Because the sums happen in a different order, trained weights differ from 0.6.1 by about 1e-15 relative. That is far below anything a result depends on, and it does break an exact-equality check against a stored map: pin python-som==0.6.1 if you need one to match bit for bit. It also removes the neighborhood kernel helpers from the private python_som._core, which had no callers outside the package.

Each change and the passage of Kohonen (2013) behind it is in the changelog.

Development

uv sync --all-extras
uv run pytest --cov          # tests and coverage
uv run ruff check .          # lint
uv run ruff format --check . # formatting
uv run mypy                  # type-check
uv run bandit -c pyproject.toml -r src/   # security checks
uv run pip-audit             # known vulnerabilities in the resolved set
uv run mkdocs serve          # docs, locally
pre-commit install           # optional, run the gates on commit

numba is not a declared extra: uv resolves every extra into one lockfile, so declaring it would cap NumPy below 2.5 for the whole project. Install it alongside when working on the accelerated path, with uv run --with numba pytest tests/test_numba_kernel.py.

If you use the SonarQube for IDE (SonarLint) VS Code extension, it will also apply Sonar's Python rules locally; the ruff configuration is set up to cover most of the same ground.

Benchmarks

Hand-run, never part of the test suite: a timing assertion on shared hardware measures noise.

uv run python benchmarks/bench_vs_minisom.py   # vs MiniSom, agreement verified before timing
cd asv_benchmarks && uv run --extra bench asv continuous master HEAD   # this package across commits

Results and the method behind them are in Comparison with MiniSom and SOMPY. The SOMPY comparison needs an interpreter of its own, since SOMPY cannot be imported on NumPy 2; benchmarks/bench_vs_sompy.py prints the setup command and installs nothing.

References

Based on:

Teuvo Kohonen, Essentials of the self-organizing map, Neural Networks, Volume 37, 2013, Pages 52-65, ISSN 0893-6080, https://doi.org/10.1016/j.neunet.2012.09.018

The Mexican hat neighborhood follows the lateral-interaction formulation in:

O. J. Vrieze, Kohonen network, in: Artificial Neural Networks: An Introduction to ANN Theory and Practice, Lecture Notes in Computer Science, Volume 931, Springer, Berlin, Heidelberg, 1995, Pages 83-100, https://doi.org/10.1007/BFb0027024

License

MIT. See LICENSE.