remove layout from exports, add lowercase calls

- the layout export blocks identifier in global scope
- new lowercase functions are easy to read for singe application
  i.e. `spring(g; kwargs...)` instead of `Spring(;kwargs)(g)`

Author: hexaeder

docs/src/index.md

@@ -27,7 +27,16 @@ callable and transforms the adjacency matrix and returns a list of `Point{N,T}`
 alg = LayoutAlgorithm(; p1="foo", p2=:bar)
 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 [`LightGraphs.jl`](https://github.com/JuliaGraphs/LightGraphs.jl) directly.
+```
+g = complete_graph(10)
+positions = layoutalgorithm(g)
+```
 
 ## Scalable Force Directed Placement
 ```@docs

docs/src/interface.md

@@ -15,17 +15,26 @@ Each layout is implemented as subtype of [`AbstractLayout`](@ref).
 AbstractLayout
 ```
 
-Therefore, each `Layout <: 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](http://juliaplots.org/GraphMakie.jl/previews/PR9/).
+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](http://juliaplots.org/GraphMakie.jl/previews/PR9/).
 
 There are some additional guidelines:
 - All of the parameters should be keyword arguments, i.e. it should be allways
-  possible to call `Layout()` without specifying any parameters.
+  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:
+```@docs
+addcall
+```
 
 ## 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`](@ref):

src/NetworkLayout.jl

@@ -5,7 +5,7 @@ using Requires
 using LinearAlgebra: norm
 using Random
 
-export LayoutIterator, layout
+export LayoutIterator
 
 """
     AbstractLayout{Dim,Ptype}
@@ -86,7 +86,11 @@ function layout(alg::IterativeLayout, adj_matrix::AbstractMatrix)
 end
 
 function __init__()
-    @require LightGraphs="093fc24a-ae57-5d10-9952-331d41423f4d" layout(l::AbstractLayout, g::LightGraphs.AbstractGraph) = layout(l, LightGraphs.adjacency_matrix(g))
+    @require LightGraphs = "093fc24a-ae57-5d10-9952-331d41423f4d" begin
+        function layout(l::AbstractLayout, g::LightGraphs.AbstractGraph)
+            layout(l, LightGraphs.adjacency_matrix(g))
+        end
+    end
 end
 
 """
@@ -100,6 +104,43 @@ function assertsquare(M::AbstractMatrix)
     return a
 end
 
+"""
+    @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)
+"""
+macro addcall(expr::Expr)
+    # assert subtype of abstract layout
+    @assert expr.head === :struct "Macro not used on struct!"
+    typedef = expr.args[2]
+    @assert typedef isa Expr &&
+            typedef.head === :<: &&
+            typedef.args[2] isa Expr && # supertype
+            typedef.args[2].args[1] ∈ [:AbstractLayout, :IterativeLayout] "Macro musst be used on subtype of AbstractLayout"
+
+    if typedef.args[1] isa Symbol # no type parameters
+        name = typedef.args[1]
+    elseif typedef.args[1] isa Expr && typedef.args[1].head === :curly && typedef.args[1].args[1] isa Symbol
+        name = typedef.args[1].args[1]
+    else
+        throw(ArgumentError("Can't find the layout name!"))
+    end
+
+    fname = Symbol(lowercase(String(name)))
+    return quote
+        Base.@__doc__ $(esc(expr))
+        Base.@__doc__ $(esc(fname))(g; kwargs...) = layout($name(; kwargs...), g)
+    end
+end
+
 include("sfdp.jl")
 include("buchheim.jl")
 include("spring.jl")

src/buchheim.jl

@@ -1,10 +1,10 @@
-export Buchheim
+export Buchheim, buchheim
 
 """
     Buchheim(; kwargs...)(adj_matrix)
     Buchheim(; kwargs...)(adj_list)
-    layout(algo::Buchheim, adj_matrix)
-    layout(algo::Buchheim, adj_list)
+    buchheim(adj_matrix; kwargs...)
+    buchheim(adj_list; kwargs...)
 
 Using the algorithm proposed in the paper,
 ["Improving Walker's Algorithm to Run in Linear Time"](http://dirk.jivas.de/papers/buchheim02improving.pdf)
@@ -20,7 +20,7 @@ and returns coordinates of the nodes.
   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.
 """
-struct Buchheim{Ptype,T} <: AbstractLayout{2,Ptype}
+@addcall struct Buchheim{Ptype,T} <: AbstractLayout{2,Ptype}
     nodesize::Vector{T}
 end
 

src/sfdp.jl

@@ -1,8 +1,8 @@
-export SFDP
+export SFDP, sfdp
 
 """
     SFDP(; kwargs...)(adj_matrix)
-    layout(algo::SFDP, adj_matrix)
+    sfdp(adj_matrix; kwargs...)
 
 Using the Spring-Electric [model suggested by Yifan Hu](http://yifanhu.net/PUB/graph_draw_small.pdf).
 Forces are calculated as:
@@ -25,7 +25,7 @@ the nodes.
 
 - `seed=1`: Seed for random initial positions.
 """
-struct SFDP{Dim,Ptype,T<:AbstractFloat} <: IterativeLayout{Dim,Ptype}
+@addcall struct SFDP{Dim,Ptype,T<:AbstractFloat} <: IterativeLayout{Dim,Ptype}
     tol::T
     C::T
     K::T

src/shell.jl

@@ -1,8 +1,8 @@
-export Shell
+export Shell, shell
 
 """
     Shell(; kwargs...)(adj_matrix)
-    layout(algo::Shell, 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
@@ -21,7 +21,7 @@ the nodes.
 
 This function started as a copy from [IainNZ](https://github.com/IainNZ)'s [GraphLayout.jl](https://github.com/IainNZ/GraphLayout.jl)
 """
-struct Shell{Ptype} <: AbstractLayout{2,Ptype}
+@addcall struct Shell{Ptype} <: AbstractLayout{2,Ptype}
     nlist::Vector{Vector{Int}}
 end
 

src/spectral.jl

@@ -1,10 +1,10 @@
 using LinearAlgebra: diag, eigen, Diagonal
 
-export Spectral
+export Spectral, spectral
 
 """
     Spectral(; kwargs...)(adj_matrix)
-    layout(algo::Spectral, adj_matrix)
+    spectral(adj_matrix; kwargs...)
 
 This algorithm uses the technique of Spectral Graph Drawing, which is an
 under-appreciated method of graph layouts; easier, simpler, and faster
@@ -23,7 +23,7 @@ the nodes.
   Vector of weights. If network size does not match the length of `nodesize` use
   `ones` instead.
 """
-struct Spectral{Ptype,FT<:AbstractFloat} <: AbstractLayout{3,Ptype}
+@addcall struct Spectral{Ptype,FT<:AbstractFloat} <: AbstractLayout{3,Ptype}
     nodeweights::Vector{FT}
 end
 

src/spring.jl

@@ -1,8 +1,8 @@
-export Spring
+export Spring, spring
 
 """
     Spring(; kwargs...)(adj_matrix)
-    layout(algo::Spring, adj_matrix)
+    spring(adj_matrix; kwargs...)
 
 Use the spring/repulsion model of Fruchterman and Reingold (1991) with
 
@@ -28,7 +28,7 @@ the nodes.
 
 - `seed=1`: Seed for random initial positions.
 """
-struct Spring{Dim,Ptype} <: IterativeLayout{Dim,Ptype}
+@addcall struct Spring{Dim,Ptype} <: IterativeLayout{Dim,Ptype}
     C::Float64
     iterations::Int
     initialtemp::Float64

src/squaregrid.jl

@@ -1,8 +1,8 @@
-export SquareGrid
+export SquareGrid, squaregrid
 
 """
     SquareGrid(; kwargs...)(adj_matrix)
-    layout(algo::SquareGrid, adj_matrix)
+    squaregrid(adj_matrix; kwargs...)
 
 Position nodes on a 2 dimensional rectagular grid. The nodes are palced in order
 from upper left to lower right. To skip positions see `skip` argument.
@@ -18,7 +18,7 @@ the nodes.
   `skip=[(i,j)]` means to keep the position in the `i`-th row and `j`-th column
   empty.
 """
-struct SquareGrid{Ptype,CT} <: AbstractLayout{2,Ptype}
+@addcall struct SquareGrid{Ptype,CT} <: AbstractLayout{2,Ptype}
     cols::CT
     dx::Ptype
     dy::Ptype

src/stress.jl

@@ -1,11 +1,11 @@
 using LinearAlgebra: checksquare, norm, pinv, mul!
 using SparseArrays: SparseMatrixCSC
 
-export Stress
+export Stress, stress
 
 """
     Stress(; kwargs...)(adj_matrix)
-    layout(algo::Stress, 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.
@@ -61,8 +61,8 @@ The main equation to solve is (8) of:
         pages={239--250},
     }
 """
-struct Stress{Dim,Ptype,IT<:Union{Symbol,Int},FT<:AbstractFloat,M<:AbstractMatrix} <:
-       IterativeLayout{Dim,Ptype}
+@addcall struct Stress{Dim,Ptype,IT<:Union{Symbol,Int},FT<:AbstractFloat,M<:AbstractMatrix} <:
+                IterativeLayout{Dim,Ptype}
     iterations::IT
     abstols::FT
     reltols::FT

test/runtests.jl

@@ -58,8 +58,10 @@ jagmesh_adj = jagmesh()
             adj_matrix = adjacency_matrix(g)
             positions = @time SFDP(; dim=2, Ptype=Float32, tol=0.1, K=1)(adj_matrix)
             @test typeof(positions) == Vector{Point2f0}
+            @test positions == sfdp(adj_matrix; dim=2, Ptype=Float32, tol=0.1, K=1)
             positions = @time SFDP(; dim=3, Ptype=Float32, tol=0.1, K=1)(adj_matrix)
             @test typeof(positions) == Vector{Point3f0}
+            @test positions == sfdp(adj_matrix; dim=3, Ptype=Float32, tol=0.1, K=1)
         end
     end
 
@@ -105,8 +107,10 @@ jagmesh_adj = jagmesh()
             adj_matrix = adjacency_matrix(g)
             positions = @time Stress(; iterations=10, Ptype=Float32)(adj_matrix)
             @test typeof(positions) == Vector{Point2f0}
+            @test positions == stress(adj_matrix; iterations=10, Ptype=Float32)
             positions = @time Stress(; iterations=10, dim=3, Ptype=Float32)(adj_matrix)
             @test typeof(positions) == Vector{Point3f0}
+            @test positions == stress(adj_matrix; iterations=10, dim=3, Ptype=Float32)
         end
     end
 
@@ -143,8 +147,11 @@ jagmesh_adj = jagmesh()
             adj_matrix = adjacency_matrix(g)
             positions = @time Spring(; C=2.0, iterations=100, initialtemp=2.0, Ptype=Float32)(adj_matrix)
             @test typeof(positions) == Vector{Point2f0}
+            @test positions == spring(adj_matrix; C=2.0, iterations=100, initialtemp=2.0, Ptype=Float32)
             positions = @time Spring(; C=2.0, iterations=100, initialtemp=2.0, Ptype=Float32, dim=3)(adj_matrix)
             @test typeof(positions) == Vector{Point3f0}
+            @test positions ==
+                  spring(adj_matrix; C=2.0, iterations=100, initialtemp=2.0, Ptype=Float32, dim=3)
         end
     end
 
@@ -155,8 +162,10 @@ jagmesh_adj = jagmesh()
             adj_matrix = adjacency_matrix(g)
             positions = @time Spectral()(adj_matrix)
             @test typeof(positions) == Vector{Point{3,Float64}}
+            @test positions == spectral(adj_matrix)
             positions = @time Spectral(; Ptype=Float32)(adj_matrix)
             @test typeof(positions) == Vector{Point{3,Float32}}
+            @test positions == spectral(adj_matrix; Ptype=Float32)
         end
     end
 
@@ -168,6 +177,7 @@ jagmesh_adj = jagmesh()
             adj_matrix = adjacency_matrix(g)
             positions = @time Shell()(adj_matrix)
             @test typeof(positions) == Vector{Point{2,Float64}}
+            @test positions == shell(adj_matrix)
         end
         @testset "Testing Base Case" begin
             g = Graph(1)
@@ -206,6 +216,7 @@ jagmesh_adj = jagmesh()
             nodesize = [1, 2, 1.5, 3, 0.5, 1, 1]
             locs = @time Buchheim(; nodesize)(adj_list)
             @test typeof(locs) == Vector{Point{2,Float64}}
+            @test locs == buchheim(adj_list; nodesize)
             locs = @time Buchheim(; Ptype=Float32)(adj_list)
             @test typeof(locs) == Vector{Point{2,Float32}}
         end
@@ -234,14 +245,17 @@ jagmesh_adj = jagmesh()
             M = adjacency_matrix(SimpleGraph(4))
             positions = SquareGrid(; Ptype=Int)(M)
             @test positions == Point2.([(0, 0), (1, 0), (0, -1), (1, -1)])
+            @test positions == squaregrid(M; Ptype=Int)
 
             M = adjacency_matrix(SimpleGraph(3))
             positions = SquareGrid(; Ptype=Int)(M)
             @test positions == Point2.([(0, 0), (1, 0), (0, -1)])
+            @test positions == squaregrid(M; Ptype=Int)
 
             M = adjacency_matrix(SimpleGraph(5))
             positions = SquareGrid(; Ptype=Int, cols=2)(M)
             @test positions == Point2.([(0, 0), (1, 0), (0, -1), (1, -1), (0, -2)])
+            @test positions == squaregrid(M; Ptype=Int, cols=2)
         end
 
         @testset "Testing dx,dy" begin
@@ -266,16 +280,16 @@ jagmesh_adj = jagmesh()
 
     @testset "test assert square" begin
         using NetworkLayout: assertsquare
-        M1 = rand(2,4)
+        M1 = rand(2, 4)
         @test_throws ArgumentError assertsquare(M1)
-        M2 = rand(4,4)
+        M2 = rand(4, 4)
         @test assertsquare(M2) == 4
-        @test_throws ArgumentError layout(Buchheim(), M1)
-        @test_throws ArgumentError layout(SFDP(), M1)
-        @test_throws ArgumentError layout(Shell(), M1)
-        @test_throws ArgumentError layout(Spectral(), M1)
-        @test_throws ArgumentError layout(Spring(), M1)
-        @test_throws ArgumentError layout(SquareGrid(), M1)
-        @test_throws ArgumentError layout(Stress(), M1)
+        @test_throws ArgumentError buchheim(M1)
+        @test_throws ArgumentError sfdp(M1)
+        @test_throws ArgumentError shell(M1)
+        @test_throws ArgumentError spectral(M1)
+        @test_throws ArgumentError spring(M1)
+        @test_throws ArgumentError squaregrid(M1)
+        @test_throws ArgumentError stress(M1)
     end
 end