# minisom-onnx
[](https://pypi.org/project/minisom2onnx/)
[](https://pepy.tech/project/minisom2onnx)
[](https://github.com/Chiragasourabh/minisom-onnx/blob/main/LICENSE)
[](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')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/chiragasourabh/minisom-onnx",
"name": "minisom2onnx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "minisom, onnx, som, machine learning, self organising maps",
"author": "Chiragasourabh",
"author_email": "chiragasourabh@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/db/c3/7d9c14cd7d0e84e0404dcbbf1c126c08df768e1cdd0990d12e096c21d6a1/minisom2onnx-0.1.0.tar.gz",
"platform": null,
"description": "# minisom-onnx\n\n[](https://pypi.org/project/minisom2onnx/)\n[](https://pepy.tech/project/minisom2onnx)\n[](https://github.com/Chiragasourabh/minisom-onnx/blob/main/LICENSE)\n[](https://github.com/psf/black)\n\n`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.\n\n## Features\n\n- Convert MiniSom models to ONNX format\n- Support for different distance functions\n- Optional quantization error thresholding (outlier detection)\n- Optional label mapping (classification)\n\n## Installation\n\nYou can install the library using `pip`:\n\n```bash\npip install minisom2onnx\n```\n\n## API\n\nThe `to_onnx` function converts a trained MiniSom model to an ONNX format.\n\n### Function Signature\n\n```python\nto_onnx(\n model, \n name: Optional[str] = None,\n description: Optional[str] = None,\n threshold: Optional[float] = None,\n labels: Optional[np.ndarray] = None,\n outputs: Optional[List[str]] = ['winner'],\n properties: Optional[Dict[str, str]] = {},\n opset: Optional[int] = 18,\n) -> ModelProto\n```\n\n### Parameters\n\n- **model**: The trained MiniSom model to be converted.\n- **name**: *(Optional)* A string specifying the name of the ONNX model. If not provided, a random uuid will be used.\n- **description**: *(Optional)* A textual description of the ONNX model's graph. \n- **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.\n- **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.\n- **outputs**: *(Optional)* A list of strings specifying the desired output names to include in the final model. The default value is ['winner'].\n- **properties**: *(Optional)* A dictionary of additional properties to include in the model's metadata.\n- **opset**: *(Optional)* An integer specifying the ONNX opset version to use. The default value is 18.\n\n### Outputs\nBy default, the following outputs are available:\n\n- `weights`: The original weights of the MiniSom model.\n- `distance`: The distance between each input sample and the weights vector of the winning neuron.\n- `quantization`: The code book BMU (weights vector of the winning neuron) for each sample in the data.\n- `quantization_error`: The quantization error, calculated as the distance between each input sample and its best matching unit.\n- `winner`: The coordinates of the BMU on the SOM grid.\n\nAdditional outputs are available based on the optional parameters:\n\n- `outlier`: A binary indicator of whether the quantization error exceeds the provided threshold. This output is only available if the threshold parameter is specified.\n- `class`: The label of the BMU. This output is only available if the labels parameter is provided.\n\n> **_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.\\\n\\\nAdditionally, 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*\\\n\\\nFor reliable inference, it is recommended to use the `euclidean` distance function with your MiniSom model when exporting to ONNX.\n\n\n\n## Usage\n\nHere\u2019s a basic example of how to use `minisom2onnx` to convert a trained MiniSom model to ONNX format:\n\n\n```python\nfrom minisom import MiniSom\nimport numpy as np\nimport random\nfrom minisom2onnx import to_onnx\n\ndata = np.random.rand(100, 4)\n\n# Create and train a MiniSom model\nsom = MiniSom(10, 10, data.shape[1], sigma=0.3, learning_rate=0.5)\nsom.random_weights_init(data)\nsom.train_random(data, 100)\n\n# Convert the model to ONNX\nonnx_model = to_onnx(som, name=\"SOMModel\")\n\n# Save the model\nimport onnx\nonnx.save(onnx_model, 'som_model.onnx')\n\n````\n\n### Using Labels\n\nTo include label information in your ONNX model, you can provide `labels` during conversion. Here\u2019s an example:\n\n```python\nfrom minisom import MiniSom\nimport numpy as np\nimport random\nfrom minisom2onnx import to_onnx\n\ndim = 10\ndata = np.random.rand(100, 4)\ntarget = [random.randint(1, 2) for i in range(100)]\n\n# Create and train a MiniSom model\nsom = MiniSom(dim, dim, data.shape[1], sigma=3, learning_rate=0.5, neighborhood_function='triangle', random_seed=10)\nsom.pca_weights_init(data)\nsom.train(data, 1000, random_order=True, use_epochs=True)\n\ndefault_label = 0\nlabels = np.full((dim, dim), fill_value=default_label, dtype=int)\nfor position, counter in som.labels_map(data, target).items():\n labels[position] = max(counter, key=counter.get)\n\n# Convert the model to ONNX\nonnx_model = to_onnx(som, name=\"SOMClassifier\", labels=labels, outputs=[\"class\"])\n\n# Save the model\nimport onnx\nonnx.save(onnx_model, 'som_model.onnx')\n```\n\n### Using Thresholding\n\nIf you want to include threshold-based outlier detection in your ONNX model, you can specify a `threshold`. Here\u2019s how:\n\n```python\nfrom minisom import MiniSom\nimport numpy as np\nimport random\nfrom minisom2onnx import to_onnx\n\ndim = 10\ndata = np.random.rand(100, 4)\n\n# Create and train a MiniSom model\nsom = MiniSom(dim, dim, data.shape[1], sigma=3, learning_rate=0.5, neighborhood_function='triangle', random_seed=10)\nsom.train(data, 1000, random_order=True, use_epochs=True)\n\nquantization_errors = np.array([som.quantization_error([x]) for x in data])\nthreshold = np.percentile(quantization_errors, 95)\n\n# Convert the model to ONNX\nonnx_model = to_onnx(som, name=\"SOMOutlier\", threshold=threshold, outputs=[\"outlier\"])\n\n# Save the model\nimport onnx\nonnx.save(onnx_model, 'som_model.onnx')\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library to convert MiniSom models to ONNX format",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/chiragasourabh/minisom-onnx"
},
"split_keywords": [
"minisom",
" onnx",
" som",
" machine learning",
" self organising maps"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd3b10bcff6dc58cc7baff7928618cfd44dd3d3fc7fbabd80d394e15ea0483c3",
"md5": "d2a8da2375ec025a6527fa0d087fe42c",
"sha256": "bc1dbb2cfe1f05dee1bc9b65b7a539e4141a11e52f89fd089c79436ad4fd8d07"
},
"downloads": -1,
"filename": "minisom2onnx-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2a8da2375ec025a6527fa0d087fe42c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8371,
"upload_time": "2024-08-10T08:30:07",
"upload_time_iso_8601": "2024-08-10T08:30:07.738070Z",
"url": "https://files.pythonhosted.org/packages/dd/3b/10bcff6dc58cc7baff7928618cfd44dd3d3fc7fbabd80d394e15ea0483c3/minisom2onnx-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dbc37d9c14cd7d0e84e0404dcbbf1c126c08df768e1cdd0990d12e096c21d6a1",
"md5": "d8e0cd2e7fcc21e1bc4035a19924dbe5",
"sha256": "82fb0ddad2d83050b7b9f72f4a73a54140f60e716e595156f11db40f8dab83f2"
},
"downloads": -1,
"filename": "minisom2onnx-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d8e0cd2e7fcc21e1bc4035a19924dbe5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7892,
"upload_time": "2024-08-10T08:30:09",
"upload_time_iso_8601": "2024-08-10T08:30:09.224796Z",
"url": "https://files.pythonhosted.org/packages/db/c3/7d9c14cd7d0e84e0404dcbbf1c126c08df768e1cdd0990d12e096c21d6a1/minisom2onnx-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-10 08:30:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chiragasourabh",
"github_project": "minisom-onnx",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "minisom2onnx"
}
JSON
