Julia Community 🟣: Interdisciplinary Physics Team

[ANN] MultilayerGraphs.jl (v1.1): Multilayer Network Science in Julia

Interdisciplinary Physics Team — Sun, 08 Jan 2023 17:09:30 +0000

We (@claudio_moroni and @pitmonticone) are excited to announce the new version of MultilayerGraphs.jl: a Julia package for the creation, manipulation and analysis of the structure, dynamics and functions of multilayer graphs.

Main Changes

Here we list the main changes since the previous announcement post:

We have integrated the package within the JuliaGraphs ecosystem;
We have integrated the package within the JuliaDynamics ecosystem so that any Multilayer(Di)Graph can be utilised as an argument to the GraphSpace constructor in Agents.jl (see the related closed issue);
We have implemented a general multilayer graph removing the requirement for each layer to have the same vertices (see the related closed issue);
We have implemented the weight tensor, the metadata tensor and the supra weight matrix (see the related closed issue);
We have implemented a concrete MultilayerGraph and MultilayerDiGraph, which are not graph wrappers in order to greatly simplify the library, since modifications to edges, vertices, etc. shall no longer be applied twice (see the related closed issue);
We have implemented multiple interfaces for layer and interlayers called "uniform", "standard" and "transparent" (see the related closed issue);
We have implemented faster graph realization algorithms such as the Havel-Hakimi algorithm for undirected graphs (Hakimi (1962)) and the Kleitman-Wang algorithm for directed ones (Kleitman and Wang (1973)) (see the related closed issue);
We have implemented more general graph generators ("configuration models") capable of using a different distribution for each dimension of multiplexity (see the related closed issue);
We have implemented graph generators ("configuration models") for layers (see the related closed issue);
We have improved the readability of console print of custom structs (see the related closed issue);
We have implemented more user-friendly constructors for layers and interlayers (see the related closed issue).

For a more comprehensive exploration of the package features and functionalities we strongly recommend consulting the package README and documentation.

Usage

Here we are going to synthetically showcase some of the main features of MultilayerGraphs.jl (v1.1) such as:

how to define layers and interlayers with a variety of constructors and underlying graphs;
how to construct a directed multilayer graph with those layers and interlayers;
how to add nodes, vertices and edges to the multilayer graph;
how to compute some multilayer metrics as presented in De Domenico et al. (2013).

Let's begin by importing the necessary dependencies and setting the relevant constants.

# Import necessary dependencies
using Distributions, Graphs, SimpleValueGraphs
using MultilayerGraphs
# Set the number of nodes
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 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.

# Create a simple directed layer
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.

# Create a simple directed weighted layer
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.

# Create a simple directed value layer
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.

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.

# Create a simple directed interlayer
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.

# Create a simple directed meta interlayer 
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).

# Create a simple directed multilayer graph
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 multilayer graph. 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.

# 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).

# 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

Contacts

Author	GitHub	Twitter	Discourse	Forem
Claudio Moroni	@ClaudMor	@Claudio__Moroni	@claudio20497	@claudio_moroni
Pietro Monticone	@pitmonticone	@PietroMonticone	@PietroMonticone	@pitmonticone

[ANN] MultilayerGraphs.jl: A Package to Construct, Handle and Analyse Multilayer Graphs

Interdisciplinary Physics Team — Fri, 19 Aug 2022 08:44:00 +0000

We are thrilled to announce MultilayerGraphs.jl: a Julia package for the construction, manipulation and analysis of multilayer graphs extending Graphs.jl.

MultilayerGraphs.jl provides two custom types, MultilayerGraph and MultilayerDiGraph, together with utilities to handle and analyse undirected and directed multilayer graphs implementing the mathematical formulation proposed by De Domenico et al. (2013).

The graphs composing the multilayer graph (i.e. layers and interlayers) can be of any type as long as they are proper extensions of AbstractGraph{T}. Then, since this package heavily relies on Graphs.jl and all of its extensions, it may also serve as a playground to test the overall status and consistency of the ecosystem API.

Main Features

In the code block below we illustrate the main features of the package.

# Import necessary packages  
using Graphs
using SimpleWeightedGraphs, MetaGraphs, SimpleValueGraphs
using MultilayerGraphs

# Set graph attributes
n_nodes   = 5        # Number of nodes 
min_edges = n_nodes  # Minimum number of edges  
max_edges = 10       # Maximum number of edges 

# Define some graphs underlying layers and interlayers 
simpledigraph         = SimpleDiGraph(n_nodes, rand(min_edges:max_edges))
simpleweighteddigraph = SimpleWeightedDiGraph(n_nodes, rand(min_edges:max_edges))
metadigraph           = MetaDiGraph(simpleweighteddigraph)
simplevalueoutgraph   = ValOutDiGraph( SimpleDiGraph(n_nodes,rand(min_edges:max_edges)); 
                                        edgeval_types=(Int64, ),
                                        edgeval_init=(s, d) -> (s + d, )
                                     )

simplevaluedigraph    = ValDiGraph( SimpleDiGraph(n_nodes,rand(min_edges:max_edges));
                                        edgeval_types=(Int64, ),
                                        edgeval_init=(s, d) -> (s + d, )
                                  ) 

# Collect all graphs in a vector
layer_graphs = [simpledigraph, simpleweighteddigraph, metadigraph, simplevalueoutgraph, simplevaluedigraph]                      

# Define layers
layers  = [ Layer(Symbol("layer_$i"),     # Layer's name
                graph;                    # Layer's underlying graph
                U = Float64)              # Layer's adjacency matrix `eltype`                  
                for (i,graph) in enumerate(layer_graphs)
          ]

# Define interlayers. Here we use the constructor for random interlayers. 
## Note that the user does not need to specify all interlayers: the unspecified one s will be taken care of by the MultilayerDiGraph constructor, that will initialize them according to the a default interlayer type passed via the keyword argument `default_interlayer_type`
interlayers = [ Interlayer(n_nodes,                     # Number of nodes
                          :interlayer_layer_1_layer_2,  # Interlayer's name
                          :layer_1,                     # Source layer name
                          :layer_2,                     # Destination layer name
                          SimpleDiGraph{Int64},         # Underlying graph type
                          rand(min_edges:max_edges);    # Number of edges
                          U = Float64                   # Interlayers's adjacency matrix `eltype`
                          ),
                 Interlayer(n_nodes, :interlayer_layer_1_layer_3,:layer_1, :layer_3, SimpleWeightedDiGraph{Int64}, rand(min_edges:max_edges); U = Float64 ), # Create another interlayer, the others will be automatically specified
              ]


# Define the MultilayerDiGraph
multilayerdigraph = MultilayerDiGraph(layers, interlayers)

# There are many other constructors for Layer, Interlayer and Multilayer(Di)Graph! Make sure to check them out in the documentation or in the REPL.

# Get all layers
multilayerdigraph.layers

# Get all Interlayers
multilayerdigraph.interlayers

# Get the adjacency_tensor
multilayerdigraph.adjacency_tensor

# Add an edge
add_edge!(multilayerdigraph, MultilayerVertex(1, :layer_1), MultilayerVertex(2, :layer_4)) # MultilayerVertex(1, :layer_1) refers to vertex 1 (i.e. the representation of node 1) in layer 1
## Check that the edge has been added
@assert has_edge(multilayerdigraph, MultilayerVertex(1, :layer_1), MultilayerVertex(2, :layer_4))
@assert multilayerdigraph.adjacency_tensor[1,2,1,4] == 1.0 # indexing is [vertex_1, vertex_2, vertex_1_layer_index, vertex_2_layer_index]

# Remove an edge
rem_edge!(multilayerdigraph, MultilayerVertex(1, :layer_1), MultilayerVertex(2, :layer_4))
## Check that the edge has been removed
@assert !has_edge(multilayerdigraph, MultilayerVertex(1, :layer_1), MultilayerVertex(2, :layer_4))
@assert multilayerdigraph.adjacency_tensor[1,2,1,4] == 0.0 # indexing is [vertex_1, vertex_2, vertex_1_layer_index, vertex_2_layer_index]

# Since Multilayer(Di)Graphs are extensions of Graphs.jl (https://juliagraphs.org/Graphs.jl/dev/ecosystem/interface/) all methods defined for AbstractGraph also work for Multilayer(Di)Graph. 
## Below are some examples of multilayer-specific functions and of Graphs.jl's functions that had to be reimplemented anyway for technical reasons.

# Get the overlay monoplex graph
get_overlay_monoplex_graph(multilayerdigraph)

# Get the depth-weighted global clustering coefficient, with weights so that it coincides with the global clustering coefficient
wcc = multilayer_weighted_global_clustering_coefficient(multilayerdigraph, [1/3, 1/3, 1/3])
@assert wcc ≈ multilayer_global_clustering_coefficient(multilayerdigraph)

# Get the eigenvector centrality of each vertex and the relative error at each iteration of the algorithm that computes it
eig_centrality, errs = eigenvector_centrality( multilayerdigraph;
                                               norm = "n",        # Normalization factor
                                               tol = 1e-3         # Target relative inter-iteration error
                                             )

# Get the modularity, given a clustering
modularity( multilayerdigraph,
            rand([1, 2, 3, 4], length(nodes(multilayerdigraph)),length(multilayerdigraph.layers)) # Communities 
          )

# Von Neumann Entropy is currently implemented only for undirected multilayer graphs (i.e. for MultilayerGraph). 
## You can find it in the tutorial included in the package documentation.

Future Developments

The package is currently under development and further steps would benefit enormously from the precious feedback of the JuliaGraph people, graph theorists, network scientists and all the users who might have general questions or suggestions.

Here we highlight the major future developments we have currently identified:

Better integration with Graphs.jl (e.g. move the AbstractVertex to Graphs.jl, standardize graphs constructors, etc.);
Better integration with MetaGraphs.jl and 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. Journal of Complex Networks
- Cozzo et al. (2015) Structure of triadic relations in multiplex networks. New Journal of Physics
- De Domenico et al. (2015) MuxViz: a tool for multilayer analysis and visualization of networks. Journal of Complex Networks
- De Domenico et al. (2015) Ranking in interconnected multilayer networks reveals versatile nodes. Nature Communications
- De Domenico (2022) Multilayer Networks: Analysis and Visualization. Springer Cham

References

For more information, tutorials and API reference please visit the documentation.

Feel free to open discussions, issues or PRs. They are very welcome!

Contacts

Author	GitHub	Twitter	Discourse	Forem
Pietro Monticone	@pitmonticone	@PietroMonticone	@PietroMonticone	@pitmonticone
Claudio Moroni	@ClaudMor	@Claudio__Moroni	@claudio20497	@claudio_moroni

[ANN] JuliaEpi: Collaborative Computational Epidemiology in Julia

Interdisciplinary Physics Team — Mon, 01 Aug 2022 23:42:00 +0000

We're building an open research community called JuliaEpi to develop an epidemiological modelling ecosystem written in Julia for the design, management, wrangling and quality assessment of multiple data types and sources and the parameterisation, calibration, validation, simulation and emulation of multiple classes of epidemiological models aimed at tackling typical problems such as situational awareness, nowcasting projection and evaluation, forecasting projection and evaluation, prospective and retrospective scenario analysis to ultimately support the preparedness, surveillance, response, control and prevention of outbreaks, epidemics and pandemics.

Contact Us

Are you an epi/eco/stat modeller or data scientist/manager?

Would you be interested in joining us to collaborate on the management and wrangling of data, the translation of past/present project-specific or package code into Julia, the conceptualization of new research projects, the open development and maintenance of new packages, offering and receiving expert feedback though issues, discussions and the whole lot of open source research communities?

Then please contact us via Twitter DM or email and let us know

if you're interested to offer your contribution or you know students/researchers/developers who might be interested in collaborating;
if you believe you could transfer some of your relevant repositories to JuliaEpi.

Announcements on Other Platforms

[ANN] ICD_GEMs.jl: A Package to Translate Between ICD-9 and ICD-10 Codes

Interdisciplinary Physics Team — Wed, 25 May 2022 22:27:33 +0000

We're glad to announce ICD_GEMs.jl: a package that allows to translate ICD-9 codes in ICD-10 and viceversa via the General Equivalence Mappings (GEMs) of the International Classification of Diseases (ICD).

The package exports the latest GEMs release from the CDC and internally utilizes it to perform translations. To understand how GEMs work and the terminology and choices found throughout this package, please read the official documentation. It may be found in the package repository (here and here), or it may be downloaded, together with the GEMs, from the CDC's website.

GEMs and applied mappings are represented by the package via a custom type GEM, and once a GEM (or an applied mapping) has been loaded (here we load an ICD10 -> ICD9 GEM from a CDC-formatted .txt source file) :

using ICD_GEMs
path      = "path/to/cdc_txt_file"
direction = "I10_I9" # If the GEM translates from ICD-10 to ICD-9, otherwise "I9_I10"
GEM_I10_I9_dictionary = get_GEM_dictionary_from_cdc_gem_txt(path, direction) # Or get_GEM_dictionary_from_cdc_gem_txt(path, direction)

It can be applied to perform custom translations:

ICD_10_neoplasms = ["C00-D48"] # This is equivalent as explicitly specifiying all codes from C00.XX to D48.XX
ICD_9_neoplasm   = execute_applied_mapping(GEM_I10_I9_dictionary, ICD_10_neoplasms)

Notice that the package supports the - notation between pairs of codes, which is equivalent to specifying all codes in between separated by commas.

More complex translations, involving both single codes and ranges with arbitrary precision on both ends, can be performed:

execute_applied_mapping(GEM_I10_I9_dictionary, ["I60-I661", "I670", "I672-I679"])

For more information, please consider reading the documentation.

Discussions, issues and PRs are always welcome!

References

Butler (2007), ICD-10 General Equivalence Mappings: Bridging the Translation Gap from ICD-9, Journal of AHIMA
CMS (2018), 2018 ICD-10 CM and GEMs
NCHS-CDC (2018), Diagnosis Code Set General Equivalence Mappings: ICD-10-CM to ICD-9-CM and ICD-9-CM to ICD-10-CM
NCHS-CDC (2022), Comprehensive Listing ICD-10-CM Files (download General Equivalence Mappings here)

Contacts

Author	GitHub	Twitter
Pietro Monticone	@pitmonticone	@PietroMonticone
Claudio Moroni	@ClaudMor	@Claudio__Moroni

[ANN] UnrollingAverages.jl: A Package to Deconvolve Time Series Data

Interdisciplinary Physics Team — Wed, 25 May 2022 22:21:10 +0000

We're happy to announce UnrollingAverages.jl: a package aimed at deconvolving (or unrolling) moving averages of time series to get the original ones back.

In the following, by "original series" or "series" we are going to mean the time series we would like to reconstruct from its "moving average".

The package exports a single function called unrollthat, with a few simple arguments, is able to handle all the following scenarios.

Scenario 1

The initial values of the moving average provided are known.

In this scenario, the original series can be exactly reconstructed.

Scenario 2

The initial values of the moving average provided are not known, but it is known that the series is exclusively composed of natural numbers;

In this scenario, all possible natural series that correspond to the input moving average are returned.

Scenario 3

The initial values of the moving average provided are not known, and it is not true or known that the series is exclusively composed of natural numbers.

In this scenario, the original series cannot be reconstructed in general, so a pseudo-inverse approximation is returned.

Examples

A real-world custom application of this package can be found in the COVID-19 integrated surveillance data repository we maintain.

The output data has been stored here and contain the following information:

Reconstructed daily time series of confirmed cases by date of diagnosis stratified by sex and age at the regional level;

Reconstructed daily time series of symptomatic cases by date of symptoms onset stratified by sex and age at the regional level;

Reconstructed daily time series of ordinary hospital admissions by date of admission stratified by sex and age at the regional level;

Reconstructed daily time series of intensive hospital admissions by date of admission stratified by sex and age at the regional level;

Reconstructed daily time series of deceased cases by date of death stratified by sex and age at the regional level.

For more details, please consider taking a look at the documentation.

Discussions, issues and PRs are always welcome!

References

Pietro Monticone & Claudio Moroni (2022) InPhyT/COVID19-Italy-Integrated-Surveillance-Data. Zenodo
Del Manso et al. (2020) COVID-19 integrated surveillance in Italy: outputs and related activities. Epidemiologia & Prevenzione
Starnini et al. (2021) Impact of data accuracy on the evaluation of COVID-19 mitigation policies. Data & Policy, 3, E28.

Contacts

Author	GitHub	Twitter
Pietro Monticone	@pitmonticone	@PietroMonticone
Claudio Moroni	@ClaudMor	@Claudio__Moroni