diff --git a/docs/toc.yml b/docs/toc.yml index 8378cdc..cd6b744 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -28,6 +28,8 @@ href: ../examples/HiddenMarkovModels/SimulatedData/README.md - name: Inferring Behavioral State from Kinematics href: ../examples/HiddenMarkovModels/InferringBehavioralStateFromKinematics/README.md +- name: Extended Model Configuration + href: ../examples/HiddenMarkovModels/ExtendedModelConfiguration/README.md - name: Torch - name: Linear Regression diff --git a/examples/HiddenMarkovModels/ExtendedModelConfiguration/README.md b/examples/HiddenMarkovModels/ExtendedModelConfiguration/README.md new file mode 100644 index 0000000..bdfcc22 --- /dev/null +++ b/examples/HiddenMarkovModels/ExtendedModelConfiguration/README.md @@ -0,0 +1,36 @@ +# HMM - Extended Configuration Example + +The code for this repo can be found [here](https://github.com/bonsai-rx/machinelearning-examples/tree/main/examples/HiddenMarkovModels/ExtendedModelConfiguration). + +In the following example, you can see how to construct a Hidden Markov Model (HMM) with a custom configuration for the model's observation and transition matrices. This example extends the basic HMM configuration to allow for more complex scenarios, and includes 2 workflows, one for saving a custom model to disk and another for loading the model in a separate workflow. + +### Instructions + +Ensure you have Bonsai 2.9 installed on your system. You will also need to have the [uv Python environment manager](https://docs.astral.sh/uv/) installed. + +> [!NOTE] +> The `ssm` package uses an old version of `setuptools` that is incompatible with modern package management tools. Because of this, you first need to create a new Python virtual environment using `uv venv`, install the required packages using `uv pip install -r requirements.txt`, and then synchronize the Python environment using `uv sync --no-build-isolation`. + +### Save a Custom HMM Configuration + +This example workflow demonstrates how to create an HMM with custom parameters. When the workflow is run, it will instantiate a custom HMM model with the specified parameters and save it to disk. + +:::workflow +![Hidden Markov Models - Saving Custom Model To Disk](SaveModelConfig.bonsai) +::: + +The default parameters when using the `CreateHMM` operator is a `Gaussian` observation model and `Stationary` transition model. However, these options don't allow for fine-grained specification of the parameters of our model. To address this, the `CreateHMM` node supports parameterizing the model's `StateParameters`. From here, we can specify the `Observations`, `Transitions`, and `InitialState` distributions, which will override the parameters set directly inside the `CreateHMM` operator. + +In this example, the `ConfigureHMM` group node encapsulates this functionality. The `ConfigureHMM` node contains externalized properties which allow us to fully specify the `Observations` and `Transitions` model. Here, we use `AutoRegressiveObservations`, and can specify the number of lags, etc. The `Transitions` model is set to `ConstrainedStationary`, which allows us to mask certain transitions from being used in the model. + +When the workflow is run, the output of the `ConfigureHMM` node is a custom HMM model that is saved to disk using the `SerializeToJson` and `WriteAllText` operators. The model will be saved to a JSON file named `hmm_config.json`. + +### Load a Custom HMM Configuration + +This example workflow demonstrates how to load the custom HMM model saved in the previous workflow. + +:::workflow +![Hidden Markov Models - Loading Custom Model From Disk](LoadModelConfig.bonsai) +::: + +The `LoadStateParameters` is a `SelectMany` operator which will load the JSON file specified in the `Path` property, and outputs a `ModelParameters` object. The `Dimensions`, `NumStates`, and `StateParameters` properties of the `ModelParameters` object are then used as input parameters to the `CreateHMM` operator, which creates an HMM model with the parameters loaded from the JSON file. \ No newline at end of file