Clean docs, test and README

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

Author: 3 people

.vscode/settings.json

@@ -11,6 +11,7 @@
         "agrs",
         "Anstee",
         "badjlist",
+        "Bianconi",
         "cond",
         "deepcopy",
         "deleteat",
@@ -62,6 +63,8 @@
         "istrait",
         "jimk",
         "jnmo",
+        "Kivela",
+        "Kivelä",
         "Kleitman",
         "kwargs",
         "layerdescriptor",
@@ -88,6 +91,7 @@
         "njom",
         "ntriangles",
         "outdeg",
+        "overlaygraph",
         "pitmonticone",
         "prettyurls",
         "println",

README.md

@@ -13,45 +13,37 @@
 
 <img align="right" width="215" height="215" src="https://github.com/JuliaGraphs/MultilayerGraphs.jl/blob/main/docs/src/assets/logo.png?raw=true">
 
-**MultilayerGraphs.jl** is a Julia package for the construction, manipulation and analysis of multilayer graphs [extending Graphs.jl](https://juliagraphs.org/Graphs.jl/dev/ecosystem/interface/).
+**MultilayerGraphs.jl** is a Julia package for the creation, manipulation and analysis of the structure, dynamics and functions of multilayer graphs [extending Graphs.jl](https://juliagraphs.org/Graphs.jl/dev/ecosystem/interface/).
 
 ## Overview
 
-**MultilayerGraphs.jl** implements the mathematical formulation of multilayer graphs proposed by [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022). It mainly revolves around two custom types, [`MultilayerGraph`](https://juliagraphs.org/MultilayerGraphs.jl/dev/internals/#MultilayerGraphs.MultilayerGraph) and [`MultilayerDiGraph`](https://juliagraphs.org/MultilayerGraphs.jl/dev/internals/#MultilayerGraphs.MultilayerDiGraph), encoding undirected and directed multilayer graphs respectively.
+**MultilayerGraphs.jl** implements the mathematical formulation of multilayer graphs proposed by [De Domenico et al. (2013)](https://doi.org/10.1103/PhysRevX.3.041022) together with insights from [Kivelä et al. (2014)](https://doi.org/10.1093/comnet/cnu016) and [Bianconi (2018)](https://global.oup.com/academic/product/multilayer-networks-9780192865540). It mainly revolves around two custom types, [`MultilayerGraph`](@ref) and [`MultilayerDiGraph`](@ref), encoding undirected and directed multilayer graphs respectively.
 
-Roughly speaking, a multilayer graph is a collection of ***layers***, i.e. graphs whose vertices are representations of the same set of nodes, and ***interlayers***, i.e the [bipartite graphs](https://en.wikipedia.org/wiki/Bipartite_graph) whose vertices are those of any two layers and whose edges are those between vertices of the same two layers.
+Roughly speaking, a multilayer graph is a collection of ***layers***, i.e. graphs whose vertices are representations of the same set of nodes (not all nodes have to be represented in every layer), and ***interlayers***, i.e the [bipartite graphs](https://en.wikipedia.org/wiki/Bipartite_graph) whose two sets of vertices are those of any two layers. A vertex of a multilayer graph will be represented via a [`MultilayerVertex`](@ref) struct, and nodes via a [`Node`](@ref) struct.
 
-[`MultilayerGraph`](https://juliagraphs.org/MultilayerGraphs.jl/dev/internals/#MultilayerGraphs.MultilayerGraph) and [`MultilayerDiGraph`](https://juliagraphs.org/MultilayerGraphs.jl/dev/internals/#MultilayerGraphs.MultilayerDiGraph) are fully-fledged [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl) extensions. Both structs are designed so that their layers and interlayers can be of any type (as long as they are Graphs.jl extensions themselves) and they need not be all of the same type. It is anyway required that all layers and interlayers of [`MultilayerGraph`](https://juliagraphs.org/MultilayerGraphs.jl/dev/internals/#MultilayerGraphs.MultilayerGraph) and [`MultilayerDiGraph`](https://juliagraphs.org/MultilayerGraphs.jl/dev/internals/#MultilayerGraphs.MultilayerDiGraph) are respectively undirected and directed. Directedness is checked via the `IsDirected` trait defined in Graphs.jl adopting [SimpleTraits.jl](https://github.com/mauro3/SimpleTraits.jl). Since the layers' and interlayers' graph types don't need to be the same, multilayer graph types are considered weighted graphs by default, and thus are assigned the trait `IsWeighted`.
+[`MultilayerGraph`](@ref) and [`MultilayerDiGraph`](@ref) are fully-fledged [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl) extensions. Both structs are designed so that their layers and interlayers can be of any type (as long as they are Graphs.jl extensions themselves) and they can be of different types. It is anyway required that all layers and interlayers of [`MultilayerGraph`](@ref) and [`MultilayerDiGraph`](@ref) are respectively undirected and directed.
+
+Both [`MultilayerGraph`](@ref) and [`MultilayerDiGraph`](@ref) allow for vertex and edge metadata, provided that the layer (or interlayer) vertex or the layer (or interlayer) edge belongs to supports metadata.
 
 ## Installation
 
 Press `]` in the Julia REPL and then
 
-```julia
+```nothing
 pkg> add MultilayerGraphs
 ```
 
-## Tutorial
-
-In the package documentation we have prepared a [tutorial](https://juliagraphs.org/MultilayerGraphs.jl/stable/#Tutorial) to illustrate how to define, handle and analyse a [`MultilayerGraph`](https://juliagraphs.org/MultilayerGraphs.jl/dev/internals/#MultilayerGraphs.MultilayerGraph) (the directed version is completely analogous).
+## Usage
 
-## Future Developments
+In the package documentation you can find a [tutorial](https://juliagraphs.org/MultilayerGraphs.jl/stable/#Tutorial) that illustrates all its main features.
 
-Here we highlight the major future developments we have currently identified:
+## Future Developments 
 
-- [ ] Better integration with [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl). We've recently opened an [issue](https://github.com/JuliaGraphs/Graphs.jl/issues/165) on Graphs.jl illustrating our proposals;
-- [ ] Better integration with [MetaGraphs.jl](https://github.com/JuliaGraphs/MetaGraphs.jl) and [SimpleValueGraphs.jl](https://github.com/simonschoelly/SimpleValueGraphs.jl). Although it is possible to specify a `MetaGraph` and `SimpleValueGraph` as layer and/or interlayer, they are not yet fully supported (i.e. API may be a little unfit for them). An example using MetaGraphs, SimpleValueGraphs can be found at our announcement post [here]();
-- [ ] Optimise the adjacency tensor;
-- [ ] More intuitive constructor for `Interlayer`;
-- [ ] Implement specialised and simplified API for `MultiplexGraph`;
-- [ ] Implement visualisation functionalities;
-- [ ] Implement other features and methods for the analysis of multilayer graphs following the scientific literature:
-  - Kivelä et al. (2014) [Multilayer networks](https://doi.org/10.1093/comnet/cnu016). *Journal of Complex Networks*
-  - Cozzo et al. (2015) [Structure of triadic relations in multiplex networks](https://doi.org/10.1088/1367-2630/17/7/073029). *New Journal of Physics*
-  - De Domenico et al. (2015) [MuxViz: a tool for multilayer analysis and visualization of networks](https://doi.org/10.1093/comnet/cnu038). *Journal of Complex Networks*
-  - De Domenico et al. (2015) [Ranking in interconnected multilayer networks reveals versatile nodes](https://doi.org/10.1038/ncomms7868). *Nature Communications*
-  - De Domenico (2022) [Multilayer Networks: Analysis and Visualization](https://doi.org/10.1007/978-3-030-75718-2). *Springer Cham*
-  - Artime et al. (2022) [Multilayer Network Science: From Cells to Societies](https://doi.org/10.1017/9781009085809). *Cambridge Elements*
+- [ ] [Implement faster graph realization algorithms](https://github.com/JuliaGraphs/MultilayerGraphs.jl/issues/32);
+- [ ] [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).
 
 ## How to Contribute
 
@@ -71,4 +63,7 @@ If you use this package in your work, please cite this repository using the meta
 
 ## References
 
-De Domenico et al. (2013) [Mathematical Formulation of Multilayer Networks](https://doi.org/10.1103/PhysRevX.3.041022). *Physical Review X*.
+1. De Domenico et al. (2013) [Mathematical Formulation of Multilayer Networks](https://doi.org/10.1103/PhysRevX.3.041022). *Physical Review X*; 
+2. Kivelä et al. (2014) [Multilayer networks](https://doi.org/10.1093/comnet/cnu016). *Journal of Complex Networks*; 
+3. Bianconi (2018) [Multilayer Networks: Structure and Function](https://global.oup.com/academic/product/multilayer-networks-9780192865540). *Oxford University Press*.
+ 

docs/Project.toml

@@ -1,10 +1,8 @@
 [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"
 MultilayerGraphs = "af984530-d72f-4904-8b81-b992bbbeaf3f"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 SimpleValueGraphs = "b43c691f-cac2-5415-8122-396fe16a49fc"
 SimpleWeightedGraphs = "47aef6b3-ad0c-573a-a1e2-d07658019622"
-StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"

docs/make.jl

@@ -2,8 +2,6 @@ using Revise
 using MultilayerGraphs
 using Documenter
 
-# cd("dev/MultilayerGraphs/docs")
-
 DocMeta.setdocmeta!(
     MultilayerGraphs, :DocTestSetup, :(using MultilayerGraphs); recursive=true
 )
@@ -24,4 +22,4 @@ makedocs(;
 
 deploydocs(;
     repo="github.com/JuliaGraphs/MultilayerGraphs.jl", devbranch="main", push_preview=true
-)
+)