diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index e9869a7..3dd1394 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-16T09:09:17","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2025-01-06T09:22:11","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index dd99b7c..16624d4 100644 --- a/dev/index.html +++ b/dev/index.html @@ -5,7 +5,7 @@ positions = alg(adj_matrix)

Each of the layouts comes with a lowercase function version:

positions = layoutalgorithm(adj_matrix; p1="foo", b2=:bar)

Instead of using the adjacency matrix you can use AbstractGraph types from Graphs.jl directly.

g = complete_graph(10)
 positions = layoutalgorithm(g)

Scalable Force Directed Placement

NetworkLayout.SFDP — Type
SFDP(; kwargs...)(adj_matrix)
 sfdp(adj_matrix; kwargs...)

Using the Spring-Electric model suggested by Hu (2005, The Mathematica Journal, pdf).

Forces are calculated as:

    f_attr(i,j) = ‖xi - xj‖ ² / K ,    i<->j
-    f_repln(i,j) = -CK² / ‖xi - xj‖ ,  i!=j

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

  • dim=2, Ptype=Float64: Determines dimension and output type Point{dim,Ptype}.

  • tol=1.0: Stop if position changes of last step Δp <= tol*K for all nodes

  • C=0.2, K=1.0: Parameters to tweak forces.

  • iterations=100: maximum number of iterations

  • initialpos=Point{dim,Ptype}[]

    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.

  • rng=DEFAULT_RNG[](seed)

    Create rng based on seed. Defaults to MersenneTwister, can be specified by overwriting DEFAULT_RNG[]

source

Example

g = wheel_graph(10)
+    f_repln(i,j) = -CK² / ‖xi - xj‖ ,  i!=j

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

source

Example

g = wheel_graph(10)
 layout = SFDP(Ptype=Float32, tol=0.01, C=0.2, K=1)
 f, ax, p = graphplot(g, layout=layout)
 hidedecorations!(ax); hidespines!(ax); ax.aspect = DataAspect(); f
Example block output

Iterator Example

iterator = LayoutIterator(layout, g)
@@ -15,7 +15,7 @@
 end

Buchheim Tree Drawing

NetworkLayout.Buchheim — Type
Buchheim(; kwargs...)(adj_matrix)
 Buchheim(; kwargs...)(adj_list)
 buchheim(adj_matrix; kwargs...)
-buchheim(adj_list; kwargs...)

Using the algorithm proposed by Buchheim, Junger and Leipert (2002, doi 10.1007/3-540-36151-0_32).

Takes adjacency matrix or list representation of given tree and returns coordinates of the nodes.

Keyword Arguments

  • Ptype=Float64: Determines the output type Point{2,Ptype}.

  • nodesize=Float64[]

    Determines the size of each of the node. If network size does not match the length of nodesize fill up with ones or truncate given parameter.

source

Example

adj_matrix = [0 1 1 0 0 0 0 0 0 0;
+buchheim(adj_list; kwargs...)

Using the algorithm proposed by Buchheim, Junger and Leipert (2002, doi 10.1007/3-540-36151-0_32).

Takes adjacency matrix or list representation of given tree and returns coordinates of the nodes.

Keyword Arguments

source

Example

adj_matrix = [0 1 1 0 0 0 0 0 0 0;
               0 0 0 0 1 1 0 0 0 0;
               0 0 0 1 0 0 1 0 1 0;
               0 0 0 0 0 0 0 0 0 0;
@@ -28,14 +28,14 @@
 g = SimpleDiGraph(adj_matrix)
 layout = Buchheim()
 f, ax, p = graphplot(g, layout=layout)
Example block output

Spring/Repulsion Model

NetworkLayout.Spring — Type
Spring(; kwargs...)(adj_matrix)
-spring(adj_matrix; kwargs...)

Use the spring/repulsion model of Fruchterman and Reingold (1991, doi 10.1002/spe.4380211102) with

  • Attractive force: f_a(d) = d^2 / k
  • Repulsive force: f_r(d) = -k^2 / d

where d is distance between two vertices and the optimal distance between vertices k is defined as C * sqrt( area / num_vertices ) where C is a parameter we can adjust

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

  • dim=2, Ptype=Float64: Determines dimension and output type Point{dim,Ptype}.

  • C=2.0: Constant to fiddle with density of resulting layout

  • iterations=100: maximum number of iterations

  • initialtemp=2.0: Initial "temperature", controls movement per iteration

  • initialpos=Point{dim,Ptype}[]

    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.

  • rng=DEFAULT_RNG[](seed)

    Create rng based on seed. Defaults to MersenneTwister, can be specified by overwriting DEFAULT_RNG[]

source

Example

g = smallgraph(:cubical)
+spring(adj_matrix; kwargs...)

Use the spring/repulsion model of Fruchterman and Reingold (1991, doi 10.1002/spe.4380211102) with

where d is distance between two vertices and the optimal distance between vertices k is defined as C * sqrt( area / num_vertices ) where C is a parameter we can adjust

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

source

Example

g = smallgraph(:cubical)
 layout = Spring(Ptype=Float32)
 f, ax, p = graphplot(g, layout=layout)
Example block output

Iterator Example

iterator = LayoutIterator(layout, g)
 record(f, "spring_animation.mp4", iterator; framerate = 10) do pos
     p[:node_pos][] = pos
     autolimits!(ax)
 end

Stress Majorization

NetworkLayout.Stress — Type
Stress(; kwargs...)(adj_matrix)
-stress(adj_matrix; kwargs...)

Compute graph layout using stress majorization. Takes adjacency matrix representation of a network and returns coordinates of the nodes.

The main equation to solve is (8) in Gansner, Koren and North (2005, doi 10.1007/978-3-540-31843-9_25).

Inputs:

  • adj_matrix: Matrix of pairwise distances.

Keyword Arguments

  • dim=2, Ptype=Float64: Determines dimension and output type Point{dim,Ptype}.

  • iterations=:auto: maximum number of iterations (:auto means 400*N^2 where N are the number of vertices)

  • abstols=0

    Absolute tolerance for convergence of stress. The iterations terminate if the difference between two successive stresses is less than abstol.

  • reltols=10e-6

    Relative tolerance for convergence of stress. The iterations terminate if the difference between two successive stresses relative to the current stress is less than reltol.

  • abstolx=10e-6

    Absolute tolerance for convergence of layout. The iterations terminate if the Frobenius norm of two successive layouts is less than abstolx.

  • weights=Array{Float64}(undef, 0, 0)

    Matrix of weights. If empty (i.e. not specified), defaults to weights[i,j] = δ[i,j]^-2 if δ[i,j] is nonzero, or 0 otherwise.

  • initialpos=Point{dim,Ptype}[]

    Provide Vector or Dict of initial positions. All positions will be initialized using random coordinates from normal distribution. 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.

  • rng=DEFAULT_RNG[](seed)

    Create rng based on seed. Defaults to MersenneTwister, can be specified by overwriting DEFAULT_RNG[]

  • uncon_dist=(maxdist, Ncomps)->maxdist*Ncomps^(1/3)

    Per default, unconnected vertices in the graph get a pairwise "ideal" distance which scales with the number of connected components and the maximum distance within the components.

source

Example

g = SimpleGraph(936)
+stress(adj_matrix; kwargs...)

Compute graph layout using stress majorization. Takes adjacency matrix representation of a network and returns coordinates of the nodes.

The main equation to solve is (8) in Gansner, Koren and North (2005, doi 10.1007/978-3-540-31843-9_25).

Inputs:

Keyword Arguments

source

Example

g = SimpleGraph(936)
 for l in eachline(joinpath(@__DIR__,"..","..","test","jagmesh1.mtx"))
     s = split(l, " ")
     src, dst = parse(Int, s[1]), parse(Int, s[2])
@@ -48,13 +48,13 @@
     p[:node_pos][] = pos
     autolimits!(ax)
 end

Shell/Circular Layout

NetworkLayout.Shell — Type
Shell(; kwargs...)(adj_matrix)
-shell(adj_matrix; kwargs...)

Position nodes in concentric circles. Without further arguments all nodes will be placed on a circle with radius 1.0. Specify placement of nodes using the nlist argument.

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

  • Ptype=Float64: Determines the output type Point{2,Ptype}.

  • nlist=Vector{Int}[]

    Vector of Vector of node indices. Tells the algorithm, which nodes to place on which shell from inner to outer. Nodes which are not present in this list will be place on additional outermost shell.

This function started as a copy from IainNZ's GraphLayout.jl

source
g = smallgraph(:petersen)
+shell(adj_matrix; kwargs...)

Position nodes in concentric circles. Without further arguments all nodes will be placed on a circle with radius 1.0. Specify placement of nodes using the nlist argument.

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

This function started as a copy from IainNZ's GraphLayout.jl

source
g = smallgraph(:petersen)
 layout = Shell(nlist=[6:10,])
 f, ax, p = graphplot(g, layout=layout)
Example block output

SquareGrid Layout

NetworkLayout.SquareGrid — Type
SquareGrid(; kwargs...)(adj_matrix)
-squaregrid(adj_matrix; kwargs...)

Position nodes on a 2 dimensional rectagular grid. The nodes are placed in order from upper left to lower right. To skip positions see skip argument.

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

  • Ptype=Float64: Determines the output type Point{2,Ptype}
  • cols=:auto: Columns of the grid, the rows are determined automatic. If :auto the layout will be square-ish.
  • dx=Ptype(1), dy=Ptype(-1): Ofsets between rows/cols.
  • skip=Tuple{Int,Int}[]: Specify positions to skip when placing nodes. skip=[(i,j)] means to keep the position in the i-th row and j-th column empty.
source
g = Grid((12,4))
+squaregrid(adj_matrix; kwargs...)

Position nodes on a 2 dimensional rectagular grid. The nodes are placed in order from upper left to lower right. To skip positions see skip argument.

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

source
g = Grid((12,4))
 layout = SquareGrid(cols=12)
 f, ax, p = graphplot(g, layout=layout, nlabels=repr.(1:nv(g)), nlabels_textsize=10, nlabels_distance=5)
Example block output

Spectral Layout

NetworkLayout.Spectral — Type
Spectral(; kwargs...)(adj_matrix)
-spectral(adj_matrix; kwargs...)

This algorithm uses the technique of Spectral Graph Drawing. For reference see Koren (2003, doi 10.1007/3-540-45071-8_50).

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

  • dim=3, Ptype=Float64: Determines dimension and output type Point{dim,Ptype}.
  • nodeweights=Float64[]: Vector of weights. If network size does not match the length of nodesize use ones instead.
source
g = watts_strogatz(1000, 5, 0.03; seed=5)
+spectral(adj_matrix; kwargs...)

This algorithm uses the technique of Spectral Graph Drawing. For reference see Koren (2003, doi 10.1007/3-540-45071-8_50).

Takes adjacency matrix representation of a network and returns coordinates of the nodes.

Keyword Arguments

source
g = watts_strogatz(1000, 5, 0.03; seed=5)
 layout = Spectral(dim=2)
 f, ax, p = graphplot(g, layout=layout, node_size=0.0, edge_width=1.0)
Example block output
layout = Spectral()
 f, ax, p = graphplot(g, layout=layout, node_size=0.0, edge_width=1.0)
Example block output

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, Spring and SFDP allow to pin nodes to certain positions, i.e. those node will stay fixed during the iteration.

g = SimpleGraph(vcat(hcat(zeros(4,4), ones(4,4)), hcat(ones(4,4), zeros(4,4))))

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:

initialpos = Dict(1=>Point2f(-1,0.5),
@@ -90,4 +90,4 @@
     p1[:node_pos][] = pos1
     p2[:node_pos][] = pos2
     p3[:node_pos][] = pos3
-end

+end

diff --git a/dev/interface/index.html b/dev/interface/index.html index 77f5a7d..8175ecf 100644 --- a/dev/interface/index.html +++ b/dev/interface/index.html @@ -1,8 +1,8 @@ -Interface · NetworkLayout.jl
GitHub

Layout Interface

At its core, each layout algorithm is a mapping 

graph ↦ node_positions

where each layout has several parameters. The main goal of the following interface is to keep the separation between parameters and function call. Each layout is implemented as subtype of AbstractLayout.

NetworkLayout.AbstractLayout — Type
AbstractLayout{Dim,Ptype}

Abstract supertype for all layouts. Each layout Layout <: AbstractLayout needs to implement

layout(::Layout, adj_matrix)::Vector{Point{Dim,Ptype}}

which takes the adjacency matrix representation of a network and returns a list of node positions. Each Layout object holds all of the necessary parameters.

The type parameters specify the returntype Vector{Point{Dim,Ptype}}:

  • Dim: the dimensionality of the layout (i.e. 2 or 3)
  • Ptype: the type of the returned points (i.e. Float32 or Float64)

By implementing layout the Layout also inherits the function-like property

Layout(; kwargs...)(adj_matrix) -> node_positions
source

Therefore, each LayoutAlgorithm <: AbstractLayout is a functor and can be passed around as a function graph ↦ node_positions which encapsulates all the parameters. This is handy for plotting libraries such as GraphMakie.jl.

There are some additional guidelines:

  • All of the parameters should be keyword arguments, i.e. it should be allways possible to call LayoutAlgorithm() without specifying any parameters.
  • Algorithms should allways return Vector{Point{Dim,Ptype}}. If the type or dimensions can be altered use the keywords dim and Ptype for it.
  • Some parameters may depend on the specific network (i.e. length of start positions vector). If possible, there should be a fallback option (i.e. truncate the list of start positions if network is to small or append with random values).

It is convenient to define the lowercase functions 

layoutalgorithm(g; kwargs...) = layout(LayoutAlgorihtm(; kwargs...), g)

which can done using this macro:

NetworkLayout.@addcall — Macro
@addcall

Annotate subtypes of AbstractLayout to create a lowercase function call for them.

@addcall struct MyLayout{Dim, Ptype} <: AbstractLayout{Dim, Ptype}
+Interface · NetworkLayout.jl
GitHub
Layout Interface
At its core, each layout algorithm is a mapping 
graph ↦ node_positions
where each layout has several parameters. The main goal of the following interface is to keep the separation between parameters and function call.  Each layout is implemented as subtype of AbstractLayout.
NetworkLayout.AbstractLayout — Type
AbstractLayout{Dim,Ptype}
Abstract supertype for all layouts. Each layout Layout <: AbstractLayout needs to implement
layout(::Layout, adj_matrix)::Vector{Point{Dim,Ptype}}
which takes the adjacency matrix representation of a network and returns a list of node positions. Each Layout object holds all of the necessary parameters.
The type parameters specify the returntype Vector{Point{Dim,Ptype}}:
  • Dim: the dimensionality of the layout (i.e. 2 or 3)
  • Ptype: the type of the returned points (i.e. Float32 or Float64)
By implementing layout the Layout also inherits the function-like property
Layout(; kwargs...)(adj_matrix) -> node_positions
source
Therefore, each LayoutAlgorithm <: AbstractLayout is a functor and can be passed around as a function graph ↦ node_positions which encapsulates all the parameters. This is handy for plotting libraries such as GraphMakie.jl.
There are some additional guidelines:
  • All of the parameters should be keyword arguments, i.e. it should be allways possible to call LayoutAlgorithm() without specifying any parameters.
  • Algorithms should allways return Vector{Point{Dim,Ptype}}. If the type or dimensions can be altered use the keywords dim and Ptype for it.
  • Some parameters may depend on the specific network (i.e. length of start positions vector). If possible, there should be a fallback option (i.e. truncate the list of start positions if network is to small or append with random values).
It is convenient to define the lowercase functions 
layoutalgorithm(g; kwargs...) = layout(LayoutAlgorihtm(; kwargs...), g)
which can done using this macro:
NetworkLayout.@addcall — Macro
@addcall
Annotate subtypes of AbstractLayout to create a lowercase function call for them.
@addcall struct MyLayout{Dim, Ptype} <: AbstractLayout{Dim, Ptype}
     para
-end
will add the function
mylayout(g; kwargs...) = layout(MyLayout(; kwargs...), g)
source
Iterative Layouts
Iterative layouts are a specific type of layouts which produce a sequence of positions rather than a single list of positions. Those algorithms are implemented as subtypes of IterativeLayout:
NetworkLayout.IterativeLayout — Type
IterativeLayout{Dim,Ptype} <: AbstractLayout{Dim,Ptype}
Abstract supertype for iterative layouts. Instead of implementing layout directly, subtypes Algorithm<:IterativeLayout need to implement the iterator interface
Base.iterate(iter::LayoutIterator{<:Algorithm})
+end
will add the function
mylayout(g; kwargs...) = layout(MyLayout(; kwargs...), g)
source
Iterative Layouts
Iterative layouts are a specific type of layouts which produce a sequence of positions rather than a single list of positions. Those algorithms are implemented as subtypes of IterativeLayout:
NetworkLayout.IterativeLayout — Type
IterativeLayout{Dim,Ptype} <: AbstractLayout{Dim,Ptype}
Abstract supertype for iterative layouts. Instead of implementing layout directly, subtypes Algorithm<:IterativeLayout need to implement the iterator interface
Base.iterate(iter::LayoutIterator{<:Algorithm})
 Base.iterate(iter::LayoutIterator{<:Algorithm}, state)
where the iteration item is a Vector{Point{Dim,Ptype}} and the iteration state depends on the algorithm.
By implementing the iterator interface the Algorithm inherits the layout and function-like call
layout(algo::Algorithm, adj_matrix) -> node_postions
-Algorithm(; kwargs...)(adj_matrix) -> node_positions
source
One can instantiate an iterable object LayoutIterator
NetworkLayout.LayoutIterator — Type
LayoutIterator{T<:IterativeLayout,M<:AbstractMatrix}(algorithm, adj_matrix)
This type bundles an IterativeLayout with an adjacency matrix to form an iterable object whose items are the node positions.
Example
for p in LayoutIterator(Stress(), adj_matrix)
+Algorithm(; kwargs...)(adj_matrix) -> node_positions
source
One can instantiate an iterable object LayoutIterator
NetworkLayout.LayoutIterator — Type
LayoutIterator{T<:IterativeLayout,M<:AbstractMatrix}(algorithm, adj_matrix)
This type bundles an IterativeLayout with an adjacency matrix to form an iterable object whose items are the node positions.
Example
for p in LayoutIterator(Stress(), adj_matrix)
     # do stuff with positions p
-end
source

+end
source
diff --git a/dev/objects.inv b/dev/objects.inv index 777f72a..5ecaeba 100644 Binary files a/dev/objects.inv and b/dev/objects.inv differ diff --git a/dev/pin_animation.mp4 b/dev/pin_animation.mp4 index f974778..5f77e96 100644 Binary files a/dev/pin_animation.mp4 and b/dev/pin_animation.mp4 differ diff --git a/dev/sfdp_animation.mp4 b/dev/sfdp_animation.mp4 index c009838..bcd3f2c 100644 Binary files a/dev/sfdp_animation.mp4 and b/dev/sfdp_animation.mp4 differ diff --git a/dev/spring_animation.mp4 b/dev/spring_animation.mp4 index 3c8c048..83df842 100644 Binary files a/dev/spring_animation.mp4 and b/dev/spring_animation.mp4 differ diff --git a/dev/stress_animation.mp4 b/dev/stress_animation.mp4 index 0824706..4f84906 100644 Binary files a/dev/stress_animation.mp4 and b/dev/stress_animation.mp4 differ