JSON model format

JSON file representations of models can be easily created with the model editor or the Python SDK and usually do not need to be created by hand.

All Genius models can be represented in JSON format. The official JSON schema can be seen on the API definitions page (see the "VFG" schema at the bottom of the page). Here we describe the basic components of format.

You may see the JSON model files referred to as "VFG" files in the model editor or parts of the documentation. VFG stands for "VERSES factor graph" and is the name for the JSON format used for models in Genius.

At the top level, this JSON file will consist of version number, metadata, variables, and factors.

JSON model components

Version number

The version number defaults to 0.5.0 and should be used for all models in the Darwin release.

Metadata

The metadata field contains store basic information about the model type and its properties. These fields are optional but may be useful to store for your reference. It contains the following fields:

• Model version - A version number for the model.

• Model type - The type of model. Must be one of:

  • factor_graph - A generic factor graph representation of a Bayesian network.

  • pomdp - Partially observable Markov decision process used in active inference.

• Description - A description for the model.

Variables

Variables are stored in a collection which consists of:

• The variable name (string) which has the following collections nested within:

  • elements - The categories of the variable represented as a string.

  • role - The role of the variable. For POMDP models, variables that correspond to actions will need the control_state role. For Bayesian networks, variables that are latent (no data is available) must have the latent role in order for Genius to understand that it needs to infer the probability of this variant from the data.

If no names are provided for the variables they will default to integer values.

Factors

Factors are collections which are stored in an array. The collections include the following:

• variables - The variables connected to the factor.

• distribution - The distribution type for the factor. Must be one of

  • categorical - A marginal or prior distribution that has no parents (conditioning variables).

  • categorical_conditional - A conditional distribution, i.e. a distribution that depends on one or more parent variables.

  • logits - An unnormalized probability distribution. Logits are used to represent preferences in active inference.

• values - The probabilities for each entry in the factor.

• role - The factor's role in the model. Must be one of:

  • transition - A transition factor used in POMDP models to represent the probability of transitioning to a state given the current state and chosen action.

  • preference - An unnormalized probability distribution used in POMDP models measured in logits that specifies relative costs/rewards for an observation variable it is connected to.

  • likelihood - A categorical conditional distribution specifying the probability of the data under a given variable.

  • initial_state_prior - A special prior distribution over hidden states used in POMDP models.

Example

An example factor graph schema for the sprinkler dataset is show below:

{
  "factors": [
        {
          "distribution": "categorical",
          "values": [
            0.5,
            0.5
          ],
          "variables": [
            "cloudy"
          ]
        },
        {
          "distribution": "categorical_conditional",
          "values": [
            [
              0.8,
              0.2
            ],
            [
              0.2,
              0.8
            ]
          ],
          "variables": [
            "rain",
            "cloudy"
          ]
        },
        {
          "distribution": "categorical_conditional",
          "values": [
            [
              0.5,
              0.9
            ],
            [
              0.5,
              0.1
            ]
          ],
          "variables": [
            "sprinkler",
            "cloudy"
          ]
        },
        {
          "distribution": "categorical_conditional",
          "values": [
            [
              [
                1,
                0.1
              ],
              [
                0.1,
                0.01
              ]
            ],
            [
              [
                0,
                0.9
              ],
              [
                0.9,
                0.99
              ]
            ]
          ],
          "variables": [
            "wet_grass",
            "sprinkler",
            "rain"
          ]
        }
      ],
      "variables": {
        "cloudy": {
          "elements": [
            "no",
            "yes"
          ]
        },
        "rain": {
          "elements": [
            "no",
            "yes"
          ]
        },
        "sprinkler": {
          "elements": [
            "off",
            "on"
          ]
        },
        "wet_grass": {
          "elements": [
            "no",
            "yes"
          ]
        }
      },
      "version": "0.4.0",
      "metadata": {
        "model_type": "bayesian_network",
        "model_version": "2q",
        "description": "A simple sprinkler demo"
    }
}