Clean docs and docstrings

Co-Authored-By: Pietro Monticone <[email protected]>
Co-Authored-By: Claudio Moroni <[email protected]>

Author: 3 people

docs/Project.toml

@@ -1,4 +1,5 @@
 [deps]
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 MetaGraphs = "626554b9-1ddb-594c-aa3c-2596fe9399a5"

docs/make.jl

@@ -1,4 +1,5 @@
 using Revise
+using Distributions
 using Graphs
 using MultilayerGraphs
 using Documenter

docs/src/API.md

@@ -8,7 +8,7 @@ This page provides a list of exported methods organized by topic and audience. M
 
 ```@docs
 Node
-
+id
 ```
 
 ### Vertices
@@ -74,6 +74,8 @@ Layer(
 ) where {T<:Integer, U <: Real, G<:AbstractGraph{T}}
 
 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}} 
 rem_vertex!(layer::Layer, mv::MultilayerVertex)
 rem_vertex!(layer::Layer, n::Node)
 
@@ -129,8 +131,6 @@ get_symmetric_interlayer(
     interlayer::In;
     symmetric_interlayer_name::String = String(interlayer.name) * "_rev"
 ) where {T,U,G,In<:Interlayer{T,U,G}}
-
-
 ```
 
 ### Multilayer-Specific Methods
@@ -200,6 +200,10 @@ mv_vertices(mg::AbstractMultilayerGraph)
 mv_inneighbors(mg::AbstractMultilayerGraph, mv::MultilayerVertex)
 mv_outneighbors(mg::AbstractMultilayerGraph, mv::MultilayerVertex)
 mv_neighbors( mg::AbstractMultilayerGraph, mv::MultilayerVertex)
+add_vertex!(mg::M, V::MultilayerVertex) where {T, U, M <: AbstractMultilayerUGraph{T,U}}
+add_vertex!(mg::M, V::MultilayerVertex) where {T, U, M <: AbstractMultilayerDiGraph{T,U}}
+rem_vertex!(mg::AbstractMultilayerUGraph, V::MultilayerVertex)
+rem_vertex!(mg::AbstractMultilayerDiGraph, V::MultilayerVertex)
 has_edge(mg::AbstractMultilayerGraph, edge::MultilayerEdge) 
 has_edge( subgraph::AbstractMultilayerGraph, s::MultilayerVertex, d::MultilayerVertex)
 ne(mg::AbstractMultilayerGraph)
@@ -220,8 +224,6 @@ is_directed(m::M) where { M <: Type{ <: AbstractMultilayerUGraph}}
 is_directed(mg::AbstractMultilayerDiGraph)
 is_directed(m::M) where { M <: Type{ <: AbstractMultilayerDiGraph}}
 has_node(mg::AbstractMultilayerGraph, n::Node)
-rem_vertex!(mg::AbstractMultilayerUGraph, V::MultilayerVertex)
-rem_vertex!(mg::AbstractMultilayerDiGraph, V::MultilayerVertex)
 set_metadata!(mg::AbstractMultilayerGraph, mv::MultilayerVertex, metadata::Union{Tuple, NamedTuple}) 
 set_metadata!(mg::AbstractMultilayerDiGraph, src::MultilayerVertex, dst::MultilayerVertex, metadata::Union{Tuple, NamedTuple})
 set_metadata!(mg::AbstractMultilayerUGraph, src::MultilayerVertex, dst::MultilayerVertex, metadata::Union{Tuple, NamedTuple})
@@ -286,8 +288,6 @@ modularity(
 
 
 von_neumann_entropy(mg::M) where {T,U,M<:AbstractMultilayerUGraph{T,U}}
-
-
 ```
 
 ### Representations
@@ -300,7 +300,6 @@ metadata_tensor(mg::M) where {T,U, M <: AbstractMultilayerGraph{T,U}}
 array(amr::AbstractMatrixRepresentation)
 SupraWeightMatrix{T,U}
 supra_weight_matrix(mg::M) where {T,U, M <: AbstractMultilayerGraph{T,U}}
-
 ```
 
 ### Traits
@@ -312,11 +311,16 @@ is_meta(g::G) where {G <: AbstractGraph}
 is_meta(g::G) where {G<:Type{<:AbstractGraph}}
 ```
 
-
-
-----------------------------------------------------
-####################################################
-----------------------------------------------------
+### Utilities
+```@docs
+multilayer_kronecker_delta(dims::NTuple{4,Int64})
+δk{T}
+δk(N::Int64)
+δ_1{T<: Number}
+δ_2{T<:Number}
+δ_3{T<:Number}
+δ_Ω{T}
+```
 
 
 ## Developer
@@ -346,7 +350,7 @@ metadata(he::MultilayerGraphs.HalfEdge)
 weight(he::MultilayerGraphs.HalfEdge)
 ```
 
-# Subgraphs
+### Subgraphs
 
 ```@docs
 has_vertex(subgraph::S, v::T ) where {T,S<:AbstractSubGraph{T}}
@@ -358,7 +362,7 @@ outneighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
 neighbors(subgraph::S, v::T) where {T,S<:AbstractSubGraph{T}}
 neighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
 edgetype(::S) where {T,U,S<:AbstractSubGraph{T,U}}
-has_edge(subgraph::S, s::MultilayerVertex, d::MultilayerVertex) where { T, S <: AbstractSubGraph{T}}
+has_edge( subgraph::S, s::T, d::T) where {T,S<:AbstractSubGraph{T}}
 add_edge!(subgraph::S, src::T, dst::T; weight::W = nothing, metadata::Union{Tuple, NamedTuple}= NamedTuple()) where {T, U<: Real, W<:Union{ U, Nothing},G<:AbstractGraph{T},S<:AbstractSubGraph{T,U,G}} 
 rem_edge!(subgraph::S, src::T, dst::T) where {T, S<:AbstractSubGraph{T}}
 AbstractLayer
@@ -374,12 +378,10 @@ AbstractInterlayer
 AbstractMultilayerGraph{T <: Integer, U <: Real}
 has_vertex(mg::M, v::T) where {T, M <: AbstractMultilayerGraph{T}}
 vertices(mg::AbstractMultilayerGraph)
-inneighbors(mg::AbstractMultilayerUGraph, v::T) where {T <: Integer, M <: AbstractMultilayerUGraph{T}}
-inneighbors(mg::M, v::T) where {T <: Integer, M <: AbstractMultilayerDiGraph{T}}
+inneighbors(mg::M, v::T) where {T,M<:AbstractMultilayerUGraph{T,<:Real}}
+inneighbors(mg::M, v::T) where {T, M<:AbstractMultilayerGraph{T,<:Real}}
 inneighbors(mg::AbstractMultilayerGraph, mv::MultilayerVertex)
-outneighbors(mg::M, v::T) where {M <: AbstractMultilayerGraph{T} } where { T <: Integer}
-outneighbors(mg::M, v::T) where {M <: AbstractMultilayerGraph{T} } where { T <: Integer}
-outneighbors(mg::M, v::T) where {M <: AbstractMultilayerGraph{T} } where { T <: Integer}
+outneighbors(mg::M, v::T) where {T, M<:AbstractMultilayerGraph{T}}
 neighbors(mg::AbstractMultilayerGraph, mv::MultilayerVertex)
 edgetype(::M) where {T,U,M<:AbstractMultilayerGraph{T,U}}
 has_edge(mg::M, src::T, dst::T) where { T, M <: AbstractMultilayerUGraph{T}}
@@ -399,8 +401,4 @@ AbstractMatrixRepresentation{T,U}
 ```@docs
 IsWeighted{X}
 IsMeta{X}
-```
-
-
-```@docs
-```
+```

docs/src/index.md

@@ -22,9 +22,9 @@ CurrentModule = MultilayerGraphs
 
 A multilayer graph is composed of *layers*, i.e. graphs whose vertices represent the same set of nodes (not all nodes need to be represented in every layer), and *interlayers*, i.e. the [bipartite graphs](https://en.wikipedia.org/wiki/Bipartite_graph) that connect vertices in two different layers. Vertices in a multilayer graph are represented using the [`MultilayerVertex`](@ref) struct, while nodes are represented using the [`Node`](@ref) struct.
 
-[`MultilayerGraph`](@ref) and [`MultilayerDiGraph`](@ref) are fully-fledged [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl) extensions. Both structs are designed to allow for layers and interlayers of any type (as long as they are Graphs.jl extensions themselves) and to permit layers and interlayers of different types. However, it is required that all layers and interlayers in [`MultilayerGraph`](@ref) are undirected, and all layers and interlayers in [`MultilayerDiGraph`](@ref) are directed.
+`MultilayerGraph` and `MultilayerDiGraph` are fully-fledged [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl) extensions. Both structs are designed to allow for layers and interlayers of any type (as long as they are Graphs.jl extensions themselves) and to permit layers and interlayers of different types. However, it is required that all layers and interlayers in `MultilayerGraph` are undirected, and all layers and interlayers in `MultilayerDiGraph` are directed.
 
-[`MultilayerGraph`](@ref) and [`MultilayerDiGraph`](@ref) support the specification of vertex and edge metadata, provided that the underlying layer or interlayer also supports metadata.
+`MultilayerGraph` and `MultilayerDiGraph` support the specification of vertex and edge metadata, provided that the underlying layer or interlayer also supports metadata.
 
 ## Installation
 
@@ -36,7 +36,7 @@ pkg> add MultilayerGraphs
 
 ## Tutorial
 
-Here we illustrate how to define, handle and analyse a [`MultilayerGraph`](@ref) (the directed version is completely analogous).
+Here we illustrate how to define, handle and analyse a `MultilayerGraph` (the directed version is completely analogous).
 
 ```julia
 using Revise
@@ -56,7 +56,6 @@ const max_vertices = 7
 const min_edges    = 1
 const max_edges    = max_vertices*(max_vertices-1)
 const n_nodes      = max_vertices
-; #hide
 ```
 
 Next we define nodes:
@@ -76,7 +75,7 @@ const all_nodes = [Node("node_$i") for i in 1:n_nodes]
  Node("node_7")
 ```
 
-And construct `MultilayerVertex`s from these nodes:
+You may access (but not modify) the `id` of a `Node` via the [`id`](@ref) function. And construct `MultilayerVertex`s from these nodes:
 
 ```julia
 ## Convert nodes to multilayer vertices without metadata
@@ -106,7 +105,7 @@ multilayervertices_meta[1]
 MV(Node("node_1"), :nothing, ("I'm node node_1",))
 ```
 
-Where `MV` is an alias for `MultilayerVertex`. The first field is the `Node` being represented, the second the (name of) the layer the vertex is represented in (here it is set to `nothing`, since these vertices are yet to be assigned), and the metadata associated to the vertex (no metadata are currently represented via an empty `NamedTuple`). `MultilayerVertex` metadata can be represented via a `Tuple` or a `NamedTuple` (see below for examples).
+Where `MV` is an alias for `MultilayerVertex`. The first field is the `Node` being represented (accessible via the [`node`](@ref) function), the second the (name of) the layer the vertex is represented in ((accessible via the [`layer`](@ref) function), here it is set to `nothing`, since these vertices are yet to be assigned), and the metadata associated to the vertex ((accessible via the [`metadata`](@ref) function), no metadata are currently represented via an empty `NamedTuple`). `MultilayerVertex` metadata can be represented via a `Tuple` or a `NamedTuple` (see below for examples).
 
 ### Layers
 
@@ -155,7 +154,6 @@ function _get_srcmv_dstmv_layer(layer::Layer)
 
     return mvs, src_mv, dst_mv
 end
-; #hide
 ```
 
 We are now are ready to define some `Layer`s. Every type of graph from the Graphs.jl ecosystem may underlie a `Layer` (or an `Interlayer`). We will construct a few of them, each time with a different number of vertices and edges.
@@ -204,14 +202,13 @@ layer_vg = Layer(   :layer_vg,
 
 # Collect all layers in an ordered list. Order will be recorded when instantiating the multilayer graph.
 layers = [layer_sg, layer_swg, layer_mg, layer_vg]
-; #hide
 ```
 
 The API that inspects and modifies `Layer`s will be shown below together with that of `Interlayer`s, since they are usually the same. There are of course other constructors that you may discover by typing `?Layer` in the console.
 
 ### Interlayers
 
-Now we turn to defining `Interlayer`s. Interlayers are the graphs containing all the edges between vertices is two distinct layers. As before, we need an utility to ease randomization:
+Now we turn to defining [`Interlayer`](@ref)s. Interlayers are the graphs containing all the edges between vertices is two distinct layers. As before, we need an utility to ease randomization:
 
 
 ```julia
@@ -240,7 +237,6 @@ function rand_ne_interlayer(layer_1, layer_2)
     _ne = rand(_nv:(_nv*(_nv-1)) ÷ 2 )
     return _ne
 end
-; #hide
 ```
 
 An `Interlayer` is constructed by passing its name, the two `Layer`s it should connect, and the other parameters just like the `Layer`'s constructor. The random constructor reads:
@@ -298,7 +294,6 @@ interlayer_empty_sg_vg = empty_interlayer(  layer_sg,
 
 # Collect all interlayers. Even though the list is ordered, order will not matter when instantiating the multilayer graph.
 interlayers = [interlayer_sg_swg, interlayer_swg_mg, interlayer_mg_vg, interlayer_multiplex_sg_mg, interlayer_empty_sg_vg]
-; #hide
 ```
 
 Next, we explore the API associated to modify and analyze `Layer`s and `Interlayer`s.
@@ -405,9 +400,9 @@ interlayer_sg_swg_vertices = mv_vertices(interlayer_sg_swg)
 
 The `vertices` command would return an internal representation of the `MultilayerVertex`s. This method, together with others, serves to make `MultilayerGraphs.jl` compatible with the Graphs.jl ecosystem, but it is not meant to be called by the end user. It is, anyway, thought to be used by developers who wish to interface their packages with `MultilayerGraphs.jl` just as with other packages of the `Graphs.jl` ecosystem: a developer-oriented guide will be compiled if there is the need. 
 
-In the [API](@ref) page the intended usage of all methods (*end-user* or *developer*) is highlighted.
+In the [API](@ref) page the intended usage of all methods ([End-User](@ref) or [Developer](@ref)) is highlighted.
 
-To add a vertex, simply use [`add_vertex!`](@ref). Let us define a vertex with metadata to add. Since nodes may not be represented more than once in layers, we have to define a new node to:
+To add a vertex, simply use [`add_vertex!(layer::Layer, mv::MultilayerVertex)`](@ref). Let us define a vertex with metadata to add. Since nodes may not be represented more than once in layers, we have to define a new node to:
 
 ```julia
 new_node     = Node("missing_node")

src/MultilayerGraphs.jl

@@ -24,6 +24,7 @@ export
     # Node.jl 
     AbstractNode,
     Node,
+    id,
     # abstractvertex.jl
     AbstractVertex,
     # multilayervertex.jl 
@@ -74,6 +75,7 @@ export
     AbstractLayer,
     Layer,
     has_node,
+    add_vertex!
     rem_vertex!,
     # interlayer.jl
     AbstractInterlayer,

src/abstractmultilayerdigraph.jl

@@ -373,12 +373,13 @@ Return `true` if `mg` is directed, `false` otherwise.
 Graphs.is_directed(mg::M) where {M<:Type{<:AbstractMultilayerDiGraph}} = true
 
 """
-    inneighbors(mg::M, v::T) where {M <: AbstractMultilayerDiGraph{T} } where { T <: Integer}
+    inneighbors(mg::M, v::T
+) where {T, M<:AbstractMultilayerGraph{T,<:Real}}
+
 
 Return the list of inneighbors of `v` within `mg`.
 """
-function Graphs.inneighbors(mg::M, v::T
-    ) where {M<:AbstractMultilayerGraph{T,<:Real}} where {T}
+function Graphs.inneighbors(mg::M, v::T) where {T, M<:AbstractMultilayerGraph{T,<:Real}}
 
     _inneighbors = T[]
 

src/abstractmultilayergraph.jl

@@ -121,7 +121,7 @@ Graphs.has_vertex(mg::AbstractMultilayerGraph, mv::MultilayerVertex) = get_bare_
 
 Return a list of the `MultilayerVertex`s contained in `mg`.
 """
-mv_vertices(mg::AbstractMultilayerGraph)  =  [get_rich_mv(mg, v) for v in vertices(mg)]
+mv_vertices(mg::AbstractMultilayerGraph) =  [get_rich_mv(mg, v) for v in vertices(mg)]
 
 """
     nv(mg::M) where {M <: AbstractMultilayerGraph }
@@ -524,13 +524,13 @@ Graphs.outneighbors( mg::AbstractMultilayerGraph, mv::MultilayerVertex) = outnei
 
 
 """
-    outneighbors(mg::M, v::T) where {M <: AbstractMultilayerGraph{T} } where { T <: Integer}
+    outneighbors(mg::M, v::T) where {T, M<:AbstractMultilayerGraph{T}}
 
 Return the list of outneighbors of `v` within `mg`.
 """
 function Graphs.outneighbors(
     mg::M, v::T
-) where {M<:AbstractMultilayerGraph{T,<:Real}} where {T}
+) where {T, M<:AbstractMultilayerGraph{T}}
 
     _outneighbors = T[]
 
@@ -780,7 +780,7 @@ degree_variance(mg::AbstractMultilayerGraph) = var(degree(mg))
         norm_factor::Union{Float64,Symbol}=:max
     )
 
-Return the complete multilayer global clustering coefficient, equal to the ratio of realized triplets over all possible triplets, including those whose every or some edges belong to interlayers, normalized by `norm_factor`. If `norm_factor == :max`, then the ratio is normalized by `maximum(mg.array)`. This function does not override Graphs.jl's `global_clustering_coefficient`, since the latter does not consider cliques where two nodes are the same node but in different layers/interlayers. See [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022).
+Return the complete multilayer global clustering coefficient, equal to the ratio of realized triplets over all possible triplets, including those whose every or some edges belong to interlayers, normalized by `norm_factor`. If `norm_factor == :max`, then the ratio is normalized by `maximum(array(weight_tensor(mg)))`, else it is not normalized. This function does not override Graphs.jl's `global_clustering_coefficient`, since the latter does not consider cliques where two nodes are the same node but in different layers/interlayers. See [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022).
 """
 function multilayer_global_clustering_coefficient(
     mg::AbstractMultilayerGraph, norm_factor::Union{Float64,Symbol}=:max
@@ -816,7 +816,7 @@ end
 """
     multilayer_weighted_global_clustering_coefficient(mg::M, norm_factor::Union{Float64, Symbol} = :max) where {M <: AbstractMultilayerGraph}
 
-Return the complete multilayer global clustering coefficient, equal to the ratio of realized triplets over all possible triplets, including those whose every or some edges belong to interlayers, normalized by `norm_factor`. Each triplets contributes for `w[1]` if all of its vertices are in one layer, `w[2]` if its vertices span two layers, and `w[3]` if they span 3 layers. If `norm_factor == :max`, then the ratio is normalized by `maximum(mg.array)`. This function does not override Graphs.jl's `global_clustering_coefficient`, since the latter does not consider cliques where two nodes are the same node but in different layers/interlayers. See [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022).
+Return the complete multilayer global clustering coefficient, equal to the ratio of realized triplets over all possible triplets, including those whose every or some edges belong to interlayers, normalized by `norm_factor`. Each triplets contributes for `w[1]` if all of its vertices are in one layer, `w[2]` if its vertices span two layers, and `w[3]` if they span 3 layers. If `norm_factor == :max`, then the ratio is normalized by `maximum(array(weight_tensor(mg)))`, else it is not normalized. This function does not override Graphs.jl's `global_clustering_coefficient`, since the latter does not consider cliques where two nodes are the same node but in different layers/interlayers. See [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022).
 """
 function multilayer_weighted_global_clustering_coefficient(
     mg::M, w::Vector{Float64}, norm_factor::Union{Float64,Symbol}=:max
@@ -851,7 +851,7 @@ end
         norm_factor::Union{Float64,Symbol}=:max
     )
 
-Return the overlay clustering coefficient as calculated in [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022).
+Return the overlay clustering coefficient as calculated in [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022). If `norm_factor == :max`, then the ratio is normalized by `maximum(array(weight_tensor(mg)))`, else it is not normalized. 
 """
 function overlay_clustering_coefficient(
     mg::AbstractMultilayerGraph, norm_factor::Union{Float64,Symbol}=:max

src/abstractmultilayerugraph.jl

@@ -342,7 +342,7 @@ Return `true` if `mg` is directed, `false` otherwise.
 Graphs.is_directed(mg::M) where {M<:Type{<:AbstractMultilayerUGraph}} = false
 
 """
-    inneighbors(mg::M, v::T) where {M <: AbstractMultilayerUGraph{T} } where { T <: Integer}
+    inneighbors(mg::M, v::T) where {T,M<:AbstractMultilayerUGraph{T,<:Real}}
 
 Return the list of inneighbors of `v` within `mg`.
 """