Merge branch 'main' of https://github.com/JuliaGraphs/MultilayerGraphs.jl

Author: InterdisciplinaryPhysicsTeam

src/abstractmultilayerdigraph.jl

@@ -1,7 +1,3 @@
-# ne
-# has_edge
-# edges
-
 """
     AbstractMultilayerDiGraph{T,U} <: AbstractMultilayerGraph{T,U} 
 
@@ -48,7 +44,6 @@ function Graphs.rem_vertex!(mg::AbstractMultilayerDiGraph, V::MultilayerVertex)
 
     # Get the v corresponding to V, delete the association and replace it with a MissingVertex. Also substitute the metadata with an empty NamedTuple
     v = get_v(mg, V)
-
     forward_halfedges_to_be_deleted = mg.fadjlist[v]
 
     # Loop over the halfedges to be removed in  `forward_halfedges_to_be_deleted`, get their v and remove halfedges to `V` in their corresponding arrays
@@ -100,7 +95,6 @@ function Graphs.rem_vertex!(mg::AbstractMultilayerDiGraph, V::MultilayerVertex)
         delete!(mg.v_V_associations, v)
         delete!(mg.v_metadata_dict, v)
     end
-
     return true
 
 end
@@ -112,11 +106,11 @@ end
 Return true if `mg` has edge between the `src` and `dst` (does not check edge or vertex metadata).
 """
 function Graphs.has_edge(mg::M, src::T, dst::T) where { T,M <: AbstractMultilayerDiGraph{T}}
-
+    # Returns true if src is a vertex of mg
     has_vertex(mg,src) || return false
+    # Returns true if dst is a vertex of mg
     has_vertex(mg,dst) || return false
 
-
     halfedges_from_src = mg.fadjlist[src]
     halfedges_to_dst   = mg.badjlist[dst]
 
@@ -127,57 +121,56 @@ function Graphs.has_edge(mg::M, src::T, dst::T) where { T,M <: AbstractMultilaye
         srcs_v = get_v.(Ref(mg), vertex.(halfedges_to_dst))
         return src in srcs_v
     end
-    
 end
 
-
 """
     set_weight!(mg::M, src::MultilayerVertex{L1}, dst::MultilayerVertex{L2}, weight::U) where {L1 <: Symbol, L2 <: Symbol, T,U, M <: AbstractMultilayerGraph{T,U}}
 
 Set the weight of the edge between `src` and `dst` to `weight`. Return true if succeeds (i.e. if the edge exists and the underlying graph chosen for the Layer/Interlayer where the edge lies is weighted under the `IsWeighted` trait).
 """
 function set_weight!(mg::M, src::MultilayerVertex, dst::MultilayerVertex, weight::U) where { T,U, M <: AbstractMultilayerDiGraph{T,U}}
+    # Get the subgraph descriptor for the layer containing both src and dst
     descriptor = get_subgraph_descriptor(mg, layer(src), layer(dst))
+    # Check if the subgraph is weighted
     is_weighted(descriptor.null_graph) || return false
+    # Check if an edge exists between src and dst
     has_edge(mg, src, dst) ||  return false
-
+    # Get the halfedge from src to dst
     halfedges_from_src = mg.fadjlist[get_v(mg, src)]
     halfedge_from_src = halfedges_from_src[findfirst(he -> vertex(he) == dst, halfedges_from_src)]
+    # Set the weight of the halfedge from src to dst
     halfedge_from_src.weight = weight
-
+    # Get the halfedge from dst to src
     halfedges_to_dst = mg.badjlist[get_v(mg, dst)]
     halfedge_to_dst = halfedges_to_dst[findfirst(he -> vertex(he) == src, halfedges_to_dst)]
+    # Set the weight of the halfedge from dst to src
     halfedge_to_dst.weight = weight
-
     return true
-
 end
 
-
-
 """
     set_metadata!(mg::M, src::MultilayerVertex{L1}, dst::MultilayerVertex{L2}, metadata::U) where {L1 <: Symbol, L2 <: Symbol, T,U, M <: AbstractMultilayerGraph{T,U}}
 
 Set the metadata of the edge between `src` and `dst` to `metadata`. Return true if succeeds (i.e. if the edge exists and the underlying graph chosen for the Layer/Interlayer where the edge lies supports metadata at the edge level  under the `IsMeta` trait).
 """
 function set_metadata!(mg::M, src::MultilayerVertex, dst::MultilayerVertex, metadata::Union{Tuple, NamedTuple}) where M <: AbstractMultilayerDiGraph
+    # Get the subgraph descriptor that corresponds to the layer of src and dst
     descriptor = get_subgraph_descriptor(mg, layer(src), layer(dst))
+    # If the subgraph descriptor's null graph is true, then the edge does not exist
     is_meta(descriptor.null_graph) || return false
+    # If the edge does not exist, return false
     has_edge(mg, src, dst) ||  return false
-
+    # Set the halfedge from src to dst
     halfedges_from_src = mg.fadjlist[get_v(mg, src)]
     halfedge_from_src = halfedges_from_src[findfirst(he -> vertex(he) == dst, halfedges_from_src)]
     halfedge_from_src.metadata = metadata
-
+    # Set the halfedge from dst to src
     halfedges_to_dst = mg.badjlist[get_v(mg, dst)]
     halfedge_to_dst = halfedges_to_dst[findfirst(he -> vertex(he) == src, halfedges_to_dst)]
     halfedge_to_dst.metadata = metadata
-
     return true
-
 end
 
-
 # Overloads that make AbstractMultilayerDiGraph an extension of Graphs.jl. These are all well-inferred .
 """
     edges(mg::M) where {T,U,M<:AbstractMultilayerDiGraph{T,U}}
@@ -389,18 +382,19 @@ end
 return _inneighbors
 end
 
-
-# function get_overlay_monoplex_graph end #approach taken from https://github.com/JuliaGraphs/Graphs.jl/blob/7152d540631219fd51c43ab761ec96f12c27680e/src/core.jl#L124
 """
     get_overlay_monoplex_graph(mg::M) where {M<: AbstractMultilayerDiGraph}
 Get overlay monoplex graph (i.e. the graph that has the same nodes as `mg` but the link between node `i` and `j` has weight equal to the sum of all edges weights between the various vertices representing `i` and `j` in `mg`, accounting for both layers and interlayers). See [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022).
 """
 function get_overlay_monoplex_graph(mg::M) where {T,U,M<:AbstractMultilayerDiGraph{T,U}}
+    # Convert the multilayer graph to a weight tensor
     wgt = weight_tensor(mg).array
+    # Sum the weights for each edge in the multilayer graph
     projected_overlay_adjacency_matrix = sum([
         wgt[:, :, i, i] for i in 1:size(wgt, 3)
     ])
     return SimpleWeightedDiGraph{T,U}(
         projected_overlay_adjacency_matrix
     )
+    # Approach taken from https://github.com/JuliaGraphs/Graphs.jl/blob/7152d540631219fd51c43ab761ec96f12c27680e/src/core.jl#L124
 end

src/subgraphs/interlayer.jl

@@ -81,7 +81,7 @@ end
         
     ) where {T<:Integer, U <: Real, G<:AbstractGraph{T}}
 
-Internal constructor used with InterlayerDescriptor
+Internal constructor used with InterlayerDescriptor.
 """
 function _Interlayer(
     layer_1_multilayervertices::Vector{<: MultilayerVertex},
@@ -336,7 +336,7 @@ multiplex_interlayer(
         forbidden_edges::Vector{NTuple{2, MultilayerVertex}}
     ) where {T <: Union{ <: Integer, AbstractVertex}, G <: AbstractGraph{T}
 
-Internal method for multiplex_interlayer
+Internal method for multiplex_interlayer.
 """
 function _multiplex_interlayer(
     layer_1_multilayervertices::Vector{MultilayerVertex{L1}},
@@ -433,9 +433,7 @@ function _empty_interlayer(
     name::Symbol = Symbol("interlayer_$(layer_1.name)_$(layer_2.name)")
 ) where {L1, L2, T<:Integer, U <: Real, G<:AbstractGraph{T}}
 
-
     edge_list = MultilayerEdge{U}[]
-
     descriptor =  InterlayerDescriptor(L1, L2, null_graph, weighttype; default_edge_weight = default_edge_weight, default_edge_metadata = default_edge_metadata,  transfer_vertex_metadata = transfer_vertex_metadata, name = name)
 
     return _Interlayer(
@@ -452,13 +450,15 @@ end
 Check if `graph`, whose vertices are interpreted via `v_V_associations` can be the underlying bipartite graph of an Interlayer graph.
 """
 function is_interlayer_bipartite(graph::G, v_V_associations::Bijection{T, MultilayerVertex}) where {T, G <: AbstractGraph{T}}
-    
     layers = unique([mv.layer for mv in image(v_V_associations)])
     # If it is an empty interlayer, we assume it is bipartite
     length(layers) == 0 && return true
     length(layers) == 2 || throw(ErrorException("The interlayer cannot be bipartite since more than two layers are involved. Found $layers in v_V_associations."))
+    # This loop iterates through all edges of the graph
     for edge in edges(graph)
+        # This if statement checks if the source and destination of the edge are on the same layer
         if !(v_V_associations[src(edge)].layer != v_V_associations[dst(edge)].layer)
+            # If they are, the graph is not a valid layering
             return false  
         end
     end
@@ -478,7 +478,9 @@ function is_multiplex_interlayer(interlayer::Interlayer)
         end
         return true
     else
+        # Loop through all nodes in both layers.
         for node in intersect(interlayer.layer_1_nodes, interlayer.layer_2_nodes)
+            # Check if there is an edge between the nodes in both layers.
             has_edge(interlayer, MV(node, interlayer.layer_1), MV(node, interlayer.layer_2)) || return false
         end
         return true
@@ -490,7 +492,7 @@ end
 
 Return `true` if `n` is a `Node` of `interlayer`.
 """
-has_node( interlayer::Interlayer, n::Node ) =  n in nodes(interlayer.layer_1) || n in nodes(interlayer.layer_2) 
+has_node(interlayer::Interlayer, n::Node ) = n in nodes(interlayer.layer_1) || n in nodes(interlayer.layer_2) 
 
 
 """
@@ -504,7 +506,6 @@ Graphs.has_vertex(interlayer::Interlayer, mv::MultilayerVertex) = get_bare_mv(mv
 """
 """
 function Graphs.add_edge!(interlayer::In, src::MultilayerVertex, dst::MultilayerVertex, args...; kwargs...) where { In <: Interlayer} 
-
     src_bare = get_bare_mv(src)
     dst_bare = get_bare_mv(dst)
     !has_vertex(interlayer, src)  && throw( ErrorException( "Vertex $(src) does not belong to the interlayer."))
@@ -545,10 +546,9 @@ end
     Base.getproperty(interlayer::In, f::Symbol) where { In <: Interlayer}
 """
 function Base.getproperty(interlayer::In, f::Symbol) where {In<:Interlayer}
-
     if f ∈(:descriptor, :graph, :v_V_associations)
-            Base.getfield(interlayer, f)
-    elseif f ∈ (:name, :layer_1, :layer_2, :null_graph, :default_edge_weight, :default_edge_metadata,  :transfer_vertex_metadata) # edge_weight_function:, :edge_metadata_function,
+        Base.getfield(interlayer, f)
+    elseif f ∈ (:name, :layer_1, :layer_2, :null_graph, :default_edge_weight, :default_edge_metadata,  :transfer_vertex_metadata) 
         Base.getfield(interlayer.descriptor, f)
     elseif f == :edge_list
         edges(interlayer)
@@ -578,19 +578,19 @@ end
 """
     get_symmetric_interlayer(interlayer::In; symmetric_interlayer_name::String) where{T,U,G, In <: Interlayer{T,U,G}}
 
-Return the `Interlayer` corresponding to `interlayer` where `layer_1` and `layer_2` are swapped. Its name will be `symmetric_interlayer_name` (defaults to `interlayer_(interlayer.layer_2)_(interlayer.layer_1)` ).
+Return the `Interlayer` corresponding to `interlayer` where `layer_1` and `layer_2` are swapped. Its name will be `symmetric_interlayer_name` (defaults to `interlayer_(interlayer.layer_2)_(interlayer.layer_1)`).
 """
 function get_symmetric_interlayer(
     interlayer::In;
     symmetric_interlayer_name::String = String(interlayer.name) * "_rev"
 ) where {T,U,G,In<:Interlayer{T,U,G}}
-
+    # Create a symmetric interlayer descriptor
     symmetric_descriptor = InterlayerDescriptor(Symbol(symmetric_interlayer_name), interlayer.layer_2, interlayer.layer_1, interlayer.null_graph, interlayer.default_edge_weight, interlayer.default_edge_metadata, interlayer.transfer_vertex_metadata, U)
-
+    # Create a symmetrized interlayer with the symmetric descriptor
     symmetrized_interlayer = Interlayer(symmetric_descriptor, interlayer.graph, interlayer.v_V_associations)
-
+    # Recompute the interlayer, using the layer 1 and layer 2 vertices from the original interlayer
     recompute_interlayer!(symmetrized_interlayer, symmetrized_interlayer.layer_1_bare_multilayer_vertices, symmetrized_interlayer.layer_2_bare_multilayer_vertices)
-
+    # Return the symmetrized interlayer
     return symmetrized_interlayer
 end
 

src/vertices/abstractgraphvertex.jl

@@ -1,3 +1,2 @@
 abstract type AbstractGraphVertex{G <: AbstractGraph} end
-
-struct LayerVertex{L} <: AbstractGraphVertex{G} end
+struct LayerVertex{L} <: AbstractGraphVertex{G} end

src/vertices/multilayervertex.jl

@@ -112,5 +112,5 @@ function compare_multilayervertices(V1::MultilayerVertex, V2::MultilayerVertex;
 end
 
 # Console print utilities
-to_string( x::M) where {S  , M <: MultilayerVertex{S}} = "MV($(x.node), :$(x.layer), $(x.metadata))" #{:$S}
+to_string( x::M) where {S  , M <: MultilayerVertex{S}} = "MV($(x.node), :$(x.layer), $(x.metadata))" 
 Base.show(io::IO, x::MultilayerVertex) = print(io, to_string(x))