Merge pull request #260 from ReactiveBayes/node_id

Add node ID plugin and rename node tag plugin

Author: bvdmitri

Project.toml

@@ -1,7 +1,7 @@
 name = "GraphPPL"
 uuid = "b3f8163a-e979-4e85-b43e-1f63d8c8b42c"
 authors = ["Wouter Nuijten <[email protected]>", "Dmitry Bagaev <[email protected]>"]
-version = "4.4.1"
+version = "4.5.0"
 
 [deps]
 BitSetTuples = "0f2f92aa-23a3-4d05-b791-88071d064721"

docs/make.jl

@@ -6,30 +6,11 @@ makedocs(
     modules  = [GraphPPL],
     clean    = true,
     sitename = "GraphPPL.jl",
-    pages    = [
-        "Home" => "index.md", 
-        "Getting Started" => "getting_started.md", 
-        "Syntax Guide" => "syntax_guide.md",
-        "Nested Models" => "nested_models.md", 
-        "Plugins" => [
-            "Overview" => "plugins/overview.md",
-            "Variational Inference & Constraints" => "plugins/constraint_specification.md",
-            "Attaching metadata to nodes" => "plugins/meta_specification.md",
-            "Tracking creation of nodes" => "plugins/created_by.md",
-            "Setting ID of nodes" => "plugins/node_id.md",
-        ], 
-        "Migration Guide (from v3 to v4)" => "migration_3_to_4.md", 
-        "Developers Guide" => "developers_guide.md", 
-        "Custom backend" => "custom_backend.md"
-    ],
+    pages    = ["Home" => "index.md", "Getting Started" => "getting_started.md", "Syntax Guide" => "syntax_guide.md", "Nested Models" => "nested_models.md", "Plugins" => ["Overview" => "plugins/overview.md", "Variational Inference & Constraints" => "plugins/constraint_specification.md", "Attaching metadata to nodes" => "plugins/meta_specification.md", "Tracking creation of nodes" => "plugins/created_by.md", "Setting tag of nodes" => "plugins/node_tag.md", "Setting ID of nodes" => "plugins/node_id.md"], "Migration Guide (from v3 to v4)" => "migration_3_to_4.md", "Developers Guide" => "developers_guide.md", "Custom backend" => "custom_backend.md"],
     format   = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
     warnonly = false
 )
 
 if get(ENV, "CI", nothing) == "true"
-    deploydocs(
-        repo = "github.com/ReactiveBayes/GraphPPL.jl.git",
-        devbranch = "main", 
-        forcepush = true
-    )
+    deploydocs(repo = "github.com/ReactiveBayes/GraphPPL.jl.git", devbranch = "main", forcepush = true)
 end

docs/src/plugins/node_id.md

@@ -6,14 +6,14 @@ GraphPPL provides a built-in plugin to mark factor nodes with a specific ID for
 GraphPPL.NodeIdPlugin
 ```
 
-The plugin allows to specify the `id` in the `where { ... }` block during the node construction. Here how it works:
+The plugin sets a field in the `GraphPPL.NodeData` for every factor node that acts as a unique identified. Here how it works:
 
 ```@example plugin-node-id
 using GraphPPL, Distributions, Test #hide
 import GraphPPL: @model #hide
 
 @model function submodel(y, x, z)
-    y ~ Normal(x, z) where { id = "from submodel" }
+    y ~ Normal(x, z)
 end
 
 @model function mainmodel() 
@@ -23,7 +23,7 @@ end
 end
 ```
 
-In this example we have created three `Normal` factor nodes and would like to access the one which has been created within the `submodel`.
+In this example we have created three `Normal` factor nodes and would like to discern between them using only the `NodeData`.
 To do that, we need to instantiate our model with the [`GraphPPL.NodeIdPlugin`](@ref) plugin.
 
 ```@example plugin-node-id
@@ -36,18 +36,12 @@ model = GraphPPL.create_model(
 nothing #hide
 ```
 
-After, we can fetch all the nodes with a specific id using the [`GraphPPL.by_nodeid`](@ref) function.
-
-```@docs
-GraphPPL.by_nodeid
-```
+After, we can fetch all the node ids.
 
 ```@example plugin-node-id
-labels = collect(filter(GraphPPL.by_nodeid("from submodel"), model))
-@test all(label -> GraphPPL.getname(label) == Normal, labels) #hide
-@test length(labels) === 1 #hide
+labels = collect(filter(GraphPPL.as_node(), model))
 foreach(labels) do label
-    println(GraphPPL.getname(label))
+    println(GraphPPL.getextra(model[label], :id))
 end
 nothing #hide
 ```

docs/src/plugins/node_tag.md

@@ -0,0 +1,53 @@
+# [Node tag plugin](@id plugins-node-tag)
+
+GraphPPL provides a built-in plugin to mark factor nodes with a specific tag for later analysis or debugging purposes.
+
+```@docs 
+GraphPPL.NodeTagPlugin
+```
+
+The plugin allows to specify the `tag` in the `where { ... }` block during the node construction. Here how it works:
+
+```@example plugin-node-tag
+using GraphPPL, Distributions, Test #hide
+import GraphPPL: @model #hide
+
+@model function submodel(y, x, z)
+    y ~ Normal(x, z) where { tag = "from submodel" }
+end
+
+@model function mainmodel() 
+    x ~ Normal(0.0, 1.0)
+    z ~ Normal(0.0, 1.0)
+    y ~ submodel(x = x, z = z)
+end
+```
+
+In this example we have created three `Normal` factor nodes and would like to access the one which has been created within the `submodel`.
+To do that, we need to instantiate our model with the [`GraphPPL.NodeTagPlugin`](@ref) plugin.
+
+```@example plugin-node-tag
+model = GraphPPL.create_model(
+    GraphPPL.with_plugins(
+        mainmodel(),
+        GraphPPL.PluginsCollection(GraphPPL.NodeTagPlugin())
+    )
+)
+nothing #hide
+```
+
+After, we can fetch all the nodes with a specific tag using the [`GraphPPL.by_nodetag`](@ref) function.
+
+```@docs
+GraphPPL.by_nodetag
+```
+
+```@example plugin-node-tag
+labels = collect(filter(GraphPPL.by_nodetag("from submodel"), model))
+@test all(label -> GraphPPL.getname(label) == Normal, labels) #hide
+@test length(labels) === 1 #hide
+foreach(labels) do label
+    println(GraphPPL.getname(label))
+end
+nothing #hide
+```

docs/src/plugins/overview.md

@@ -19,7 +19,8 @@ The following plugins are available by default in `GraphPPL`:
 - [`GraphPPL.VariationalConstraintsPlugin`](@ref): adds [constraints](@ref constraints-specification) to the model that are used in variational inference.
 - [`GraphPPL.MetaPlugin`](@ref): adds arbitrary metadata to nodes in the model.
 - [`GraphPPL.NodeCreatedByPlugin`](@ref): adds information about the line of code that created the node. 
-- [`GraphPPL.NodeIdPlugin`](@ref): allows attaching an `id` to factor nodes for later inspection.
+- [`GraphPPL.NodeTagPlugin`](@ref): allows attaching a `tag` to factor nodes for later inspection.
+- [`GraphPPL.NodeIdPlugin`](@ref): allows attaching a unique `id` to factor nodes for later inspection.
 
 ## Using a plugin
 

src/GraphPPL.jl

@@ -11,6 +11,7 @@ include("model_macro.jl")
 
 include("plugins/node_created_by.jl")
 include("plugins/node_id.jl")
+include("plugins/node_tag.jl")
 include("plugins/variational_constraints/variational_constraints.jl")
 include("plugins/meta/meta.jl")
 

src/graph_engine.jl

@@ -255,7 +255,6 @@ Base.broadcastable(label::NodeLabel) = Ref(label)
 
 getname(label::NodeLabel) = label.name
 getname(labels::ResizableArray{T, V, N} where {T <: NodeLabel, V, N}) = getname(first(labels))
-getid(label::NodeLabel) = label.global_counter
 iterate(label::NodeLabel) = (label, nothing)
 iterate(label::NodeLabel, any) = nothing
 
@@ -766,10 +765,9 @@ mutable struct NodeData
     const context    :: Context
     const properties :: Union{VariableNodeProperties, FactorNodeProperties{NodeData}}
     const extra      :: UnorderedDictionary{Symbol, Any}
-    const id         :: Int
 end
 
-NodeData(context, properties, id) = NodeData(context, properties, UnorderedDictionary{Symbol, Any}(), id)
+NodeData(context, properties) = NodeData(context, properties, UnorderedDictionary{Symbol, Any}())
 
 function Base.show(io::IO, nodedata::NodeData)
     context = getcontext(nodedata)
@@ -1531,7 +1529,7 @@ end
 function __add_variable_node!(model::Model, context::Context, options::NodeCreationOptions, name::Symbol, index)
     # In theory plugins are able to overwrite this
     potential_label = generate_nodelabel(model, name)
-    potential_nodedata = NodeData(context, convert(VariableNodeProperties, name, index, options), getid(potential_label))
+    potential_nodedata = NodeData(context, convert(VariableNodeProperties, name, index, options))
     label, nodedata = preprocess_plugins(
         UnionPluginType(VariableNodePlugin(), FactorAndVariableNodesPlugin()), model, context, potential_label, potential_nodedata, options
     )
@@ -1645,7 +1643,7 @@ function add_atomic_factor_node!(model::Model, context::Context, options::NodeCr
     factornode_id = generate_factor_nodelabel(context, fform)
 
     potential_label = generate_nodelabel(model, fform)
-    potential_nodedata = NodeData(context, convert(FactorNodeProperties, fform, options), getid(potential_label))
+    potential_nodedata = NodeData(context, convert(FactorNodeProperties, fform, options))
 
     label, nodedata = preprocess_plugins(
         UnionPluginType(FactorNodePlugin(), FactorAndVariableNodesPlugin()), model, context, potential_label, potential_nodedata, options

src/plugins/node_id.jl

@@ -1,8 +1,7 @@
 """
     NodeIdPlugin
 
-A plugin that adds an `id` property to the factor node. This field can be used to
-find a node given its `id` with the `GraphPPL.by_nodeid` filter.
+A plugin that adds an `id` property to the factor node. This field is unique for every factor node.
 """
 struct NodeIdPlugin end
 
@@ -11,23 +10,6 @@ plugin_type(::NodeIdPlugin) = FactorAndVariableNodesPlugin()
 function preprocess_plugin(
     ::NodeIdPlugin, model::Model, context::Context, label::NodeLabel, nodedata::NodeData, options::NodeCreationOptions
 )
-    if haskey(options, :id)
-        setextra!(nodedata, :id, getindex(options, :id))
-    end
+    setextra!(nodedata, :id, label.global_counter)
     return label, nodedata
 end
-
-struct FilterById <: AbstractModelFilterPredicate
-    id
-end
-
-"""
-    by_nodeid(id)
-
-A filter predicate that can be used to find a node given its `id` in a model.
-"""
-by_nodeid(id) = FilterById(id)
-
-function apply(predicate::FilterById, model, something)
-    return hasextra(model[something], :id) && isequal(getextra(model[something], :id), predicate.id)
-end

src/plugins/node_tag.jl

@@ -0,0 +1,33 @@
+"""
+    NodeTagPlugin
+
+A plugin that adds an `tag` property to the factor node. This field can be used to
+find a node given its `tag` with the `GraphPPL.by_nodetag` filter.
+"""
+struct NodeTagPlugin end
+
+plugin_type(::NodeTagPlugin) = FactorAndVariableNodesPlugin()
+
+function preprocess_plugin(
+    ::NodeTagPlugin, model::Model, context::Context, label::NodeLabel, nodedata::NodeData, options::NodeCreationOptions
+)
+    if haskey(options, :tag)
+        setextra!(nodedata, :tag, getindex(options, :tag))
+    end
+    return label, nodedata
+end
+
+struct FilterByTag <: AbstractModelFilterPredicate
+    tag
+end
+
+"""
+    by_nodetag(tag)
+
+A filter predicate that can be used to find a node given its `tag` in a model.
+"""
+by_nodetag(tag) = FilterByTag(tag)
+
+function apply(predicate::FilterByTag, model, something)
+    return hasextra(model[something], :tag) && isequal(getextra(model[something], :tag), predicate.tag)
+end

test/graph_construction_tests.jl

@@ -2002,4 +2002,4 @@ end
     @test length(collect(filter(as_node(Normal), model))) == 2
     @test length(collect(filter(as_variable(:y), model))) == 1
     @test length(collect(filter(as_variable(:x), model))) == 1
-end
+end