python-som 0.2.0__tar.gz → 0.3.0__tar.gz

{python_som-0.2.0 → python_som-0.3.0}/.gitignore

@@ -129,4 +129,10 @@ dmypy.json
 .pyre/
 
 # .dump directory
-/.dump
+/.dump
+
+# Claude Code working files. CLAUDE.md holds this maintainer's agent conventions rather than
+# repository policy, so it stays local instead of being imposed on contributors.
+/CLAUDE.md
+/CLAUDE.local.md
+/.claude/

python_som-0.3.0/CHANGELOG.md

@@ -0,0 +1,179 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-07-29
+
+Modernizes the packaging and corrects four methodology defects. **Numerical results differ from
+0.2.0.** The changes are listed with the passage of Kohonen (2013) each one follows.
+
+### Changed, and results differ
+
+- **Seeds no longer reproduce 0.1.x/0.2.0 results.** The random generator is now a per-instance
+  `np.random.Generator`. Previously the constructor called `np.random.seed`, which reseeded NumPy's
+  *global* generator as a side effect of building a SOM, disturbing the whole host program. The
+  side effect is gone, but `random_seed=42` now yields a different map.
+
+  To reproduce figures made with an earlier version, pin `python-som==0.2.0`.
+
+- Batch training no longer destroys models whose neighborhood contains no data. `_train_batch`
+  built its result from a zeroed array and assigned it wholesale, so every model it did not touch
+  became the zero vector. On a 30x30 map with 20 samples and a small radius, that wiped 282 of 900
+  models in a single step, and drove the quantization error from 0.0 to 0.196. Untouched models now
+  keep their previous value, and the denominator is compared against a tolerance rather than exact
+  zero. (Kohonen Eq. 8.)
+
+- Linear initialization now spans the principal-component plane. It used
+  `pca.explained_variance_`, the two eigen*values*, where it needed `pca.components_`, the
+  eigen*vectors*. Every model came out as a scalar broadcast across all features: a constant vector
+  on the all-ones diagonal, rank 1 rather than a plane. PCA is also now fitted on the raw data
+  instead of standardized data, so the models live in the same space as the inputs they are compared
+  against during training. (Kohonen Section 4.3.)
+
+- `random` training now samples i.i.d. with replacement. It previously drew with
+  `replace=(n_iteration > len(data))`, so it was a random permutation whenever the iteration count
+  did not exceed the sample count, and independent draws only beyond it. The character of the
+  sampling therefore depended on how many iterations you asked for. It is now uniformly i.i.d.,
+  which is the stochastic approximation of Robbins and Monro (1951) that Kohonen cites in
+  Section 4.1.
+
+- `sequential` training honours `n_iteration`. It iterated the dataset exactly once regardless
+  of the requested count, so asking for 500 iterations over 30 samples ran 30 steps while the decay
+  functions still used 500 as their horizon, leaving the learning rate almost unchanged. It now
+  cycles the dataset until the requested number of steps has run.
+
+- The automatic map-size ratio uses `sqrt(lambda_1 / lambda_2)` rather than the raw eigenvalue
+  ratio, rounds instead of floor-dividing, and clamps to at least 1 so a side can no longer come out
+  as zero. Kohonen Section 3.5 asks for side lengths matching "the lengths of the two largest
+  principal components"; a component is a unit direction, so its length in the data is the standard
+  deviation. For Iris with `x=20`, `y` moves from 6 to 11.
+
+- The neighborhood radius is floored at the new `min_neighborhood_radius` parameter, default
+  0.5. Kohonen Section 4.2: "the final value of sigma shall not go to zero, because otherwise the
+  process loses its ordering power. It should always remain, say, above half of the grid spacing."
+  This also stops `linear_decay` from reaching a division by zero at its horizon.
+
+- `get_shape()` returns `tuple[int, int]` rather than NumPy integers, so
+  `plt.figure(figsize=som.get_shape())` works without the `float()` workaround the old example
+  needed.
+
+### Added
+
+- `mexican_hat` is accepted as an alias for `mexicanhat`.
+- A test suite, where there was none: 190 tests at 100% coverage, including one regression test
+  per defect above carrying its measured numbers, and property-based tests via Hypothesis over
+  generated grid sizes, radii and centres.
+- Type annotations are now exported, via a `py.typed` marker. The library was already annotated,
+  but without the marker PEP 561 requires downstream type checkers to ignore it.
+- Documentation site at <https://andremsouza.github.io/python-som/>, built with Material for
+  MkDocs, including the derivations behind the neighborhood functions.
+- Continuous integration across Python 3.10 to 3.13, with ruff, mypy `--strict`, coverage
+  gating, and a build that installs the wheel into a clean environment and imports it.
+- Releases publish through PyPI Trusted Publishing, so no long-lived API token exists.
+
+### Performance
+
+- Batch training is about 30x faster. The nested Python loop over every pair of nodes is
+  replaced by a NumPy contraction. Measured on a 20x20 map with 150 samples over 5 iterations: 1.89 s
+  to 0.06 s. A regression test asserts the new result matches the old formulation to 1e-12.
+
+### Internal
+
+- The package moves to a `src/` layout and splits into `_som`, `_neighborhood`, `_decay` and
+  `_distance`. `import python_som; python_som.SOM(...)` is unchanged, and the pre-0.3.0 private names
+  (`_asymptotic_decay`, `_euclidean_distance`, and the rest) still resolve.
+- `test_iris.ipynb` is removed; its narrative moved into the documentation. `SOM_atualizado.py`, an
+  untracked experimental variant that the sdist had been sweeping up, is gone.
+- `print` calls become `logging`; `verbose=True` still drives the tqdm progress bar.
+
+### Fixed
+
+- The `bubble` neighborhood is documented as using the Chebyshev metric, so its region is a
+  square rather than a disc. The behavior is unchanged and follows Vrieze's appendix pseudo-code
+  (`b = MAX(ABS(i - w_i), ABS(j - w_j))`), but it was previously unstated, and it means the bubble is
+  *not* isotropic under the Euclidean metric. The test suite shipped in 0.2.0 asserted that it was;
+  that assertion passed only because no counterexample exists on a grid that small. The smallest is
+  at radius `sqrt(50)`, where `(5, 5)` is inside a `sigma = 5` square and `(7, 1)` is outside.
+
+## [0.2.0] - 2026-07-28
+
+### Added
+
+- Mexican hat neighborhood function, selectable with `neighborhood_function='mexicanhat'`
+  (contributed by [@Arne49](https://github.com/Arne49) in
+  [#2](https://github.com/andremsouza/python-som/pull/2)).
+
+  Implemented as the isotropic 2-D form `(1 - u) * exp(-u)` over `u = sqdist(c, i) / (2 * sigma^2)`,
+  normalized so that `h(c, c) = 1`. It crosses zero at a radius of `sqrt(2) * sigma` and reaches its
+  minimum of `-exp(-2)` at a radius of `2 * sigma`.
+
+  Note that a neighborhood function must depend on the grid distance alone, not on the two axis
+  offsets separately, per `sqdist(c, i)` in Kohonen (2013) Eq. (5) and the "lateral distance"
+  abscissa of Vrieze (1995) Fig. 3. The gaussian happens to be separable into a product of per-axis
+  terms, but that is a property of the exponential rather than of neighborhood functions in general.
+
+- `## Neighborhood functions` section in the README, comparing all three and documenting the
+  batch-mode restriction below.
+- Test suite for the neighborhood functions, asserting closed-form analytic properties rather than
+  golden values.
+
+### Fixed
+
+- Cyclic (toroidal) neighborhoods were only correct in one direction. The fold-back handled
+  offsets above `+length/2` but left those below `-length/2` alone, so a winner in the upper half of
+  an axis did not wrap. On a 10x10 toroidal map with sigma=1, a winner at row 0 gave `h[9] = 0.6065`
+  while a winner at row 9 gave `h[0] = 0.0` instead of the same 0.6065. Now uses the minimum-image
+  convention, which folds both tails.
+
+  This changes results for any map built with `cyclic_x=True` or `cyclic_y=True`.
+
+- A neighborhood radius of zero divided by zero and produced `inf`/`nan` weights instead of raising.
+  `_gaussian` and `_mexicanhat` now reject a non-finite or non-positive radius; `_bubble` still
+  accepts a radius of zero, which selects the winner alone.
+
+- An unknown `neighborhood_function` raised a bare `KeyError`. It now raises `ValueError` listing the
+  valid names, matching the behavior of `weight_initialization`.
+
+### Changed
+
+- `requires-python` is now `>=3.10`. The declared floor of `>=3.9` was never accurate: the module
+  uses PEP 604 unions (`int | None`) in runtime-evaluated annotations without
+  `from __future__ import annotations`, so importing it on Python 3.9 raises `TypeError`. Python 3.9
+  reached end of life in October 2025. Installers will now decline the package on 3.9 rather than
+  install something that cannot be imported.
+
+- `train(mode='batch')` combined with `neighborhood_function='mexicanhat'` now raises `ValueError`.
+  The batch update of Kohonen (2013) Eq. (8) is a weighted mean whose denominator `sum_j n_j * h_ji`
+  is only well defined for a non-negative neighborhood function. The mexican hat is signed by
+  construction, so the denominator can vanish or turn negative: on a 12x12 grid, 49 of 144
+  denominators come out negative, which inverts or explodes the update. This is a property of the
+  function itself rather than of this implementation. Use `mode='random'` or `mode='sequential'`.
+
+### Packaging
+
+- Restored the `cli` extra (`pip install python-som[cli]`, which pulls in `tqdm` for training
+  progress bars). This extra shipped in 0.1.3 on PyPI but was never committed to the repository, so
+  releasing from the repository as-is would have silently removed it.
+
+### Note on 0.1.3
+
+There is no changelog entry for 0.1.3 because it was published to PyPI from an uncommitted working
+tree and has no corresponding commit. Its `python_som/__init__.py` is byte-identical to the 0.1.2
+tag; the only differences are the version string and the `cli` extra restored above.
+
+## [0.1.3] - 2025-01-14
+
+Published to PyPI only. See the note above.
+
+## [0.1.2] - 2025-01-14
+
+Earlier releases predate this changelog. See the
+[commit history](https://github.com/andremsouza/python-som/commits/master) for details.
+
+[0.3.0]: https://github.com/andremsouza/python-som/releases/tag/v0.3.0
+[0.2.0]: https://github.com/andremsouza/python-som/releases/tag/v0.2.0
+[0.1.3]: https://pypi.org/project/python-som/0.1.3/
+[0.1.2]: https://pypi.org/project/python-som/0.1.2/

python_som-0.3.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: python-som
+Version: 0.3.0
+Summary: Python implementation of the Self-Organizing Map
+Project-URL: Homepage, https://github.com/andremsouza/python-som
+Project-URL: Documentation, https://andremsouza.github.io/python-som/
+Project-URL: Changelog, https://github.com/andremsouza/python-som/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/andremsouza/python-som/issues
+Author-email: André Moreira Souza <msouza.andre@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Provides-Extra: cli
+Requires-Dist: tqdm>=4.66; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: hypothesis==6.163.0; extra == 'dev'
+Requires-Dist: mypy==2.3.0; extra == 'dev'
+Requires-Dist: pandas-stubs==3.0.3.260530; (python_version >= '3.11') and extra == 'dev'
+Requires-Dist: pre-commit==4.6.1; extra == 'dev'
+Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Requires-Dist: ruff==0.16.0; extra == 'dev'
+Requires-Dist: tomli==2.4.1; (python_version < '3.11') and extra == 'dev'
+Requires-Dist: twine==7.0.0; extra == 'dev'
+Requires-Dist: types-tqdm==4.69.0.20260728; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material==9.7.7; extra == 'docs'
+Requires-Dist: mkdocstrings-python==2.0.5; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.8; extra == 'examples'
+Requires-Dist: seaborn>=0.13; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# python-som
+
+[![CI](https://github.com/andremsouza/python-som/actions/workflows/ci.yml/badge.svg)](https://github.com/andremsouza/python-som/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/python-som.svg)](https://pypi.org/project/python-som/)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-som.svg)](https://pypi.org/project/python-som/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/andremsouza/python-som/blob/master/LICENSE)
+
+Implementation of Kohonen's 2-D self-organizing map, built on NumPy, with scikit-learn for PCA and
+standardization. Accepts NumPy arrays, pandas DataFrames and plain lists.
+
+[Documentation](https://andremsouza.github.io/python-som/) ·
+[Changelog](https://github.com/andremsouza/python-som/blob/master/CHANGELOG.md)
+
+## Install
+
+```bash
+pip install python-som              # requires Python 3.10+
+pip install "python-som[cli]"       # adds tqdm progress bars
+```
+
+## Quick start
+
+```python
+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])
+```
+
+A full worked example with plots is in [examples/iris.py](https://github.com/andremsouza/python-som/blob/master/examples/iris.py) and in the
+[getting-started guide](https://andremsouza.github.io/python-som/getting-started/).
+
+![U-matrix of a SOM trained on Iris](https://raw.githubusercontent.com/andremsouza/python-som/master/docs/assets/iris.png)
+
+## Features
+
+* 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
+* 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](https://andremsouza.github.io/python-som/neighborhood-functions/) for
+the derivations, including why the Mexican hat is not an outer product of two 1-D wavelets.
+
+## Upgrading
+
+0.3.0 corrects several methodology defects, so numerical 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 figures
+made with an older version, pin `python-som==0.2.0`.
+
+Each change and the passage of Kohonen (2013) behind it is in the
+[changelog](https://github.com/andremsouza/python-som/blob/master/CHANGELOG.md).
+
+## Development
+
+```bash
+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 mkdocs serve          # docs, locally
+pre-commit install           # optional, run the gates on commit
+```
+
+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.
+
+## 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](https://github.com/andremsouza/python-som/blob/master/LICENSE).

python_som-0.3.0/README.md

@@ -0,0 +1,125 @@
+# python-som
+
+[![CI](https://github.com/andremsouza/python-som/actions/workflows/ci.yml/badge.svg)](https://github.com/andremsouza/python-som/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/python-som.svg)](https://pypi.org/project/python-som/)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-som.svg)](https://pypi.org/project/python-som/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/andremsouza/python-som/blob/master/LICENSE)
+
+Implementation of Kohonen's 2-D self-organizing map, built on NumPy, with scikit-learn for PCA and
+standardization. Accepts NumPy arrays, pandas DataFrames and plain lists.
+
+[Documentation](https://andremsouza.github.io/python-som/) ·
+[Changelog](https://github.com/andremsouza/python-som/blob/master/CHANGELOG.md)
+
+## Install
+
+```bash
+pip install python-som              # requires Python 3.10+
+pip install "python-som[cli]"       # adds tqdm progress bars
+```
+
+## Quick start
+
+```python
+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])
+```
+
+A full worked example with plots is in [examples/iris.py](https://github.com/andremsouza/python-som/blob/master/examples/iris.py) and in the
+[getting-started guide](https://andremsouza.github.io/python-som/getting-started/).
+
+![U-matrix of a SOM trained on Iris](https://raw.githubusercontent.com/andremsouza/python-som/master/docs/assets/iris.png)
+
+## Features
+
+* 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
+* 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](https://andremsouza.github.io/python-som/neighborhood-functions/) for
+the derivations, including why the Mexican hat is not an outer product of two 1-D wavelets.
+
+## Upgrading
+
+0.3.0 corrects several methodology defects, so numerical 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 figures
+made with an older version, pin `python-som==0.2.0`.
+
+Each change and the passage of Kohonen (2013) behind it is in the
+[changelog](https://github.com/andremsouza/python-som/blob/master/CHANGELOG.md).
+
+## Development
+
+```bash
+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 mkdocs serve          # docs, locally
+pre-commit install           # optional, run the gates on commit
+```
+
+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.
+
+## 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](https://github.com/andremsouza/python-som/blob/master/LICENSE).

python_som-0.3.0/docs/api.md

@@ -0,0 +1,26 @@
+# API reference
+
+::: python_som
+    options:
+      members:
+        - SOM
+
+## Neighborhood functions
+
+::: python_som._neighborhood
+    options:
+      members:
+        - gaussian
+        - bubble
+        - mexican_hat
+        - axis_offsets
+        - squared_grid_distance
+        - resolve
+
+## Decay functions
+
+::: python_som._decay
+
+## Distance functions
+
+::: python_som._distance

python_som-0.3.0/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

python_som-0.3.0/docs/getting-started.md

@@ -0,0 +1,138 @@
+# Getting started
+
+## Install
+
+```bash
+pip install python-som
+
+# with tqdm progress bars during training
+pip install "python-som[cli]"
+```
+
+Requires Python 3.10 or later.
+
+## A complete example
+
+This walks through the Iris dataset end to end. The runnable version is
+[`examples/iris.py`](https://github.com/andremsouza/python-som/blob/master/examples/iris.py).
+
+### Load the data
+
+```python
+import numpy as np
+import seaborn as sns
+
+iris = sns.load_dataset("iris")
+target = iris.iloc[:, -1].to_numpy()
+features = iris.iloc[:, :-1].to_numpy()
+```
+
+### Build the map
+
+```python
+import python_som
+
+som = python_som.SOM(
+    x=20,
+    y=None,  # chosen from the data by PCA
+    input_len=features.shape[1],
+    learning_rate=0.5,
+    neighborhood_radius=1.0,
+    neighborhood_function="gaussian",
+    cyclic_x=True,
+    cyclic_y=True,
+    data=features,  # required when a dimension is None
+    random_seed=42,
+)
+print(som.get_shape())
+```
+
+Leaving one dimension as `None` asks the library to pick it. Kohonen Section 3.5 advises matching
+the side lengths to *"the lengths of the two largest principal components"*; since a component is a
+unit direction, its length in the data is the standard deviation, so the ratio is
+$\sqrt{\lambda_1/\lambda_2}$.
+
+### Initialize the models
+
+```python
+som.weight_initialization(mode="linear", data=features)
+```
+
+Linear initialization is the one to prefer. Kohonen Section 4.3: *"much faster and convergence
+follow if the initial values are selected as a regular, two-dimensional sequence of vectors taken
+along a hyperplane spanned by the two largest principal components"*. It is also the only
+deterministic initializer.
+
+The alternatives are `mode="random"` (draws from a distribution) and `mode="sample"` (copies random
+rows of your data).
+
+### Train
+
+```python
+error = som.train(features, n_iteration=len(features), mode="batch", verbose=True)
+print(f"quantization error: {error:.4f}")
+```
+
+See [Training modes](training-modes.md) for how the three modes differ and why batch is
+recommended.
+
+### Inspect the result
+
+```python
+umatrix = som.distance_matrix().T  # the U-matrix
+activations = som.activation_matrix(features)  # samples per node
+labels = som.label_map(features, target)  # label frequencies per node
+```
+
+### Plot it
+
+```python
+import matplotlib.pyplot as plt
+
+plt.figure(figsize=som.get_shape())
+plt.pcolor(umatrix, cmap="bone_r")
+
+markers, colors = ["o", "s", "D"], ["C0", "C1", "C2"]
+codes = {name: i for i, name in enumerate(np.unique(target))}
+for sample, label in zip(features, target):
+    w = som.winner(sample)
+    plt.plot(
+        w[0] + 0.5,
+        w[1] + 0.5,
+        markers[codes[label]],
+        markerfacecolor="None",
+        markeredgecolor=colors[codes[label]],
+        markersize=12,
+        markeredgewidth=2,
+    )
+plt.axis((0, som.get_shape()[0], 0, som.get_shape()[1]))
+plt.savefig("iris.png")
+```
+
+![U-matrix of a SOM trained on Iris](assets/iris.png)
+
+Darker regions of the U-matrix mean neighbouring models are far apart, so they read as boundaries
+between clusters.
+
+## Progress output
+
+`verbose=True` shows a tqdm progress bar when `python-som[cli]` is installed. It also logs on the
+`python_som` logger at INFO level, which is off by default the way any library logger is; enable it
+with:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+```
+
+## Reproducibility
+
+```python
+som = python_som.SOM(x=10, y=10, input_len=4, random_seed=42)
+print(som.get_random_seed())
+```
+
+Same seed, same map. The generator belongs to the instance, so building a SOM will not disturb
+NumPy's global random state. Note that seeds do not reproduce across the 0.3.0 boundary; see the
+warning in [Training modes](training-modes.md#reproducibility).

python_som-0.3.0/docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"