-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #22 from bonsai-rx/hidden-markov-models
Introducing Online Inference with Hidden Markov Models (HMMs)
- Loading branch information
Showing
65 changed files
with
5,650 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,16 +1,44 @@ | ||
| # Bonsai - Machine Learning | ||
|
|
||
| The Bonsai.ML project is a collection of packages with reactive infrastructure for adding machine learning algorithms in Bonsai. Below you will find the list of packages (and the included subpackages) currently available within the Bonsai.ML collection. | ||
| The **Bonsai.ML** project is a collection of packages designed to integrate machine learning algorithms with Bonsai. This document provides an overview of the available packages and their functionalities. | ||
|
|
||
| * Bonsai.ML - provides core functionality across all Bonsai.ML packages. | ||
| * Bonsai.ML.LinearDynamicalSystems - package for performing inference of linear dynamical systems. Interfaces with the [lds_python](https://github.com/joacorapela/lds_python) package. | ||
| - *Bonsai.ML.LinearDynamicalSystems.Kinematics* - subpackage included in the LinearDynamicalSystems package which supports using the Kalman Filter to infer kinematic data. | ||
| - *Bonsai.ML.LinearDynamicalSystems.LinearRegression* - subpackage included in the LinearDynamicalSystems package which supports using the Kalman Filter to perform Bayesian linear regression. | ||
| * Bonsai.ML.Visualizers - provides a set of visualizers for dynamic graphing/plotting. | ||
| ## Core Packages | ||
|
|
||
| - **Bonsai.ML** | ||
| Provides common tools and functionality. | ||
|
|
||
| - **Bonsai.ML.Data** | ||
| Provides common tools and functionality for working with data. | ||
|
|
||
| - **Bonsai.ML.Python** | ||
| Provides common tools and functionality for C# packages to interface with Python. | ||
|
|
||
| ## Available Packages | ||
|
|
||
| ### Bonsai.ML.LinearDynamicalSystems | ||
| Facilitates inference using linear dynamical systems (LDS). It interfaces with the [lds_python](https://github.com/joacorapela/lds_python) package using the [Bonsai - Python Scripting](https://github.com/bonsai-rx/python-scripting) library. | ||
|
|
||
| - **Bonsai.ML.LinearDynamicalSystems.Kinematics** | ||
| Supports the use of the Kalman Filter for inferring kinematic data. | ||
|
|
||
| - **Bonsai.ML.LinearDynamicalSystems.LinearRegression** | ||
| Utilizes the Kalman Filter to perform online Bayesian linear regression. | ||
|
|
||
| ### Bonsai.ML.HiddenMarkovModels | ||
| Facilitates inference using Hidden Markov Models (HMMs). It interfaces with the [ssm](https://github.com/lindermanlab/ssm) package using the [Bonsai - Python Scripting](https://github.com/bonsai-rx/python-scripting) library. | ||
|
|
||
| - **Bonsai.ML.HiddenMarkovModels.Observations** | ||
| Provides functionality for specifying different types of observations. | ||
|
|
||
| - **Bonsai.ML.HiddenMarkovModels.Transitions** | ||
| Provides functionality for specifying different types of transition models. | ||
|
|
||
| ### Bonsai.ML.Visualizers | ||
| Graphing and plotting library for visualizing data. | ||
|
|
||
| > [!NOTE] | ||
| > Bonsai.ML packages are installed through Bonsai's integrated package manager and are typically available for use immediately. However, certain packages may require additional steps for installation. See the dedicated package section for specific guides and documentation. | ||
| > Bonsai.ML packages can be installed through Bonsai's integrated package manager and are generally ready for immediate use. However, some packages may require additional installation steps. Refer to the specific package section for detailed installation guides and documentation. | ||
| ## Acknowledgments | ||
|
|
||
| Development of this package was supported by funding from the Biotechnology and Biological Sciences Research Council [grant number BB/W019132/1]. | ||
| Development of the Bonsai.ML package is supported by the Biotechnology and Biological Sciences Research Council [grant number BB/W019132/1]. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # Getting Started | ||
|
|
||
| The workflow starts with creating a python runtime, followed by loading the ssm package, referred to as the HMM module. After this, you can instantiate the HMM model and pass it observations of data to perform inference. Since this package relies on communication between Bonsai and Python, the observations that the model uses must be formatted into a valid string representation of a Python data type, namely a list of numbers. | ||
|
|
||
| ## Workflow | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| A(["Create Python Runtime"]) | ||
| B(["Load HMM Module"]) | ||
| C(["Create HMM"]) | ||
| D(["Generate Observations"]) | ||
| E(["Infer Hidden State"]) | ||
| A --> B | ||
| B --> C | ||
| C --> D | ||
| D --> E | ||
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > Due to the way Bonsai.ML interacts with Python, it is necessary for the first two steps to complete before instantiating the model. It is important to know that the initialization of the Python runtime, loading the module, and creating the model takes time to complete, and that only once the model has been created can inference be performed. | ||
| ## Implementation | ||
|
|
||
| Below is a simplified Bonsai workflow that implements the core logic of the package. | ||
|
|
||
| :::workflow | ||
|  | ||
| ::: | ||
|
|
||
| A `CreateRuntime` node is used to initialize a python runtime engine, which gets passed to a `BehaviorSubject` called `PythonEngine`. Bonsai's `CreateRuntime` node should automatically detect the python virtual environment if it was activated in the same terminal that was used to launch Bonsai, otherwise the path to the virtual environment can be specified in the `CreateRuntime` node by setting the `PythonHome` property. | ||
|
|
||
| Next, the `PythonEngine` node is passed to a `LoadHMMModule` node which will load the ssm package into the python environment. | ||
|
|
||
| Once the HMM module has been initialized, the `CreateHMM` node instantiates a python instance of the HMM model. Here, you can specify the initialization parameters of the model and provide a `ModelName` parameter that gets used to reference the model in other parts of the Bonsai workflow. | ||
|
|
||
| It is crucial that the `Data` are formatted into a string that the model can use, namely a string representing a Python list. For example, if you pass a Tuple with 2 items as your data, then the formatter should look something like `"[" + Item1.ToString() + Item2.ToString() + "]"`. The output of this should be used as your observations into the model, so connect your data source to a `Subject` named `Data` and modify the `FormatToPython` node to fit with your data. | ||
|
|
||
| `Observations` are then passed to an `InferState` node, which will use the specified model (given by the `ModelName` property) to infer the latent state of the model and outputs the `StateProbabilities`, or probabilities of being in each state given the observation. | ||
|
|
||
| ### Further Examples | ||
|
|
||
| For further examples and demonstrations for how this package works, see the [Bonsai - Machine Learning Examples](~/examples/README.md) section. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,134 @@ | ||
| # Bonsai.ML.HiddenMarkovModels Overview | ||
|
|
||
| The HiddenMarkovModels package provides a Bonsai interface to interact with the [ssm](https://github.com/lindermanlab/ssm) package. | ||
|
|
||
| ## General Guide | ||
|
|
||
| Since the package relies on both Bonsai and Python, installation steps for both are required. Detailed instructions are provided for installing the package in a new environment, integrating it with existing workflows, and running examples from the example folder. | ||
|
|
||
| - To install the package for integrating with existing workflows, see the [Installation Guide](#installation-guide). | ||
| - To get started with integrating the package into workflows, see the [Getting Started](hmm-getting-started.md) section. | ||
| - To test the specific examples provided, check out the [Examples](~/examples/README.md) tab. | ||
|
|
||
| ## Installation Guide | ||
|
|
||
| ### Dependencies | ||
|
|
||
| To get started, you must install the following tools: | ||
|
|
||
| - [Python (v3.10)](https://www.python.org/downloads/) | ||
| - [dotnet-sdk (v8)](https://dotnet.microsoft.com/en-us/download) | ||
| - [Git](https://git-scm.com/downloads) | ||
| - [Bonsai-Rx Templates tool](https://www.nuget.org/packages/Bonsai.Templates) | ||
|
|
||
| > [!TIP] | ||
| > Install Python through the standard installer and add to the system PATH. | ||
| ### Installation Guide - Windows | ||
|
|
||
| #### Creating New Project Environment | ||
|
|
||
| 1. Open the terminal and create a project folder: | ||
| ```cmd | ||
| cd ~\Desktop | ||
| mkdir HiddenMarkovModels | ||
| cd .\HiddenMarkovModels | ||
| ``` | ||
| 2. Create a Python virtual environment: | ||
| ```cmd | ||
| python -m venv .venv | ||
| ``` | ||
| 3. Create a Bonsai environment: | ||
| ```cmd | ||
| dotnet new bonsaienv | ||
| ``` | ||
| #### Python Environment Setup | ||
| 1. Activate the Python environment: | ||
| ```cmd | ||
| .\.venv\Scripts\activate | ||
| ``` | ||
| 2. Install the ssm package: | ||
| ```cmd | ||
| pip install numpy cython | ||
| pip install ssm@git+https://github.com/lindermanlab/ssm@6c856ad3967941d176eb348bcd490cfaaa08ba60 | ||
| ``` | ||
| 3. Verify installation: | ||
| ```python | ||
| import ssm | ||
| ``` | ||
| #### Bonsai Environment Setup | ||
| 1. Launch Bonsai: | ||
| ```cmd | ||
| .bonsai\Bonsai.exe | ||
| ``` | ||
| 2. Install the `Bonsai.ML.HiddenMarkovModels` package from the Package Manager. | ||
| > [!TIP] | ||
| > You can quickly search for the package by entering `Bonsai.ML.HiddenMarkovModels` into the search bar. | ||
| ### Installation Guide - Linux | ||
| #### Creating New Project Environment | ||
| 1. Create a project folder: | ||
| ```cmd | ||
| cd ~/Desktop | ||
| mkdir HiddenMarkovModels | ||
| cd HiddenMarkovModels | ||
| ``` | ||
| 2. Create a Python virtual environment: | ||
| ```cmd | ||
| python3 -m venv .venv | ||
| ``` | ||
| > [!TIP] | ||
| > Install the virtual environment package if needed: | ||
| > ```cmd | ||
| > sudo apt install python3.10-venv | ||
| > ``` | ||
| 3. Create a Bonsai environment: | ||
| ```cmd | ||
| dotnet new bonsaienv | ||
| ``` | ||
| > [!NOTE] | ||
| > This step uses the [Bonsai Linux Environment Template tool](https://github.com/ncguilbeault/bonsai-linux-environment-template) for easy creation of bonsai environments on Linux. | ||
| > See [this discussion](https://github.com/orgs/bonsai-rx/discussions/1101) for more information on getting Bonsai running on Linux. | ||
| #### Python Environment Setup | ||
| 1. Activate the Python environment: | ||
| ```cmd | ||
| source .venv/bin/activate | ||
| ``` | ||
| 2. Install the ssm package: | ||
| ```cmd | ||
| pip install numpy cython | ||
| pip install ssm@git+https://github.com/lindermanlab/ssm@6c856ad3967941d176eb348bcd490cfaaa08ba60 | ||
| ``` | ||
| 3. Verify installation: | ||
| ```python | ||
| import ssm | ||
| ``` | ||
| #### Bonsai Environment Setup | ||
| 1. Activate and launch Bonsai: | ||
| ```cmd | ||
| source .bonsai/activate | ||
| bonsai | ||
| ``` | ||
| 2. Install the `Bonsai.ML.HiddenMarkovModels` package from the Package Manager. | ||
| > [!TIP] | ||
| > You can quickly search for the package by entering `Bonsai.ML.HiddenMarkovModels` into the search bar. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| <?xml version="1.0" encoding="utf-8"?> | ||
| <WorkflowBuilder Version="2.8.5" | ||
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
| xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python" | ||
| xmlns:rx="clr-namespace:Bonsai.Reactive;assembly=Bonsai.Core" | ||
| xmlns:p1="clr-namespace:Bonsai.ML.HiddenMarkovModels;assembly=Bonsai.ML.HiddenMarkovModels" | ||
| xmlns="https://bonsai-rx.org/2018/workflow"> | ||
| <Workflow> | ||
| <Nodes> | ||
| <Expression xsi:type="Combinator"> | ||
| <Combinator xsi:type="py:CreateRuntime" /> | ||
| </Expression> | ||
| <Expression xsi:type="rx:BehaviorSubject"> | ||
| <Name>PythonEngine</Name> | ||
| </Expression> | ||
| <Expression xsi:type="SubscribeSubject"> | ||
| <Name>PythonEngine</Name> | ||
| </Expression> | ||
| <Expression xsi:type="IncludeWorkflow" Path="Bonsai.ML.HiddenMarkovModels:LoadHMMModule.bonsai" /> | ||
| <Expression xsi:type="IncludeWorkflow" Path="Bonsai.ML.HiddenMarkovModels:CreateHMM.bonsai"> | ||
| <Name>hmm</Name> | ||
| <NumStates>2</NumStates> | ||
| <Dimensions>2</Dimensions> | ||
| <ObservationsType>Gaussian</ObservationsType> | ||
| <TransitionsType>Stationary</TransitionsType> | ||
| </Expression> | ||
| <Expression xsi:type="SubscribeSubject"> | ||
| <Name>Data</Name> | ||
| </Expression> | ||
| <Expression xsi:type="Combinator"> | ||
| <Combinator xsi:type="p1:FormatToPythonList" /> | ||
| </Expression> | ||
| <Expression xsi:type="rx:BehaviorSubject"> | ||
| <Name>Observation</Name> | ||
| </Expression> | ||
| <Expression xsi:type="SubscribeSubject"> | ||
| <Name>Observation</Name> | ||
| </Expression> | ||
| <Expression xsi:type="IncludeWorkflow" Path="Bonsai.ML.HiddenMarkovModels:InferState.bonsai"> | ||
| <Name>hmm</Name> | ||
| </Expression> | ||
| <Expression xsi:type="rx:BehaviorSubject"> | ||
| <Name>InferredState</Name> | ||
| </Expression> | ||
| </Nodes> | ||
| <Edges> | ||
| <Edge From="0" To="1" Label="Source1" /> | ||
| <Edge From="2" To="3" Label="Source1" /> | ||
| <Edge From="3" To="4" Label="Source1" /> | ||
| <Edge From="5" To="6" Label="Source1" /> | ||
| <Edge From="6" To="7" Label="Source1" /> | ||
| <Edge From="8" To="9" Label="Source1" /> | ||
| <Edge From="9" To="10" Label="Source1" /> | ||
| </Edges> | ||
| </Workflow> | ||
| </WorkflowBuilder> |
File renamed without changes
Oops, something went wrong.