Merge pull request #64 from JuliaGraphs/minor_fixes

Update API, README and docs with minor fixes

Author: pitmonticone

.vscode/settings.json

@@ -1,11 +1,14 @@
 {
     "cSpell.words": [
+        "abstractmatrixrrepresentation",
         "abstractmultilayerdigraph",
         "abstractmultilayergraph",
         "abstractmultilayerugraph",
         "abstractmultiplexdigraph",
         "abstractmultiplexugraph",
         "abstractsubgraph",
+        "abstracttensorrepresentation",
+        "abstractvertex",
         "add_vertex",
         "adjm",
         "agrs",
@@ -107,6 +110,7 @@
         "supraweightmatrix",
         "swdg",
         "tensoreig",
+        "tensorfacoriazations",
         "tensorsfactorizations",
         "testset",
         "traitdef",

README.md

@@ -39,25 +39,211 @@ Finally, MultilayerGraphs.jl has been integrated within the [JuliaDynamics](http
 
 ## Installation
 
-Press `]` in the Julia REPL and then
+To install MultilayerGraphs.jl it is sufficient to activate the `pkg` mode by pressing `]` in the Julia REPL and then run the following command:
 
 ```nothing
 pkg> add MultilayerGraphs
 ```
 
 ## Usage
 
-In the package documentation you can find a [tutorial](https://juliagraphs.org/MultilayerGraphs.jl/stable/#Tutorial) that illustrates all its main features and functionalities.
+Here we are going to synthetically illustrate some of the main features of MultilayerGraphs.jl. For a more comprehensive exploration of the package functionalities we strongly recommend consulting the [documentation](https://juliagraphs.org/MultilayerGraphs.jl). 
+
+Let's begin by importing the necessary dependencies and setting the relevant constants.
+
+```julia
+using Distributions, Graphs, SimpleValueGraphs
+using MultilayerGraphs
+
+# Set the number of nodes: objects represented by multilayer vertices
+const n_nodes = 100 
+# Create a list of nodes
+const node_list = [Node("node_$i") for i in 1:n_nodes]
+```
+
+### Layers and Interlayers 
+
+We will instantiate layers and interlayers with randomly-selected edges and vertices adopting a variety of techniques. Layers and Interlayers are not immutable, and mostly behave like normal graphs. The user is invited to consult the [API](https://juliagraphs.org/MultilayerGraphs.jl/stable/API/) for further details.
+
+Here we define a layer with an underlying simple directed graph using a graph generator-like (or "configuration model"-like) constructor which allows us to specify both the **indegree** and the **outdegree sequences**. Before instantiating each layer we sample the number of its vertices and, optionally, of its edges.
+
+```julia
+n_vertices = rand(1:100)                          # Number of vertices 
+layer_simple_directed = layer_simpledigraph(      # Layer constructor 
+    :layer_simple_directed,                       # Layer name
+    sample(node_list, n_vertices; replace=false), # Nodes represented in the layer
+    Truncated(Normal(5, 5), 0, 20), # Indegree sequence distribution 
+    Truncated(Normal(5, 5), 0, 20)  # Outdegree sequence distribution
+)
+```
+
+Then we define a layer with an underlying simple weighted directed graph. This is another kind of constructor that allows the user to specify the number of edges to be randomly distributed among vertices. 
+
+```julia
+n_vertices = rand(1:n_nodes)                                   # Number of vertices 
+n_edges = rand(n_vertices:(n_vertices * (n_vertices - 1) - 1)) # Number of edges 
+layer_simple_directed_weighted = layer_simpleweighteddigraph(  # Layer constructor 
+    :layer_simple_directed_weighted,                           # Layer name
+    sample(node_list, n_vertices; replace=false), # Nodes represented in the layer
+    n_edges;                                 # Number of randomly distributed edges
+    default_edge_weight=(src, dst) -> rand() # Function assigning weights to edges 
+)
+```
+
+Similar constructors, more flexible at the cost of ease of use, enable a finer tuning. The constructor we use below should be necessary only in rare circumstances, e.g. if the equivalent simplified constructor `layer_simplevaldigraph` is not able to infer the correct return types of `default_vertex_metadata` or `default_edge_metadata`, or to use and underlying graph structure that isn't currently supported.
+
+```julia
+n_vertices = rand(1:n_nodes)                                   # Number of vertices 
+n_edges = rand(n_vertices:(n_vertices * (n_vertices - 1) - 1)) # Number of edges 
+default_vertex_metadata = v -> ("vertex_$(v)_metadata")        # Vertex metadata 
+default_edge_metadata = (s, d) -> (rand(),)                    # Edge metadata 
+layer_simple_directed_value = Layer(                           # Layer constructor
+    :layer_simple_directed_value,                              # Layer name
+    sample(node_list, n_vertices; replace=false), # Nodes represented in the layer
+    n_edges,                                      # Number of randomly distributed edges
+    ValDiGraph(                                                
+        SimpleDiGraph{Int64}(); 
+        vertexval_types=(String,),
+        vertexval_init=default_vertex_metadata,
+        edgeval_types=(Float64,),
+        edgeval_init=default_edge_metadata,
+    ),
+    Float64;
+    default_vertex_metadata=default_vertex_metadata, # Vertex metadata 
+    default_edge_metadata=default_edge_metadata      # Edge metadata 
+)
+
+# Create a list of layers 
+layers = [layer_simple_directed, layer_simple_directed_weighted, layer_simple_directed_value]
+```
+
+There are many more constructors the user is encouraged to explore in the package [documentation](https://juliagraphs.org/MultilayerGraphs.jl).
+
+The interface of interlayers is very similar to that of layers. It is very important to notice that, in order to define a `Multilayer(Di)Graph`, interlayers don't need to be explicitly constructed by the user since they are automatically identified by the `Multilayer(Di)Graph` constructor, but for more complex interlayers the manual instantiation is required.
+
+Here we define an interlayer with an underlying simple directed graph.
+
+```julia
+n_vertices_1 = nv(layer_simple_directed)               # Number of vertices of layer 1
+n_vertices_2 = nv(layer_simple_directed_weighted)      # Number of vertices of layer 2
+n_edges = rand(1:(n_vertices_1 * n_vertices_2 - 1))    # Number of interlayer edges 
+interlayer_simple_directed = interlayer_simpledigraph( # Interlayer constructor 
+    layer_simple_directed,                             # Layer 1 
+    layer_simple_directed_weighted,                    # Layer 2 
+    n_edges                                            # Number of edges 
+)
+```
+
+The interlayer exports a more flexible constructor too.
+
+```julia
+n_vertices_1 = nv(layer_simple_directed_weighted)   # Number of vertices of layer 1
+n_vertices_2 = nv(layer_simple_directed_value)      # Number of vertices of layer 2
+n_edges = rand(1:(n_vertices_1 * n_vertices_2 - 1)) # Number of interlayer edges 
+interlayer_simple_directed_meta = interlayer_metadigraph( # Interlayer constructor
+    layer_simple_directed_weighted,                       # Layer 1 
+    layer_simple_directed_value,                          # Layer 2
+    n_edges;                                              # Number of edges
+    default_edge_metadata=(src, dst) ->                   # Edge metadata 
+        (edge_metadata="metadata_of_edge_from_$(src)_to_$(dst)"),
+    transfer_vertex_metadata=true # Boolean deciding layer vertex metadata inheritance
+)
+
+# Create a list of interlayers 
+interlayers = [interlayer_simple_directed, interlayer_simple_directed_meta]
+```
+
+### Multilayer Graphs
+
+Let's construct a directed multilayer graph (`MultilayerDiGraph`).
+
+```julia
+multilayerdigraph = MultilayerDiGraph( # Constructor 
+    layers,                     # The (ordered) collection of layers
+    interlayers;                # The manually specified interlayers
+                                # The interlayers that are left unspecified 
+                                # will be automatically inserted according 
+                                # to the keyword argument below
+    default_interlayers_structure="multiplex" 
+    # The automatically specified interlayers will have only diagonal couplings
+)
+
+# Layers and interlayer can be accessed as properties using their names
+multilayerdigraph.layer_simplevaldigraph
+```
+
+Then we proceed by showing how to add nodes, vertices and edges to a directed multilayer graph. The user may add vertices that do or do not represent nodes which are already present in the multilayergraph. In the latter case, we have to create a node first and then add the vertex representing such node to the multilayer graph. The vertex-level metadata are effectively considered only if the graph underlying the relevant layer or interlayer supports them, otherwise they are discarded. The same holds for edge-level metadata and/or weight. 
+
+```julia
+# Create a node 
+new_node_1 = Node("new_node_1")
+# Add the node to the multilayer graph 
+add_node!(multilayerdigraph, new_node_1)
+# Create a vertex representing the node 
+new_vertex_1 = MV(           # Constructor (alias for "MultilayerVertex")
+    new_node_1,              # Node represented by the vertex
+    :layer_simplevaldigraph, # Layer containing the vertex 
+    ("new_metadata")         # Vertex metadata 
+)
+# Add the vertex 
+add_vertex!(
+    multilayerdigraph, # MultilayerDiGraph the vertex will be added to
+    new_vertex_1       # MultilayerVertex to add
+)
+
+# Create another node in another layer 
+new_node_2 = Node("new_node_2")
+# Create another vertex representing the new node
+new_vertex_2 = MV(new_node_2, :layer_simpledigraph)
+# Add the new vertex
+add_vertex!(
+    multilayerdigraph,
+    new_vertex_2;
+    add_node=true # Add the associated node before adding the vertex
+)
+# Create an edge 
+new_edge = MultilayerEdge( # Constructor 
+    new_vertex_1,          # Source vertex
+    new_vertex_2,          # Destination vertex 
+    ("some_edge_metadata") # Edge metadata 
+)
+# Add the edge 
+add_edge!(
+    multilayerdigraph, # MultilayerDiGraph the edge will be added to
+    new_edge           # MultilayerVertex to add
+)
+```
+
+Finally we illustrate how to compute a few multilayer metrics such as the global clustering coefficient, the overlay clustering coefficient, the multilayer eigenvector centrality, and the multilayer modularity as defined in [De Domenico  et al. (2013)](https://doi.org/10.1103/physrevx.3.041022). 
+
+```julia
+# Compute the global clustering coefficient
+multilayer_global_clustering_coefficient(multilayerdigraph) 
+# Compute the overlay clustering coefficient
+overlay_clustering_coefficient(multilayerdigraph)
+# Compute the multilayer eigenvector centrality 
+eigenvector_centrality(multilayerdigraph)
+# Compute the multilayer modularity 
+modularity(
+    multilayerdigraph,
+    rand([1, 2, 3, 4], length(nodes(multilayerdigraph)), length(multilayerdigraph.layers))
+)
+```
 
 ## Future Developments 
 
-- [ ] [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 configuration models / graph generators for interlayers](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/46);
+- [ ] [Implement a fully-fledged multilayer configuration model / graph generator](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/48);
 - [ ] [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).
+- [ ] [Implement multilayer graph data visualisation functionalities](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/54);
+- [ ] [Infer `weighttype` from `default_edge_weight`](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/58);
+- [ ] [Improve error explanations](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/59); 
+- [ ] [Improve integration with Agents.jl](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/61);
+- [ ] [Allow configuration models to specify a minimum discrepancy between the sampled (di)graphical sequence(s) and the provided distribution](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/62);
+- [ ] [Add to `add_layer!` a kwarg that allows the user to specify some new interlayers, skipping the instantiation of the default ones.](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/63).
 
 ## How to Contribute 
 
@@ -67,7 +253,9 @@ We therefore encourage you to participate in [discussions](https://github.com/Ju
 
 ## How to Cite
 
-If you utilize this package in your project, please consider citing this repository using the citation information provided in [`CITATION.bib`](https://github.com/JuliaGraphs/MultilayerGraphs.jl/blob/main/CITATION.bib). This will help to give appropriate credit to the [contributors](https://github.com/JuliaGraphs/MultilayerGraphs.jl/graphs/contributors) and support the continued development of the package.
+If you utilize this package in your project, please consider citing this repository using the citation information provided in [`CITATION.bib`](https://github.com/JuliaGraphs/MultilayerGraphs.jl/blob/main/CITATION.bib). 
+
+This will help to give appropriate credit to the [contributors](https://github.com/JuliaGraphs/MultilayerGraphs.jl/graphs/contributors) and support the continued development of the package.
 
 ## Announcements 
 

docs/make.jl

@@ -1,4 +1,3 @@
-using Revise
 using Distributions
 using Graphs
 using MultilayerGraphs

docs/src/API.md

@@ -235,8 +235,7 @@ 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}}
+add_vertex!(mg::AbstractMultilayerGraph, mv::MultilayerVertex; add_node::Bool)
 rem_vertex!(mg::AbstractMultilayerUGraph, V::MultilayerVertex)
 rem_vertex!(mg::AbstractMultilayerDiGraph, V::MultilayerVertex)
 has_edge(mg::AbstractMultilayerGraph, edge::MultilayerEdge)