Add node ID plugin and rename node tag plugin

Author: wouterwln

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.0"
+version = "4.4.2"
 
 [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/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

test/plugins/node_id_tests.jl

@@ -3,50 +3,35 @@
 
     import GraphPPL:
         NodeIdPlugin,
-        EmptyID,
         NodeCreationOptions,
         PluginsCollection,
         add_atomic_factor_node!,
         create_model,
         getcontext,
         hasextra,
         getextra,
-        by_nodeid
+        create_model,
+        with_plugins
 
     include("../testutils.jl")
-
-    model = create_test_model(plugins = PluginsCollection(NodeIdPlugin()))
+    @model function node_with_two_anonymous()
+        x[1] ~ Normal(0, 1)
+        y[1] ~ Normal(0, 1)
+        for i in 2:10
+            y[i] ~ Normal(0, 1)
+            x[i] ~ Normal(y[i - 1] + 1, y[i] + 1)
+        end
+    end
+    model = create_model(with_plugins(node_with_two_anonymous(), GraphPPL.PluginsCollection(NodeIdPlugin())))
     ctx = getcontext(model)
 
     @testset begin
-        label1, nodedata1, properties1 = add_atomic_factor_node!(model, ctx, NodeCreationOptions(id = 1), Normal)
-        label2, nodedata2, properties2 = add_atomic_factor_node!(model, ctx, NodeCreationOptions(id = "2"), Normal)
-        label3, nodedata3, properties3 = add_atomic_factor_node!(model, ctx, NodeCreationOptions(id = :id3), Normal)
-        label4, nodedata4, properties4 = add_atomic_factor_node!(model, ctx, NodeCreationOptions(), Normal)
-        label5, nodedata5, properties5 = add_atomic_factor_node!(model, ctx, NodeCreationOptions(id = 4), Normal)
-        label6, nodedata6, properties6 = add_atomic_factor_node!(model, ctx, NodeCreationOptions(id = 4), Normal)
-
-        @test length(collect(filter(as_node(Normal), model))) === 6
-        # Not all have the `id` label associated with them
-        @test !all(n -> hasextra(model[n], :id), collect(filter(as_node(Normal), model)))
-        # But at least some should have the `id` label associated with it
-        @test any(n -> hasextra(model[n], :id), collect(filter(as_node(Normal), model)))
-
-        # id = 1
-        @test length(collect(filter(by_nodeid(1), model))) === 1
-        @test model[first(collect(filter(by_nodeid(1), model)))] === nodedata1
-
-        # id = "2"
-        @test length(collect(filter(by_nodeid("2"), model))) === 1
-        @test model[first(collect(filter(by_nodeid("2"), model)))] === nodedata2
-
-        # id = :id3
-        @test length(collect(filter(by_nodeid(:id3), model))) === 1
-        @test model[first(collect(filter(by_nodeid(:id3), model)))] === nodedata3
+        nodes = collect(filter(as_node(), model))
+        nodedata = getindex.(Ref(model), nodes)
+        for node in nodedata
+            @test hasextra(node, :id)
+        end
 
-        # id = 4
-        @test length(collect(filter(by_nodeid(4), model))) === 2
-        @test model[collect(filter(by_nodeid(4), model))[1]] === nodedata5
-        @test model[collect(filter(by_nodeid(4), model))[2]] === nodedata6
+        @test length(unique(getextra.(nodedata, :id))) == length(nodedata)
     end
 end