many addition to the graph interface

Author: CarloLucibello

README.md

@@ -5,18 +5,21 @@
 ![](https://github.com/CarloLucibello/GraphNeuralNetworks.jl/actions/workflows/ci.yml/badge.svg)
 [![codecov](https://codecov.io/gh/CarloLucibello/GraphNeuralNetworks.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/CarloLucibello/GraphNeuralNetworks.jl)
 
-A graph neural network library for Julia based on the deep learning framework [Flux.jl](https://github.com/FluxML/Flux.jl). Its features include:
+GraphNeuralNetworks.jl is a graph neural network library written in Julia and based on the deep learning framework [Flux.jl](https://github.com/FluxML/Flux.jl).
 
-* Integration with [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl).
-* Implementation of common graph convolutional layers.
-* Fast operations on batched graphs. 
+Among its features:
+
+* Implements common graph convolutional layers.
+* Supports computations on batched graphs. 
 * Easy to define custom layers.
+* Integration with the JuliaGraphs ecosystem.
 * CUDA support.
+* Integration with [Graph.jl](https://github.com/JuliaGraphs/Graphs.jl).
+* [Examples](https://github.com/CarloLucibello/GraphNeuralNetworks.jl/tree/master/examples) of node, edge, and graph level machine learning tasks. 
 
 ## Installation
 
-GraphNeuralNetworks.jl is a registered julia package. 
-You can easily install it through the package manager:
+GNN.jl is a registered julia package. You can easily install it through the package manager:
 
 ```julia
 pkg> add GraphNeuralNetworks
@@ -26,6 +29,9 @@ pkg> add GraphNeuralNetworks
 
 Usage examples can be found in the [examples](https://github.com/CarloLucibello/GraphNeuralNetworks.jl/tree/master/examples) folder. Also, make sure to read the [documentation](https://CarloLucibello.github.io/GraphNeuralNetworks.jl/dev) for a comprehensive introduction to the library.
 
-## Acknowledgements
+## Acknowledgments
+
+GNN.jl is largely inspired by [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/),[Deep Graph Library](https://docs.dgl.ai/),
+and [GeometricFlux.jl](https://fluxml.ai/GeometricFlux.jl/stable/).
+
 
-A big thanks goes to @yuehhua for creating [GeometricFlux.jl](https://github.com/FluxML/GeometricFlux.jl) of which GraphNeuralNetworks.jl is a radical redesign. 

docs/src/gnngraph.md

@@ -138,14 +138,6 @@ g′ = remove_self_loops(g)
 g′ = add_edges(g, [1, 2], [2, 3]) # add edges 1->2 and 2->3
 ```
 
-## JuliaGraphs ecosystem integration
-
-Since `GNNGraph <: Graphs.AbstractGraph`, we can use any functionality from Graphs.jl. 
-
-```julia
-@assert Graphs.isdirected(g)
-```
-
 ## GPU movement
 
 Move a `GNNGraph` to a CUDA device using `Flux.gpu` method. 
@@ -155,3 +147,35 @@ using Flux: gpu
 
 g_gpu = g |> gpu
 ```
+
+## JuliaGraphs/Graphs.jl integration
+
+Since `GNNGraph <: Graphs.AbstractGraph`, we can use any functionality from Graphs.jl. 
+Moreover, `GNNGraphs` can be constructed from `Graphs.Graph` and `Graphs.DiGraph`
+and viceversa.
+
+```julia
+julia> import Graphs
+
+julia> using GraphNeuralNetworks
+
+# A Graphs.jl undirected graph
+julia> gu = Graphs.erdos_renyi(10, 20)    
+{10, 20} undirected simple Int64 graph
+
+# Since GNNGraphs are undirected, the edges are doubled when converting 
+# to GNNGraph
+julia> GNNGraph(gu)  # Since GNNGraphs are 
+GNNGraph:
+    num_nodes = 10
+    num_edges = 40
+
+# A Graphs.jl directed graph
+julia> gd = Graphs.erdos_renyi(10, 20, is_directed=true)
+{10, 20} directed simple Int64 graph
+
+julia> GNNGraph(gd)
+GNNGraph:
+    num_nodes = 10
+    num_edges = 20
+```

docs/src/index.md

@@ -6,12 +6,13 @@ and [GeometricFlux.jl](https://fluxml.ai/GeometricFlux.jl/stable/).
 
 Among its features:
 
-* Integration with the JuliaGraphs ecosystem.
-* Implementation of common graph convolutional layers.
-* Fast operations on batched graphs. 
+* Implements common graph convolutional layers.
+* Supports computations on batched graphs. 
 * Easy to define custom layers.
+* Integration with the JuliaGraphs ecosystem.
 * CUDA support.
-* Examples of node-wise, edge-wise, and graph-wise machine learning tasks. 
+* Integration with [Graph.jl](https://github.com/JuliaGraphs/Graphs.jl).
+* [Examples](https://github.com/CarloLucibello/GraphNeuralNetworks.jl/tree/master/examples) of node, edge, and graph level machine learning tasks. 
 
 
 ## Package overview
@@ -45,7 +46,6 @@ GNNGraph:
     num_graphs = 1000
     ndata:
         x => (16, 10000)
-    edata:
     gdata:
         y => (1000,)
 ```

examples/link_prediction_pubmed.jl

@@ -1,10 +1,8 @@
 # An example of link prediction using negative and positive samples.
 # Ported from https://docs.dgl.ai/tutorials/blitz/4_link_predict.html#sphx-glr-tutorials-blitz-4-link-predict-py
+# See the comparison paper https://arxiv.org/pdf/2102.12557.pdf for more details
 
 using Flux
-# Link prediction task
-# https://arxiv.org/pdf/2102.12557.pdf
-
 using Flux: onecold, onehotbatch
 using Flux.Losses: logitbinarycrossentropy
 using GraphNeuralNetworks
@@ -24,19 +22,19 @@ Base.@kwdef mutable struct Args
     infotime = 10 	     # report every `infotime` epochs
 end
 
+# We define our own edge prediction layer but could also 
+# use GraphNeuralNetworks.DotDecoder instead.
 struct DotPredictor end
 
 function (::DotPredictor)(g, x)
     z = apply_edges((xi, xj, e) -> sum(xi .* xj, dims=1), g, xi=x, xj=x)
+    # z = apply_edges(xi_dot_xj, g, xi=x, xj=x) # Same with  buit-in methods
     return vec(z)
 end
 
-using ChainRulesCore
-
 function train(; kws...)
-    # args = Args(; kws...)
-    args = Args()
-
+    args = Args(; kws...)
+    
     args.seed > 0 && Random.seed!(args.seed)
 
     if args.usecuda && CUDA.functional()
@@ -50,10 +48,11 @@ function train(; kws...)
 
     ### LOAD DATA
     data = Cora.dataset()
+    # data = PubMed.dataset()
     g = GNNGraph(data.adjacency_list) |> device
+    @show is_bidirected(g)
     X = data.node_features |> device
 
-    
     #### SPLIT INTO NEGATIVE AND POSITIVE SAMPLES
     s, t = edge_index(g)
     eids = randperm(g.num_edges)
@@ -67,9 +66,11 @@ function train(; kws...)
 
     test_neg_g = negative_sample(g, num_neg_edges=test_size)
 
+
     ### DEFINE MODEL #########
     nin, nhidden = size(X,1), args.nhidden
 
+    # We embed the graph with positive training edges in the model 
     model = WithGraph(GNNChain(GCNConv(nin => nhidden, relu),
                                GCNConv(nhidden => nhidden)),
                       train_pos_g) |> device
@@ -84,7 +85,7 @@ function train(; kws...)
     function loss(pos_g, neg_g = nothing)
         h = model(X)
         if neg_g === nothing
-            # we sample a negative graph at each training step
+            # We sample a negative graph at each training step
             neg_g = negative_sample(pos_g)
         end
         pos_score = pred(pos_g, h)
@@ -93,15 +94,6 @@ function train(; kws...)
         labels = [fill!(similar(pos_score), 1); fill!(similar(neg_score), 0)]
         return logitbinarycrossentropy(scores, labels)
     end
-
-    # function accuracy(pos_g, neg_g)
-    #     h = model(train_pos_g, X)
-    #     pos_score = pred(pos_g, h)
-    #     neg_score = pred(neg_g, h)
-    #     scores = [pos_score; neg_score]
-    #     labels = [fill!(similar(pos_score), 1); fill!(similar(neg_score), 0)]
-    #     return logitbinarycrossentropy(scores, labels)
-    # end
 
     ### LOGGING FUNCTION
     function report(epoch)

examples/neural_ode.jl renamed to examples/neural_ode_cora.jl

@@ -16,29 +16,43 @@ using ChainRulesCore
 using LinearAlgebra, Random
 
 include("gnngraph.jl")
-export GNNGraph, node_features, edge_features, graph_features
+export GNNGraph, 
+       node_features, 
+       edge_features, 
+       graph_features
 
 include("query.jl")
-export  edge_index, adjacency_list, normalized_laplacian, scaled_laplacian,
-        graph_indicator
+export edge_index, 
+       adjacency_list, 
+       normalized_laplacian, 
+       scaled_laplacian,
+       graph_indicator, 
+       is_bidirected,
+       # from Graphs
+       adjacency_matrix, 
+       degree, 
+       outneighbors, 
+       inneighbors
 
 include("transform.jl")
-export add_nodes, add_edges, add_self_loops, remove_self_loops, getgraph,
-       negative_sample
+export add_nodes, 
+       add_edges, 
+       add_self_loops, 
+       remove_self_loops, 
+       remove_multi_edges,
+       getgraph,
+       negative_sample,
+       # from Flux
+       batch, 
+       unbatch,
+       # from SparseArrays
+       blockdiag
 
 include("generate.jl")
 export rand_graph
 
-
 include("convert.jl")
 include("utils.jl")
 
-export 
-    # from Graphs
-    adjacency_matrix, degree, outneighbors, inneighbors,
-    # from SparseArrays
-    sprand, sparse, blockdiag,
-    # from Flux
-    batch, unbatch
-
+    
 end #module

src/GNNGraphs/GNNGraphs.jl

@@ -19,11 +19,6 @@ julia> g = rand_graph(5, 4, bidirected=false)
 GNNGraph:
     num_nodes = 5
     num_edges = 4
-    num_graphs = 1
-    ndata:
-    edata:
-    gdata:
-
 
 julia> edge_index(g)
 ([1, 3, 3, 4], [5, 4, 5, 2])
@@ -33,11 +28,8 @@ julia> g = rand_graph(5, 4, edata=rand(16, 2))
 GNNGraph:
     num_nodes = 5
     num_edges = 4
-    num_graphs = 1
-    ndata:
     edata:
         e => (16, 4)
-    gdata:
 
 # Each edge has a reverse
 julia> edge_index(g)

src/GNNGraphs/generate.jl

@@ -195,19 +195,25 @@ end
 function Base.show(io::IO, g::GNNGraph)
     println(io, "GNNGraph:
     num_nodes = $(g.num_nodes)
-    num_edges = $(g.num_edges)
-    num_graphs = $(g.num_graphs)")
-    println(io, "    ndata:")
-    for k in keys(g.ndata)
-        println(io, "        $k => $(size(g.ndata[k]))")
+    num_edges = $(g.num_edges)")
+    g.num_graphs > 1 && println("num_graphs = $(g.num_graphs)")
+    if !isempty(g.ndata)
+        println(io, "    ndata:")
+        for k in keys(g.ndata)
+            println(io, "        $k => $(size(g.ndata[k]))")
+        end
     end
-    println(io, "    edata:")
-    for k in keys(g.edata)
-        println(io, "        $k => $(size(g.edata[k]))")
+    if !isempty(g.edata)
+        println(io, "    edata:")
+        for k in keys(g.edata)
+            println(io, "        $k => $(size(g.edata[k]))")
+        end
     end
-    println(io, "    gdata:")
-    for k in keys(g.gdata)
-        println(io, "        $k => $(size(g.gdata[k]))")
+    if !isempty(g.gdata)
+        println(io, "    gdata:")
+        for k in keys(g.gdata)
+            println(io, "        $k => $(size(g.gdata[k]))")
+        end
     end
 end
 

src/GNNGraphs/gnngraph.jl

@@ -229,6 +229,20 @@ function graph_features(g::GNNGraph)
     end
 end
 
+"""
+    is_bidirected(g::GNNGraph)
+
+Check if the directed graph `g` essentially corresponds
+to an undirected graph, i.e. if for each edge it also contains the 
+reverse edge. 
+"""
+function is_bidirected(g::GNNGraph)
+    s, t = edge_index(g)
+    s1, t1 = sort_edge_index(s, t)
+    s2, t2 = sort_edge_index(t, s)
+    all((s1 .== s2) .& (t1 .== t2))
+end
+
 @non_differentiable normalized_laplacian(x...)
 @non_differentiable normalized_adjacency(x...)
 @non_differentiable scaled_laplacian(x...)