MiniSom: a Numpy-only Self-Organizing Map you can read end to end
:red_circle: MiniSom is a minimalistic implementation of the Self Organizing Maps
At a glance
- What is it?
- MiniSom implements Kohonen's Self-Organizing Map in roughly numpy-only Python, with optional Numba JIT acceleration, and its stated goal is to stay small enough for researchers to extend and students to read. The trade-off is that the library stops at training and quantization: the map display, the clustering and the outlier scores are your code, and the README points you at the examples directory rather than the API.
- Who is it for?
- Adopt MiniSom if you need a Self-Organizing Map you can read in one sitting and extend, and if you are willing to write the visualization, clustering and outlier logic yourself. Do not adopt it as a full clustering or dimensionality-reduction framework: it has no fit_transform contract and no built-in plotting.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 99 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What MiniSom actually solves, and who the README is written for
A Self-Organizing Map takes high-dimensional vectors and places them onto a low-dimensional grid so that nearby inputs land on nearby neurons. MiniSom does that in Python, and the README is explicit about the intended audience: the library is "designed to allow researchers to easily build on top of it and to give students the ability to quickly grasp its details." That sentence is also a scope statement. MiniSom is not a clustering pipeline that returns labels, and it is not a plotting library. It gives you a grid of weight vectors and a winner lookup, and it expects you to interpret the result. If you want a map image, the README points to the examples directory, which contains scripts producing a Seeds map, class assignment pies, handwritten digit mapping, hexagonal topology, color quantization and outlier detection. Those are demonstrations of what you build on top, not functions you import. The dependency footprint follows the same logic: the project "relying only on the numpy library and emphasizing vectorization in coding style," with Numba as an optional extra rather than a requirement.
The training loop, the winner lookup, and what the API does not expose
The mechanism is the classic Kohonen update, exposed through a constructor that takes grid dimensions, input dimension and the two decay parameters. The README's example is a 6 by 6 map over 4-dimensional data: MiniSom(6, 6, 4, sigma=0.3, learning_rate=0.5), followed by som.train(data, 100) for 100 iterations. Input is a Numpy matrix with one observation per row, or a list of lists in the same shape. After training, som.winner(data[0]) returns the position of the winning neuron for a sample, which is the primitive you build quantization and assignment on. Notice what is absent from the documented surface: there is no scikit-learn style fit_transform, no method that returns cluster labels, and no built-in distance-to-map or outlier score. The README's outlier detection example exists as a script, which tells you the scoring logic lives in user code. The constructor's sigma and learning_rate are the levers that matter, and the README gives no guidance on choosing them beyond the example values, so you are expected to know the algorithm or to experiment.
Getting it running, including the JIT path and its cold-start cost
Installation is one command: pip install minisom. For the Numba-accelerated path, pip install minisom[fast]. The README also documents a source route, git clone https://github.com/JustGlowing/minisom.git followed by python setup.py install, with the caveat that this installs the latest version "which might contain changes that are not parte of the stable release" (the typo is in the README). The fast path swaps the training call rather than the constructor: som.train_batch_offline_fast(data, 100) instead of som.train(data, 100). The README is honest about the cost of that switch: "The first call will be slightly slower due to JIT compilation; subsequent calls reuse the compiled code." No speedup number is given, so the only way to know whether the extra dependency earns its place is to time both calls on your own matrix. Persistence is plain pickle: dump the trained object to a file and load it back. One documented constraint sits here, and it is easy to trip over: "if a lambda function is used to define the decay factor MiniSom will not be pickable anymore." If you pass a lambda for decay, your trained model cannot be saved with the pattern the README shows.
Where MiniSom is the wrong tool
The first limitation is the one the project advertises as a feature. Minimalism means no plotting, no label assignment, no evaluation metric. A team that wants k-means-like output with an inertia curve and a predict method will spend more time writing glue than training maps. The second limitation is scale. MiniSom is numpy-based and vectorized, which is efficient for moderate matrices, but the map itself is a dense grid of weight vectors and the update touches neighborhoods of neurons per sample. The README offers Numba acceleration for "large datasets" without quantifying what large means, so treat that as unverified for your data. The third is reproducibility of the decay schedule: because a lambda decay function breaks pickling, the convenient way to customize decay and the convenient way to persist a model are in tension, and the README does not offer a workaround. Fourth, initialization is not seeded in any documented way. The README shows no random_state parameter, so two runs of the same script may produce different maps, and the examples do not demonstrate how to make results repeatable. If your workflow requires bit-identical reruns, that gap matters more than any speed consideration.
MiniSom against scikit-learn's SOM-shaped alternatives
The obvious comparison is scikit-learn, which ships clustering and manifold learning but no Self-Organizing Map. If your goal is grouping rows, sklearn.cluster.KMeans or sklearn.cluster.AgglomerativeClustering gives you fit_predict, labels_ and an established evaluation path in one object. MiniSom gives you a grid and a winner function, and the topological neighborhood is the reason to prefer it: the map preserves neighborhood relations, so adjacent neurons represent similar inputs, which is what makes the Seeds and digits visualizations in the examples meaningful. K-means has no such adjacency. If your goal is dimensionality reduction for visualization, sklearn.manifold.TSNE and sklearn.manifold.SpectralEmbedding produce embeddings directly, whereas MiniSom produces a grid you then have to render yourself. The honest framing is that MiniSom occupies a narrower slot: it is the choice when the grid topology is the point, and scikit-learn is the choice when you want a fitted estimator with a stable interface and no extra code. The two are not interchangeable, and the README does not position MiniSom as a replacement for either.
Maintenance, releases and the MIT licence in practice
The repository is not archived, the default branch is master, and the release history shows 2.3.4 and 2.3.5 both dated 2025-02-26, with 2.3.6 on 2026-02-11. Two releases on the same day suggests a quick correction rather than a planned cadence, and the gap between 2.3.5 and 2.3.6 is roughly a year, so do not plan around frequent updates. The README notes that updates are posted on X, which is a thin channel for a library you depend on: there is no changelog excerpt in the supplied material, so pinning a version and reading the diff between tags is the safer habit. The licence is MIT, which is permissive and imposes no source-disclosure obligation on your own code, but this is not legal advice and the licence text itself is the authority. One practical consequence of the minimal dependency set is that upgrading MiniSom rarely drags in transitive packages; the exception is the [fast] extra, which pulls Numba and therefore ties your upgrade path to Numba's Python version support. If you install the extra, treat Numba compatibility as part of your upgrade testing, not just MiniSom's version number.
Who should adopt it, and what to check before you do
MiniSom fits a research or teaching context where the algorithm is the subject: someone extending the SOM, comparing decay schedules, or demonstrating topological mapping on a small matrix. The code is small enough to read, the dependency surface is numpy plus optional Numba, and the examples cover the visualizations you would otherwise write from scratch. It does not fit a production pipeline that needs a stable estimator interface, automatic label assignment, or reproducible runs without extra work, because none of those are documented. Before adopting, verify three things on your own data. First, whether the Numba extra pays for itself: run pip install minisom[fast] and time train against train_batch_offline_fast, since the README gives no figure and warns the first call is slower. Second, whether you can persist your model: if your decay configuration uses a lambda, the pickle pattern in the README will fail, so decide on a named function before training anything you intend to save. Third, whether unseeded initialization is acceptable, because no random_state parameter appears in the documented constructor and the examples do not show how to fix the map across runs.
Editorial conclusion
Adopt MiniSom if you need a Self-Organizing Map you can read in one sitting and extend, and if you are willing to write the visualization, clustering and outlier logic yourself. Do not adopt it as a full clustering or dimensionality-reduction framework: it has no fit_transform contract and no built-in plotting. Before committing, run pip install minisom[fast] and time train versus train_batch_offline_fast on your own matrix, because the README states the first JIT call is slower and gives no speedup figure.
Community notes