{"id":13444561,"url":"https://github.com/milosgajdos/gosom","last_synced_at":"2025-04-23T20:14:10.392Z","repository":{"id":39660456,"uuid":"66353069","full_name":"milosgajdos/gosom","owner":"milosgajdos","description":"Self-organizing maps in Go","archived":false,"fork":false,"pushed_at":"2022-05-28T17:55:31.000Z","size":1785,"stargazers_count":74,"open_issues_count":0,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-23T20:13:55.885Z","etag":null,"topics":["data-clustering","go","golang","neural-networks","som-clustering","som-training-algorithms","unsupervised-learning-algorithms"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/milosgajdos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-23T09:28:05.000Z","updated_at":"2024-08-11T16:40:22.000Z","dependencies_parsed_at":"2022-09-06T17:11:27.826Z","dependency_job_id":null,"html_url":"https://github.com/milosgajdos/gosom","commit_stats":null,"previous_names":["milosgajdos83/gosom"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milosgajdos%2Fgosom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milosgajdos%2Fgosom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milosgajdos%2Fgosom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milosgajdos%2Fgosom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/milosgajdos","download_url":"https://codeload.github.com/milosgajdos/gosom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250506141,"owners_count":21441723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-clustering","go","golang","neural-networks","som-clustering","som-training-algorithms","unsupervised-learning-algorithms"],"created_at":"2024-07-31T04:00:30.320Z","updated_at":"2025-04-23T20:14:10.342Z","avatar_url":"https://github.com/milosgajdos.png","language":"Go","funding_links":[],"categories":["Neural Networks"],"sub_categories":["Vector Database"],"readme":"# gosom: Self-organizing maps in Go\n\n[![Build Status](https://github.com/milosgajdos/gosom/workflows/CI/badge.svg)](https://github.com/milosgajdos/gosom/actions?query=workflow%3ACI)\n[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white\u0026style=flat-square)](https://pkg.go.dev/github.com/milosgajdos/gosom)\n[![GoDoc](https://godoc.org/github.com/milosgajdos/gosom?status.svg)](https://godoc.org/github.com/milosgajdos/gosom)\n[![Go Report Card](https://goreportcard.com/badge/milosgajdos/gosom)](https://goreportcard.com/report/github.com/milosgajdos/gosom)\n[![License](https://img.shields.io/:license-apache-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nThis project provides an implementation of [Self-Organizing Map](https://en.wikipedia.org/wiki/Self-organizing_map) (SOM) in Go. It implements the two most well known SOM training algorithms: `sequential` and `batch`. The `batch` training is faster than the `sequential` as it can be parallelized, taking advantage of as many cores as your machine provides. However it can be less accurate as it merely provides a resonable approximation of SOM, but still acceptable. The `sequential` algorithm is performed as its name implies, sequentially. Because of its sequential nature it's slower than `batch` training, but more accurate. You can read more about SOM training algorithms [here](http://www.scholarpedia.org/article/Kohonen_network).\n\nThe goal of this project is to provide an API to build SOMs in `Go`. The project also implements various SOM quality measures which can help you validate the results of the training algorithm. In particular the project implements `quantization` and `topographic` error to measure both the projection and topography as well as `topographic product` which can help you make a decision about the size of the SOM grid.\n\nSee the accompanying introductory [blog post](https://cybernetist.com/2017/01/13/self-organizing-maps-in-go/).\n\n# Get started\n\nGet the source code:\n\n```\n$ go get -u github.com/milosgajdos/gosom\n```\n\nGet all dependencies:\n\n```\n$ make dep\n```\n\nRun the tests:\n\n```\n$ make test\n```\n\n# Example\n\nYou can see the simplest example of `SOM` below:\n\n```go\nfunc main() {\n        // make random data\n        d := []float64{5.1, 3.5, 1.4, 0.1,\n                4.9, 3.0, 1.4, 0.2,\n                4.7, 3.2, 1.3, 0.3,\n                4.6, 3.1, 1.5, 0.4,\n                5.0, 3.6, 1.4, 0.5}\n        data := mat64.NewDense(5, 4, d)\n        // SOM configuration\n        grid := \u0026som.GridConfig{\n                Size:   []int{2, 2},\n                Type:   \"planar\",\n                UShape: \"hexagon\",\n        }\n        cb := \u0026som.CbConfig{\n                Dim:      4,\n                InitFunc: som.RandInit,\n        }\n        mapCfg := \u0026som.MapConfig{\n                Grid: grid,\n                Cb:   cb,\n        }\n        // create new SOM\n        m, err := som.NewMap(mapCfg, data)\n        if err != nil {\n                fmt.Fprintf(os.Stderr, \"\\nERROR: %s\\n\", err)\n                os.Exit(1)\n        }\n        // training configuration\n        trainCfg := \u0026som.TrainConfig{\n                Algorithm: \"seq\",\n                Radius:    500.0,\n                RDecay:    \"exp\",\n                NeighbFn:  som.Gaussian,\n                LRate:     0.5,\n                LDecay:    \"exp\",\n        }\n        if err := m.Train(trainCfg, data, 300); err != nil {\n                fmt.Fprintf(os.Stderr, \"\\nERROR: %s\\n\", err)\n                os.Exit(1)\n        }\n        // check quantization error\n        qe, err := m.QuantError(data)\n        if err != nil {\n                fmt.Fprintf(os.Stderr, \"\\nERROR: %s\\n\", err)\n                os.Exit(1)\n        }\n        log.Printf(\"Quantization Error: %f\\n\", qe)\n}\n```\n\nIf you build and run this program it will spit out `quantization` error. It's not that particularly exciting. You could generate a `u-matrix`, but since the data set is very simple, it would not be particularly interesting either. If you want to see more elaboarate and moreinteresting stuff you can do, check out the samples programs in `examples` directory.\n\n# Clustering\n\nSOMs are a very good tool to perform data clustering. Examples directory contains two more elaborate programs that illustrate the power of SOM clustering.\n\n## Colors example\n\nA classic \"schoolbook\" example of self-organisation is clustering of colors in arbitrarily \"nosiy\" images. You can find a simple program which does this in the `colors` subdirectory of `examples`. When you build the program you can run it as follows:\n\n```\n$ make colors\n$ ./_build/colors -umatrix umatrix.html -dims 40,40 -radius 500.0 -rdecay exp -lrate 0.5 -ldecay exp -ushape hexagon -iters 30000 -training seq -input ./examples/colors/testdata/colors.png -output som.png\n[ gosom ] Loading data set ./examples/colors/testdata/colors.png\n[ gosom ] Creating new SOM. Dimensions: [40 40], Grid Type: planar, Unit shape: hexagon\n[ gosom ] Starting SOM training. Method: seq, iterations: 30000\n[ gosom ] Training successfully completed. Duration: 3.843383347s\n[ gosom ] Saving U-Matrix to umatrix.html\n```\n\nThis program reads in a sample \"noisy\" image (each pixel has a random pixel value assigned from Uniform distribution `[0,255]`). The training then \"organizes\" the input values into SOM model (aka codebook) vectors. You can see the results of the training below along with a simple capture of the training process:\n\n\u003cp float=\"center\"\u003e\n\u003cimg src=\"./examples/colors/testdata/colors.png\" alt=\"Noisy image\" width=\"200\"\u003e\n\u003cimg src=\"./examples/colors/out.gif\" alt=\"Self-organization\" width=\"200\"\u003e\n\u003cimg src=\"./examples/colors/som.png\" alt=\"Self-organized color image\" width=\"200\"\u003e\n\u003c/p\u003e\n\n## Arbitrary labeled data\n\nEven more elaborate example can be found in `fpcs` directory. It is used to demostrate that both implemented algorithm behave as expected according to the following [research](http://www.uni-marburg.de/fb12/arbeitsgruppen/datenbionik/data?language_sync=1). You can verify this yourself. First you have to build the `fcps` example program:\n\n```\n$ make fcps\n```\n\nThe program provides various cli options:\n\n```\n$ ./_build/fcps -h\n```\n\nExamples of both `batch` and `sequential` training runs can be found below:\n\n### Batch algorithm\n\n```\n$ D=Target ./_build/fcps -umatrix umatrix_batch.html -dims 30,30 -radius 500.0 -rdecay exp -ushape rectangle -iters 100 -training batch -input examples/fcps/testdata/fcps/${D}.lrn -cls examples/fcps/testdata/fcps/${D}.cls\n[ gosom ] Loading data set testdata/fcps/Target.lrn\n[ gosom ] Creating new SOM. Dimensions: [30 30], Grid: planar, Unit shape: rectangle\n[ gosom ] Starting SOM training. Method: batch, iterations: 100\n[ gosom ] Training successfully completed. Duration: 1.923548243s\n[ gosom ] Saving U-Matrix to umatrix_batch.html\n[ gosom ] Quantization Error: 0.023212\n[ gosom ] Topographic Product: +Inf\n[ gosom ] Topographic Error: 0.015584\n```\n\n### Sequential algorithm\n\n```\n$ D=Target ./_build/fcps -umatrix umatrix_seq.html -dims 30,30 -radius 500.0 -rdecay exp -lrate 0.5 -ldecay exp -ushape hexagon -iters 30000 -training seq -input examples/fcps/testdata/fcps/${D}.lrn -cls examples/fcps/testdata/fcps/${D}.cls\n[ gosom ] Loading data set testdata/fcps/Target.lrn\n[ gosom ] Creating new SOM. Dimensions: [30 30], Grid: planar, Unit shape: hexagon\n[ gosom ] Starting SOM training. Method: seq, iterations: 30000\n[ gosom ] Training successfully completed. Duration: 2.261068582s\n[ gosom ] Saving U-Matrix to umatrix_seq.html\n[ gosom ] Quantization Error: 0.064704\n[ gosom ] Topographic Product: 0.010281\n[ gosom ] Topographic Error: 0.014286\n```\n\n### Results\n\nBoth of the above mentioned runs generate a simple `umatrix` that displays the clustered data in `svg` format. You can now inspect the files to cmpare the both algorithms.\n\n# Acknowledgements\n\nTest data present in `fcps` subdirectory of `testdata` come from [Philipps University of Marburg](http://www.uni-marburg.de/fb12/arbeitsgruppen/datenbionik/data?language_sync=1):\n\n**Ultsch, A.**: Clustering with SOM: U*C, In *Proc. Workshop on Self-Organizing Maps, Paris, France, (2005) , pp. 75-82*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmilosgajdos%2Fgosom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmilosgajdos%2Fgosom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmilosgajdos%2Fgosom/lists"}