Improve documentation of IncludeWorkflows #40

ncguilbeault · 2024-11-20T13:54:41Z

Summary

This PR updates the main bonsai environment with the latest Bonsai.ML packages and adds documentation to IncludeWorkflows within Bonsai.ML packages. Fixes #32

glopesdev · 2025-01-10T11:13:40Z

.bonsai/Bonsai.config

+    <Package id="Bonsai.ML" version="0.4.0" />
+    <Package id="Bonsai.ML.Data" version="0.4.0" />
+    <Package id="Bonsai.ML.Design" version="0.4.0" />
+    <Package id="Bonsai.ML.HiddenMarkovModels" version="0.4.0" />
+    <Package id="Bonsai.ML.HiddenMarkovModels.Design" version="0.4.0" />
+    <Package id="Bonsai.ML.LinearDynamicalSystems" version="0.4.0" />
+    <Package id="Bonsai.ML.LinearDynamicalSystems.Design" version="0.4.0" />
+    <Package id="Bonsai.ML.NeuralDecoder" version="0.4.0" />
+    <Package id="Bonsai.ML.NeuralDecoder.Design" version="0.4.0" />
+    <Package id="Bonsai.ML.Python" version="0.4.0" />


Since the source for these packages is already in this repo, I feel we might not want to add them to the documentation environment, and instead simply use the local builds.

The advantage of the latter is that we don't need to remember to keep updating the versions in the config file, since it will always be using what exactly is in the repository source code.

src/Bonsai.ML.HiddenMarkovModels/CheckFitFinished.bonsai

glopesdev · 2025-01-10T11:18:13Z

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>


This is more a general question about casing in documentation. Do we want to use python or Python? I think I am happy one way or the other as long as we are consistent. I may have a slight preference to Python since that is how it is cased in c# namespaces and classes, e.g. Python.NET, Bonsai.Scripting.Python, etc.

glopesdev · 2025-01-10T11:22:45Z

src/Bonsai.ML.HiddenMarkovModels/CreateHMM.bonsai

+        <Property Name="NumStates" Description="The number of discrete latent states of the HMM model." />
+        <Property Name="Dimensions" Description="The dimensionality of the observations into the HMM model." />
+        <Property Name="ObservationsModelType" 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 model. If an observations model or transitions model is defined within the state parameters, they will override the values set in the observations model type and transitions model type properties, respectively." />
+        <Property Name="TransitionsModelType" Description="The type of transition model that the HMM will use to calculate the probabilities of transitioning between states."/>


Suggested change

<Property Name="NumStates" Description="The number of discrete latent states of the HMM model." />

<Property Name="Dimensions" Description="The dimensionality of the observations into the HMM model." />

<Property Name="ObservationsModelType" 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 model. If an observations model or transitions model is defined within the state parameters, they will override the values set in the observations model type and transitions model type properties, respectively." />

<Property Name="TransitionsModelType" Description="The type of transition model that the HMM will use to calculate the probabilities of transitioning between states."/>

<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="ObservationsModelType" 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 observations model or transitions model is defined within the state parameters, these will override the values set in the observations model type and transitions 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."/>

A few suggestions to improve clarity and simplify sentence structure. Also in general I think we don't need the word "model" after HMM since it is included in the acronym.

A final question about the property TransitionsModelType. In general one rule of thumb is to try and avoid pluralizing words unless we are talking about manipulation of collections, so I would rather use TransitionModelType, but we can definitely discuss further.

glopesdev · 2025-01-10T11:25:37Z

src/Bonsai.ML.HiddenMarkovModels/RunFitAsync.bonsai

@@ -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 to use for fitting the model to a single batch of data." Category="Hyperparameters" />


Suggested change

<Property Name="Value" DisplayName="NumIterations" Description="The number of iterations to use for fitting the model to a single batch of data." 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" />

glopesdev · 2025-01-10T11:28:01Z

src/Bonsai.ML.LinearDynamicalSystems/Kinematics/CreateKFModel.bonsai

+        <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" />


In general in Bonsai / C# we would use Pascal casing rather than snake case, but no need to change anything now, this is just a general comment for us to think about regarding casing of properties coming from Python.

glopesdev · 2025-01-10T11:28:38Z

src/Bonsai.ML.LinearDynamicalSystems/Kinematics/KFModelParameters.cs

@@ -51,10 +51,10 @@ public class KFModelParameters
        private string fpsString;

        /// <summary>
-        /// x position at time 0
+        /// The initial x position.


Depending on casing we would change this to X but see comment above, no need to change anything now.

glopesdev · 2025-01-10T11:29:44Z

src/Bonsai.ML.LinearDynamicalSystems/Learning/CheckOptimizationFinished.bonsai

@@ -6,6 +6,7 @@
                 xmlns:rx="clr-namespace:Bonsai.Reactive;assembly=Bonsai.Core"
                 xmlns:scr="clr-namespace:Bonsai.Scripting.Expressions;assembly=Bonsai.Scripting.Expressions"
                 xmlns="https://bonsai-rx.org/2018/workflow">
+  <Description>Periodically evaluates the `get_optimization_finished` function of the LDS model. Returns true when the `optimization_finished` attribute is true. This should onle be used after the `RunOptimizationAsync` function has already been started.</Description>


Suggested change

<Description>Periodically evaluates the `get_optimization_finished` function of the LDS model. Returns true when the `optimization_finished` attribute is true. This should onle be used after the `RunOptimizationAsync` function has already been started.</Description>

<Description>Periodically evaluates the `get_optimization_finished` function of the LDS model. Returns whether the `optimization_finished` attribute is true. This should only be used after the `RunOptimizationAsync` function has already been started.</Description>

glopesdev · 2025-01-10T11:30:37Z

src/Bonsai.ML.LinearDynamicalSystems/Learning/RunOptimizationAsync.bonsai

  <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 of data to use for fitting the model." Category="TrainingData" />


Suggested change

<Property Name="Value" DisplayName="BatchSize" Description="The size of the batch of data to use for fitting the model." Category="TrainingData" />

<Property Name="Value" DisplayName="BatchSize" Description="The size of the batch used for fitting the model." Category="TrainingData" />

… property

glopesdev reviewed Jan 10, 2025

View reviewed changes

glopesdev added the documentation Improvements or additions to documentation label Jan 10, 2025

ncguilbeault added 7 commits January 10, 2025 13:29

Add scripts for bonsai linux environment

54a1f38

Added description to the include workflow and description to the Name…

9e7214f

… property

Added descriptions to include workflows and properties

5cc3b4a

Added periods to the end of descriptions.

3066365

Added descriptions to workflows and properties

9a3666d

Improved documentation strings

644ed5e

Removed unused parameters

dcf81d2

ncguilbeault force-pushed the dev/improve-documentation branch from 4f7f5c3 to dcf81d2 Compare January 10, 2025 13:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation of IncludeWorkflows #40

Improve documentation of IncludeWorkflows #40

ncguilbeault commented Nov 20, 2024

glopesdev Jan 10, 2025

glopesdev Jan 10, 2025

glopesdev Jan 10, 2025

glopesdev Jan 10, 2025

glopesdev Jan 10, 2025

glopesdev Jan 10, 2025

glopesdev Jan 10, 2025

glopesdev Jan 10, 2025

	<Property Name="Value" DisplayName="NumIterations" Description="The number of iterations to use for fitting the model to a single batch of data." 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" />

	<Description>Periodically evaluates the `get_optimization_finished` function of the LDS model. Returns true when the `optimization_finished` attribute is true. This should onle be used after the `RunOptimizationAsync` function has already been started.</Description>
	<Description>Periodically evaluates the `get_optimization_finished` function of the LDS model. Returns whether the `optimization_finished` attribute is true. This should only be used after the `RunOptimizationAsync` function has already been started.</Description>

	<Property Name="Value" DisplayName="BatchSize" Description="The size of the batch of data to use for fitting the model." Category="TrainingData" />
	<Property Name="Value" DisplayName="BatchSize" Description="The size of the batch used for fitting the model." Category="TrainingData" />

Improve documentation of IncludeWorkflows #40

Are you sure you want to change the base?

Improve documentation of IncludeWorkflows #40

Conversation

ncguilbeault commented Nov 20, 2024

Summary

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment