GeniusModel

The GeniusModel class is used to build factor graphs from scratch. The class has the following capabilities:

• Create a model from a JSON file path

• Construct model by adding variables or factors

• Validate a constructed model with POST /validate in the fastAPI

• Save (export) a model to JSON

• Visualize the model with networkx

• Get variable names and values for a given model

• Get factor attributes for a given model

Internally, the model is stored in the vfg instance variable and is just a dict that is converted to and from JSON as needed.

To import the GeniusModel class use: `from genius_client_sdk.model import GeniusModel

Usage patterns

Create a Genius model from an existing JSON file:

The agent_url and version must be set

GeniusModel(agent_url, json_path)

Creates an empty Genius model to build off of:

GeniusModel(agent_url)

After creating the model, add_variables() and add_factors() can be used to add variables and factors to the model. See the Python SDK for more details and examples.

Attributes

Variable	Type	Description
agent_url	str	The URL of the agent associated with the model.
vfg	VFG	The class representation of the JSON model.
version	str	The Genius model version.

Parameters

Class initialization parameters.

Parameter	Type	Default	Description
agent_url	str	"http://localhost:3000"	The URL of the agent associated with the model.
json_path	str	Optional	The path to an existing JSON file to load into the class.
etag	str	Optional	The ETag for the model.

Methods

add_variable

Adds a variable to the vfg instance variable.

Parameter	Type	Default	Description
name	str	Required	The name of the variable.
values	list[str]	Required	The values for the variable.
role	str	Optional	The role of the variable. Set to latent to indicate a latent variable.

Example:

model = GeniusModel()
model.add_variable(name="sprinkler", values=["on", "off"])

add_variables

Adds a list of variables to the vfg instance variable.

Parameter	Type	Default	Description
variables	list[tuple[str, list]]	Required	A list of variables to add to the factor graph.

Example:

model = GeniusModel()
model.add_variables(variables=[
    ("sprinkler", ["on", "off"]), 
    ("rain", ["yes", "no"])])

add_factor

Adds a factor to the vfg instance variable. The factor may be a marginal or conditional distribution.

Variables must be added to a model before adding any factors.

• Marginal distributions only require the values and target parameters.

• Conditional distributions require the values, targets, and parents parameters.

For conditional distributions, the target variable is set as the first value and the parents follow:

$P(target \mid parent_1, parent_2, \dots, parent_n)$

In other words, the distribution $P(wet\_grass \mid rain, sprinkler)$ will be stored internally as the list [wet_grass, rain, sprinkler], where the target variable comes first and the parent variables come after.

When constructing the values, the target variable must appear on the first axis and each parent on the following axis. So if the variables are [wet_grass, rain, sprinkler] then the dimension of the probability tensor must match this order.

Parameter	Type	Default	Description
values	numpy.ndarray	Required	The probability values for the factor.
target	str	Required	The conditioned (target) variable)
parents	list[str]	Optional	The conditioning (parent) variables.
role	str	NoRole	The role of the factor. Used in POMDP models. Must be one of "NoRole", "Transition", "Preference", "Likelihood" or "InitialStatePrior".
counts	numpy.ndarray	Optional	The counts for the factor.

Example (conditional distribution):

model = GeniusModel()

model.add_variable(name="rain", values=["no", "yes"])
model.add_variable(name="sprinkler", values=["off", "on"])
model.add_variable(name="wet_grass", values=["no", "yes"])

values = np.array(
    [[[1., 0.1], 
     [0., 0.9]], 
    [[0.1, 0.01], 
     [0.9, 0.99]]])

model.add_factor(values=values, target="wet_grass", parents=["sprinkler", "rain"])

Example (marginal distribution):

model = GeniusModel()

model.add_variable(name="cloudy", values=["no", "yes"])
values = np.array([0.5, 0.5])
model.add_factor(values=values, target="cloudy", parents=None)

get_factor_attributes

Returns the attributes of a selected factor. factor_id is an integer determined by the order that factors were added using add_factor().

Variables and factors must be added to the model with add_variables() and add_factors() before getting factor attributes.

Parameter	Type	Default	Description
factor_id	int	Required	The ID of the factor in the JSON model.
attribute	str	Required	The attribute of the factor to return. Must be one of "variables", "distribution", "values", or "role".

Returns:

Condition	Type	Description
attribute=="variable"	list[str]	Returns all variables connected to a factor.
attribute=="distribution"	str	Returns the distribution type of the factor. Return will be either "categorical" (marginal) or "conditional categorical".
attribute=="values"	list[list..[list...]	Returns the probability tensor associated with the factor.
attribute=="role"	str	Returns the factor's role. Must be one of "NoRole", "Transition", "Preference", "Likelihood" or "InitialStatePrior".

get_variable_names

Returns a list of names of the variables associated with the model.

Variables must be added to a model with add_variables() before calling get_variable_names().

Returns:

Type	Description
list	A list containing the names of the variables in the model.

get_variable_values

Returns a list of the categories associated with a variable.

Variables must be added to a model with add_variables() before calling get_variable_names().

Parameter	Type	Default	Description
variable_id	str	Required	The name of the variable whose categories will be returned.

Returns:

Type	Description
list	A list containing categories associated with a variable.

save

Exports a created model to a JSON file at a given path.

Parameter	Type	Default	Description
out_path	str	Required	The path to write the JSON export of the model to.

validate

Validates that a model created with the GeniusModel class is valid.

Parameter	Type	Default	Description
model_type	ModelType	FactorGraph	Defines the type of model the model should be validated as.
correct_errors	bool	False	If True, the validate endpoint will attempt to correct fixable errors.
verbose	bool	True	Whether the logger should report if a model was successfully validated.

visualize

Visualize a model created with the GeniusModel class.

Parameter	Type	Default	Description
factor_color	str	"lightgreen"	The color of the factor nodes in the model visualization.
variable_color	str	"lightcoral"	The color of the variable nodes in the model visualization.

Input colors must either be hex strings or one of the standard Matplotlib CSS colors.

add_metadata

Adds metadata to the JSON model dict.

Parameter	Type	Default	Description
model_type	ModelType	BayesianNetwork	The type of the model.
model_version	str	Optional	The version of the model.
description	str	Optional	A description of the model.