Developers guide

Model(graph::MetaGraph)

A structure representing a probabilistic graphical model. It contains a MetaGraph object representing the factor graph and a Base.RefValue{Int64} object to keep track of the number of nodes in the graph.

Fields:

• graph: A MetaGraph object representing the factor graph.
• plugins: A PluginsCollection object representing the plugins enabled in the model.
• backend: A Backend object representing the backend used in the model.
• counter: A Base.RefValue{Int64} object keeping track of the number of nodes in the graph.

is_variable(nodedata::NodeData)

Returns true if the node data is associated with a variable node, false otherwise. See also: is_factor,

is_factor(nodedata::NodeData)

Returns true if the node data is associated with a factor node, false otherwise. See also: is_variable,

getcontext(model::Model)

Retrieves the context of a model. The context of a model contains the complete hierarchy of variables and factor nodes. Additionally, contains all child submodels and their respective contexts. The Context supplies a mapping from symbols to GraphPPL.NodeLabel structures with which the model can be queried.

getorcreate!(model::Model, context::Context, options::NodeCreationOptions, name, index)

Get or create a variable (name) from a factor graph model and context, using an index if provided.

This function searches for a variable (name) in the factor graph model and context specified by the arguments model and context. If the variable exists, it returns it. Otherwise, it creates a new variable and returns it.

Arguments

• model::Model: The factor graph model to search for or create the variable in.
• context::Context: The context to search for or create the variable in.
• options::NodeCreationOptions: Options for creating the variable. Must be a NodeCreationOptions object.
• name: The variable (name) to search for or create. Must be a symbol.
• index: Optional index for the variable. Can be an integer, a collection of integers, or nothing. If the index is nothing creates a single variable.

If the index is an integer creates a vector-like variable. If the index is a collection of integers creates a tensor-like variable.

Returns

The variable (name) found or created in the factor graph model and context.

create_model([callback], generator::ModelGenerator)

Create a model from the ModelGenerator. Accepts an optional callback that can be used to inject extra keyword arguments into the model creation process by downstream packages. For example:

using GraphPPL, Distributions

GraphPPL.@model function beta_bernoulli(y, a, b)
    θ ~ Beta(a, b)
    for i in eachindex(y)
        y[i] ~ Bernoulli(θ)
    end
end

data_for_y = rand(Bernoulli(0.5), 100)

model = GraphPPL.create_model(beta_bernoulli(a = 1, b = 1)) do model, ctx 
    # Inject the data into the model
    y = GraphPPL.datalabel(model, ctx, GraphPPL.NodeCreationOptions(kind = GraphPPL.VariableKindData), :y, data_for_y)
    return (; y = y, )
end

model isa GraphPPL.Model
# output
true

ResizableArray{T, V, N} <: AbstractArray{T, N}

A ResizableArray is an array that can grow in any dimension. It handles like a regular AbstractArray when calling getindex, but for setindex! it will automatically resize the array if the index is out of bounds. It is also possible to iterate over the array in the same way as for a regular array. The data is stored internally as a recursive vector. The depth of the recursion is fixed at construction time and cannot be changed.

Constructor

• ResizableArray(::Type{T}): Create an empty resizable array of type T with depth 1, similar to a vector.
• ResizableArray(::Type{T}, ::Val{N}): Create an empty resizable array of type T with depth N, similar to AbstractArray{T, N}.

Context

Contains all information about a submodel in a probabilistic graphical model.

ModelGenerator(model, kwargs, plugins)

The ModelGenerator structure is used to lazily create the model with the given model and kwargs and plugins.

FactorID(fform, index)

A unique identifier for a factor node in a probabilistic graphical model.

NodeData(context, properties, plugins)

Data associated with a node in a probabilistic graphical model. The context field stores the context of the node. The properties field stores the properties of the node. The plugins field stores additional properties of the node depending on which plugins were enabled.

NodeLabel(name, global_counter::Int64)

Unique identifier for a node (factor or variable) in a probabilistic graphical model.

EdgeLabel(symbol, index)

A unique identifier for an edge in a probabilistic graphical model.

ProxyLabel(name, index, proxied)

A label that proxies another label in a probabilistic graphical model. The proxied objects must implement the is_proxied(::Type) = True(). The proxy labels may spawn new variables in a model, if maycreate is set to True().

Splat{T}

A type used to represent splatting in the model macro. Any call on the right hand side of ~ that uses splatting will be wrapped in this type.

Similar to Base.last when applied on ProxyLabel, but also applies checked_getindex while unrolling

The lift_index function "lifts" (or tracks) the index that is going to be used to determine the shape of the container upon creation for a variable during the unrolling of the ProxyLabel. This index is used only if the container is set to be created and is not used if variable container already exists.

datalabel(model, context, options, name, collection = MissingCollection())

A function for creating proxy data labels to pass into the model upon creation. Can be useful in combination with ModelGenerator and create_model.

A structure that holds interfaces of a node in the type argument I. Used for dispatch.

VariableRef(model::Model, context::Context, name::Symbol, index, external_collection = nothing)

VariableRef implements a lazy reference to a variable in the model. The reference does not create an actual variable in the model immediatelly, but postpones the creation until strictly necessarily, which is hapenning inside the unroll function. The postponed creation allows users to define pass a single variable into a submodel, e.g. y ~ submodel(x = x), but use it as an array inside the submodel, e.g. y[i] ~ Normal(x[i], 1.0).

Optionally accepts an external_collection, which defines the upper limit on the shape of the underlying collection. For example, an external collection [ 1, 2, 3 ] can be used both as y ~ ... and y[i] ~ ..., but not as y[i, j] ~ .... By default, the MissingCollection is used for the external_collection, which does not restrict the shape of the underlying collection.

The index is always a Tuple. By default, (nothing, ) is used, to indicate empty indices with no restrictions on the shape of the underlying collection. If "non-nothing" index is supplied, e.g. (1, ) the shape of the udnerlying collection will be fixed to match the index (1-dimensional in case of (1, ), 2-dimensional in case of (1, 1) and so on).

makevarref(fform::F, model::Model, context::Context, options::NodeCreationOptions, name::Symbol, index::Tuple)

A function that creates VariableRef, but takes the fform into account. When fform happens to be Atomic creates the underlying variable immediatelly without postponing. When fform is Composite does not create the actual variable, but waits until strictly necessarily.

A placeholder collection for VariableRef when the actual external collection is not yet available.

VariableNodeProperties(name, index, kind, link, value)

Data associated with a variable node in a probabilistic graphical model.

FactorNodeProperties(fform, neighbours)

Data associated with a factor node in a probabilistic graphical model.

VarDict

A recursive dictionary structure that contains all variables in a probabilistic graphical model. Iterates over all variables in the model and their children in a linear fashion, but preserves the recursive nature of the actual model.

AnonymousVariable(model, context)

Defines a lazy structure for anonymous variables. The actual anonymous variables materialize only in make_node! upon calling, because it needs arguments to the make_node! in order to create proper links.

A compile time key to access the extra properties of the NodeData structure.

IndexedVariable(name, index)

IndexedVariable represents a reference to a variable named name with index index.

Defines a random (or latent) kind for a variable in a probabilistic graphical model.

Defines a data kind for a variable in a probabilistic graphical model.

Defines a constant kind for a variable in a probabilistic graphical model.

Placeholder for a variable kind in a probabilistic graphical model.

Deterministic

Deterministic object used to parametrize factor node object with determinstic type of relationship between variables.

Stochastic

Stochastic object used to parametrize factor node object with stochastic type of relationship between variables.

Atomic

Atomic object used as a trait of structs and functions that are composed of a single node and are therefore materialized as a single node in the factor graph.

Composite

Composite object used as a trait of structs and functions that are composed of multiple nodes and therefore implement make_node!.

NodeCreationOptions(namedtuple)

Options for creating a node in a probabilistic graphical model. These are typically coming from the where {} block in the @model macro, but can also be created manually. Expects a NamedTuple as an input.

A version variable_nodes(model) that uses a callback function to process the variable nodes. The callback function accepts both the label and the node data.

A version factor_nodes(model) that uses a callback function to process the factor nodes. The callback function accepts both the label and the node data.

missing_interfaces(node_type, val, known_interfaces)

Returns the interfaces that are missing for a node. This is used when inferring the interfaces for a node that is composite.

Arguments

• node_type: The type of the node as a Function object.
• val: The value of the amount of interfaces the node is supposed to have. This is a Static.StaticInt object.
• known_interfaces: The known interfaces for the node.

Returns

• missing_interfaces: A Vector of the missing interfaces.

hasextra(node::NodeData, key::Symbol)

Checks if NodeData has an extra property with the given key.

getextra(node::NodeData, key::Symbol, [ default ])

Returns the extra property with the given key. Optionally, if the property does not exist, returns the default value.

setextra!(node::NodeData, key::Symbol, value)

Sets the extra property with the given key to the given value.

make_node!

Make a new factor node in the Model and specified Context, attach it to the specified interfaces, and return the interface that is on the lhs of the ~ operator.

Arguments

• model::Model: The model to add the node to.
• ctx::Context: The context in which to add the node.
• fform: The function that the node represents.
• lhs_interface: The interface that is on the lhs of the ~ operator.
• rhs_interfaces: The interfaces that are the arguments of fform on the rhs of the ~ operator.
• __parent_options__::NamedTuple = nothing: The options to attach to the node.
• __debug__::Bool = false: Whether to attach debug information to the factor node.

add_atomic_factor_node!(model::Model, context::Context, options::NodeCreationOptions, fform)

Add an atomic factor node to the model with the given name. The function generates a new symbol for the node and adds it to the model with the generated symbol as the key and a FactorNodeData struct.

Args: - model::Model: The model to which the node is added. - context::Context: The context to which the symbol is added. - options::NodeCreationOptions: The options for the creation process. - fform::Any: The functional form of the node.

Returns: - The generated label for the node.

Add the fform as the toplevel model to the model and context with the specified interfaces. Calls the postprocess logic for the attached plugins of the model. Should be called only once for a given Model object.

add_variable_node!(model::Model, context::Context, options::NodeCreationOptions, name::Symbol, index)

Add a variable node to the model with the given name and index. This function is unsafe (doesn't check if a variable with the given name already exists in the model).

Args: - model::Model: The model to which the node is added. - context::Context: The context to which the symbol is added. - options::NodeCreationOptions: The options for the creation process. - name::Symbol: The ID of the variable. - index: The index of the variable.

Returns: - The generated symbol for the variable.

Add a composite factor node to the model with the given name.

The function generates a new symbol for the node and adds it to the model with the generated symbol as the key and a NodeData struct with is_variable set to false and node_name set to the given name.

Args: - model::Model: The model to which the node is added. - parent_context::Context: The context to which the symbol is added. - context::Context: The context of the composite factor node. - node_name::Symbol: The name of the node.

Returns: - The generated id for the node.

copy_markov_blanket_to_child_context(child_context::Context, interfaces::NamedTuple)

Copy the variables in the Markov blanket of a parent context to a child context, using a mapping specified by a named tuple.

The Markov blanket of a node or model in a Factor Graph is defined as the set of its outgoing interfaces. This function copies the variables in the Markov blanket of the parent context specified by the named tuple interfaces to the child context child_context, by setting each child variable in child_context.individual_variables to its corresponding parent variable in interfaces.

Arguments

• child_context::Context: The child context to which to copy the Markov blanket variables.
• interfaces::NamedTuple: A named tuple that maps child variable names to parent variable names.

generate_nodelabel(model::Model, name::Symbol)

Generate a new NodeLabel object with a unique identifier based on the specified name and the number of nodes already in the model.

Arguments:

• model: A Model object representing the probabilistic graphical model.
• name: A symbol representing the name of the node.
• variable_type: A UInt8 representing the type of the variable. 0 = factor, 1 = individual variable, 2 = vector variable, 3 = tensor variable
• index: An integer or tuple of integers representing the index of the variable.

FunctionalIndex

A special type of an index that represents a function that can be used only in pair with a collection. An example of a FunctionalIndex can be firstindex or lastindex, but more complex use cases are possible too, e.g. firstindex + 1. Important part of the implementation is that the resulting structure is isbitstype(...) = true, that allows to store it in parametric type as valtype. One use case for this structure is to dispatch on and to replace begin or end (or more complex use cases, e.g. begin + 1).

FunctionalRange(left, range)

A range can handle FunctionalIndex as one of (or both) the bounds.

julia> first = GraphPPL.FunctionalIndex{:begin}(firstindex)
(begin)

julia> last = GraphPPL.FunctionalIndex{:end}(lastindex)
(end)

julia> range = GraphPPL.FunctionalRange(first + 1, last - 1)
((begin) + 1):((end) - 1)

julia> [ 1.0, 2.0, 3.0, 4.0 ][range]
2-element Vector{Float64}:
 2.0
 3.0

combine_args(args::Vector, kwargs::Nothing)

Combines a vector of arguments into a single expression.

Arguments

• args::Vector: The vector of arguments.
• kwargs::Nothing: The keyword arguments. This argument is always nothing.

Returns

An Expr with the combined arguments.

combine_args(args::Vector, kwargs::Vector)

Combines a vector of arguments and a vector of keyword arguments into a single expression.

Arguments

• args::Vector: The vector of arguments.
• kwargs::Vector: The vector of keyword arguments.

Returns

An Expr with the combined arguments and keyword arguments.

combine_args(args::Nothing, kwargs::Nothing)

Returns nothing.

Arguments

• args::Nothing: The arguments. This argument is always nothing.
• kwargs::Nothing: The keyword arguments. This argument is always nothing.

convert_local_statement(expr::Expr)

Converts a statement with the local keyword to the creation of an additional variable and the inclusion of thie variable in the subsequent tilde expression.

add_get_or_create_expression(e::Expr)

Add code to get or create a variable in the graph. The code generated by this function ensures that the left-hand-side is always defined in the local scope and can be used in make_node! afterwards.

Arguments

• e::Expr: The expression to modify.

Returns

A quote block with the modified expression.

keyword_expressions_to_named_tuple(keywords::Vector)

Converts a vector of keyword expressions to a named tuple.

Arguments

• keywords::Vector: The vector of keyword expressions.

Returns

• NamedTuple: The named tuple.

Examples

julia> keyword_expressions_to_named_tuple([:($(Expr(:kw, :in1, :y))), :($(Expr(:kw, :in2, :z)))])
(in1 = y, in2 = z)

convert_anonymous_variables(e::Expr)

Convert a function argument in the right-hand side of an expression to an anonymous variable. This function is used to convert function calls in the arguments of node creations to anonymous variables in the graph.

Example

```jldoctest
julia> convert_anonymous_variables(:(x ~ Normal(μ, sqrt(σ2)) where {created_by=:(Normal(μ, sqrt(σ2)))}))
:(x ~ (Normal(μ, anon_1 ~ (sqrt(σ2) where {anonymous = true, created_by = :(Normal(μ, sqrt(σ2)))})) where (created_by = :(Normal(μ, sqrt(σ2))))))
```

is_kwargs_expression(e::Expr)

Returns true if the given expression e is a keyword argument expression, i.e., if its head is either :kw or :parameters.

convert_to_kwargs_expression(expr::Expr)

Convert an expression to a keyword argument expression. This function is used in the conversion of tilde and dot-tilde expressions to ensure that the arguments are passed as keyword arguments.

convert_deterministic_statement(expr::Expr)

Convert a deterministic statement to a tilde statement with the is_deterministic option set to true.

Converts an expression into its proxied equivalent. Used to pass variables in sub-models and create a chain of proxied labels.

julia> x = GraphPPL.NodeLabel(:x, 1)
x_1
julia> GraphPPL.proxy_args(:(y = x))
:(y = GraphPPL.proxylabel(:x, x, nothing, GraphPPL.False()))

save_expression_in_tilde(expr::Expr)

Save the expression found in the tilde syntax in the created_by field of the expression. This function also ensures that the where clause is always present in the tilde syntax.

convert_meta_object(e::Expr)

Converts a variable meta or a factor meta call on the left hand side of a meta specification to a GraphPPL.MetaObject.

Arguments

• e::Expr: The expression to convert.

Returns

• Expr: The resulting expression with the variable reference or factor function call converted to a GraphPPL.MetaObject.

Examples

get_boilerplate_functions(ms_name, ms_args, num_interfaces)

Returns a quote block containing boilerplate functions for a model macro.

Arguments

• ms_name: The name of the model macro.
• ms_args: The arguments of the model macro.
• num_interfaces: The number of interfaces of the model macro.

Returns

• quote: A quote block containing the boilerplate functions for the model macro.

apply_pipeline_collection(e::Expr, collection)

Similar to apply_pipeline, but applies a collection of pipeline functions to an expression.

Arguments

• e::Expr: An expression to apply the pipeline to.
• collection: A collection of functions to apply to the expressions in e.

Returns

The result of applying the pipeline function to e.

convert_tilde_expression(e::Expr)

Converts a tilde expression to a make_node! call. Converts broadcasted tile expressions to make_node! calls with nothing as the lhs to indicate that a variable should be created on every broadcasted pass.

Arguments

• e::Expr: The expression to convert.

Returns

• Expr: The converted expression.

Examples

julia> convert_tilde_expression(:(x ~ Normal(0, 1) where {created_by = (x~Normal(0,1))}))
quote
    GraphPPL.make_node!(__model__, __context__, Normal, x, [0, 1]; options = Dict{Any, Any}(:created_by => :(x ~ Normal(0, 1))), debug = debug)
end

check_reserved_variable_names_model(expr::Expr)

Check if any of the variable names in the given expression are reserved in the model macro. Reserved variable names are:

• __parent_options__
• __debug__
• __model__
• __context__
• __parent_context__
• __lhs_interface__
• __rhs_interfaces__
• __interfaces__

Arguments

• expr::Expr: The expression to check for reserved variable names.

Examples

jldoctest julia> check_reserved_variable_names_model(:(__parent_options__ ~ Normal(μ, σ)) ERROR: Variable name in __parent_options__ ~ Normal(μ, σ) cannot be used as it is a reserved variable name in the model macro.`

generate_get_or_create(s::Symbol, lhs::Symbol, index::Nothing)

Generates code to get or create a variable in the graph. This function is used to generate code for variables that are not indexed.

Arguments

• s::Symbol: The symbol representing the variable.
• index::Nothing: The index of the variable. This argument is always nothing.

Returns

A quote block with the code to get or create the variable in the graph.

generate_get_or_create(s::Symbol, lhs::Expr, index::AbstractArray)

Generates code to get or create a variable in the graph. This function is used to generate code for variables that are indexed.

Arguments

• s::Symbol: The symbol representing the variable.
• index::AbstractArray: The index of the variable.

Returns

A quote block with the code to get or create the variable in the graph.

add_meta_construction(e::Expr)

Add a meta construction to the given expression e. This function creates a new GraphPPL.MetaSpecification object and assigns it to the __meta__ variable. It then evaluates the given expression e in the context of this new GraphPPL.MetaSpecification object, and returns the resulting GraphPPL.MetaSpecification object.

Arguments

• e::Expr: The expression to evaluate in the context of the new GraphPPL.MetaSpecification object.

Returns

• e::Expr: The expression that will generate the GraphPPL.MetaSpecification object.

apply_pipeline(e::Expr, pipeline)

Apply a pipeline function to an expression.

The apply_pipeline function takes an expression e and a pipeline function and applies the function in the pipeline to e when walking over it. The walk utilized can be specified by implementing what_walk for a pipeline funciton.

Arguments

• e::Expr: An expression to apply the pipeline to.
• pipeline: A function to apply to the expressions in e.

Returns

The result of applying the pipeline function to e.

options_vector_to_named_tuple(options::AbstractArray)

Converts the array found by pattern matching on the where clause in a tilde expression into a named tuple.

Arguments

• options::AbstractArray: An array of options.

Returns

• result: A named tuple of options.

get_created_by(options::AbstractArray)

Retrieve the created_by option from the given options. Expects the options to be retrieved using the MacroTools.@capture macro.

convert_to_anonymous(e::Expr, created_by)

Convert an expression to an anonymous variable. This function is used to convert function calls in the arguments of node creations to anonymous variables in the graph.

prune!(m::Model)

Remove all nodes from the model that are not connected to any other node.