Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/franckalbinet/teuvo
Self-Organising Map implemented as Literate Programming
https://github.com/franckalbinet/teuvo
data-visualization dimensionality-reduction neural-network
Last synced: about 24 hours ago
JSON representation
Self-Organising Map implemented as Literate Programming
- Host: GitHub
- URL: https://github.com/franckalbinet/teuvo
- Owner: franckalbinet
- License: apache-2.0
- Created: 2024-12-17T06:40:25.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-01-19T16:18:21.000Z (26 days ago)
- Last Synced: 2025-01-19T17:27:05.531Z (26 days ago)
- Topics: data-visualization, dimensionality-reduction, neural-network
- Language: Jupyter Notebook
- Homepage: https://fr.anckalbi.net/teuvo/
- Size: 2.84 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Teuvo
## Design Philosophy
Developed through the innovative **“SolveIt”** tool and methodology
currently featured at [Answer.ai](https://www.answer.ai), this Python
package embodies a transformative approach to problem-solving. Rather
than treating AI as a mysterious black box that simply produces answers,
it leverages **AI as an illuminating tool that deepens our understanding
of problems and guides us toward solutions**.
At its core, the package draws inspiration from George Pólya’s seminal
“How to Solve It” framework. What makes this implementation unique is
its radical commitment to transparency and literate programming - the
entire development process is meticulously documented in this [**“How
was it created?” notebook**](workflow/how-was-it-created.ipynb), serving
as both a comprehensive guide and a testament to the step-by-step
problem-solving methodology.
The package’s **source code emerges naturally from this foundational
notebook**, carefully refactoring the core functionality that was
thoughtfully developed through deliberate, incremental steps. This
approach ensures that every component is not only well-documented but
also deeply understood.
## Features
- Multiple initialization methods:
- Random initialization
- PCA-based initialization (for faster convergence)
- Flexible training options:
- Customizable learning rate schedules
- Adjustable neighborhood functions
- Quantization and Topographic Errors monitoring plots during
training:
- Comprehensive quality metrics:
- Quantization Error
- Topographic Error
- Rich visualization tools:
- U-Matrix visualization
- Hit histograms and Component planes (coming soon)
## Installation
``` bash
pip install teuvo
```
## Quick Start
``` python
from teuvo.core import SOM
import numpy as np
from sklearn.datasets import load_digits
# Load and normalize MNIST data
X, y = load_digits(return_X_y=True)
X_norm = (X - np.mean(X, axis=-1, keepdims=True))/X.max()
# Create and train SOM
som = SOM(grid_sz=(20,20), input_dim=64, init='pca')
som.fit(X_norm, n_epochs=20, verbose=True)
# Visualize results
som.plot_umatrix(figsize=(4,4))
```
Training Progress
| | | |
|:------|-------:|-------:|
| Epoch | QE | TE |
| 1 | 2.0001 | 2.0590 |
| 2 | 1.9462 | 4.7301 |
| 3 | 1.8539 | 0.6121 |
| 4 | 1.8458 | 1.5582 |
| 5 | 1.7964 | 1.8364 |
| 6 | 1.7228 | 0.7791 |
| 7 | 1.6385 | 0.4452 |
| 8 | 1.5939 | 0.3339 |
| 9 | 1.5624 | 0.3339 |
| 10 | 1.4959 | 0.5565 |
| 11 | 1.4390 | 0.6121 |
| 12 | 1.3935 | 0.6678 |
| 13 | 1.3539 | 0.6678 |
| 14 | 1.3116 | 0.8904 |
| 15 | 1.2758 | 1.0017 |
| 16 | 1.2444 | 0.7234 |
| 17 | 1.2162 | 0.7234 |
| 18 | 1.1915 | 0.7234 |
| 19 | 1.1701 | 0.8347 |
| 20 | 1.1523 | 0.6678 |
/* Turns off some styling */
progress {
/* gets rid of default border in Firefox and Opera. */
border: none;
/* Needs to be in here for Safari polyfill so background images work as expected. */
background-size: auto;
}
progress:not([value]), progress:not([value])::-webkit-progress-bar {
background: repeating-linear-gradient(45deg, #7e7e7e, #7e7e7e 10px, #5c5c5c 10px, #5c5c5c 20px);
}
.progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {
background: #F44336;
}
## Detailed Example: MNIST Digit Classification
``` python
from teuvo.core import SOM, Scheduler
import numpy as np
from sklearn.datasets import load_digits
import matplotlib.pyplot as plt
# Load and preprocess data
X, y = load_digits(return_X_y=True)
X_norm = (X - np.mean(X, axis=-1, keepdims=True))/X.max()
# Initialize SOM
som = SOM(
grid_sz=(20,20),
input_dim=64,
init='pca' # Use PCA initialization
)
# Create custom schedulers
lr_scheduler = Scheduler(start_val=1.0, end_val=0.01,
step_size=200, n_samples=len(X), n_epochs=20)
sigma_scheduler = Scheduler(start_val=10.0, end_val=1.0,
step_size=200, n_samples=len(X), n_epochs=20)
# Train
weights, qe_errors, te_errors = som.fit(
X_norm,
n_epochs=15,
lr_scheduler=lr_scheduler,
sigma_scheduler=sigma_scheduler
)
```
Training Progress
| | | |
|:------|-------:|-------:|
| Epoch | QE | TE |
| 1 | 1.9399 | 1.3912 |
| 2 | 2.0015 | 1.6694 |
| 3 | 1.9254 | 2.7824 |
| 4 | 1.7919 | 0.6121 |
| 5 | 1.7639 | 1.1686 |
| 6 | 1.7188 | 0.7791 |
| 7 | 1.6138 | 0.6121 |
| 8 | 1.5829 | 0.4452 |
| 9 | 1.5376 | 0.2782 |
| 10 | 1.4790 | 0.5008 |
| 11 | 1.4333 | 0.3339 |
| 12 | 1.3924 | 0.3895 |
| 13 | 1.3472 | 1.0017 |
| 14 | 1.3150 | 0.2782 |
| 15 | 1.2801 | 0.3895 |
/* Turns off some styling */
progress {
/* gets rid of default border in Firefox and Opera. */
border: none;
/* Needs to be in here for Safari polyfill so background images work as expected. */
background-size: auto;
}
progress:not([value]), progress:not([value])::-webkit-progress-bar {
background: repeating-linear-gradient(45deg, #7e7e7e, #7e7e7e 10px, #5c5c5c 10px, #5c5c5c 20px);
}
.progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {
background: #F44336;
}
``` python
som.plot_umatrix(figsize=(4,4))
```
## Contributing
We welcome contributions! Please see our contributing guidelines for
details.
## References
- Kohonen, T. (1982). Self-organized formation of topologically correct
feature maps
- Kohonen, T. (2013). Essentials of the self-organizing map
- Polya, G. (1945). How to Solve It
## License
Apache 2.0
## Acknowledgments
Named in honor of Teuvo Kohonen, who introduced the Self-Organizing Map
algorithm.