There are three common workflows for using Genius. The best option depends on your your case, experience with model building, and available data.
Workflow #1: Data to Model Wizard
If you have data available in CSV format and domain knowledge about how to model your problem of interest but would like a tutorial that walks you through the steps, then we suggest using the Data to Model Wizard. Using this wizard, you will flow through the following steps:
Load data from a CSV (data will be validated automatically)
If you have some data available in CSV format and domain knowledge about how to model your problem of interest but have experience building models in Genius, then we suggest the following workflow:
About lists the model editor version, service versions, and summarizes the Genius model editor's capabilities.
Help
Help menu options
Documentation provides links to this documentation and lists the keyboard shortcuts.
Model editing tools
The model editing tools are used to build the model. We will only cover the last three buttons in this section. See the Building a model section for an explanation of the buttons not covered here.
Loads the model currently used by the agent into the model editor canvas.
Checks to see that the structure of the model in the model editing canvas and factor probabilities are valid.
Sends the model in the model editing canvas to the agent.
Model editing canvas
The main workspace for drafting a model or editing a loaded model. The mouse scroll wheel can be used to zoom in and out. Pressing the mouse scroll wheel while moving around the model editing area will pan.
Model panel
Clicking on the icon will hide/reveal the variable panel to expose more room in the model editing canvas.
The model panel is dynamic and will change depending on the variables and factors in the model. When you load a CSV dataset, this panel will be populated with variables from this dataset. You can then add and remove these variables to the model editing canvas.
Clicking on the icon will hide/reveal the inspector panel to expose more room in the model editing canvas.
The inspector panel is dynamic and will change depending on the type of model you have loaded into the model editing canvas and the specific nodes of a factor graph you have selected. This panel will allow you to inspect the properties of your model, as well provide the interface needed to perform probabilistic inference or action selection.
Controls the zoom settings in the model editing canvas. The plus and minus buttons are used to change the zoom percentage in the model editing canvas. When the frame button is clicked the model will be auto-zoomed to fit in the screen. When the lock button is clicked the model components will be locked in place and cannot be edited.
Zoom controls
Basics
In this section, we will provide an overview of the basic operations required to set up a Genius agent to enable inference and action selection on a model.
Loading a model from JSON to the model editor
If you do not wish to build a model from scratch and already have a model file available, you can load it into the model editing canvas. Alternatively, if you have data available you can create a model with the Data to Model wizard.
Select Model in the main menu and click Open.
Select the JSON file from your local file system that you would like to load.
After loading the model, you will see it appear on the model editor canvas. At this point, the loaded model is in "draft mode" and has not yet been loaded to a service. You can make changes to the model as needed (see the "building a model" section for more detail). After you are finished working on your model, you must connect to and send the model to a Genius service.
Connecting to a service
After your model is finished in the model editor, you can connect to a service which will enable you to send the model to a service. To connect to a service, follow these steps:
Select Account in the main menu.
Click on Settings.
In the Service URL field at the URL for the Genius service you would like to connect to.
Click Save.
Sending the model to a service
After you have connected to a service and finished creating your model, you can send it to the service with the following steps.
Click Inference in the main menu.
Click Upload Model to Service .
Alternatively, you can click the button in the model editing tools toolbar.
Confirmation that a model has been sent from the model builder to the service.
You should receive a confirmation at the top of the screen that the model has been received by the service.
Validating the model
After you have sent a model to the service, you can validate the model to ensure that the format is correct. This step should be performed before running learning, inference, or action selection to avoid confusing errors that may occur with an invalid model.
Select the Model menu.
Click on Validate.
Alternatively, you can click the button in the modeling editing tools toolbar to validate.
You will receive a message at the top of the screen indicating whether the model has been validated.
Exporting a model
JSON is the standard format that is used for uploading models to Genius (see "JSON model format" page for more detail). When a model is exported, it will be saved with the json file extension.
Select Model.
Click on Export.
Exporting a model as JSON will also export metadata that tracks editing in progress in the model builder. If you reload this saved model later you can continue your work where you left off.
Loading a model
The model editor canvas will display the model you are currently working on. If you wish to replace the model shown in the canvas with a new model loaded from the service, then follow these steps:
Select Inference.
Click Download Model from Service.
Alternatively, you can click on the Download Model from Service in the model editing toolbar.
After you load your model you should receive a confirmation.
The Model Panel
The model panel tracks all the variables and factors that have been placed in the model editing canvas. It can also be used to load variables from an existing dataset.
The Model Tab
The model tab contains a summary of all variables and factors currently placed in the model editing canvas. Initially, the Model tab will be empty. As you add variables and factors to the model editing canvas, either manually using the icons, or by importing data by other means, they will appear in the Model tab as a list. The following image shows an example of the Model tab with a few variables and factors added:
The Model tab of the model panel
There are three variables ( icons) and two factors ( icons). Clicking on any of these elements will highlight them in the model editing canvas and open up the Properties tab of the inspector panel.
The Data Tab
If you already have data available, it can be used to speed up the model building process. The Data tab will enable you to pre-populate the variables with set categories based on sample CSV data and add them to the model editing canvas automatically. Initially, the Data tab will look like this:
The Data tab of the model panel
To get started, click the Upload Data button. This will open a window that allows you upload a CSV file containing sample data. See the CSV data format page for more information on the required structure of this data file. Once the data is uploaded it will be validated by Genius before import. If validation fails, see the page on tips for importing data to get your data in the correct format. Once validation is successful, the variable panel will now look as follows (using the medical diagnosis dataset as an example):
From here there are a number of options available under the Data tab:
The trash icon appears next to the dataset name: .This icon is used to delete the dataset. It will only appear if you hover over the dataset name.
The Variables sub panel lists the different variables that were uploaded from the CSV data. You can see that under each variable name you can see the distribution type ("Categorical" in this case) and the number of categories or levels (unique values) defined for this variable.
Click the Add All button to add all variables to the model editing canvas for further editing and model building.
If you have added multiple variable to the model editing canvas you can remove them by clicking the Remove All button.
The variables can be added to the model editing canvas using the icon. When the variable is added, you will see confirmation with the On Canvas text under the variable that was added.
The Inspector Panel
The tabs and content of the tabs in this panel will change dynamically depending on the elements of the model editing canvas that are selected.
Properties tab
The properties tab shows the properties of the a selected element (variable node or factor node) in the model editing canvas. The two boxes below describe the properties displayed for either variable nodes or factor nodes.
Variable node properties
The following screenshot shows an example of the variable node properties:
Properties for the smoke variable node from the Asia dataset
Variable nodes have the following properties:
The Data-connected variable box will only appear when you select a variable node in the model editing canvas if you have loaded this variable from a pre-existing dataset. This box indicates the name of the variable, the CSV dataset source for this variable, and the type of the variable in the CSV dataset. The icon will select the variable of interest in the Data tab of the model panel.
The Name field will only appear when you select a variable node in the model editing canvas that was added manually (i.e. not from a pre-existing dataset). Here you have the option to change the name of the variable.
The Role field indicates the role the variable plays in the model. The role will be set automatically if the variable was loaded from a pre-existing dataset. Otherwise, you have the choice of the following options:
Observation: A variable in the model for which data is available, an "observed" variable.
Hidden: A variable in the model for which data is not available; an "unobserved" or "latent" variable.
Action: A variable in the model that corresponds to actions the agent can take. Actions are only applicable when using active inference which relies on a POMDP model.
The Variable States box will only appear when you select a variable node in the model editing canvas if you have loaded this variable from a pre-existing dataset. In this box you will see the current number of categories (states) corresponding to this variable. Clicking on the icon reveals further options to transform the data. For more detail see the Data transformation options section.
The Variable Options box will only appear when you select a variable node in the model editing canvas that was added manually (i.e. not from a pre-existing dataset). Here you can change the names of the states of the variable, reorder the states, or add/remove states from the variable.
Factor node properties
The following screenshot shows an example of the factor node properties:
Properties of the smoke | lung factor from the Asia dataset
The Name field indicates the name of the factor node that will appear as text inside it in the model editing canvas. For factor nodes, this value is auto-generated based on the order of the variables connected to the factor with the conditioned variable listed first.
The Role field indicated the factor's role in the model. This value should be set to Likelihood unless you are building a POMDP model for use in active inference.
The Probability Table field shows the marginal or conditional probability table defined for the factor. By default, the values here are set to uniform. They can be modified manually or through parameter learning. Clicking the icon will expand the table to make it easier to read. A factor that is not connected to any variable nodes will not have a probability table.
If you select an edge, an option will appear in the Properties tab to delete the connection between the variables joined by the edge.
Inference tab
The Inference tab is used to perform probabilistic inference with a model loaded to a Genius service. See the section on performing probabilistic inference with the model builder for more detail. Note that the contents of this tab is fixed for all current variables in the model editing canvas. The contents will only change if a variable is deleted from the model editing canvas. An example of this tab is shown below:
The "What do you want to know" section allows you to select variables in your model that you wish to infer the probability over. The "What do you want to observe" section allows you to specify the states of the variables in your model that you observe. When you have selected your nodes of interest, click Send and Run to send the inference request to the Genius inference service.
Action Selection tab
The Action Selection tab is used to perform action selection with an active inference model that has been loaded to a Genius service. This panel tab will only appear if a model containing POMDP factors (transitions, or preferences) is selected. See the section on performing active inference with the model builder for more detail. An example of this tab is shown below:
The Policy Length field indicates the number of timesteps into the future that the Genius agent should plan.
The observation field indicates the observations that the Genius agent receives from its environment at the current point in time.
After selecting the policy length and observation, click Send and Run to run the action selection service with the Genius agent.
Data transformation options
If you load your data from a pre-existing CSV dataset, you will be presented with the option to transform the data for different variable nodes in the model. An example of this section of the inspector panel is shown below:
Data transformation field of the Properties tab of the inspector panel
The options in this panel are described below:
Clicking the icon will hide this panel.
The Data type? field allows you to select the data type of the column uploaded from the CSV import. Genius will do its best to guess the data type for you upon import but you can always change it here manually.
The How to use values? field allows you to perform binning to transform the data. Binning options vary depending on the data type:
Continuous (Decimal numbers) - This data type can be binned with the Equal Ranges grouping method (fixed-width binning) or Equal Distribution grouping method (quantile binning). After you have selected your binning method and the number of groups to bin the data into, click Create Groups to apply the method to the categories of this variable.
Categorical (Text values) - This data type cannot be binned so there are no options available except to use the raw values.
Count (Whole numbers) - This data type can be binned with the Smart Grouping method (K-modes clustering). After you have selected your binning method and the number of groups to bin the data into, click Create Groups to apply the method to the categories of this variable.
Building a model with the Data to Model wizard
The Data to Model wizard guides you step-by-step through the process of model building in the model editor using a pre-existing CSV dataset. To get started, go to Model > Create > From Wizard. You should see a blurb explaining the steps of the Data to Model wizard. When you are ready, click Create, to proceed through the next steps:
Step 1: Load Data
Step 1 of the Data to Model Wizard
Click Tell us your intention to help narrow down the appropriate set of steps for Genius to execute given your use case. A window will pop up with a question to help Genius understand the nature of the results you would like to achieve.
Note: At this time, only the Reasoning option is available. Click this option and select Next.
Next, you need to import a valid CSV file. Click this button to begin. You will see a window pop up with rules governing valid CSV files. Click Next. The next screen will allow you to upload a CSV file. The CSV file will be validated to ensure it conforms to the specified rules.
If validation fails you should see a description on the screen pop up indicating what you need to fix for the CSV file to pass validation:
Example of a failed CSV dataset validation
Once your CSV file passes all validation checks, click Next.
Step 2: Build Model
Step 2 of the Data to Model Wizard
The Build Model section will walk you through the model building process.
First, you must add at least 2 variables to the canvas. The variables imported from your dataset appear in the left-hand model panel. Click the icon to add at least two variables.
Next, create a factor. A factor will be created automatically when you connect two variable nodes together. Select a node that you believe depends on another node. For example, we want to establish a relationship that shows that lung cancer is dependent on whether or not someone is a smoker. To encapsulate this relationship in a factor, start with the dependent variable, i.e. the variable that depends on another, (in this case, "lung") and drag an edge toward the variable it depends on ("smoke"). A factor will appear in probabilistic notation - lung | smoke - indicating that the first variable depends on the second variable.
Step 3: Train Model
Step 3 of the Data to Model Wizard
This step will show you how to execute model training (parameter learning). Click "Execute Training" to begin. A new window will pop up allowing you to upload your dataset. After you upload your dataset, click Start Training. When training is complete, you will be presented with a few options:
End of Step 3 of the Data to Model Wizard
Re-train - This option will clear out all model probabilities in your model back to a uniform distribution so the model can be trained from scratch with some data. We refer to this as de novo learning.
Train with additional dataset - This option will keep the existing probabilities from training and allow you to add an additional dataset to update the probabilities. We refer to this as continual learning. This option in the scenario where some time has passed and you have new data and wish to update the model in light of this new information but also while retaining the training from the past dataset. In this way, the model will reflect the cumulative training of both datasets, and the model will continue to stay aligned with changes in the real world.
When you are ready, click Done Training.
Step 4: Complete
Step 4 of the Data to Model Wizard
Training is now complete, and you can begin running queries to the Genius inference service. If you click on a factor in the model editing canvas and inspect its properties, you will notice that probabilities have now been added to this factor from the training step.
Updated probabilities of a factor as a result of training (parameter learning)
Building a model in the canvas
This tutorial demonstrates how to create a Genius model from scratch in the model editor canvas. We will focus on creating the well-known sprinkler model in this section.
It is also possible to load an existing model and then edit or modify it in the model editor canvas.
To begin drafting a new model follows these steps:
Go to the main menu and click Model > Create > From Scratch.
Click on the field labeled Untitled Graph to the left of the main menu, and choose a name for the model you wish to create.
Click Rename in the Edit Model Title modal to preserve your model name.
Using the model building tools
The model editing toolbar consists of following buttons:
Selection : This tool is used to click and drag to select one or multiple objects on the canvas, allowing users to move or edit them.is used to add a node to the model drafting area.
Duplicate : This tool is used to duplicate variable and factor nodes on the canvas.
Delete : This tool is used to delete selected objects on the canvas.
Undo : This tool is used to undo actions or edits made on the canvas.
Redo : This tool is used to redo actions or edits made on the canvas.
Layout : This tool is used to automatically rearrange the layout of the graph in layered, force, box, or tree formats.
Add Variable : This tool is used to add a variable node to the canvas.
Add Factor : This tool is used to add a factor node to the canvas.
Download Model from Service : This tool is used to load a model saved to the service to the canvas.
Validate Model : This tool is used to validate the structure of the graph.
Upload Model to Service : This tool is used to send the model to the service.
Creating and connecting model nodes
This section will demonstrate the creation of a valid factor graph for the well-known sprinkler model. This will entail creating two types of nodes: variable nodes and factor nodes.
To be a valid model, variable nodes must only connect to factor nodes and factor nodes must only connect to variable nodes.
The steps to create the sprinkler model are shown below
1
Click the add variable node icon to create a variable node. A circle node will appear with a default Variable node type. Double-click on the node to assign a caption to the node. In this case, we will write the name cloudy.
Creating the "cloudy" variable node.
2
Click the add factor node icon to create a factor node. Drag an edge out from a handle on the border of the cloudy variable and drag it to the border of the factor node to create a factor node for the cloudy variable. Alternatively, you can drag out an edge from a variable to automatically create a factor for that variable.
3
To connect the two nodes we have created, click within the halo that appears around the circle node and drag the line that appears to the other node. A factor caption will be automatically added. Then, click on the factor node and edit the probability table under the Properties tab.
Connecting the "cloudy" factor.
If you are creating a discrete Bayesian network, be sure to set the role to Likelihood. Additionally, ensure that the probabilities that you set sum to one.
4
Add variable nodes for rainy and sprinkler and connect them to factor nodes. Click on the factor node and change the distribution to categorical conditional to capture the dependency relationship between variables in the factor node caption. The caption will record variable nodes in the order they were connected, e.g. for rain | cloudy, this relationship appears when the rain variable node is connected to a factor first and the cloudy variable node is connected to the factor second.
Connecting categorical conditional factors to their corresponding variables.
5
Continue in this fashion to create the full model.
Full Sprinkler model.
Editing factor probabilities
The probabilities encoded in factor nodes in the factor graph can be edited in the information panel.
Click on a factor node you wish to edit.
Navigate down to the Probability Table.
Change probabilities by either:
Clicking on a cell of interest in the table and then double-clicking on the probability in this cell to change its value.
Clicking on a cell of interest in the table and then clicking the up and down arrow to change the probability in increments of 0.01.
Probabilities in the columns must sum to 1 to be a valid probability distribution. If this is not the case then the sum row at the bottom of the table will be colored red instead of green.
Model training (parameter learning)
Parameter learning uses an input CSV dataset to learn the probabilities of the model. Please ensure your CSV file is in the correct format before performing parameter learning. To train the model and learn parameters, you must already have a built model in the model editor, as demonstrated above. Once you are ready to train, follow these steps:
Select Model in the main menu.
Select Train.
Follow the prompts which instruct you to upload your CSV and train the model.
Please ensure that the variables in the dataset you upload match the variables in the model. See the section on tips for importing data for more info.
Probabilistic inference
To perform probabilistic inference, you must first have a valid model file sent to the service. We will take the sprinkler data set as an example in this section. We will solve the forward inference problem to answer the question: "what is the probability that the crop is wet given that we have data that the sprinkler is on and it is raining?" In probabilistic notation this is
P(wet_crop∣sprinkler=On,rain=Yes)
Click the Inference tab in the information panel.
Under "what do you want to know" select the variable for which you want to know the probability. In this case, this variable is wet_crop.
Click on the variables for which you have data to provide evidence. In this case, we click rain and then select yes in the radio buttons that appear below. Then click on sprinkler and select on for the radio buttons that appear below.
Click Send and Run.
These results of inference have the following interpretation:
Evidence: The input data that we gave to the Genius inference service. In this case, we indicated that it was raining and the sprinkler was on.
Probabilities: The resulting probabilities for each of the categories under the variable we are inferring. In this case, we wanted to infer whether the grass was wet given the evidence we provided (rain=yes and sprinkler=on).
Results: The resultant probabilities for the query we made.
Status: Telemetry which includes the execution time and memory used.
Action selection
In order to run active inference in the model editor, you must use a special type of probabilistic model known as a partially observable Markov decision process (POMDP) model. POMDPs are explained in more detail in the active inference and building a POMDP model from scratch pages. In a POMDP model, the following variables are required:
Actions
States
Observations
Additionally, three factors must be defined, with the following roles:
Likelihood
Preference
Transition
Typically, active inference is intended to be run in a continuous loop with an intractable environment. In the model editor, the user serves as the environment. For more detail, see the agent navigation example.
Load a POMDP model into the model editing panel.
Send the POMDP model to the agent.
Click on the Action Selection tab in the right-hand panel.
Select an appropriate policy length (future lookahead steps).
Loads the model currently used by the agent into the model editor canvas.
Checks to see that the structure of the model in the model editing canvas and factor probabilities are valid.
Sends the model in the model editing canvas to the agent.
icon will hide/reveal the variable panel to expose more room in the model editing canvas.
icon will hide/reveal the inspector panel to expose more room in the model editing canvas.
icons, or by importing data by other means, they will appear in the 
icons) and two factors (
icons). Clicking on any of these elements will highlight them in the model editing canvas and open up the 
.This icon is used to delete the dataset. It will only appear if you hover over the dataset name.
icon. When the variable is added, you will see confirmation with the 
icon will select the variable of interest in the 
icon reveals further options to transform the data. For more detail see the Data transformation options section.
icon will expand the table to make it easier to read. A factor that is not connected to any variable nodes will not have a probability table.
icon will hide this panel.
icon to add at least two variables.
: This tool is used to click and drag to select one or multiple objects on the canvas, allowing users to move or edit them.is used to add a node to the model drafting area.
: This tool is used to duplicate variable and factor nodes on the canvas.
: This tool is used to delete selected objects on the canvas.
: This tool is used to undo actions or edits made on the canvas.
: This tool is used to redo actions or edits made on the canvas.
: This tool is used to automatically rearrange the layout of the graph in layered, force, box, or tree formats.
: This tool is used to add a variable node to the canvas.
: This tool is used to add a factor node to the canvas.
: This tool is used to load a model saved to the service to the canvas.
: This tool is used to validate the structure of the graph.
: This tool is used to send the model to the service.
