README.md

Welcome to mgng

An experimental implementation of the Merge Growing Neural Gas algorithm. The project turned into an exercise for using state-of-the-art python tools. This project has been created with my cookiecutter for science projects

The Growing Neural Gas and Merge Growing Neural Gas Algorithms

Growing Neural Gas (NGN) is a topology preserving (see this blog for a demonstration) or this explaination) extension to the Neural gas (NG) approach is usefull for learning when an underlying topology is not known (as in the case of the Self-organizing maps (SOM) algorithm). When it comes to time series data (such as trajectories), an extension to the neural gas algorithm has been approached (Merge Neural Gas (MNG)) and a combination with the GNG leads to the Merge growing neural gas (MNGN) approach. It adds a context memory to the neurons of the NGN and is useful for recognising temporal sequences and with a single weighting parameter, can be reduced to a regular NGN for which an implementation is available.

This packages implements the MGNG algorithm as a vanilla numpy implementation (which can be executed on the GPU with Cupy). The package uses modern python tools such as poetry, attrs (a focus has been laid on those two for this release), and sphinx and mypy/pylint/black for documentation and coding standards.

See the notebooks in the repective subfolder of the project root and the documentation.

Installation and development

First make sure to install Python (^3.7) the dependency management tool Poetry then create an isolated virtual environment and install the dependencies:

poetry install

Per terminal session, the following command should be executed to activate the virtual environment.

poetry shell

To generate the documentation run:

cd doc/
make api # optional, only when the code base changes
make html

To run unit tests, run:

pytest --log-level=WARNING
# Specify a selected test
pytest --log-level=DEBUG -k "TestExample"
pytest --log-level=DEBUG tests/test_example.py::TestExample::test_example

To work with VisualStudio Code:

cp .vscode/template.settings.json .vscode/settings.json
which python # copy the path without the executable

and add the path to the virtual environment to in the "python.pythonPath" setting.

cp .vscode/template.settings.json .vscode/settings.json
which python # copy the path without the executable

and add the path to the virtual environment to in the "python.pythonPath" setting.