Add Temporal random radius graph generator (#305)

* Add `temporal_rand_radius_graph` function

* New version

* Add test for `temporal_rand_radius_graph`

* Update on a square with border

* Add docstring

* Export `temporal_rand_radius_graph`

* Add more spaces

Co-authored-by: Carlo Lucibello <[email protected]>

* Improved docstring

Co-authored-by: Carlo Lucibello <[email protected]>

* Rename

* Add ref

---------

Co-authored-by: Carlo Lucibello <[email protected]>

Author: aurorarossi

src/GNNGraphs/GNNGraphs.jl

@@ -89,7 +89,8 @@ export rand_graph,
        rand_heterograph,
        rand_bipartite_heterograph,
        knn_graph,
-       radius_graph
+       radius_graph,
+       rand_temporal_radius_graph
 
 include("sampling.jl")
 export sample_neighbors

src/GNNGraphs/generate.jl

@@ -270,6 +270,8 @@ GNNGraph:
     num_graphs = 2
 
 ```
+# References
+Section B paragraphs 1 and 2 of the paper [Dynamic Hidden-Variable Network Models](https://arxiv.org/pdf/2101.00414.pdf)
 """
 function radius_graph(points::AbstractMatrix, r::AbstractFloat;
                       graph_indicator = nothing,
@@ -298,3 +300,65 @@ function radius_graph(points::AbstractMatrix, r::AbstractFloat;
     end
     return g
 end
+
+"""
+    rand_temporal_radius_graph(number_nodes::Int, 
+                               number_snapshots::Int,
+                               speed::AbstractFloat,
+                               r::AbstractFloat;
+                               self_loops = false,
+                               dir = :in,
+                               kws...)
+
+Create a random temporal graph given `number_nodes` nodes and `number_snapshots` snapshots.
+First, the positions of the nodes are randomly generated in the unit square. Two nodes are connected if their distance is less than a given radius `r`.
+Each following snapshot is obtained by applying the same construction to new positions obtained as follows.
+For each snapshot, the new positions of the points are determined by applying random independent displacement vectors to the previous positions. The direction of the displacement is chosen uniformly at random and its length is chosen uniformly in `[0, speed]`. Then the connections are recomputed.
+If a point happens to move outside the boundary, its position is updated as if it had bounced off the boundary.
+
+# Arguments
+
+- `number_nodes`: The number of nodes of each snapshot.
+- `number_snapshots`: The number of snapshots.
+- `speed`: The speed to update the nodes.
+- `r`: The radius of connection.
+- `self_loops`: If `true`, consider the node itself among its neighbors, in which
+                case the graph will contain self-loops. 
+- `dir`: The direction of the edges. If `dir=:in` edges go from the
+         neighbors to the central node. If `dir=:out` we have the opposite
+         direction.
+- `kws`: Further keyword arguments will be passed to the [`GNNGraph`](@ref) constructor of each snapshot.
+
+# Example
+
+```julia-repl
+julia> n, snaps, s, r = 10, 5, 0.1, 1.5;
+
+julia> tg = rand_temporal_radius_graph(n,snaps,s,r) # complete graph at each snapshot
+TemporalSnapshotsGNNGraph:
+  num_nodes: [10, 10, 10, 10, 10]
+  num_edges: [90, 90, 90, 90, 90]
+  num_snapshots: 5
+```  
+
+"""
+function rand_temporal_radius_graph(number_nodes::Int, 
+                                    number_snapshots::Int,
+                                    speed::AbstractFloat,
+                                    r::AbstractFloat;
+                                    self_loops = false,
+                                    dir = :in,
+                                    kws...)
+    points=rand(2, number_nodes)
+    tg = Vector{GNNGraph}(undef, number_snapshots)
+    for t in 1:number_snapshots
+        tg[t] = radius_graph(points, r; graph_indicator = nothing, self_loops, dir, kws...)
+        for i in 1:number_nodes
+            ρ = 2 * speed * rand() - speed
+            theta=2*pi*rand()
+            points[1,i]=1-abs(1-(abs(points[1,i]+ρ*cos(theta))))
+            points[2,i]=1-abs(1-(abs(points[2,i]+ρ*sin(theta))))
+        end
+    end
+    return TemporalSnapshotsGNNGraph(tg)
+end

test/GNNGraphs/generate.jl

@@ -92,3 +92,16 @@ end
     @test has_edge(g, (:A,:to,:B), 1, 1)
     @test !has_edge(g, (:B,:to,:A), 1, 1)
 end
+
+@testset "rand_temporal_radius_graph" begin
+    number_nodes = 30
+    number_snapshots = 5
+    r = 0.1
+    speed = 0.1
+    tg = rand_temporal_radius_graph(number_nodes, number_snapshots, speed, r)
+    @test tg.num_nodes == [number_nodes for i in 1:number_snapshots]
+    @test tg.num_snapshots == number_snapshots
+    r2 = 0.95
+    tg2 = rand_temporal_radius_graph(number_nodes, number_snapshots, speed, r2)
+    @test mean(mean(degree.(tg.snapshots)))<=mean(mean(degree.(tg2.snapshots)))
+end