RusticSOM
Rust library for Self Organising Maps (SOM).
Using this Crate
Add rusticsom as a dependency in Cargo.toml
[dependencies]
rusticsom = "1.1.0"
Include the crate
use rusticsom::SOM;
API
Use SOM::create to create an SOM object using the API call below, which creates an SOM with length x breadth cells and accepts neurons of length inputs.
pub fn create(length: usize, breadth: usize, inputs: usize, randomize: bool, learning_rate: Option<f32>, sigma: Option<f32>, decay_function: Option<fn(f32, u32, u32) -> f64>, neighbourhood_function: Option<fn((usize, usize), (usize, usize), f32) -> Array2<f64>>) -> SOM { ... }
randomize is a flag, which, if true, initializes the weights of each cell to random, small, floating-point values.
learning_rate, optional, is the learning_rate of the SOM; by default it will be 0.5.
sigma, optional, is the spread of the neighbourhood function; by default it will be 1.0.
decay_function, optional, is a function pointer that accepts functions that take 3 parameters of types f32, u32, u32, and returns an f64. This function is used to "decay" both the learning_rate and sigma. By default it is
new_value = old_value / (1 + current_iteration/total_iterations)
neighbourhood_function, optional, is also a function pointer that accepts functions that take 3 parameters, a tuple of type (usize, usize) representing the size of the SOM, another tuple of type (usize, usize) representing the position of the winner neuron, and an f32 representing sigma; and returns a 2D Array containing weights of the neighbours of the winning neuron, i.e, centered at winner. By default, the Gaussian function will be used, which returns a "Gaussian centered at the winner neuron".
pub fn from_json(serialized: &str, decay_function: Option<fn(f32, u32, u32) -> f64>, neighbourhood_function: Option<fn((usize, usize), (usize, usize), f32) -> Array2<f64>>) -> serde_json::Result<SOM> { ... }
This function allows to create a SOM from a previously exported SOM json data using SOM::to_json().
Use SOM_Object.train_random() to train the SOM with the input dataset, where samples from the input dataset are picked in a random order.
pub fn train_random(&mut self, data: Array2<f64>, iterations: u32) { ... }
Samples (rows) from the 2D Array data are picked randomly and the SOM is trained for iterations iterations!
Use SOM_Object.train_batch() to train the SOM with the input dataset, where samples from the input dataset are picked in a sequential order.
pub fn train_batch(&mut self, data: Array2<f64>, iterations: u32) { ... }
Samples (rows) from the 2D Array data are picked sequentially and the SOM is trained for iterations iterations!
Use SOM_Object.winner() to find the winning neuron for a given sample.
pub fn winner(&mut self, elem: Array1<f64>) -> (usize, usize) { ... }
This function must be called with an SOM object.
Requires one parameter, a 1D Array of f64s representing the input sample.
Returns a tuple (usize, usize) representing the x and y coordinates of the winning neuron in the SOM.
Use SOM_Object.winner_dist() to find the winning neuron for a given sample, and it's distance from this winner neuron.
pub fn winner_dist(&mut self, elem: Array1<f64>) -> ((usize, usize), f64) { ... }
This function must be called with an SOM object.
Requires one parameter, a 1D Array of f64s representing the input sample.
Returns a tuple (usize, usize) representing the x and y coordinates of the winning neuron in the SOM.
Also returns an f64 representing the distance of the input sample from this winner neuron.
pub fn activation_response(&self) -> ArrayView2<usize> { ... }
This function returns the activation map of the SOM. The activation map is a 2D Array where each cell at (i, j) represents the number of times the (i, j) cell of the SOM was picked to be the winner neuron.
pub fn get_size(&self) -> (usize, usize)
This function returns a tuple representing the size of the SOM. Format is (length, breadth).
pub fn distance_map(self) -> Array2<f64> { ... }
Returns the distance map of the SOM, i.e, the normalized distance of every neuron with every other neuron.
pub fn to_json(&self) -> serde_json::Result<String> { ... }
Returns the internal SOM data as pretty printed json (using serde_json).
Primary Contributors
 |
Aditi Srinivas |
 |
Avinash Shenoy |
Example
We've tested this crate on the famous iris dataset (present in csv format in the extras folder).
The t_full_test function in /tests/test.rs was used to produce the required output. The following plots were obtained using matplotlib for Python.
Using a 5 x 5 SOM, trained for 250 iterations :
Using a 10 x 10 SOM, trained for 1000 iterations :
| Symbol | Represents |
|---|---|
| Circle | setosa |
| Square | versicolor |
| Diamond | virginica |
![[docs] Reformat docstrings to be auto-generated](https://avatars.githubusercontent.com/u/33420535?v=4)
1.5k Jan 8, 2023
139 Dec 30, 2022
0 Sep 2, 2021
1.2k Dec 31, 2022
351 Dec 29, 2022
95 Nov 30, 2022
223 Jan 1, 2023
41 Dec 25, 2022
12 Jul 17, 2022
411 Jan 9, 2023
63 Dec 23, 2022
24 Dec 20, 2022
163 Dec 25, 2022
20 Jun 14, 2022
25 Apr 29, 2022
2.3k Jan 3, 2023
4 Nov 29, 2021
2 Apr 28, 2021
8 Sep 22, 2022