Merge pull request #40 from bonsai-rx/dev/improve-documentation

Improve documentation of IncludeWorkflows
bonsai-rx · Mar 7, 2025 · 3854f9e · 3854f9e
2 parents 3be46d3 + 40d7133
commit 3854f9e
Show file tree

Hide file tree

Showing 23 changed files with 217 additions and 94 deletions.
diff --git a/.bonsai/Setup.sh b/.bonsai/Setup.sh
@@ -0,0 +1,41 @@
+#! /bin/bash
+
+SETUP_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+
+DEFAULT_VERSION="latest"
+VERSION="$DEFAULT_VERSION"
+
+while [[ "$#" -gt 0 ]]; do
+    case $1 in
+        --version) VERSION="$2"; shift ;;
+        *) echo "Unknown parameter passed: $1"; exit 1 ;;
+    esac
+    shift
+done
+
+echo "Setting up Bonsai v=$VERSION environment..."
+
+if [ ! -f "$SETUP_SCRIPT_DIR/Bonsai.exe" ]; then
+    CONFIG="$SETUP_SCRIPT_DIR/Bonsai.config"
+    if [ -f "$CONFIG" ]; then
+        DETECTED=$(xmllint --xpath '//PackageConfiguration/Packages/Package[@id="Bonsai"]/@version' "$CONFIG" | sed -e 's/^[^"]*"//' -e 's/"$//')
+        echo "Version detected v=$DETECTED."
+        RELEASE="https://github.com/bonsai-rx/bonsai/releases/download/$DETECTED/Bonsai.zip"
+    else
+        if [ $VERSION = "latest" ]; then
+            RELEASE="https://github.com/bonsai-rx/bonsai/releases/latest/download/Bonsai.zip"
+        else
+            RELEASE="https://github.com/bonsai-rx/bonsai/releases/download/$VERSION/Bonsai.zip"
+        fi
+    fi
+    echo "Download URL: $RELEASE"
+    wget $RELEASE -O "$SETUP_SCRIPT_DIR/temp.zip"
+    mv -f "$SETUP_SCRIPT_DIR/NuGet.config" "$SETUP_SCRIPT_DIR/temp.config"
+    unzip -d "$SETUP_SCRIPT_DIR" -o "$SETUP_SCRIPT_DIR/temp.zip"
+    mv -f "$SETUP_SCRIPT_DIR/temp.config" "$SETUP_SCRIPT_DIR/NuGet.config"
+    rm -rf "$SETUP_SCRIPT_DIR/temp.zip"
+    rm -rf "$SETUP_SCRIPT_DIR/Bonsai32.exe"
+fi
+
+source "$SETUP_SCRIPT_DIR/activate"
+source "$SETUP_SCRIPT_DIR/run" --no-editor
diff --git a/.bonsai/activate b/.bonsai/activate
@@ -0,0 +1,15 @@
+#!/bin/bash
+# activate.sh
+if [[ -v BONSAI_EXE_PATH ]]; then
+    echo "Error! Cannot have multiple bonsai environments activated at the same time. Please deactivate the current environment before activating the new one."
+    return
+fi
+BONSAI_ENV_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+export BONSAI_ENV_DIR
+export BONSAI_EXE_PATH="$BONSAI_ENV_DIR/Bonsai.exe"
+export ORIGINAL_PS1="$PS1"
+export PS1="($(basename "$BONSAI_ENV_DIR")) $PS1"
+alias bonsai='source "$BONSAI_ENV_DIR"/run'
+alias bonsai-clean='GTK_DATA_PREFIX= source "$BONSAI_ENV_DIR"/run'
+alias deactivate='source "$BONSAI_ENV_DIR"/deactivate'
+echo "Activated bonsai environment in $BONSAI_ENV_DIR"
diff --git a/.bonsai/deactivate b/.bonsai/deactivate
@@ -0,0 +1,8 @@
+#!/bin/bash
+unset BONSAI_EXE_PATH
+export PS1="$ORIGINAL_PS1"
+unset ORIGINAL_PS1
+unalias bonsai
+unalias bonsai-clean
+unalias deactivate
+echo "Deactivated bonsai environment."
diff --git a/.bonsai/run b/.bonsai/run
@@ -0,0 +1,58 @@
+#!/bin/bash
+# run.sh
+
+SETUP_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+CONFIG="$SETUP_SCRIPT_DIR/Bonsai.config"
+
+cleanup() {
+    update_paths_to_windows
+}
+
+update_paths_to_linux() {
+    ASSEMBLYLOCATIONS=$(xmllint --xpath '//PackageConfiguration/AssemblyLocations/AssemblyLocation/@location' "$CONFIG" | sed -e 's/^[^"]*"//' -e 's/"$//')
+    for ASSEMBLYLOCATION in $ASSEMBLYLOCATIONS; do
+        NEWASSEMBLYLOCATION="${ASSEMBLYLOCATION//\\/\/}"
+        xmlstarlet edit --inplace --update "/PackageConfiguration/AssemblyLocations/AssemblyLocation[@location='$ASSEMBLYLOCATION']/@location" --value "$NEWASSEMBLYLOCATION" "$CONFIG"
+    done
+
+    LIBRARYFOLDERS=$(xmllint --xpath '//PackageConfiguration/LibraryFolders/LibraryFolder/@path' "$CONFIG" | sed -e 's/^[^"]*"//' -e 's/"$//')
+    for LIBRARYFOLDER in $LIBRARYFOLDERS; do
+        NEWLIBRARYFOLDER="${LIBRARYFOLDER//\\/\/}"
+        xmlstarlet edit --inplace --update "//PackageConfiguration/LibraryFolders/LibraryFolder[@path='$LIBRARYFOLDER']/@path" --value "$NEWLIBRARYFOLDER" "$CONFIG"
+    done
+}
+
+update_paths_to_windows() {
+    ASSEMBLYLOCATIONS=$(xmllint --xpath '//PackageConfiguration/AssemblyLocations/AssemblyLocation/@location' "$CONFIG" | sed -e 's/^[^"]*"//' -e 's/"$//')
+    for ASSEMBLYLOCATION in $ASSEMBLYLOCATIONS; do
+        NEWASSEMBLYLOCATION="${ASSEMBLYLOCATION//\//\\}"
+        xmlstarlet edit --inplace --update "/PackageConfiguration/AssemblyLocations/AssemblyLocation[@location='$ASSEMBLYLOCATION']/@location" --value "$NEWASSEMBLYLOCATION" "$CONFIG"
+    done
+
+    LIBRARYFOLDERS=$(xmllint --xpath '//PackageConfiguration/LibraryFolders/LibraryFolder/@path' "$CONFIG" | sed -e 's/^[^"]*"//' -e 's/"$//')
+    for LIBRARYFOLDER in $LIBRARYFOLDERS; do
+        NEWLIBRARYFOLDER="${LIBRARYFOLDER//\//\\}"
+        xmlstarlet edit --inplace --update "//PackageConfiguration/LibraryFolders/LibraryFolder[@path='$LIBRARYFOLDER']/@path" --value "$NEWLIBRARYFOLDER" "$CONFIG"
+    done
+}
+
+if [[ -v BONSAI_EXE_PATH ]]; then
+    if [ ! -f "$BONSAI_EXE_PATH" ]; then
+        bash "$BONSAI_ENV_DIR"/Setup.sh
+        bash "$BONSAI_ENV_DIR"/run "$@"
+    else
+        BONSAI_VERSION=$(xmllint --xpath "//PackageConfiguration/Packages/Package[@id='Bonsai']/@version" "$CONFIG" | sed -e 's/^[^"]*"//' -e 's/"$//')       
+        if [[ -z ${BONSAI_VERSION+x} ]] && [ "$BONSAI_VERSION" \< "2.8.4" ]; then
+            echo "Updating paths to Linux format..."
+            trap cleanup EXIT INT TERM
+            update_paths_to_linux
+            mono "$BONSAI_EXE_PATH" "$@"
+            cleanup
+        else
+            mono "$BONSAI_EXE_PATH" "$@"
+        fi
+    fi
+else
+    echo "BONSAI_EXE_PATH is not set. Please set the path to the Bonsai executable."
+    return
+fi
diff --git a/src/Bonsai.ML.HiddenMarkovModels/CheckFitFinished.bonsai b/src/Bonsai.ML.HiddenMarkovModels/CheckFitFinished.bonsai
@@ -6,13 +6,14 @@
                  xmlns:p1="clr-namespace:Bonsai.ML;assembly=Bonsai.ML"
                  xmlns:scr="clr-namespace:Bonsai.Scripting.Expressions;assembly=Bonsai.Scripting.Expressions"
                  xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Periodically evaluates the `get_fit_finished` function of the HMM. Returns whether the `fit_finished` attribute is true. This should only be used after the `RunFitAsync` function has already been started.</Description>
   <Workflow>
     <Nodes>
       <Expression xsi:type="WorkflowInput">
         <Name>Source1</Name>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Name" DisplayName="Name" Category="ModelReference" />
+        <Property Name="Name" DisplayName="Name" Description="The name of the Python variable referencing the model object." Category="ModelReference" />
         <Property Name="TimerFrequency" DisplayName="TimerFrequency" Description="The frequency with which to check if the asynchronous fit loop is complete." Category="Polling" />
       </Expression>
       <Expression xsi:type="rx:SelectMany">

diff --git a/src/Bonsai.ML.HiddenMarkovModels/CreateHMM.bonsai b/src/Bonsai.ML.HiddenMarkovModels/CreateHMM.bonsai
@@ -6,10 +6,11 @@
                  xmlns:p2="clr-namespace:Bonsai.ML.HiddenMarkovModels;assembly=Bonsai.ML.HiddenMarkovModels"
                  xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
                  xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Creates a new HMM Python object inside of the HMM module and assigns it to a named Python variable.</Description>
   <Workflow>
     <Nodes>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Name" Category="ModelReference" />
+        <Property Name="Name" DisplayName="Name" Description="The name of the Python variable referencing the model object." Category="ModelReference" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="p1:CreateModelReference">
@@ -26,11 +27,11 @@
         <Name>Source1</Name>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="NumStates" />
-        <Property Name="Dimensions" />
-        <Property Name="ObservationsModelType" />
-        <Property Name="StateParameters" />
-        <Property Name="TransitionsModelType" />
+        <Property Name="NumStates" Description="The number of discrete latent states in the HMM." />
+        <Property Name="Dimensions" Description="The dimensionality of the observations going into the HMM." />
+        <Property Name="ObservationModelType" Description="The type of distribution that the HMM will use to model the emission of data observations." />
+        <Property Name="StateParameters" Description="The optional state parameters of the HMM. If an observation model or transition model is defined within the state parameters, these will override the values set in the observation model type and transition model type properties, respectively." />
+        <Property Name="TransitionModelType" Description="The type of model that the HMM will use to calculate the probabilities of transitioning between states."/>
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="p2:ModelParameters">

diff --git a/src/Bonsai.ML.HiddenMarkovModels/GetGaussianObservationsStatistics.bonsai b/src/Bonsai.ML.HiddenMarkovModels/GetGaussianObservationsStatistics.bonsai
@@ -6,6 +6,7 @@
                  xmlns:rx="clr-namespace:Bonsai.Reactive;assembly=Bonsai.Core"
                  xmlns:p2="clr-namespace:Bonsai.ML.HiddenMarkovModels.Observations;assembly=Bonsai.ML.HiddenMarkovModels"
                  xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Computes the statistics of the Gaussian observations in the HMM. Only works for models with Gaussian observations.</Description>
   <Workflow>
     <Nodes>
       <Expression xsi:type="WorkflowInput">
@@ -16,7 +17,7 @@
         <Combinator xsi:type="py:ObserveOnGIL" />
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Name" />
+        <Property Name="Name" DisplayName="Name" Description="The name of the Python variable referencing the model object." Category="ModelReference" />
       </Expression>
       <Expression xsi:type="SubscribeSubject" TypeArguments="p1:ModelReference">
         <Name>hmm</Name>

diff --git a/src/Bonsai.ML.HiddenMarkovModels/InferState.bonsai b/src/Bonsai.ML.HiddenMarkovModels/InferState.bonsai
@@ -6,6 +6,7 @@
                  xmlns:rx="clr-namespace:Bonsai.Reactive;assembly=Bonsai.Core"
                  xmlns:p2="clr-namespace:Bonsai.ML.HiddenMarkovModels;assembly=Bonsai.ML.HiddenMarkovModels"
                  xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Infers the state of the HMM given the observations.</Description>
   <Workflow>
     <Nodes>
       <Expression xsi:type="WorkflowInput">
@@ -15,7 +16,7 @@
         <Combinator xsi:type="py:ObserveOnGIL" />
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Name" />
+        <Property Name="Name" DisplayName="Name" Description="The name of the Python variable referencing the model object." Category="ModelReference" />
       </Expression>
       <Expression xsi:type="SubscribeSubject" TypeArguments="p1:ModelReference">
         <Name>hmm</Name>

diff --git a/src/Bonsai.ML.HiddenMarkovModels/LoadHMMModule.bonsai b/src/Bonsai.ML.HiddenMarkovModels/LoadHMMModule.bonsai
@@ -4,6 +4,7 @@
                  xmlns:rx="clr-namespace:Bonsai.Reactive;assembly=Bonsai.Core"
                  xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
                  xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Loads the HMM module into the workflow.</Description>
   <Workflow>
     <Nodes>
       <Expression xsi:type="WorkflowInput">

diff --git a/src/Bonsai.ML.HiddenMarkovModels/ModelParameters.cs b/src/Bonsai.ML.HiddenMarkovModels/ModelParameters.cs
@@ -29,9 +29,9 @@ public class ModelParameters : PythonStringBuilder
         private StateParameters stateParameters = null;
 
         /// <summary>
-        /// The number of states of the HMM model.
+        /// The number of discrete latent states in the HMM model.
         /// </summary>
-        [Description("The number of discrete latent states of the HMM model")]
+        [Description("The number of discrete latent states in the HMM.")]
         [Category("ModelSpecification")]
         public int NumStates 
         { 
@@ -44,9 +44,9 @@ public int NumStates
         }
 
         /// <summary>
-        /// The dimensionality of the observations into the HMM model.
+        /// The dimensionality of the observations going into the HMM.
         /// </summary>
-        [Description("The dimensionality of the observations into the HMM model")]
+        [Description("The dimensionality of the observations going into the HMM.")]
         [Category("ModelSpecification")]
         public int Dimensions 
         { 

diff --git a/src/Bonsai.ML.HiddenMarkovModels/RunFitAsync.bonsai b/src/Bonsai.ML.HiddenMarkovModels/RunFitAsync.bonsai
@@ -6,13 +6,14 @@
                  xmlns:p1="clr-namespace:Bonsai.ML;assembly=Bonsai.ML"
                  xmlns:scr="clr-namespace:Bonsai.Scripting.Expressions;assembly=Bonsai.Scripting.Expressions"
                  xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Runs the asynchronous fit loop of the HMM.</Description>
   <Workflow>
     <Nodes>
       <Expression xsi:type="WorkflowInput">
         <Name>Source1</Name>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Value" DisplayName="BatchSize" Category="TrainingData" />
+        <Property Name="Value" DisplayName="BatchSize" Description="The size of the batch used for fitting the model." Category="TrainingData" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="IntProperty">
@@ -47,7 +48,7 @@
         <Combinator xsi:type="py:ObserveOnGIL" />
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Name" />
+        <Property Name="Name" DisplayName="Name" Description="The name of the Python variable referencing the model object." Category="ModelReference" />
       </Expression>
       <Expression xsi:type="SubscribeSubject" TypeArguments="p1:ModelReference">
         <Name>hmm</Name>
@@ -64,39 +65,39 @@
         </Combinator>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Value" DisplayName="NumIterations" Category="Hyperparameters" />
+        <Property Name="Value" DisplayName="NumIterations" Description="The number of iterations used for fitting the model to a single batch of data." Category="Hyperparameters" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="IntProperty">
           <Value>50</Value>
         </Combinator>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Value" DisplayName="FlushDataBetweenBatches" Category="TrainingData" />
+        <Property Name="Value" DisplayName="FlushDataBetweenBatches" Description="Determines whether to append new batches of data to the existing batch or whether to flush the previous batch and fit only on the new batch." Category="TrainingData" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="BooleanProperty">
           <Value>false</Value>
         </Combinator>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Value" DisplayName="InitialStateDistribution" Category="ParametersToFit" />
+        <Property Name="Value" DisplayName="InitialStateDistribution" Description="Determines whether or not the model will fit the initial state distribution." Category="ParametersToFit" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="BooleanProperty">
           <Value>true</Value>
         </Combinator>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Value" DisplayName="TransitionParams" Category="ParametersToFit" />
+        <Property Name="Value" DisplayName="TransitionParams" Description="Determines whether or not the model will fit the state transition parameters." Category="ParametersToFit" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="BooleanProperty">
           <Value>true</Value>
         </Combinator>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Value" DisplayName="ObservationParams" Category="ParametersToFit" />
+        <Property Name="Value" DisplayName="ObservationParams" Description="Determines whether or not the model will fit the observation model parameters." Category="ParametersToFit" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="BooleanProperty">

diff --git a/src/Bonsai.ML.LinearDynamicalSystems/Kinematics/CreateKFModel.bonsai b/src/Bonsai.ML.LinearDynamicalSystems/Kinematics/CreateKFModel.bonsai
@@ -6,10 +6,11 @@
                  xmlns:p2="clr-namespace:Bonsai.ML.LinearDynamicalSystems.Kinematics;assembly=Bonsai.ML.LinearDynamicalSystems"
                  xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
                  xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Creates a Kalman filter model for kinematics estimation based on the discrete Weiner process acceleration model.</Description>
   <Workflow>
     <Nodes>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Name" Category="ModelReference" />
+        <Property Name="Name" DisplayName="Name" Description="The name of the Python variable referencing the model object." Category="ModelReference" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="p1:CreateModelReference" />
@@ -24,17 +25,17 @@
         <Name>Source1</Name>
       </Expression>
       <Expression xsi:type="ExternalizedMapping">
-        <Property Name="Fps" Category="ModelParams" />
-        <Property Name="Pos_x0" Category="ModelParams" />
-        <Property Name="Pos_y0" Category="ModelParams" />
-        <Property Name="Vel_x0" Category="ModelParams" />
-        <Property Name="Vel_y0" Category="ModelParams" />
-        <Property Name="Acc_x0" Category="ModelParams" />
-        <Property Name="Acc_y0" Category="ModelParams" />
-        <Property Name="Sigma_a" Category="ModelParams" />
-        <Property Name="Sigma_x" Category="ModelParams" />
-        <Property Name="Sigma_y" Category="ModelParams" />
-        <Property Name="Sqrt_diag_V0_value" Category="ModelParams" />
+        <Property Name="Fps" Description="The frames per second of the observations." Category="ModelParams" />
+        <Property Name="Pos_x0" Description="The initial x position." Category="ModelParams" />
+        <Property Name="Pos_y0" Description="The initial y position." Category="ModelParams" />
+        <Property Name="Vel_x0" Description="The initial x velocity." Category="ModelParams" />
+        <Property Name="Vel_y0" Description="The initial y velocity." Category="ModelParams" />
+        <Property Name="Acc_x0" Description="The initial x acceleration." Category="ModelParams" />
+        <Property Name="Acc_y0" Description="The initial y acceleration." Category="ModelParams" />
+        <Property Name="Sigma_a" Description="A scalar value representing the measurement noise." Category="ModelParams" />
+        <Property Name="Sigma_x" Description="A scalar value representing the prediction noise along the x axis." Category="ModelParams" />
+        <Property Name="Sigma_y" Description="A scalar value representing the prediction noise along the y axis." Category="ModelParams" />
+        <Property Name="Sqrt_diag_V0_value" Description="The initial value of the diagonal of the state covariance matrix." Category="ModelParams" />
       </Expression>
       <Expression xsi:type="Combinator">
         <Combinator xsi:type="p2:KFModelParameters">

diff --git a/src/Bonsai.ML.LinearDynamicalSystems/Kinematics/CreateObservation2D.bonsai b/src/Bonsai.ML.LinearDynamicalSystems/Kinematics/CreateObservation2D.bonsai
@@ -3,6 +3,7 @@
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:p1="clr-namespace:Bonsai.ML.LinearDynamicalSystems.Kinematics;assembly=Bonsai.ML.LinearDynamicalSystems"
                  xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Creates a 2 dimensional object with the properties X and Y from the input.</Description>
   <Workflow>
     <Nodes>
       <Expression xsi:type="WorkflowInput">