Improve constructors and reflect them in tests

Author: gdalle

src/dict_utils.jl

@@ -120,7 +120,3 @@ function _copy_props!(old_meta_graph::MetaGraph, new_meta_graph::MetaGraph, code
     end
     return nothing
 end
-
-# TODO - It would be nice to be able to apply a function to properties.
-# Not sure how this might work, but if the property is a vector,
-# a generic way to append to it would be a good thing.

src/metagraph.jl

@@ -16,12 +16,12 @@ Vertex labels have type `Label`, while vertex (resp. edge, resp. graph) metadata
 It is recommended not to set `Label` to an integer type, so as to avoid confusion between vertex labels and vertex codes (which have type `Code<:Integer`).
 
 # Fields
-- `graph::Graph`: underlying, data-less graph with vertex indices of type `Code`
+- `graph::Graph`: underlying, data-less graph with vertex codes of type `Code`
 - `vertex_labels::Dict{Code,Label}`: dictionary mapping vertex codes to vertex labels
-- `vertex_properties::Dict{Label,Tuple{Code,VertexData}}`: dictionary mapping vertex labels to vertex codes & data
-- `edge_data::Dict{Tuple{Label,Label},EdgeData}`: dictionary mapping edge labels such as `(label_u, label_v)` to edge data
-- `graph_data::GraphData`: global data for the graph object
-- `weight_function::WeightFunction`: function computing edge weight from edge data, its output must have the same type as `default_weight`
+- `vertex_properties::Dict{Label,Tuple{Code,VertexData}}`: dictionary mapping vertex labels to vertex codes & metadata
+- `edge_data::Dict{Tuple{Label,Label},EdgeData}`: dictionary mapping edge labels such as `(label_u, label_v)` to edge metadata
+- `graph_data::GraphData`: metadata for the graph object as a whole
+- `weight_function::WeightFunction`: function computing edge weight from edge metadata, its output must have the same type as `default_weight`
 - `default_weight::Weight`: default weight used when an edge doesn't exist
 """
 struct MetaGraph{
@@ -46,48 +46,32 @@ end
 """
     MetaGraph(
         graph,
-        vertices_description,
-        edges_description,
+        label_type,
+        vertex_data_type=Nothing,
+        edge_data_type=Nothing,
         graph_data=nothing,
         weight_function=edge_data -> 1.0,
-        default_weight=1.0,
+        default_weight=1.0
     )
 
-Construct a non-empty `MetaGraph` based on lists of vertices and edges with their labels and data.
-
-These lists must be constructed as follows:
-- `vertices_description` is a vector of pairs `label => data` (the code of a vertex will correspond to its rank in the list)
-- `edges_description` is a vector of pairs `(label1, label2) => data`
-
-Furthermore, they must be coherent with the `graph` argument, i.e. describe the same set of vertices and edges.
+Construct an empty `MetaGraph` based on an empty `graph`, initializing storage with the given metadata types *as positional arguments*.
 """
 function MetaGraph(
     graph::AbstractGraph{Code},
-    vertices_description::Vector{Pair{Label,VertexData}},
-    edges_description::Vector{Pair{Tuple{Label,Label},EdgeData}},
+    label_type::Type{Label},
+    vertex_data_type::Type{VertexData}=Nothing,
+    edge_data_type::Type{EdgeData}=Nothing,
     graph_data=nothing,
     weight_function=edge_data -> 1.0,
     default_weight=1.0,
 ) where {Code,Label,VertexData,EdgeData}
-    # Construct vertex data
-    @assert length(vertices_description) == nv(graph)
+    @assert nv(graph) == 0
+    if Label <: Integer
+        @warn "Constructing a MetaGraph with integer labels is not advised."
+    end
     vertex_labels = Dict{Code,Label}()
     vertex_properties = Dict{Label,Tuple{Code,VertexData}}()
-    for (code, (label, data)) in enumerate(vertices_description)
-        vertex_labels[code] = label
-        vertex_properties[label] = (code, data)
-    end
-    # Construct edge data
-    @assert length(edges_description) == ne(graph)
-    for ((label_1, label_2), _) in edges_description
-        code_1 = vertex_properties[label_1][1]
-        code_2 = vertex_properties[label_2][1]
-        @assert has_edge(graph, code_1, code_2)
-    end
     edge_data = Dict{Tuple{Label,Label},EdgeData}()
-    for ((label_1, label_2), data) in edges_description
-        edge_data[label_1, label_2] = data
-    end
     return MetaGraph(
         graph,
         vertex_labels,
@@ -102,35 +86,84 @@ end
 """
     MetaGraph(
         graph;
-        Label=Symbol,
-        VertexData=Nothing,
-        EdgeData=Nothing,
+        label_type,
+        vertex_data_type=Nothing,
+        edge_data_type=Nothing,
         graph_data=nothing,
         weight_function=edge_data -> 1.0,
         default_weight=1.0
     )
 
-Construct an empty `MetaGraph` with the given metadata types and weights.
+Construct an empty `MetaGraph` based on an empty `graph`, initializing storage with the given metadata types *as keyword arguments*.
 
-!!! danger "Warning"
-    This constructor is not type-stable, it is only there for convenience.
+!!! warning "Warning"
+    This constructor uses keyword arguments for convenience, which means it is type-unstable.
 """
 function MetaGraph(
-    graph::AbstractGraph{Code};
-    Label=Symbol,
-    VertexData=Nothing,
-    EdgeData=Nothing,
+    graph;
+    label_type,
+    vertex_data_type=Nothing,
+    edge_data_type=Nothing,
     graph_data=nothing,
     weight_function=edge_data -> 1.0,
     default_weight=1.0,
-) where {Code}
-    @assert nv(graph) == 0
-    if Label <: Integer
-        @warn "Constructing a MetaGraph with integer labels is not advised."
-    end
+)
+    return MetaGraph(
+        graph,
+        label_type,
+        vertex_data_type,
+        edge_data_type,
+        graph_data,
+        weight_function,
+        default_weight,
+    )
+end
+
+"""
+    MetaGraph(
+        graph,
+        vertices_description,
+        edges_description,
+        graph_data=nothing,
+        weight_function=edge_data -> 1.0,
+        default_weight=1.0,
+    )
+
+Construct a non-empty `MetaGraph` based on a non-empty `graph` with specified vertex and edge data.
+
+The data must be given as follows:
+- `vertices_description` is a vector of pairs `label => data` (the code of a vertex will correspond to its rank in the list)
+- `edges_description` is a vector of pairs `(label1, label2) => data`
+
+Furthermore, these arguments must be coherent with the `graph` argument, i.e. describe the same set of vertices and edges.
+"""
+function MetaGraph(
+    graph::AbstractGraph{Code},
+    vertices_description::Vector{Pair{Label,VertexData}},
+    edges_description::Vector{Pair{Tuple{Label,Label},EdgeData}},
+    graph_data=nothing,
+    weight_function=edge_data -> 1.0,
+    default_weight=1.0,
+) where {Code,Label,VertexData,EdgeData}
+    # Construct vertex data
+    @assert length(vertices_description) == nv(graph)
     vertex_labels = Dict{Code,Label}()
     vertex_properties = Dict{Label,Tuple{Code,VertexData}}()
+    for (code, (label, data)) in enumerate(vertices_description)
+        vertex_labels[code] = label
+        vertex_properties[label] = (code, data)
+    end
+    # Construct edge data
+    @assert length(edges_description) == ne(graph)
+    for ((label_1, label_2), _) in edges_description
+        code_1 = vertex_properties[label_1][1]
+        code_2 = vertex_properties[label_2][1]
+        @assert has_edge(graph, code_1, code_2)
+    end
     edge_data = Dict{Tuple{Label,Label},EdgeData}()
+    for ((label_1, label_2), data) in edges_description
+        edge_data[label_1, label_2] = data
+    end
     return MetaGraph(
         graph,
         vertex_labels,
@@ -151,3 +184,18 @@ function Base.show(
     )
     return nothing
 end
+
+function Base.:(==)(meta_graph_1::MetaGraph, meta_graph_2::MetaGraph)
+    return (
+        (meta_graph_1.graph == meta_graph_2.graph) &&
+        (meta_graph_1.vertex_labels == meta_graph_2.vertex_labels) &&
+        (meta_graph_1.vertex_properties == meta_graph_2.vertex_properties) &&
+        (meta_graph_1.edge_data == meta_graph_2.edge_data) &&
+        (meta_graph_1.graph_data == meta_graph_2.graph_data) &&
+        all(
+            meta_graph_1.weight_function(ed) == meta_graph_2.weight_function(ed) for
+            ed in meta_graph_1.edge_data
+        ) &&
+        (meta_graph_1.default_weight == meta_graph_2.default_weight)
+    )
+end

test/labels_codes_directedness.jl

@@ -1,6 +1,10 @@
 # undirected MetaGraph
 colors = MetaGraph(
-    Graph(); VertexData=String, EdgeData=Symbol, graph_data="graph_of_colors"
+    Graph();
+    label_type=Symbol,
+    vertex_data_type=String,
+    edge_data_type=Symbol,
+    graph_data="graph_of_colors",
 )
 @test istrait(IsDirected{typeof(colors)}) == is_directed(colors) == false
 labels = [:red, :yellow, :blue]
@@ -22,7 +26,11 @@ end
 
 # directed MetaGraph
 dcolors = MetaGraph(
-    SimpleDiGraph(); VertexData=String, EdgeData=Symbol, graph_data="graph_of_colors"
+    SimpleDiGraph();
+    label_type=Symbol,
+    vertex_data_type=String,
+    edge_data_type=Symbol,
+    graph_data="graph_of_colors",
 )
 @test istrait(IsDirected{typeof(dcolors)}) == is_directed(dcolors) == true
 labels = [:red, :yellow, :blue]

test/tutorial/1_basics.jl

@@ -6,17 +6,31 @@ using Test  #src
 
 # ## Creating a `MetaGraph`
 
-# We provide a default constructor which looks as follows:
+# We provide a convenience constructor for creating empty graphs, which looks as follows:
 
 colors = MetaGraph(
     Graph();  # underlying graph structure
-    Label=Symbol,  # color name
-    VertexData=NTuple{3,Int},  # RGB code
-    EdgeData=String,  # result of the addition between two colors
+    label_type=Symbol,  # color name
+    vertex_data_type=NTuple{3,Int},  # RGB code
+    edge_data_type=String,  # result of the addition between two colors
     graph_data="additive colors",  # tag for the whole graph
 )
 
-# The `Label` type defines how vertices will be referred to, it can be anything but an integer type (to avoid confusion with codes, see below). The `VertexData` and `EdgeData` type determine what kind of data will be associated with each vertex and edge. Finally, `graph_data` can contain an arbitrary object associated with the graph as a whole.
+# The `label_type` argument defines how vertices will be referred to, it can be anything but an integer type (to avoid confusion with codes, see below). The `vertex_data_type` and `edge_data_type` type determine what kind of data will be associated with each vertex and edge. Finally, `graph_data` can contain an arbitrary object associated with the graph as a whole.
+
+# However, since this constructor receives types as keyword arguments, it is type-unstable. Casual users may not care, but if your goal is performance, you should use the following syntax instead, which relies on positional arguments.
+
+colors_stable = MetaGraph(Graph(), Symbol, NTuple{3,Int}, String, "additive colors")
+
+@test @inferred MetaGraph(  #src
+    Graph(),  #src
+    Symbol,  #src
+    NTuple{3,Int},  #src
+    String,  #src
+    "additive colors",  #src
+) == colors_stable  #src
+
+# Be careful with the order!
 
 # ## Modifying the graph
 
@@ -47,13 +61,13 @@ colors[:green, :blue] = "cyan";
 # To check the presence of a vertex or edge, use `haskey`:
 
 haskey(colors, :red)
-@test haskey(colors, :red)  #src
+@test @inferred haskey(colors, :red)  #src
 #-
 haskey(colors, :black)
 @test !haskey(colors, :black)  #src
 #-
 haskey(colors, :red, :green) && haskey(colors, :green, :red)
-@test haskey(colors, :red, :green) && haskey(colors, :green, :red)  #src
+@test (@inferred haskey(colors, :red, :green)) && haskey(colors, :green, :red)  #src
 #-
 !haskey(colors, :red, :black)
 @test !haskey(colors, :red, :black)  #src
@@ -63,28 +77,28 @@ haskey(colors, :red, :green) && haskey(colors, :green, :red)
 # All kinds of metadata can be accessed with `getindex`:
 
 colors[]
-@test colors[] == "additive colors"  #src
+@test @inferred colors[] == "additive colors"  #src
 #-
 colors[:blue]
-@test colors[:blue] == (0, 0, 255)  #src
+@test @inferred colors[:blue] == (0, 0, 255)  #src
 #-
 colors[:green, :blue]
-@test colors[:green, :blue] == "cyan"  #src
+@test @inferred colors[:green, :blue] == "cyan"  #src
 
 # ## Using vertex codes
 
 # In the absence of removal, vertex codes correspond to order of insertion in the underlying graph. They are the ones used by most algorithms in the Graphs.jl ecosystem.
 
 code_for(colors, :red)
-@test code_for(colors, :red) == 1  #src
+@test @inferred code_for(colors, :red) == 1  #src
 #-
 code_for(colors, :blue)
 @test code_for(colors, :blue) == 3  #src
 
 # You can retrieve the associated labels as follows:
 
 label_for(colors, 1)
-@test label_for(colors, 1) == :red  #src
+@test @inferred label_for(colors, 1) == :red  #src
 #-
 label_for(colors, 3)
 @test label_for(colors, 3) == :blue  #src
@@ -93,32 +107,35 @@ label_for(colors, 3)
 
 # The most simple way to add edge weights is to speficy a default weight for all of them.
 
-weighted_default = MetaGraph(Graph(); default_weight=2);
+weighted_default = MetaGraph(Graph(); label_type=Symbol, default_weight=2);
 #-
 default_weight(weighted_default)
-@test default_weight(weighted_default) == 2  #src
+@test @inferred default_weight(weighted_default) == 2  #src
 #-
 weighttype(weighted_default)
-@test weighttype(weighted_default) == Int  #src
+@test @inferred weighttype(weighted_default) == Int  #src
 
 # You can use the `weight_function` keyword to specify a function which will transform edge metadata into a weight. This weight must always be the same type as the `default_weight`.
 
-weighted = MetaGraph(Graph(); EdgeData=Float64, weight_function=ed -> ed^2);
+weighted = MetaGraph(
+    Graph(); label_type=Symbol, edge_data_type=Float64, weight_function=ed -> ed^2
+);
 
 weighted[:alice] = nothing;
 weighted[:bob] = nothing;
 weighted[:alice, :bob] = 2.0;
 #-
 weight_matrix = Graphs.weights(weighted)
+@test @inferred Graphs.weights(weighted) == weight_matrix
 #-
 size(weight_matrix)
 @test size(weight_matrix) == (2, 2)  #src
 #-
 weight_matrix[1, 2]
-@test weight_matrix[1, 2] ≈ 4.0  #src
+@test @inferred weight_matrix[1, 2] ≈ 4.0  #src
 #-
 wf = get_weight_function(weighted)
 wf(3)
-@test wf(3) == 9  #src
+@test @inferred wf(3) == 9  #src
 
 # You can then use all functions from Graphs.jl that require weighted graphs (see the rest of the tutorial).