minisom2onnx 0.1.0
A library to convert MiniSom models to ONNX format
License: MIT
Requires Python: >=3.8
Keywords: minisom, onnx, som, machine learning, self organising maps

# minisom-onnx

[![PyPI version fury.io](https://badge.fury.io/py/minisom2onnx.svg)](https://pypi.org/project/minisom2onnx/)
[![Downloads](https://static.pepy.tech/badge/minisom2onnx)](https://pepy.tech/project/minisom2onnx)
[![License - MIT](https://img.shields.io/pypi/l/minisom2onnx.svg)](https://github.com/Chiragasourabh/minisom-onnx/blob/main/LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

`minisom2onnx`  is a Python library for converting MiniSom models to ONNX (Open Neural Network Exchange) format, allowing for deployment in various environments. It provides flexibility to include additional information, such as quantization error thresholds and label mappings.

## Features

- Convert MiniSom models to ONNX format
- Support for different distance functions
- Optional quantization error thresholding (outlier detection)
- Optional label mapping (classification)

## Installation

You can install the library using `pip`:

```bash
pip install minisom2onnx
```

## API

The `to_onnx` function converts a trained MiniSom model to an ONNX format.

### Function Signature

```python
to_onnx(
    model, 
    name: Optional[str] = None,
    description: Optional[str] = None,
    threshold: Optional[float] = None,
    labels: Optional[np.ndarray] = None,
    outputs: Optional[List[str]] = ['winner'],
    properties: Optional[Dict[str, str]] = {},
    opset: Optional[int] = 18,
) -> ModelProto
```

### Parameters

- **model**: The trained MiniSom model to be converted.
- **name**: *(Optional)* A string specifying the name of the ONNX model. If not provided, a random uuid will be used.
- **description**: *(Optional)* A textual description of the ONNX model's graph.   
- **threshold**: *(Optional)* A float value representing the threshold for quantization error. If provided, an additional node indicating whether the quantization error exceeds this threshold will be included in the ONNX model.
- **labels**: *(Optional)* A 2D numpy array containing labels corresponding to the SOM grid. If provided, an additional node mapping the best matching unit (BMU) to a label will be included.
- **outputs**: *(Optional)* A list of strings specifying the desired output names to include in the final model. The default value is ['winner'].
- **properties**: *(Optional)* A dictionary of additional properties to include in the model's metadata.
- **opset**: *(Optional)* An integer specifying the ONNX opset version to use. The default value is 18.

### Outputs
By default, the following outputs are available:

- `weights`: The original weights of the MiniSom model.
- `distance`: The distance between each input sample and the weights vector of the winning neuron.
- `quantization`: The code book BMU (weights vector of the winning neuron) for each sample in the data.
- `quantization_error`: The quantization error, calculated as the distance between each input sample and its best matching unit.
- `winner`: The coordinates of the BMU on the SOM grid.

Additional outputs are available based on the optional parameters:

- `outlier`: A binary indicator of whether the quantization error exceeds the provided threshold. This output is only available if the threshold parameter is specified.
- `class`: The label of the BMU. This output is only available if the labels parameter is provided.

> **_NOTE:_** The MiniSom model supports several distance functions, including `euclidean`, `cosine`, `manhattan`, and `chebyshev`. However, the ONNX operator `CDist` currently has an implementation only for `euclidean` distance. As a result, while the model can be exported to ONNX successfully, onnxruntime will fail if a distance function other than `euclidean` (default) is used.\
\
Additionally, MiniSom allows for custom distance functions. If a custom distance function is employed in the model, the `to_onnx` with throw an *ValueError: Unsupported activation_distance*\
\
For reliable inference, it is recommended to use the `euclidean` distance function with your MiniSom model when exporting to ONNX.



## Usage

Here’s a basic example of how to use `minisom2onnx` to convert a trained MiniSom model to ONNX format:


```python
from minisom import MiniSom
import numpy as np
import random
from minisom2onnx import to_onnx

data = np.random.rand(100, 4)

# Create and train a MiniSom model
som = MiniSom(10, 10, data.shape[1], sigma=0.3, learning_rate=0.5)
som.random_weights_init(data)
som.train_random(data, 100)

# Convert the model to ONNX
onnx_model = to_onnx(som, name="SOMModel")

# Save the model
import onnx
onnx.save(onnx_model, 'som_model.onnx')

````

### Using Labels

To include label information in your ONNX model, you can provide `labels` during conversion. Here’s an example:

```python
from minisom import MiniSom
import numpy as np
import random
from minisom2onnx import to_onnx

dim = 10
data = np.random.rand(100, 4)
target = [random.randint(1, 2) for i in range(100)]

# Create and train a MiniSom model
som = MiniSom(dim, dim, data.shape[1], sigma=3, learning_rate=0.5, neighborhood_function='triangle', random_seed=10)
som.pca_weights_init(data)
som.train(data, 1000, random_order=True, use_epochs=True)

default_label = 0
labels = np.full((dim, dim), fill_value=default_label, dtype=int)
for position, counter in som.labels_map(data, target).items():
    labels[position] = max(counter, key=counter.get)

# Convert the model to ONNX
onnx_model = to_onnx(som, name="SOMClassifier", labels=labels, outputs=["class"])

# Save the model
import onnx
onnx.save(onnx_model, 'som_model.onnx')
```

### Using Thresholding

If you want to include threshold-based outlier detection in your ONNX model, you can specify a `threshold`. Here’s how:

```python
from minisom import MiniSom
import numpy as np
import random
from minisom2onnx import to_onnx

dim = 10
data = np.random.rand(100, 4)

# Create and train a MiniSom model
som = MiniSom(dim, dim, data.shape[1], sigma=3, learning_rate=0.5, neighborhood_function='triangle', random_seed=10)
som.train(data, 1000, random_order=True, use_epochs=True)

quantization_errors = np.array([som.quantization_error([x]) for x in data])
threshold = np.percentile(quantization_errors, 95)

# Convert the model to ONNX
onnx_model = to_onnx(som, name="SOMOutlier", threshold=threshold, outputs=["outlier"])

# Save the model
import onnx
onnx.save(onnx_model, 'som_model.onnx')
```