Merge pull request #28 from CarloLucibello/cl/dev

some doc improve

Author: CarloLucibello

README.md

@@ -6,7 +6,7 @@
 [![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).
-Most relevant features are:
+Its most relevant features are:
 * Provides CUDA support.
 * It's integrated with the JuliaGraphs ecosystem.
 * Implements many common graph convolutional layers.

docs/src/gnngraph.md

@@ -1,98 +1,105 @@
 # Graphs
 
-TODO
+The fundamental graph type in GraphNeuralNetworks.jl is the [`GNNGraph`](@ref), 
+A GNNGraph `g` is a directed graph with nodes labeled from 1 to `g.num_nodes`.
+The underlying implementation allows for efficient application of graph neural network
+operators, gpu movement, and storage of node/edge/graph related feature arrays.
 
 ## Graph Creation
-
+A GNNGraph can be created from several different data sources encoding the graph topology:
 
 ```julia
 using GraphNeuralNetworks, LightGraphs, SparseArrays
 
 
-# From LightGraphs's graph
-lg_graph = erdos_renyi(10, 0.3)
-g = GNNGraph(lg_graph)
-
+# Construct GNNGraph from From LightGraphs's graph
+lg = erdos_renyi(10, 30)
+g = GNNGraph(lg)
 
-# From adjacency matrix
+# From an adjacency matrix
 A = sprand(10, 10, 0.3)
-
 g = GNNGraph(A)
 
-@assert adjacency_matrix(g) == A
-
-# From adjacency list
-adjlist = [[] [] [] ]
-
+# From an adjacency list
+adjlist = [[2,3], [1,3], [1,2,4], [3]]
 g = GNNGraph(adjlist)
 
-@assert sort.(adjacency_list(g)) == sort.(adjlist)
-
 # From COO representation
-source = []
-target = []
+source = [1,1,2,2,3,3,3,4]
+target = [2,3,1,3,1,2,4,3]
 g = GNNGraph(source, target)
-@assert edge_index(g) == (source, target)
 ```
 
-We have also seen some useful methods such as [`adjacency_matrix`](@ref) and [`edge_index`](@ref).
-
+See also the related methods [`adjacency_matrix`](@ref), [`edge_index`](@ref), and [`adjacency_list`](@ref).
 
 
 ## Data Features
 
 ```julia
-GNNGraph(erods_renyi(10,  30), ndata = (; X=rand(Float32, 32, 10)))
-# or equivalently
-GNNGraph(sprand(10, 0.3), ndata=rand(Float32, 32, 10))
+# Create a graph with a single feature array `x` associated to nodes
+g = GNNGraph(erdos_renyi(10,  30), ndata = (; x = rand(Float32, 32, 10)))
+# Equivalent definition
+g = GNNGraph(erdos_renyi(10,  30), ndata = rand(Float32, 32, 10))
+
+# You can have multiple feature arrays
+g = GNNGraph(erdos_renyi(10,  30), ndata = (; x=rand(Float32, 32, 10), y=rand(Float32, 10)))
+
 
-g = GNNGraph(sprand(10, 0.3), ndata = (X=rand(Float32, 32, 10), y=rand(Float32, 10)))
+# Attach an array with edge features
+g = GNNGraph(erdos_renyi(10,  30), edata = rand(Float32, 30))
 
-g = GNNGraph(g, edata=rand(Float32, 6, g.num_edges))
+# Create a new graph from previous one, inheriting edge data
+# but replacing node data
+g′ = GNNGraph(g, ndata =(; z = ones(Float32, 16, 10)))
 ```
 
 
 ## Graph Manipulation
 
 ```julia
-g = add_self_loops(g)
+g′ = add_self_loops(g)
 
-g = remove_self_loops(g)
+g′ = remove_self_loops(g)
 ```
 
 ## Batches and Subgraphs
 
 ```julia
 using Flux
 
-gall = Flux.batch([GNNGraph(erdos_renyi(10, 30), ndata=rand(3,10)) for _ in 1:100])
+gall = Flux.batch([GNNGraph(erdos_renyi(10, 30), ndata=rand(Float32,3,10)) for _ in 1:160])
 
-getgraph(gall, 2:3)
+g23 = getgraph(gall, 2:3)
+@assert g23.num_graphs == 16
+@assert g23.num_nodes == 32
+@assert g23.num_edges == 60
 
 
 # DataLoader compatibility
 train_loader = Flux.Data.DataLoader(gall, batchsize=16, shuffle=true)
 
-for g for gall
+for g in train_loader
     @assert g.num_graphs == 16
     @assert g.num_nodes == 160
-    @assert size(g.ndata.X) = (3, 160)    
+    @assert size(g.ndata.x) = (3, 160)    
     .....
 end
 ```
 
-## LightGraphs integration
+## JuliaGraphs ecosystem integration
+
+Since `GNNGraph <: LightGraphs.AbstractGraph`, we can use any functionality from LightGraphs. 
 
 ```julia
 @assert LightGraphs.isdirected(g)
 ```
 
 ## GPU movement
 
+Move a `GNNGraph` to a CUDA device using `Flux.gpu` method. 
+
 ```julia
 using Flux: gpu
 
-g |> gpu
+g_gpu = g |> gpu
 ```
-
-## Other methods

docs/src/index.md

@@ -1,7 +1,36 @@
 # GraphNeuralNetworks
 
-Documentation for [GraphNeuralNetworks](https://github.com/CarloLucibello/GraphNeuralNetworks.jl).
+This is the documentation page for the [GraphNeuralNetworks.jl](https://github.com/CarloLucibello/GraphNeuralNetworks.jl) library.
 
+A graph neural network library for Julia based on the deep learning framework [Flux.jl](https://github.com/FluxML/Flux.jl).
+Its most relevant features are:
+* Provides CUDA support.
+* It's integrated with the JuliaGraphs ecosystem.
+* Implements many common graph convolutional layers.
+* Performs fast operations on batched graphs. 
+* Makes it easy to define custom graph convolutional layers.
 
-## Getting Started
+
+
+
+## Package overview
+
+### Data preparation
+
+
+```
+using LightGraphs
+
+lg = LightGraphs.Graph(5) # create a light's graph graph
+add_edge!(g, 1, 2)
+add_edge!(g, 1, 3)
+add_edge!(g, 2, 4)
+add_edge!(g, 2, 5)
+add_edge!(g, 3, 4)
+
+g = GNNGraph(g)
+```
+### Model building 
+
+### Training 
 

docs/src/messagepassing.md

@@ -15,7 +15,7 @@ The message passing corresponds to the following operations
 \end{aligned}
 ```
 where ``\phi`` is expressed by the [`compute_message`](@ref) function, 
-``\gamma_x`` and ``\gamma_v`` by [`update_node`](@ref) and [`update_edge`](@ref)
+``\gamma_x`` and ``\gamma_e`` by [`update_node`](@ref) and [`update_edge`](@ref)
 respectively.
 
 See [`GraphConv`](ref) and [`GATConv`](ref)'s implementations as usage examples. 

examples/graph_classification_tudataset.jl

@@ -19,7 +19,7 @@ function eval_loss_accuracy(model, data_loader, device)
         g = g |> device
         n = g.num_graphs
         y = g.gdata.y
-        ŷ = model(g, g.ndata.X) |> vec
+        ŷ = model(g, g.ndata.x) |> vec
         loss += logitbinarycrossentropy(ŷ, y) * n 
         acc += mean((ŷ .> 0) .== y) * n
         ntot += n
@@ -30,16 +30,16 @@ end
 function getdataset()
     data = TUDataset("MUTAG")
 
-    X = Array{Float32}(onehotbatch(data.node_labels, 0:6))
+    x = Array{Float32}(onehotbatch(data.node_labels, 0:6))
     y = (1 .+ Array{Float32}(data.graph_labels)) ./ 2
     @assert all(∈([0,1]), y) # binary classification 
     # The dataset also has edge features but we won't be using them
-    E = Array{Float32}(onehotbatch(data.edge_labels, sort(unique(data.edge_labels))))
+    e = Array{Float32}(onehotbatch(data.edge_labels, sort(unique(data.edge_labels))))
 
     return GNNGraph(data.source, data.target, 
                 num_nodes=data.num_nodes, 
                 graph_indicator=data.graph_indicator,
-                ndata=(; X), edata=(; E), gdata=(; y))
+                ndata=(; x), edata=(; e), gdata=(; y))
 end
 
 # arguments for the `train` function 
@@ -83,7 +83,7 @@ function train(; kws...)
 
     # DEFINE MODEL
 
-    nin = size(gtrain.ndata.X, 1)
+    nin = size(gtrain.ndata.x, 1)
     nhidden = args.nhidden
 
     model = GNNChain(GraphConv(nin => nhidden, relu),
@@ -111,7 +111,7 @@ function train(; kws...)
         for g in train_loader
             g = g |> device
             gs = Flux.gradient(ps) do
-                ŷ = model(g, g.ndata.X) |> vec
+                ŷ = model(g, g.ndata.x) |> vec
                 logitbinarycrossentropy(ŷ, g.gdata.y)
             end
             Flux.Optimise.update!(opt, ps, gs)

examples/node_classification_cora.jl

@@ -62,7 +62,7 @@ function train(; kws...)
     ps = Flux.params(model)
     opt = ADAM(args.η)
 
-    @info "NUM NODES: $(g.num_nodes)  NUM EDGES: $(g.num_edges)"
+    @info g
 
     ## LOGGING FUNCTION
     function report(epoch)

src/gnngraph.jl

@@ -156,9 +156,9 @@ end
 
 function GNNGraph(g::GNNGraph; ndata=g.ndata, edata=g.edata, gdata=g.gdata)
 
-    ndata = normalize_graphdata(ndata, :X)
-    edata = normalize_graphdata(edata, :E)
-    gdata = normalize_graphdata(gdata, :U)
+    ndata = normalize_graphdata(ndata, :x)
+    edata = normalize_graphdata(edata, :e)
+    gdata = normalize_graphdata(gdata, :u)
 
     GNNGraph(g.graph, 
             g.num_nodes, g.num_edges, g.num_graphs, 

src/layers/conv.jl

@@ -143,7 +143,7 @@ Graph convolution layer from Reference: [Weisfeiler and Leman Go Neural: Higher-
 
 Performs:
 ```math
-\mathbf{x}_i' = W^1 \mathbf{x}_i + \square_{j \in \mathcal{N}(i)} W^2 \mathbf{x}_j)
+\mathbf{x}_i' = W_1 \mathbf{x}_i + \square_{j \in \mathcal{N}(i)} W_2 \mathbf{x}_j
 ```
 
 where the aggregation type is selected by `aggr`.

test/gnngraph.jl

@@ -143,24 +143,25 @@
         U = rand(10, g.num_graphs)
 
         g = GNNGraph(g, ndata=X, edata=E, gdata=U)
-        @test g.ndata.X === X
-        @test g.edata.E === E
-        @test g.gdata.U === U
+        @test g.ndata.x === X
+        @test g.edata.e === E
+        @test g.gdata.u === U
 
         # Check no args
         g = GNNGraph(g)
-        @test g.ndata.X === X
-        @test g.edata.E === E
-        @test g.gdata.U === U
+        @test g.ndata.x === X
+        @test g.edata.e === E
+        @test g.gdata.u === U
+
 
         # multiple features names
-        g = GNNGraph(g, ndata=(x=2X, g.ndata...), edata=(e=2E, g.edata...), gdata=(u=2U, g.gdata...))
-        @test g.ndata.X === X
-        @test g.edata.E === E
-        @test g.gdata.U === U
-        @test g.ndata.x ≈ 2X
-        @test g.edata.e ≈ 2E
-        @test g.gdata.u ≈ 2U
+        g = GNNGraph(g, ndata=(x2=2X, g.ndata...), edata=(e2=2E, g.edata...), gdata=(u2=2U, g.gdata...))
+        @test g.ndata.x === X
+        @test g.edata.e === E
+        @test g.gdata.u === U
+        @test g.ndata.x2 ≈ 2X
+        @test g.edata.e2 ≈ 2E
+        @test g.gdata.u2 ≈ 2U
     end 
 
     @testset "LearnBase and DataLoader compat" begin