mully - an R Package to create, modify and visualize multilayered graphs

Zaynab Hammoud

zaynabhassanhammoud@gmail.com

2021-10-14

Introduction

Network theory has been used for many years in the modeling and analysis of complex systems, as epidemiology, biology and biomedicine . As the data evolves and becomes more heterogeneous and complex, monoplex networks become an oversimplification of the corresponding systems. This imposes a need to go beyond traditional networks into a richer framework capable of hosting objects and relations of different scales, called Multilayered Network Mully, multilayer networks, is an R package that provides a multilayer network framework. Using this package, the user can create, modify and visualize graphs with multiple layers. This package is an extension to the igraph package that provides a monolayer graph framework. The package is implemented as a part of the Multipath Project directed by Dr. Frank Kramer . ## Publication More information and references can be found in the mully paper:

https://www.mdpi.com/2073-4425/9/11/519

Installation

Installation via Github

require(devtools)
install_github("frankkramer-lab/mully")

Load the package

library("mully")

Test the package

In this section, we provide a demo to test the package by calling some of the function. After running this script, you will have a graph g with 3 layers and 8 nodes. the graph can also be modified by calling other functions. Please refer to help to see the available functions. ### Create new mully graph

g=mully("MyFirstMully",direct = F)

Add Layers

g=addLayer(g, c("Gene", "Drug", "Disease"))

Add/print Nodes

g=addNode(g,"d1","disease",attributes=list(type="t1"))
  
g=addNode(g,"d2","disease",attributes=list(type="t1"))
  
g=addNode(g,"d3","disease",attributes=list(type="t1"))
  
g=addNode(g,"dr1","drug",attributes=list(effect="strong"))
  
g=addNode(g,"dr2","drug",attributes=list(effect="strong"))

g=addNode(g,"dr3","drug",attributes=list(effect="moderate"))

g=addNode(g,"g1","gene",attributes=list(desc="AF"))
  
g=addNode(g,"g2","gene",attributes=list(desc="BE"))

#See vertices attributes
print(getNodeAttributes(g))

Add/print/remove Edges

g=addEdge(g,"dr1","d2",list(name="treats"))
g=addEdge(g,"dr1","d2",list(name="extraEdge"))
g=addEdge(g,"d2","g1",list(name="targets"))
g=addEdge(g,"g2","dr3",list(name="mutates and causes"))
g=addEdge(g,"dr3","d3",list(name="treats"))

print(getEdgeAttributes(g))
        
removeEdge(g,"d2","dr1",multi=T)

Merge two graphs

#Create a Second graph
g1=mully()

g1=addLayer(g1,c("protein","drug","gene"))

g1=addNode(g1,"dr4","drug",attributes=list(effect="strong"))
g1=addNode(g1,"dr5","drug",attributes=list(effect="strong"))
g1=addNode(g1,"dr6","drug",attributes=list(effect="moderate"))

g1=addNode(g1,"p1","protein")
g1=addNode(g1,"p2","protein")
g1=addNode(g1,"p3","protein")

g1=addNode(g1,"g3","gene")
g1=addNode(g1,"g4","gene")

g1=addEdge(g1,nodeStart = "p2",nodeDest = "p3",attributes = list(name="interacts"))
g1=addEdge(g1,nodeStart = "dr6",nodeDest = "g4",attributes = list(name="targets"))

#Merge both graphs
g12=merge(g,g1)

#Print the graph
print(g12)

Visualization

plot(g12,layout = "scaled")
plot3d(g12)

Available Functions

mully functions are divided into different files depending on their functionnality range: Constructor , Layers Functions , Node Functions , Edge Functions , Merge Function , Visualization Functions , Import Functions , Export Functions , Demo.

Function Description
mully(name,direct) Constructor Function, Create an empty multilayered graph
print(g) Print function
addLayer(g, nameLayer) Add a layer or a set of layers to a graph
removeLayer(g, name,trans) Delete a layer or a set of layers from a graph
isLayer(g, name) Verify if the layer exists in a graph
getLayersCount(g) Get the number of layers in a graph
getLayer(g, nameLayer) Get the nodes on a layer in a graph
getNode(g,nameNode) Get a node from a graph
getIDNode(g,nameNode) Get the id of a node
addNode(g, nodeName, layerName, attributes) Add a node with assigned layer and attributes to a graph
removeNode(g, name,trans) Delete a node or a set of nodes from a graph
getNodeAttributes(g,nameNode) Get the attributes of one or all nodes
addEdge(g, nodeStart, nodeDest, attributes) Add an edge
removeEdge(g, nodeStart, nodeDest,attributes, multi) Delete an edge
getEdgeAttributes(g,nodeStart,nodeDest) Get the attributes of the edges connecting two nodes or all the edges in the graph
getIDEdge(g,nodeStart,nodeDest) Get the ids of the edges connecting two nodes
merge(g1,g2) Merge or unite two graphs
plot(g,layout) Plot the graph in 2D
plot3d(g) Plot the graph in 3D using rgl
importGraphCSV(name,direct,layers,nodes,edges) Import a mully graph from csv files
importLayersCSV(g,file) Import layers to a mully graph from a CSV file
importNodesCSV(g,file) Import nodes to a mully graph from a CSV file
importEdgesCSV(g,file) Import edges to a mully graph from a CSV file

addEdge

Add an edge

The function is used to add an edge to a given mully graph. mully supports multi-edges, i.e. two nodes can be connected with multiple edges. The uniqueness of the edges is based on the connection with the attributes. When adding a new connection between two nodes that are already cnnected, the new edge should have different attributes. The function needs the following arguments:

The function returns the graph, with the added edge.

Example

g=mully::demo()
addEdge(g,"dr3","g2",attributes=list(name="newEdge"))

addLayer

Add a layer or a set of layers to a graph

The function is used to add a new layer to a given mully graph. The layer name should be unique and should not already exist in the graph. The names are not case-sensitive. the function has an internal count, and assigns new IDs to new layers. The internal counr number only increases, i.e. it does not change after deleting a lyer. Therefore the ID of the last added layer is not necessarily the number of layers in the mully graph. The function needs the following arguments:

The function returns the graph, with the layers added.

Example

g=mully::demo()
addLayer(g,"Complex")

addNode

Add a node with assigned layer and attributes to a graph

The function is used to add a node to a given mully graph. The layer to which this node should be added is required. Nodes on single layers should be unique, but can not be on different layers. Layer Names are not case-sensitive. The function needs the following arguments:

The function returns the graph, with the new node.

Example

g=mully::demo()
attributes=list("specie"="Homo Sapiens")
addNode(g = g,nodeName = "g3",layerName = "Gene",attributes = attributes)

exportCSV

Export mully into CSV files

The function is used to export a given mully graph in the CSV Format. Three files will be generated, respectively containing the layers’, nodes’ and edges’ information. The function needs the following arguments:

Example

g=mully::demo()
exportCSV(g)

getEdgeAttributes

Get the attributes of the edges connecting two nodes

The function is used to obtain information on the edges in a given mully graph. The information can be on a single edge or all the edges in the graph. The function needs the following arguments:

The function returns a dataframe containing the edges with their attributes. If both nodes’ arguments are missing, it returns the complete information on edges and their attributes.

Example

g=mully::demo()
##Print all Edges
getEdgeAttributes(g)
##Get a Single Edge
getEdgeAttributes(g,"d2","g1")

getIDEdge

Get the ids of the edges connecting two nodes

The function is used to get the internal ID of an edge in a given mully graph. The function needs the following arguments:

The nodes passed to this function as arguments should be the unique names assigned to the nodes upon addition. mully supports multi-edges, therefore this function may return a list of edges connecting two nodes. The function returns a list containing the ids of the edges connecting the nodes.

Example

g=mully::demo()
getIDEdge(g,"d2","dr1")

getIDNode

Get the id of a node

The function is used to get the internal ID of a given node in a given mully graph. The function needs the following arguments:

The function returns the id of the specified node.

getLayer

Get the nodes on a layer in a graph

The function is used to get the nodes on a given layer in a given mully graph. The layer name is not case-sensitive. The function needs the following arguments:

The function returns a List of the nodes on the given layer.

Example

g=mully::demo()
getLayer(g,"gene")

getLayersCount

Get the number of layers in a graph

The function is used to get the number of layers in a given mully graph. The function needs the following arguments:

The function returns the count of the layers.

Example

g=mully::demo()
getLayersCount(g)

getNode

Get a node from a graph

The function is used to get a node from a given mully graph as an igraph.vs object. The function needs the following arguments:

The function returns the node as igraph.vs.

getNodeAttributes

Get the attributes of a node

The function is used to get a node or a list of nodes with corresponding attributes from a given mully graph. If the node name is missing, the complete node information is extracted. The function needs the following arguments:

The function returns a dataframe containing the attributes of the specified node.

Example

g=mully::demo()
getNodeAttributes(g,layerByName = TRUE)

importEdgesCSV

Import Edges to a mully graph from a CSV file

The function is used to import edges to a mully graph. The function reads a CSV file and adds edges between existing nodes to the graph. The graph should already contain layers and nodes. The function needs the following arguments:

The function returns the mully graph with the added edges.

importGraphCSV

Import a mully graph from CSV files

The function is used to create a graph from CSV files. To create the graph, three files are needed: the layers, nodes and edges. mully also offers functions to import individual files containing nodes’, edges’ and layers information. See Functions importLayersCSV(), importNodesCSV() and importEdgesCSV(). The function needs the following arguments:

The function returns a new mully graph.

importLayersCSV

Import Layers to a mully graph from a CSV file

The function is used to add layers to a mully graph. The function reads a CSV file and adds the layers to the graph. The file should contain the layers’ names. Layer IDs are assigned automatically. The function needs the following arguments:

The function returns the mully graph with the added layers.

importNodesCSV

Import Nodes to a mully graph from a CSV file

The function is used to import nodes into an existing mully graph. The function reads a CSV file and adds the nodes with the attributes to the graph. The graph should already contain layers, and the nodes in the file should have an attribute n referring to the layer assignment. The function needs the following arguments:

The function returns the mully graph with the added nodes.

is.mully

Is this a mully graph?

The function check if a given graph is a mully graph. The function needs the following arguments:

The function returns a boolean indicating whether the graph is or not a mully object. ### isLayer Verify if the layer exists in a graph

This function is used to check if a given mully graph contains a given layer. The layer name is not case-sensitive. The function needs the following arguments:

The function returns a boolean value.

Example

g=mully::demo()
isLayer(g,"Gene")
isLayer(g,"Complex")

merge

Merge or unite two graphs

The function is used to merge two mully graphs. The merge is layer based, i.e. nodes belonging to similar layers in both graphs will be combined in the returned graph. The node names are unique on single layers but can be redundant over different layers. The merge is based on the first arguments, therefore all elements of the second argument will be added to the first. The function needs the following arguments:

The function returns the merge of the two graphs. The merge is based on the first given graph.

Example


#Create First Graph
g=mully::demo()

#Create Second Graph
g1 <- mully("MySecondMully",direct = F)

g1 <- addLayer(g1, c("gene", "Protein", "Drug"))

g1=addNode(g1,"p1","Protein",attributes=list(type="t1"))

g1=addNode(g1,"p2","Protein",attributes=list(type="t1"))

g1=addNode(g1,"p3","Protein",attributes=list(type="t1"))

g1=addNode(g1,"dr6","drug",attributes=list(effect="strong"))

g1=addNode(g1,"dr7","drug",attributes=list(effect="strong"))

g1=addNode(g1,"dr8","drug",attributes=list(effect="moderate"))

g1=addNode(g1,"g3","gene",attributes=list(desc="AF"))

g1=addNode(g1,"g9","gene",attributes=list(desc="BE"))

g1=addEdge(g1,"dr8","g9",list(name="targets"))

g1=addEdge(g1,"p3","p2",list(name="interactWith"))

#Merge Graphs
merge(g,g1)

mully

Create an empty multilayered graph

The function create an empty mully graph. The function needs the following arguments:

The function returns the created multilayered graph. ### plot,mully Plot the graph in 2D

The function is used to plot the mully graph. It uses the plot function from igraph. We do not recommend using this function to plot big graphs, and use plot3d instead. The function needs the following arguments:

plot3d

Plot the graph in 3D using rgl

The funstion is used to generate 3D interactive plots of a mully graph. The 3D plot is generated using the R Package rgl, and uses some of the arguments passed to the igraph function rgl.plot. Most of the arguments are set to default values, but can be changed. The layout is calculated internally based on the layers. The function needs the following arguments:

The function can take the following arguments supported and not ignored by rglplot}: vertex.label, vertex.label.color, edge.color, edge.width, edge.arrow.size,edge.arrow.width.

print,mully

Print a mully graph

The function prints a mully graph. The function needs the following arguments:

Example

g=mully::demo()
print(g)

removeEdge

Delete an edge

The function is used to remove an edge from a given mully graph. Since mully supports multi-edges, a boolean multi is needed to specify whether to delete multiple edges or a single edge. In case one edge should be deleted, the named list of attributes of the edge is required. The function needs the following arguments:

The function returns the graph with the deleted edges.

Example

g=mully::demo()
removeEdge(g,"dr1","d2",multi=TRUE)

removeLayer

Delete a layer or a set of layers from a graph

The function is used to remove a layer from a given mully graph. Removing a layer results deleting all nodes assigned to the layer, and the edges connecting these nodes to other nodes in the graph. Transitive edges between nodes can be added by setting trans to TRUE. The function needs the following arguments:

The function returns the graph, with the given layer and its corresponding nodes and edges removed.

Example

g=mully::demo()
removeLayer(g,"gene",trans=TRUE)

removeNode

Delete a node or a set of nodes from a graph

The function is used to remove a node from a given mully graph. Removing a node results removing the edges connecting this node to other nodes in the graph. Transitive edges can also be added after deletion by setting trans to TRUE (a->b, b->c, removing b with trans=TRUE will add a->c). The function needs the following arguments:

The function returns the graph, with the nodes deleted.

Example

g=mully::demo()
removeNode(g,"dr1",trans=TRUE)