Merge pull request #53 from JuliaGraphs/hw/fixed

add option to pin node positions

Author: hexaeder

.github/workflows/CI.yml

@@ -1,7 +1,10 @@
 name: CI
 on:
-  - push
-  - pull_request
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}

Project.toml

@@ -8,10 +8,12 @@ LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 
 [compat]
 GeometryBasics = "0.4"
 Requires = "1"
+StaticArrays = "1"
 julia = "1"
 
 [extras]

docs/localmake.jl

@@ -0,0 +1,24 @@
+#! julia --startup-file=no
+
+using Pkg
+Pkg.activate(@__DIR__)
+Pkg.develop(PackageSpec(path=dirname(@__DIR__))) # adds the package this script is called from
+Pkg.update()
+Pkg.instantiate()
+
+using LiveServer
+@async serve(dir=joinpath(@__DIR__, "build"))
+
+run = true
+while run
+    try
+        include("make.jl")
+    catch e
+        @info "make.jl error" e
+    end
+
+    println("Run again? Enter! Exit with 'q'.")
+    if readline() == "q"
+        global run = false
+    end
+end

docs/make.jl

@@ -12,7 +12,19 @@ makedocs(; modules=[NetworkLayout],
          format=Documenter.HTML(; prettyurls=get(ENV, "CI", "false") == "true",
                                 canonical="https://juliagraphs.org/NetworkLayout.jl", assets=String[]),
          pages=["Home" => "index.md",
-                "Interface" => "interface.md"])
+                "Interface" => "interface.md"],
+         strict=[:autodocs_block,
+                 :cross_references,
+                 :docs_block,
+                 :doctest,
+                 :eval_block,
+                 :example_block,
+                 :footnote,
+                 :linkcheck,
+                 :meta_block,
+                 #:missing_docs,
+                 :parse_error,
+                 :setup_block])
 
 # if gh_pages branch gets to big, check out
 # https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#gh-pages-Branch

docs/servedocs

@@ -11,7 +11,6 @@ All example images on this page are created using [`Makie.jl`](https://github.co
 using CairoMakie
 CairoMakie.activate!(type="png") # hide
 set_theme!(resolution=(800, 400)) #hide
-CairoMakie.inline!(true) # hide
 using NetworkLayout
 using GraphMakie, Graphs
 nothing #hide
@@ -174,3 +173,62 @@ layout = Spectral()
 f, ax, p = graphplot(g, layout=layout, node_size=0.0, edge_width=1.0)
 f #hide
 ```
+
+## `pin` Positions in Interative Layouts
+Sometimes it is desired to fix the positions of a few nodes while arranging the rest "naturally" around them.
+The iterative layouts [`Stress`](@ref), [`Spring`](@ref) and [`SFDP`](@ref) allow to pin
+nodes to certain positions, i.e. those node will stay fixed during the iteration.
+```@example layouts
+g = SimpleGraph(vcat(hcat(zeros(4,4), ones(4,4)), hcat(ones(4,4), zeros(4,4))))
+nothing #hide
+```
+
+The keyword argument `pin` takes a Vector or a Dict of key - value pairs. The key has to be
+the index of the node. The value can take three forms:
+  - `idx => Point2(x,y) ` or `idx => (x,y)` overwrites the initial position of that vertex and pins it there,
+  - `idx => true/false` pins or unpins the vertex, position is taken from `initialpos`-keyword argument or random,
+  - `idx => (false, true)` allows for fine control over which coordinate to pin.
+
+```@example layouts
+initialpos = Dict(1=>Point2f(-1,0.5),
+                  3=>Point2f(1,0),
+                  4=>Point2f(1,0))
+pin = Dict(1=>true,
+           2=>(-1,-0.5),
+           3=>(true, false),
+           4=>(true, false))
+nothing #hide
+```
+Example animation on how those keyword arguments effect different iterative layouts:
+```@example layouts
+springl = Spring(;initialpos, pin, seed=11) #2
+sfdpl   = SFDP(;initialpos, pin, tol=0.0)
+stressl = Stress(;initialpos, pin, reltols=0.0, abstolx=0.0, iterations=100)
+
+f = Figure(resolution=(1200,500))
+ax1 = f[1,1] = Axis(f; title="Spring")
+ax2 = f[1,2] = Axis(f; title="SFDP")
+ax3 = f[1,3] = Axis(f; title="Stress")
+
+for ax in [ax1, ax2, ax3]
+    xlims!(ax,-2,2); ylims!(ax,-1.4,1.4); vlines!(ax, 1; color=:red); hidespines!(ax); hidedecorations!(ax)
+end
+
+node_color = vcat(:green, :green, :red, :red, [:black for _ in 1:4])
+node_size = vcat([40 for _ in 1:4], [20 for _ in 1:4])
+nlabels = vcat("1", "2", "3", "4", ["" for _ in 1:4])
+nlabels_align = (:center, :center)
+nlabels_color = :white
+p1 = graphplot!(ax1, g; layout=springl, node_color, node_size, nlabels, nlabels_align, nlabels_color)
+p2 = graphplot!(ax2, g; layout=sfdpl, node_color, node_size, nlabels, nlabels_align, nlabels_color)
+p3 = graphplot!(ax3, g; layout=stressl, node_color, node_size, nlabels, nlabels_align, nlabels_color)
+
+iterators = [LayoutIterator(l, g) for l in (springl, sfdpl, stressl)]
+record(f, "pin_animation.mp4", zip(iterators...); framerate = 10) do (pos1, pos2, pos3)
+    p1[:node_pos][] = pos1
+    p2[:node_pos][] = pos2
+    p3[:node_pos][] = pos3
+end
+nothing #hide
+```
+![pin animation](pin_animation.mp4)

docs/src/index.md

@@ -4,6 +4,7 @@ using GeometryBasics
 using Requires
 using LinearAlgebra: norm
 using Random
+using StaticArrays
 
 export LayoutIterator
 
@@ -137,6 +138,66 @@ function make_symmetric!(A::AbstractMatrix)
     return A
 end
 
+"""
+Initialpos and pin can be given as diffent types (dicts, vectors, ...)
+Sanitize and transform them into
+
+    _initialpos :: Dict{Int,Point{dim,Ptype}}()
+    _pin        :: Dict{Int,SVector{dim,Bool}}()
+"""
+function _sanitize_initialpos_pin(dim, Ptype, initialpos, pin)
+    if !isempty(initialpos)
+        _initialpos = Dict{Int,Point{dim,Ptype}}(k => Point{dim,Ptype}(v) for (k, v) in pairs(initialpos))
+    else
+        _initialpos = Dict{Int,Point{dim,Ptype}}()
+    end
+
+    _pin = Dict{Int,SVector{dim,Bool}}()
+    for (k, v) in pairs(pin)
+        if v == nothing
+            continue
+        elseif v isa Bool
+            _pin[k] = SVector{dim,Bool}(v for i in 1:dim)
+        else # some container
+            if eltype(v) <: Bool
+                _pin[k] = v
+            else
+                # seems to be an initial position
+                _initialpos[k] = v
+                _pin[k] = SVector{dim,Bool}([true for i in 1:dim])
+            end
+        end
+    end
+    return _initialpos, _pin
+end
+
+"""
+From an point or a colletion of point like objects try to
+infer the PType and the dimension.
+
+i.e.
+    infer_pointtype([(1,2), (2.3, 4)]) == (2, Float64)
+"""
+infer_pointtype(::AbstractPoint{dim,t}) where {dim,t} = dim, t
+infer_pointtype(::NTuple{dim,t}) where {dim,t} = dim, t
+infer_pointtype(t::Tuple) = length(t), promote_type(typeof(t).parameters...)
+function infer_pointtype(v)
+    v = values(v) # needed for broadcast ofer dict
+    isempty(v) && throw(ArgumentError("Can not infer pointtype of empty container!"))
+    elt = isconcretetype(eltype(v)) ? eltype(v) : promote_type(typeof.(v)...)
+
+    if elt <: Number
+        return (length(v), elt)
+    else
+        ty = infer_pointtype.(v)
+        dims = getindex.(ty, 1)
+        if !all(isequal(first(dims)), dims)
+            throw(ArgumentError("Got container with different point dimesions!"))
+        end
+        (dims[1], promote_type(getindex.(ty, 2)...))
+    end
+end
+
 """
     @addcall
 

src/NetworkLayout.jl

@@ -20,8 +20,15 @@ the nodes.
 - `iterations=100`: maximum number of iterations
 - `initialpos=Point{dim,Ptype}[]`
 
-  Provide list of initial positions. If length does not match Network size the initial
-  positions will be truncated or filled up with random values between [-1,1] in every coordinate.
+  Provide `Vector` or `Dict` of initial positions. All positions will be initialized
+  using random coordinates between [-1,1]. Random positions will be overwritten using
+  the key-val-pairs provided by this argument.
+
+- `pin=[]`: Pin node positions (won't be updated). Can be given as `Vector` or `Dict`
+   of node index -> value pairings. Values can be either
+    - `(12, 4.0)` : overwrite initial position and pin
+    - `true/false` : pin this position
+    - `(true, false, false)` : only pin certain coordinates
 
 - `seed=1`: Seed for random initial positions.
 """
@@ -30,44 +37,45 @@ the nodes.
     C::T
     K::T
     iterations::Int
-    initialpos::Vector{Point{Dim,Ptype}}
+    initialpos::Dict{Int,Point{Dim,Ptype}}
+    pin::Dict{Int,SVector{Dim,Bool}}
     seed::UInt
 end
 
 # TODO: check SFDP default parameters
-function SFDP(; dim=2, Ptype=Float64, tol=1.0, C=0.2, K=1.0, iterations=100, initialpos=Point{dim,Ptype}[],
+function SFDP(; dim=2, Ptype=Float64,
+              tol=1.0, C=0.2, K=1.0,
+              iterations=100,
+              initialpos=[], pin=[],
               seed=1)
     if !isempty(initialpos)
-        initialpos = Point.(initialpos)
-        Ptype = eltype(eltype(initialpos))
-        # TODO fix initial pos if list has points of multiple types
-        Ptype == Any && error("Please provide list of Point{N,T} with same T")
-        dim = length(eltype(initialpos))
+        dim, Ptype = infer_pointtype(initialpos)
+        Ptype = promote_type(Float32, Ptype) # make sure to get at least f32 if given as int
     end
-    return SFDP{dim,Ptype,typeof(tol)}(tol, C, K, iterations, initialpos, seed)
+    _initialpos, _pin = _sanitize_initialpos_pin(dim, Ptype, initialpos, pin)
+
+    return SFDP{dim,Ptype,typeof(tol)}(tol, C, K, iterations, _initialpos, _pin, seed)
 end
 
 function Base.iterate(iter::LayoutIterator{SFDP{Dim,Ptype,T}}) where {Dim,Ptype,T}
     algo, adj_matrix = iter.algorithm, iter.adj_matrix
     N = size(adj_matrix, 1)
-    M = length(algo.initialpos)
     rng = MersenneTwister(algo.seed)
-    startpos = Vector{Point{Dim,Ptype}}(undef, N)
-    # take the first
-    for i in 1:min(N, M)
-        startpos[i] = algo.initialpos[i]
-    end
-    # fill the rest with random points
-    for i in (M + 1):N
-        startpos[i] = 2 .* rand(rng, Point{Dim,Ptype}) .- 1
+    startpos = [2 .* rand(rng, Point{Dim,Ptype}) .- 1 for _ in 1:N]
+
+    for (k, v) in algo.initialpos
+        startpos[k] = v
     end
-    # iteratorstate: (#iter, energy, step, progress, old pos, stopflag)
-    return startpos, (1, typemax(T), one(T), 0, startpos, false)
+
+    pin = [get(algo.pin, i, SVector{Dim,Bool}(false for _ in 1:Dim)) for i in 1:N]
+
+    # iteratorstate: (#iter, energy, step, progress, old pos, pin, stopflag)
+    return startpos, (1, typemax(T), one(T), 0, startpos, pin, false)
 end
 
 function Base.iterate(iter::LayoutIterator{<:SFDP}, state)
     algo, adj_matrix = iter.algorithm, iter.adj_matrix
-    iter, energy0, step, progress, locs0, stopflag = state
+    iter, energy0, step, progress, locs0, pin, stopflag = state
     K, C, tol = algo.K, algo.C, algo.tol
 
     # stop if stopflag (tol reached) or nr of iterations reached
@@ -93,7 +101,14 @@ function Base.iterate(iter::LayoutIterator{<:SFDP}, state)
                                ((locs[j] .- locs[i]) / norm(locs[j] .- locs[i])))
             end
         end
-        locs[i] = locs[i] .+ step .* (force ./ norm(force))
+        if any(isnan, force)
+            # if two points are at the exact same location
+            # use random force in any direction
+            rng = MersenneTwister(algo.seed + i)
+            force = randn(rng, Ftype)
+        end
+        mask = (!).(pin[i]) # where pin=true mask will multiply with 0
+        locs[i] = locs[i] .+ (step .* (force ./ norm(force))) .* mask
         energy = energy + norm(force)^2
     end
     step, progress = update_step(step, energy, energy0, progress)
@@ -103,7 +118,7 @@ function Base.iterate(iter::LayoutIterator{<:SFDP}, state)
         stopflag = true
     end
 
-    return locs, (iter + 1, energy, step, progress, locs, stopflag)
+    return locs, (iter + 1, energy, step, progress, locs, pin, stopflag)
 end
 
 # Calculate Attractive force