Allow passing random number generator to label-propagation (#95)

This also fixes an issue where the randomized tests for label-propagation would sporadically fail.

Author: simonschoelly

src/community/label_propagation.jl

@@ -1,5 +1,5 @@
 """
-    label_propagation(g, maxiter=1000)
+    label_propagation(g, maxiter=1000; rng=GLOBAL_RNG)
 
 Community detection using the label propagation algorithm.
 Return two vectors: the first is the label number assigned to each node, and
@@ -9,7 +9,10 @@ the second is the convergence history for each node. Will return after
 ### References
 - [Raghavan et al.](http://arxiv.org/abs/0709.2938)
 """
-function label_propagation(g::AbstractGraph{T}, maxiter=1000) where T
+function label_propagation(g::AbstractGraph{T}, maxiter=1000; rng::Union{Nothing, AbstractRNG} = nothing, seed::Union{Nothing, Integer} = nothing) where T
+
+    rng = rng_from_rng_or_seed(rng, seed)
+
     n = nv(g)
     n == 0 && return (T[], Int[])
 
@@ -28,11 +31,11 @@ function label_propagation(g::AbstractGraph{T}, maxiter=1000) where T
         for (j, node) in enumerate(active_vs)
             random_order[j] = node
         end
-        range_shuffle!(1:num_active, random_order)
+        range_shuffle!(rng, 1:num_active, random_order)
         @inbounds for j = 1:num_active
             u = random_order[j]
             old_comm = label[u]
-            label[u] = vote!(g, label, c, u)
+            label[u] = vote!(rng, g, label, c, u)
             if old_comm != label[u]
                 for v in outneighbors(g, u)
                     push!(active_vs, v)
@@ -59,13 +62,11 @@ mutable struct NeighComm{T<:Integer}
 end
 
 """
-    range_shuffle!(r, a; seed=-1)
+    range_shuffle!(rng, r, a)
 
 Fast shuffle Array `a` in UnitRange `r`.
-Uses `seed` to initialize the random number generator, defaulting to `Random.GLOBAL_RNG` for `seed=-1`.
 """
-function range_shuffle!(r::UnitRange, a::AbstractVector; seed::Int=-1)
-    rng = getRNG(seed)
+function range_shuffle!(rng::AbstractRNG, r::UnitRange, a::AbstractVector)
     (r.start > 0 && r.stop <= length(a)) || throw(DomainError(r, "range indices are out of bounds"))
     @inbounds for i = length(r):-1:2
         j = rand(rng, 1:i)
@@ -76,11 +77,11 @@ function range_shuffle!(r::UnitRange, a::AbstractVector; seed::Int=-1)
 end
 
 """
-    vote!(g, m, c, u)
+    vote!(rng, g, m, c, u)
 
 Return the label with greatest frequency.
 """
-function vote!(g::AbstractGraph, m::Vector, c::NeighComm, u::Integer)
+function vote!(rng::AbstractRNG, g::AbstractGraph, m::Vector, c::NeighComm, u::Integer)
     @inbounds for i = 1:c.neigh_last - 1
         c.neigh_cnt[c.neigh_pos[i]] = -1
     end
@@ -102,7 +103,7 @@ function vote!(g::AbstractGraph, m::Vector, c::NeighComm, u::Integer)
         end
     end
     # ties breaking randomly
-    range_shuffle!(1:c.neigh_last - 1, c.neigh_pos)
+    range_shuffle!(rng, 1:c.neigh_last - 1, c.neigh_pos)
 
     result_lbl = zero(eltype(c.neigh_pos))
     for lbl in c.neigh_pos

src/utils.jl

@@ -44,6 +44,27 @@ sample(a::AbstractVector, k::Integer; exclude=()) = sample!(getRNG(), collect(a)
 
 getRNG(seed::Integer=-1) = seed >= 0 ? MersenneTwister(seed) : GLOBAL_RNG
 
+"""
+    rng_from_rng_or_seed(rng, seed)
+
+Helper function for randomized functions that can take a random generator as well as a seed argument.
+
+Currently most randomized functions in this package take a seed integer as an argument.
+As modern randomized Julia functions tend to take a random generator instead of a seed,
+this function helps with the transition by taking `rng` and `seed` as an argument and
+always returning a random number generator.
+At least one of these arguments must be `nothing`.
+"""
+function rng_from_rng_or_seed(rng::Union{Nothing, AbstractRNG}, seed::Union{Nothing, Integer})
+
+    # TODO at some point we might emit a deprecation warning if a seed is specified
+
+    !(isnothing(seed) || isnothing(rng)) && throw(ArgumentError("Cannot specify both, seed and rng"))
+    !isnothing(seed)                     && return getRNG(seed)
+    isnothing(rng)                       && return GLOBAL_RNG
+    return rng
+end
+
 """
     insorted(item, collection)
 

test/community/label_propagation.jl

@@ -1,12 +1,15 @@
 @testset "Label propagation" begin
+
+    rng = MersenneTwister(1234)
+
     n = 10
     g10 = complete_graph(n)
     for g in testgraphs(g10)
         z = copy(g)
         for k = 2:5
             z = blockdiag(z, g)
             add_edge!(z, (k - 1) * n, k * n)
-            c, ch = @inferred(label_propagation(z))
+            c, ch = @inferred(label_propagation(z; rng=rng))
             a = collect(n:n:(k * n))
             a = Int[div(i - 1, n) + 1 for i = 1:(k * n)]
           # check the number of communities

test/runtests.jl

@@ -4,6 +4,7 @@ using Graphs.Experimental
 using Test
 using SparseArrays
 using LinearAlgebra
+using Compat
 using DelimitedFiles
 using Base64
 using Random

test/utils.jl

@@ -33,6 +33,18 @@
         end
     end
 
+    @testset "rng_from_rng_or_seed" begin
+        @test Graphs.rng_from_rng_or_seed(nothing, nothing) === Random.GLOBAL_RNG
+        @test Graphs.rng_from_rng_or_seed(nothing, -10) === Random.GLOBAL_RNG
+        @test Graphs.rng_from_rng_or_seed(nothing, 456) == Graphs.getRNG(456)
+        @compat if ismutable(Random.GLOBAL_RNG)
+            @test Graphs.rng_from_rng_or_seed(nothing, 456) !== Random.GLOBAL_RNG
+        end
+        rng = Random.MersenneTwister(789)
+        @test Graphs.rng_from_rng_or_seed(rng, nothing) === rng
+        @test_throws ArgumentError Graphs.rng_from_rng_or_seed(rng, -1)
+    end
+
     A = [false, true, false, false, true, true]
     @test findall(A) == Graphs.findall!(A, Vector{Int16}(undef, 6))[1:3]
 end