Merge pull request #55 from JuliaGraphs/default_layer_constructors

General improvements to the user experience

Author: pitmonticone

Project.toml

@@ -13,6 +13,7 @@ IterTools = "c8e1da08-722c-5040-9ed9-7db0dc04731e"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MetaGraphs = "626554b9-1ddb-594c-aa3c-2596fe9399a5"
 OMEinsum = "ebe7aa44-baf0-506c-a96f-8464559b3922"
+PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 SimpleTraits = "699a6c99-e7fa-54fc-8d76-47d257e15c1d"
 SimpleValueGraphs = "b43c691f-cac2-5415-8122-396fe16a49fc"
 SimpleWeightedGraphs = "47aef6b3-ad0c-573a-a1e2-d07658019622"

README.md

@@ -54,7 +54,10 @@ In the package documentation you can find a [tutorial](https://juliagraphs.org/M
 - [ ] [Implement more general configuration models / graph generators](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/33);
 - [ ] [Implement graph of layers](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/34);
 - [ ] [Implement projected monoplex and overlay graphs](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/35);
-- [ ] [Implement more default multilayer graphs](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/36) (e.g. multiplex graphs).
+- [ ] [Implement more default multilayer graphs](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/36) (e.g. multiplex graphs);
+- [ ] [Implement configuration models / graph generators for interlayers](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/46);
+- [ ] [Relax the requirement of same `T` and `U` for all `Layer`s and `Interlayer`s that are meant to constitute a `Multilayer(Di)Graph`](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/53);
+- [ ] [Implement multilayer graph data visualisation functionalities (or a new package)](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/54).
 
 ## How to Contribute 
 

docs/src/API.md

@@ -50,6 +50,16 @@ Layer(
     allow_self_loops::Bool = false
 ) where {T<:Integer, U <: Real, G<:AbstractGraph{T}}
 
+layer_simplegraph
+layer_simpledigraph
+layer_simpleweightedgraph
+layer_simpleweighteddigraph
+layer_metadigraph
+layer_valgraph
+layer_valoutdigraph
+layer_valdigraph
+layer_metagraph
+
 has_node(layer::Layer, n::Node)
 add_vertex!(layer::Layer, mv::MultilayerVertex)
 add_vertex!(layer::L, n::Node, args...; kwargs...) where {T, L <: Layer{T}} 
@@ -80,6 +90,16 @@ Interlayer(
     transfer_vertex_metadata::Bool = false
 ) where {T<:Integer, U <: Union{Nothing, <: Real},  G<:AbstractGraph{T}}
 
+interlayer_simplegraph
+interlayer_simpleweightedgraph
+interlayer_metagraph
+interlayer_valgraph
+interlayer_simpledigraph
+interlayer_simpleweighteddigraph
+interlayer_metadigraph
+interlayer_valoutdigraph
+interlayer_valdigraph
+
 
 multiplex_interlayer(
     layer_1::Layer{T,U},
@@ -112,6 +132,7 @@ mv_outneighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
 mv_neighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
 has_edge(subgraph::AbstractSubGraph,me::MultilayerEdge)
 has_edge( subgraph::AbstractSubGraph, s::MultilayerVertex, d::MultilayerVertex)
+has_edge( layer::Layer, s::MultilayerVertex{nothing}, d::MultilayerVertex{nothing})
 ne(subgraph::AbstractSubGraph)
 edges(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}} 
 add_edge!( subgraph::S, me::E) where {T,U<:Real,S<:AbstractSubGraph{T,U},E<:MultilayerEdge{ <: Union{U, Nothing}}}
@@ -126,14 +147,16 @@ is_directed(subgraph::AbstractSubGraph)
 is_directed(::Type{S}) where {T,U,G,S <: AbstractSubGraph{T,U,G}}
 adjacency_matrix(subgraph::AbstractSubGraph)
 MultilayerGraphs.weights(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}}
-name(subgraph::AbstractSubGraph)
- 
+
 is_multiplex_interlayer(interlayer::Interlayer)
 
 get_symmetric_interlayer(
     interlayer::In;
     symmetric_interlayer_name::String = String(interlayer.name) * "_rev"
 ) where {T,U,G,In<:Interlayer{T,U,G}}
+
+name(subgraph::AbstractSubGraph)
+graph(subgraph::AbstractSubGraph)
 ```
 
 ### [Multilayer-Specific Methods](@id msm_eu)

docs/src/index.md

@@ -14,7 +14,7 @@
 
 # The δ_Ω implementation could be moved to a separate file.
 
-# The usage of mutable `MissingVertex`s (although limited to SupraWeightMatrix) points to the fact that Bijections (at least as they are used right now) are not the best way to represent integer label-MultilayerVertex associations. We my implement our own container object or use the exixtsing ons differently.
+# The usage of mutable `MissingVertex`s (although limited to SupraWeightMatrix) points to the fact that Bijections (at least as they are used right now) are not the best way to represent integer label-MultilayerVertex associations. We my implement our own container object or use the existing ons differently.
 
 # We need a quick Multilayer(Di)Graph constructor of the form Multilayer(Di)Graph(nn, nl; nv = rand(0:nn*nl), ne = rand(0:nv*(nv-1)) kwargs...) where kwargs may be used to further specify it.
 
@@ -59,6 +59,7 @@ export
     mv_outneighbors,
     neighbors,
     mv_neighbors,
+    get_v,
     edgetype,
     has_edge,
     ne,
@@ -71,15 +72,34 @@ export
     adjacency_matrix,
     weights,
     name,
+    graph,
     # layer.jl
     AbstractLayer,
     Layer,
+    layer_simplegraph,
+    layer_simpledigraph,
+    layer_simpleweightedgraph,
+    layer_simpleweighteddigraph,
+    layer_metadigraph,
+    layer_valgraph,
+    layer_valoutdigraph,
+    layer_valdigraph,
+    layer_metagraph,
     has_node,
     add_vertex!,
     rem_vertex!,
     # interlayer.jl
     AbstractInterlayer,
     Interlayer,
+    interlayer_simplegraph,
+    interlayer_simpleweightedgraph,
+    interlayer_metagraph,
+    interlayer_valgraph,
+    interlayer_simpledigraph,
+    interlayer_simpleweighteddigraph,
+    interlayer_metadigraph,
+    interlayer_valoutdigraph,
+    interlayer_valdigraph,
     multiplex_interlayer,
     empty_interlayer,
     is_multiplex_interlayer,
@@ -151,7 +171,7 @@ export
     kleitman_wang_graph_generator
 # tensorfacoriazations.jl
 
-using Base, InteractiveUtils, IterTools, SimpleTraits, Bijections
+using Base, InteractiveUtils, IterTools, SimpleTraits, Bijections, PrettyTables
 using Distributions: Uniform
 using LinearAlgebra, Statistics, OMEinsum, TensorOperations, Distributions
 using DataStructures, SparseArrays
@@ -163,6 +183,7 @@ include("vertices/multilayervertex.jl")
 include("vertices/missingvertex.jl")
 include("multilayeredge.jl")
 include("halfedge.jl")
+include("subgraphs/abstractdescriptor.jl")
 include("subgraphs/layerdescriptor.jl")
 include("subgraphs/interlayerdescriptor.jl")
 include("subgraphs/abstractsubgraph.jl")

src/MultilayerGraphs.jl

@@ -496,8 +496,8 @@ function _specify_interlayer!(
         new_interlayer.descriptor
 
     for edge in edges(new_interlayer)
-        success = add_edge!(mg, edge)
-        @assert success
+        @assert add_edge!(mg, edge)
+        # assert success
     end
 
     return true
@@ -1188,9 +1188,64 @@ function get_rich_mv(
 ) where {T,U,M<:AbstractMultilayerGraph{T,U}}
     if perform_checks
         haskey(mg.v_V_associations, i) ||
-            throw(ErrorException("$i is not a vertex of the multilayer graph"))
+            throw(ErrorException("$i is not a vertex of the multilayer graph."))
     end
 
     bare_V = mg.v_V_associations[i]
     return MV(bare_V.node, bare_V.layer, mg.v_metadata_dict[i])
 end
+
+# Console print utilities
+function to_string(x::AbstractMultilayerGraph)
+    unionall_type = typeof(x).name.wrapper
+    parameters = typeof(x).parameters
+
+    layers_names = name.(x.layers)
+    layers_underlying_graphs = typeof.(graph.(x.layers))
+
+    layers_table = pretty_table(
+        String,
+        hcat(layers_names, layers_underlying_graphs);
+        title="### LAYERS",
+        header=(["NAME", "UNDERLYING GRAPH"]),
+        alignment=:c,
+        header_alignment=:c,
+        header_crayon=crayon"yellow bold",
+        hlines=:all,
+    )
+
+    interlayers_names = name.(values(x.interlayers))
+    interlayers_underlying_graphs = typeof.(graph.(values(x.interlayers)))
+    interlayer_layer_1s = getproperty.(values(x.interlayers), Ref(:layer_1))
+    interlayer_layer_2s = getproperty.(values(x.interlayers), Ref(:layer_2))
+    interlayer_tranfers =
+        getproperty.(values(x.interlayers), Ref(:transfer_vertex_metadata))
+
+    interlayers_table = pretty_table(
+        String,
+        hcat(
+            interlayers_names,
+            interlayer_layer_1s,
+            interlayer_layer_2s,
+            interlayers_underlying_graphs,
+            interlayer_tranfers,
+        );
+        title="### INTERLAYERS",
+        header=([
+            "NAME", "LAYER 1", "LAYER 2", "UNDERLYING GRAPH", "TRANSFER VERTEX METADATA"
+        ]),
+        alignment=:c,
+        header_alignment=:c,
+        header_crayon=crayon"yellow bold",
+        hlines=:all,
+    )
+
+    return """
+           `$unionall_type` with vertex type `$(parameters[1])` and weight type `$(parameters[2])`.
+
+           $layers_table
+
+           $interlayers_table
+           """
+end
+Base.show(io::IO, x::AbstractMultilayerGraph) = print(io, to_string(x))

src/abstractmultilayergraph.jl

@@ -272,13 +272,9 @@ function get_subgraph(
         v for (v, mv) in collect(mg.v_V_associations) if mv.layer == descriptor.name
     ])
 
-    _vertices = get_rich_mv.(Ref(mg), vs)#MultilayerVertex{descriptor.name}[]
+    _vertices = get_rich_mv.(Ref(mg), vs)
 
-    #=     for (v,mv) in zip(vs, getindex.(Ref(mg.v_V_associations),vs))
-            push!(_vertices, get_rich_mv(mg, v)) #MV(mv.node, mv.layer, mg.v_metadata_dict[v] )
-        end
-     =#
-    edge_list = MultilayerEdge{U}[]#MultilayerEdge{U}[MultilayerEdge(src, vertex(halfedge),  weight(halfedge), metadata(halfedge)) for (src,halfedge) in zip(_vertices,mg.fadjlist[vs]) if vertex(halfedge).layer == descriptor.name && get_v(mg, vertex(halfedge)) >= get_v(mg,src) ]
+    edge_list = MultilayerEdge{U}[]
 
     for (src_v, halfedges_from_src) in zip(vs, getindex.(Ref(mg.fadjlist), vs))
         src_bare_V = mg.v_V_associations[src_v]

src/abstractmultilayerugraph.jl

@@ -63,7 +63,9 @@ function _add_edge!(
 ) where {T<:Integer,W<:Union{<:Real,Nothing}}
     (isnothing(weight) || weight == 1.0) ||
         @warn "Trying to add a weighted edge to an unweighted graph of type $(typeof(g)). Weight $weight will be ignored."
-    return add_edge!(g, src, dst, Dict(key => value for (key, value) in pairs(metadata)))
+    return add_edge!(
+        g, src, dst, Dict(Symbol(pair.first) => pair.second for pair in pairs(metadata))
+    ) #Symbol(string(key)) => value for (key, value) in pairs(metadata)
 end
 
 function _get_edge_weight(

src/graphs_extensions/metagraphs.jl

@@ -32,7 +32,7 @@ vertex(he::HalfEdge) = he.vertex
 
 Return the weight of the edge.
 """
-weight(he::HalfEdge) = he.weight
+SimpleWeightedGraphs.weight(he::HalfEdge) = he.weight
 """
     metadata(he::HalfEdge) 
 

src/halfedge.jl

@@ -9,7 +9,7 @@ mutable struct MultilayerDiGraph{T,U} <: AbstractMultilayerDiGraph{T,U}
     v_V_associations::Bijection{T,<:MultilayerVertex} # A Bijection from Bijections.jl that associates numeric vertices to `MultilayerVertex`s.
     idx_N_associations::Bijection{Int64,Node} # A Bijection from Bijections.jl that associates Int64 to `Node`s.
     fadjlist::Vector{Vector{HalfEdge{<:MultilayerVertex,<:Union{Nothing,U}}}} # the forward adjacency list of the MultilayerDiGraph. It is a vector of vectors of `HalfEdge`s. Its i-th element are the `HalfEdge`s that originate from `v_V_associations[i]`.
-    badjlist::Vector{Vector{HalfEdge{<:MultilayerVertex,<:Union{Nothing,U}}}} # the bacward adjacency list of the MultilayerDiGraph. It is a vector of vectors of `HalfEdge`s. Its i-th element are the `HalfEdge`s that insost on `v_V_associations[i]`.
+    badjlist::Vector{Vector{HalfEdge{<:MultilayerVertex,<:Union{Nothing,U}}}} # the backward adjacency list of the MultilayerDiGraph. It is a vector of vectors of `HalfEdge`s. Its i-th element are the `HalfEdge`s that insist on `v_V_associations[i]`.
     v_metadata_dict::Dict{T,<:Union{<:Tuple,<:NamedTuple}} # A Dictionary that associates numeric vertices to their metadata
 end
 
@@ -162,12 +162,6 @@ function MultilayerDiGraph(
         ),
     )
 
-    minimum(support(indegree_distribution)) >= 0 || throw(
-        ErrorException(
-            "Both the `indegree_distribution` and the `outdegree_distribution` must have positive support. Found $(support(indegree_distribution)) and $(support(outdegree_distribution)).",
-        ),
-    )
-
     empty_multilayerdigraph = MultilayerDiGraph(
         empty_layers,
         empty_interlayers;
@@ -177,23 +171,9 @@ function MultilayerDiGraph(
 
     n = nv(empty_multilayerdigraph)
 
-    indegree_sequence = Vector{Int64}(undef, n)
-    outdegree_sequence = Vector{Int64}(undef, n)
-    acceptable = false
-
-    @info "Trying to sample a digraphical sequence from the two provided distributions..."
-    while !acceptable
-        indegree_sequence .=
-            round.(Ref(Int), rand(indegree_distribution, nv(empty_multilayerdigraph)))
-        outdegree_sequence .=
-            round.(Ref(Int), rand(outdegree_distribution, nv(empty_multilayerdigraph)))
-
-        acceptable = all(0 .<= vcat(indegree_sequence, outdegree_sequence) .< n)
-
-        if acceptable
-            acceptable = isdigraphical(indegree_sequence, outdegree_sequence)
-        end
-    end
+    indegree_sequence, outdegree_sequence = sample_digraphical_degree_sequences(
+        indegree_distribution, outdegree_distribution, n
+    )
 
     return MultilayerDiGraph(
         empty_multilayerdigraph,
@@ -223,7 +203,7 @@ function MultilayerDiGraph(
     perform_checks::Bool=false,
 ) where {T,U}
     (allow_self_loops && perform_checks) &&
-        @warn "Checks for graphicality and coherence with the provided `empty_multilayerdigraph` are currently performed without taking into account self-loops. Thus said checks may fail event though the provided `indegree_sequence` and `outdegree_sequence` may be graphical when one allows for self-loops within the directed multilayer graph to be present. If you are sure that the provided `indegree_sequence` and `outdegree_sequence` are indeed graphical under those circumstances, you may want to disable checks by setting `perform_checks = false`. We apologize for the inconvenient."
+        @warn "Checks for graphicality and coherence with the provided `empty_multilayerdigraph` are currently performed without taking into account self-loops. Thus said checks may fail event though the provided `indegree_sequence` and `outdegree_sequence` may be graphical when one allows for self-loops within the directed multilayer graph to be present. If you are sure that the provided `indegree_sequence` and `outdegree_sequence` are indeed graphical under those circumstances, you may want to disable checks by setting `perform_checks = false`. We apologize for the inconvenience."
 
     _multilayerdigraph = deepcopy(empty_multilayerdigraph)
 
@@ -237,19 +217,19 @@ function MultilayerDiGraph(
         n = nv(_multilayerdigraph)
         n == length(indegree_sequence) == length(outdegree_sequence) || throw(
             ErrorException(
-                "The number of vertices of the provided empty MultilayerDiGraph does not match the length of the `indegree_sequence` or the `outdegree_sequence`. Found $(nv(_multilayerdigraph)) , $(length(indegree_sequence)) and  $(length(outdegree_sequence))",
+                "The number of vertices of the provided empty MultilayerDiGraph does not match the length of the `indegree_sequence` or the `outdegree_sequence`. Found $(nv(_multilayerdigraph)) , $(length(indegree_sequence)) and  $(length(outdegree_sequence)).",
             ),
         )
 
         sum(indegree_sequence) == sum(outdegree_sequence) || throw(
             ErrorException(
-                "The sum of the `indegree_sequence` and the `outdegree_sequence` must match. Found $(sum(indegree_sequence)) and $(sum(outdegree_sequence))",
+                "The sum of the `indegree_sequence` and the `outdegree_sequence` must match. Found $(sum(indegree_sequence)) and $(sum(outdegree_sequence)).",
             ),
         )
 
         isdigraphical(degree_sequence) || throw(
             ArgumentError(
-                "`indegree_sequence` and `outdegree_sequence` must be digraphical"
+                "`indegree_sequence` and `outdegree_sequence` must be digraphical."
             ),
         )
     end