igraph (R interface)

Installation

To install the library from CRAN, use:

install.packages("igraph")

More details on dependencies, requirements, and troubleshooting on installation are found on the main documentation page.

Usage

To use igraph in your R code, you must first load the library:

library("igraph")

## 
## Attaching package: 'igraph'

## The following objects are masked from 'package:stats':
## 
##     decompose, spectrum

## The following object is masked from 'package:base':
## 
##     union

Now you have all igraph functions available.

Creating a graph

igraph offers many ways to create a graph. The simplest one is the function make_empty_graph():

g <- make_empty_graph()

The most common way to create a graph is make_graph(), which constructs a network based on specified edges. For example, to make a graph with 10 nodes (numbered 1 to 10) and two edges connecting nodes 1-2 and 1-5:

g <- make_graph(edges = c(1, 2, 1, 5), n = 10, directed = FALSE)

Starting from igraph 0.8.0, you can also include literal here, via igraph’s formula notation. In this case, the first term of the formula has to start with a ~ character, just like regular formulae in R. The expressions consist of vertex names and edge operators. An edge operator is a sequence of - and + characters, the former is for the edges and the latter is used for arrow heads. The edges can be arbitrarily long, that is to say, you may use as many - characters to “draw” them as you like. If all edge operators consist of only - characters then the graph will be undirected, whereas a single + character implies a directed graph: that is to say to create the same graph as above:

g <- make_graph(~ 1--2, 1--5, 3, 4, 5, 6, 7, 8, 9, 10)

We can print the graph to get a summary of its nodes and edges:

g

## IGRAPH 5546ea9 UN-- 10 2 -- 
## + attr: name (v/c)
## + edges from 5546ea9 (vertex names):
## [1] 1--2 1--5

This means: Undirected Named graph with 10 vertices and 2 edges, with the exact edges listed out. If the graph has a [name] attribute, it is printed as well.

NOTE: summary() does not list the edges, which is convenient for large graphs with millions of edges:

summary(g)

## IGRAPH 5546ea9 UN-- 10 2 -- 
## + attr: name (v/c)

The same function make_graph() can create some notable graphs by just specifying their name. For example you can create the graph that represents the social network of Zachary’s karate club, that shows the friendship between 34 members of a karate club at a US university in the 1970s:

g <- make_graph("Zachary")

To visualize a graph you can use plot():

plot(g)

A more detailed description of plotting options is provided later on in this tutorial.

Vertex and edge IDs

Vertices and edges have numerical vertex IDs in igraph. Vertex IDs are always consecutive and they start with 1. For a graph with n vertices the vertex IDs are always between 1 and n. If some operation changes the number of vertices in the graphs, for instance a subgraph is created via induced_subgraph(), then the vertices are renumbered to satisfy this criterion.

The same is true for the edges as well: edge IDs are always between 1 and m, the total number of edges in the graph.

NOTE: If you are familiar with the C core or the Python interface of igraph, you might have noticed that in those languages vertex and edge IDs start from 0. In the R interface, both start from 1 instead, to keep consistent with the convention in each language.

In addition to IDs, vertices and edges can be assigned a name and other attributes. That makes it easier to track them whenever the graph is altered. Examples of this pattern are shown later on in this tutorial.

Adding/deleting vertices and edges

Let’s continue working with the Karate club graph. To add one or more vertices to an existing graph, use add_vertices():

g <- add_vertices(g, 3)

Similarly, to add edges you can use add_edges():

g <- add_edges(g, edges = c(1, 35, 1, 36, 34, 37))

Edges are added by specifying the source and target vertex IDs for each edge. This call added three edges, one connecting vertices 1 and 35, one connecting vertices 1 and 36, and one connecting vertices 34 and 37.

In addition to the add_vertices() and add_edges() functions, the plus operator can be used to add vertices or edges to graph. The actual operation that is performed depends on the type of the right hand side argument:

g <- g + edges(c(1, 35, 1, 36, 34, 37))

You can add a single vertex/edge at a time using add_vertex() and add_edge() (singular).

Warning: If you need to add multiple edges to a graph, it is much more efficient to call add_edges() once rather than repeatedly calling add_edge() with a single new edge. The same applies when deleting edges and vertices.

If you try to add edges to vertices with invalid IDs (i.e., you try to add an edge to vertex 38 when the graph has only 37 vertices), igraph shows an error:

g <- add_edges(g, edges = c(38, 37))

## Error in add_edges(g, edges = c(38, 37)): At vendor/cigraph/src/graph/type_indexededgelist.c:261 : Out-of-range vertex IDs when adding edges. Invalid vertex ID

Let us add some more vertices and edges to our graph. In igraph we can use the magrittr package, which provides a mechanism for chaining commands with the operator %\>%:

g <- g %>%
  add_edges(edges = c(1, 34)) %>%
  add_vertices(3) %>%
  add_edges(edges = c(38, 39, 39, 40, 40, 38, 40, 37))
g

## IGRAPH 9d8b3c7 U--- 40 86 -- Zachary
## + attr: name (g/c)
## + edges from 9d8b3c7:
##  [1]  1-- 2  1-- 3  1-- 4  1-- 5  1-- 6  1-- 7  1-- 8  1-- 9  1--11  1--12
## [11]  1--13  1--14  1--18  1--20  1--22  1--32  2-- 3  2-- 4  2-- 8  2--14
## [21]  2--18  2--20  2--22  2--31  3-- 4  3-- 8  3--28  3--29  3--33  3--10
## [31]  3-- 9  3--14  4-- 8  4--13  4--14  5-- 7  5--11  6-- 7  6--11  6--17
## [41]  7--17  9--31  9--33  9--34 10--34 14--34 15--33 15--34 16--33 16--34
## [51] 19--33 19--34 20--34 21--33 21--34 23--33 23--34 24--26 24--28 24--33
## [61] 24--34 24--30 25--26 25--28 25--32 26--32 27--30 27--34 28--34 29--32
## [71] 29--34 30--33 30--34 31--33 31--34 32--33 32--34 33--34  1--35  1--36
## + ... omitted several edges

We now have an undirected graph with 40 vertices and 86 edges. Vertex and edge IDs are always contiguous, so if you delete a vertex all subsequent vertices will be renumbered. When a vertex is renumbered, edges are not renumbered, but their source and target vertices will be. Use delete_vertices() and delete_edges() to perform these operations. For instance, to delete the edge connecting vertices 1-34, get its ID and then delete it:

edge_id_to_delete <- get.edge.ids(g, c(1, 34))
edge_id_to_delete

## [1] 82

g <- delete_edges(g, edge_id_to_delete)

As an example, to create a broken ring:

g <- make_ring(10) %>% delete_edges("10|1")
plot(g)

The example above shows that you can also refer to edges with strings containing the IDs of the source and target vertices, connected by a pipe symbol |. "10|1" in the above example means the edge that connects vertex 10 to vertex 1. Of course you can also use the edge IDs directly, or retrieve them with the get.edge.ids() function:

g <- make_ring(5)
g <- delete_edges(g, get.edge.ids(g, c(1, 5, 4, 5)))
plot(g)

As another example, let’s make a chordal graph. Remember that a graph is chordal (or triangulated) if each of its cycles of four or more nodes has a chord, which is an edge joining two nodes that are not adjacent in the cycle. First, let’s create the initial graph using graph_from_literal():

g1 <- graph_from_literal(
  A - B:C:I, B - A:C:D, 
  C - A:B:E:H, 
  D - B:E:F,
  E - C:D:F:H, 
  F - D:E:G, 
  G - F:H, 
  H - C:E:G:I,
  I - A:H
)
plot(g1)

In the example above, the : operator was used to define vertex sets. If an edge operator connects two vertex sets, then every vertex from the first set will be connected to every vertex in the second set. Then we use is_chordal() to evaluate if our graph is chordal and to search what edges are missing to fill-in the graph:

is_chordal(g1, fillin = TRUE)

## $chordal
## [1] FALSE
## 
## $fillin
##  [1] 2 6 8 7 5 7 2 7 6 1 7 1
## 
## $newgraph
## NULL

We can then add the edges required to make the initial graph chordal in a single line:

chordal_graph <- add_edges(g1, is_chordal(g1, fillin = TRUE)$fillin)
plot(chordal_graph)

Constructing graphs

In addition to make_empty_graph(), make_graph(), and make_graph_from_literal(), igraph includes many other function to construct a graph. Some are deterministic, that is to say they produce the same graph each single time, for instance make_tree():

graph1 <- make_tree(127, 2, mode = "undirected")
summary(g)

## IGRAPH 44a2acb U--- 5 3 -- Ring graph
## + attr: name (g/c), mutual (g/l), circular (g/l)

This generates a regular tree graph with 127 vertices, each vertex having two children. No matter how many times you call make_tree(), the generated graph will always be the same if you use the same parameters:

graph2 <- make_tree(127, 2, mode = "undirected")

identical_graphs(graph1, graph2)

## [1] TRUE

Other functions generate graphs stochastically, which means they produce a different graph each time. For instance sample_grg():

graph1 <- sample_grg(100, 0.2)
summary(graph1)

## IGRAPH d29faea U--- 100 507 -- Geometric random graph
## + attr: name (g/c), radius (g/n), torus (g/l)

This generates a geometric random graph: n points are chosen randomly and uniformly inside the unit square and pairs of points closer to each other than a predefined distance d are connected by an edge. If you generate GRGs with the same parameters, they will be different:

graph2 <- sample_grg(100, 0.2)
identical_graphs(graph1, graph2)

## [1] FALSE

A slightly looser way to check if the graphs are equivalent is via isomorphic. Two graphs are said to be isomorphic if they have the same number of components (vertices and edges) and maintain a one-to-one correspondence between vertices and edges, that is to say, they are connected in the same way.

isomorphic(graph1, graph2)

## [1] FALSE

Checking for isomorphism can take a while for large graphs (in this case, the answer can quickly be given by checking the degree sequence of the two graphs). identical_graph() is a stricter criterion than isomorphic(): the two graphs must have the same list of vertices and edges, in exactly the same order, with same directedness, and the two graphs must also have identical graph, vertex and edge attributes.

Setting and retrieving attributes

In addition to IDs, vertex and edges can have attributes such as a name, coordinates for plotting, metadata, and weights. The graph itself can have such attributes too (for instance a name, which will show in summary()). In a sense, every graph, vertex and edge can be used as an R namespace to store and retrieve these attributes.

To demonstrate the use of attributes, let us create a simple social network:

g <- make_graph(
  ~ Alice - Boris:Himari:Moshe, Himari - Alice:Nang:Moshe:Samira,
  Ibrahim - Nang:Moshe, Nang - Samira
)

Each vertex represents a person, so we want to store ages, genders and types of connection between two people (is_formal() refers to whether a connection between one person or another is formal or informal, respectively colleagues or friends). The \$ operator is a shortcut to get and set graph attributes. It is shorter and just as readable as graph_attr() and set_graph_attr().

V(g)$age <- c(25, 31, 18, 23, 47, 22, 50)
V(g)$gender <- c("f", "m", "f", "m", "m", "f", "m")
E(g)$is_formal <- c(FALSE, FALSE, TRUE, TRUE, TRUE, FALSE, TRUE, FALSE, FALSE)
summary(g)

## IGRAPH fddc1b6 UN-- 7 9 -- 
## + attr: name (v/c), age (v/n), gender (v/c), is_formal (e/l)

V() and E() are the standard way to obtain a sequence of all vertices and edges, respectively. This assigns an attribute to all vertices/edges at once. Another way to generate our social network is with the use of set_vertex_attr() and set_edge_attr() and the operator %\>%:

g <- make_graph(
  ~ Alice - Boris:Himari:Moshe, Himari - Alice:Nang:Moshe:Samira,
  Ibrahim - Nang:Moshe, Nang - Samira
) %>%
  set_vertex_attr("age", value = c(25, 31, 18, 23, 47, 22, 50)) %>%
  set_vertex_attr("gender", value = c("f", "m", "f", "m", "m", "f", "m")) %>%
  set_edge_attr("is_formal", value = c(FALSE, FALSE, TRUE, TRUE, TRUE, FALSE, TRUE, FALSE, FALSE))
summary(g)

To assign or modify an attribute for a single vertex/edge:

E(g)$is_formal

## [1] FALSE FALSE  TRUE  TRUE  TRUE FALSE  TRUE FALSE FALSE

E(g)$is_formal[1] <- TRUE
E(g)$is_formal

## [1]  TRUE FALSE  TRUE  TRUE  TRUE FALSE  TRUE FALSE FALSE

Attribute values can be set to any R object, but note that storing the graph in some file formats might result in the loss of complex attribute values. Vertices, edges and the graph itself can all be used to set attributes, for instance to add a date to the graph:

g$date <- c("2022-02-11")
graph_attr(g, "date")

## [1] "2022-02-11"

To retrieve attributes, you can also use graph_attr(), vertex_attr(), and edge_attr(). To find the ID of a vertex you can use the function match():

match(c("Ibrahim"), V(g)$name)

## [1] 7

To assign attributes to a subset of vertices or edges, you can use:

V(g)$name[1:3] <- c("Alejandra", "Bruno", "Carmina")
V(g)

## + 7/7 vertices, named, from fddc1b6:
## [1] Alejandra Bruno     Carmina   Moshe     Nang      Samira    Ibrahim

To delete attributes:

g <- delete_vertex_attr(g, "gender")
V(g)$gender

## NULL

If you want to save a graph in R with all the attributes use the R’s standard function dput() function and retrieve it later with dget(). You can also just save the R workspace and restore it later.

Structural properties of graphs

igraph provides a large set of functions to calculate various structural properties of graphs. It is beyond the scope of this tutorial to document all of them, hence this section will only introduce a few of them for illustrative purposes. We will work on the small social network constructed in the previous section.

Perhaps the simplest property one can think of is the degree. The degree of a vertex equals the number of edges adjacent to it. In case of directed networks, we can also define in-degree (the number of edges pointing towards the vertex) and out-degree (the number of edges originating from the vertex). igraph is able to calculate all of them using a simple syntax:

degree(g)

## Alejandra     Bruno   Carmina     Moshe      Nang    Samira   Ibrahim 
##         3         1         4         3         3         2         2

If the graph was directed, we would have been able to calculate the in- and out-degrees separately using degree(mode = "in") and degree(mode = "out"). You can also pass a single vertex ID or a list of vertex IDs to degree() if you want to calculate the degrees for only a subset of vertices:

degree(g, 7)

## Ibrahim 
##       2

degree(g, v = c(3, 4, 5))

## Carmina   Moshe    Nang 
##       4       3       3

Most functions that accept vertex IDs also accept vertex names (the values of the name vertex attribute) as long as the names are unique:

degree(g, v = c("Carmina", "Moshe", "Nang"))

## Carmina   Moshe    Nang 
##       4       3       3

It also works for single vertices:

degree(g, "Bruno")

## Bruno 
##     1

A similar syntax is used for most of the structural properties igraph can calculate. For vertex properties, the functions accept a vertex ID, a vertex name, or a list of vertex IDs or names (and if they are omitted, the default is the set of all vertices). For edge properties, the functions accept a single edge ID or a list of edge IDs.

NOTE: For some measures, it does not make sense to calculate them only for a few vertices or edges instead of the whole graph, as it would take the same time anyway. In this case, the functions won’t accept vertex or edge IDs, but you can still restrict the resulting list later using standard operations. One such example is eigenvector centrality (evcent()).

Besides degree, igraph includes built-in routines to calculate many other centrality properties, including vertex and edge betweenness (edge_betweenness()) or Google’s PageRank (page_rank()) just to name a few. Here we just illustrate edge betweenness:

edge_betweenness(g)

## [1] 6 6 4 3 4 4 4 2 3

Now we can also figure out which connections have the highest betweenness centrality:

ebs <- edge_betweenness(g)
as_edgelist(g)[ebs == max(ebs), ]

##      [,1]        [,2]     
## [1,] "Alejandra" "Bruno"  
## [2,] "Alejandra" "Carmina"

Querying vertices and edges based on attributes

which.max(degree(g))

## Carmina 
##       3

graph <- graph.full(n = 10)
only_odd_vertices <- which(V(graph) %% 2 == 1)
length(only_odd_vertices)

## [1] 5

seq <- V(graph)[2, 3, 7]
seq

## + 3/10 vertices, from f1741e6:
## [1] 2 3 7

seq <- seq[1, 3] # filtering an existing vertex set
seq

## + 2/10 vertices, from f1741e6:
## [1] 2 7

seq <- V(graph)[2, 3, 7, "foo", 3.5]
## Error in simple_vs_index(x, ii, na_ok) : Unknown vertex selected

V(g)[age < 30]$name

## [1] "Alejandra" "Carmina"   "Moshe"     "Samira"

`%notin%` <- Negate(`%in%`)

V(g)$degree <- c("A", "B", "B+", "A+", "C", "A", "B")
V(g)$degree[degree(g) == 3]

## [1] "A"  "A+" "C"

V(g)$name[degree(g) == 3]

## [1] "Alejandra" "Moshe"     "Nang"

E(g)[.from(3)]

## + 4/9 edges from fddc1b6 (vertex names):
## [1] Alejandra--Carmina Carmina  --Moshe   Carmina  --Nang    Carmina  --Samira

E(g)[.from("Carmina")]

## + 4/9 edges from fddc1b6 (vertex names):
## [1] Alejandra--Carmina Carmina  --Moshe   Carmina  --Nang    Carmina  --Samira

E(g)[3:5 %--% 5:6]

## + 3/9 edges from fddc1b6 (vertex names):
## [1] Carmina--Nang   Carmina--Samira Nang   --Samira

V(g)$gender <- c("f", "m", "f", "m", "m", "f", "m")

men <- V(g)[gender == "m"]$name
men

## [1] "Bruno"   "Moshe"   "Nang"    "Ibrahim"

women <- V(g)[gender == "f"]$name
women

## [1] "Alejandra" "Carmina"   "Samira"

E(g)[men %--% women]

## + 5/9 edges from fddc1b6 (vertex names):
## [1] Alejandra--Bruno  Alejandra--Moshe  Carmina  --Moshe  Carmina  --Nang  
## [5] Nang     --Samira

Treating a graph as an adjacency matrix

The adjacency matrix is another way to represent a graph. In an adjacency matrix, rows and columns are labeled by graph vertices, and the elements of the matrix indicate the number of edges between vertices i and j. The adjacency matrix for the example graph is:

as_adjacency_matrix(g)

## 7 x 7 sparse Matrix of class "dgCMatrix"
##           Alejandra Bruno Carmina Moshe Nang Samira Ibrahim
## Alejandra         .     1       1     1    .      .       .
## Bruno             1     .       .     .    .      .       .
## Carmina           1     .       .     1    1      1       .
## Moshe             1     .       1     .    .      .       1
## Nang              .     .       1     .    .      1       1
## Samira            .     .       1     .    1      .       .
## Ibrahim           .     .       .     1    1      .       .

For example, Carmina (1, 0, 0, 1, 1, 1, 0) is directly connected to Alejandra (who has vertex index 1), Moshe (index 4), Nang (index 5) and Samira (index 6), but not to Bruno (index 2) or to Ibrahim (index 7).

Layouts and plotting

A graph is an abstract mathematical object without a specific representation in 2D, 3D or any other geometric space. This means that whenever we want to visualise a graph, we have to find a mapping from vertices to coordinates in two- or three-dimensional space first, preferably in a way that is useful and/or pleasing for the eye. A separate branch of graph theory, namely graph drawing, tries to solve this problem via several graph layout algorithms. igraph implements quite a few layout algorithms and is also able to draw them onto the screen or to any output format that R itself supports.

layout <- layout_with_kk(g)

layout <- layout_as_tree(g, root = 2)

layout <- layout_with_kk(g)

plot(g, layout = layout, main = "Social network with the Kamada-Kawai layout algorithm")

plot(
  g,
  layout = layout_with_fr,
  main = "Social network with the Fruchterman-Reingold layout algorithm"
)

V(g)$color <- ifelse(V(g)$gender == "m", "yellow", "red")
plot(
  g,
  layout = layout, vertex.label.dist = 3.5,
  main = "Social network - with genders as colors"
)

plot(g, layout = layout, vertex.label.dist = 3.5, vertex.color = as.factor(V(g)$gender))

plot(g,
  layout = layout, vertex.label.dist = 3.5, vertex.size = 20,
  vertex.color = ifelse(V(g)$gender == "m", "yellow", "red"),
  edge.width = ifelse(E(g)$is_formal, 5, 1)
)

igraph and the outside world

No graph module would be complete without some kind of import/export functionality that enables the package to communicate with external programs and toolkits. igraph is no exception: it provides functions to read the most common graph formats and to save graphs into files obeying these format specifications. The main functions for reading and writing from/to file are read_graph() and write_graph(), respectively. The following table summarises the formats igraph can read or write:

NOTE: Each file format has its own limitations. For instance, not all of them can store attributes. Your best bet is probably GraphML or GML if you want to save igraph graphs in a format that can be read from an external package and you want to preserve numeric and string attributes. Edge list and NCOL is also fine if you don’t have attributes (NCOL supports vertex names and edge weights, though).

Where to go next

This tutorial is a brief introduction to igraph in R. We sincerely hope you enjoyed reading it and that it will be useful for your own network analyses.

For a detailed description of specific functions, see https://r.igraph.org/reference/. For questions on how to use igraph, please visit our Forum. To report a bug, open a Github issue. Please do not ask usage questions on Github directly as it’s meant for developers rather than users.

Session info

For the sake of reproducibility, the session information for the code above is the following:

sessionInfo()

## R version 4.3.2 (2023-10-31)
## Platform: aarch64-apple-darwin20 (64-bit)
## Running under: macOS Sonoma 14.3.1
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRblas.0.dylib 
## LAPACK: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0
## 
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## time zone: Europe/Zurich
## tzcode source: internal
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] igraph_2.0.3
## 
## loaded via a namespace (and not attached):
##  [1] digest_0.6.34     R6_2.5.1          fastmap_1.1.1     Matrix_1.6-5     
##  [5] xfun_0.42         lattice_0.22-5    magrittr_2.0.3    cachem_1.0.8     
##  [9] knitr_1.45        pkgconfig_2.0.3   htmltools_0.5.7   rmarkdown_2.26   
## [13] lifecycle_1.0.4   cli_3.6.2         grid_4.3.2        sass_0.4.8       
## [17] jquerylib_0.1.4   compiler_4.3.2    highr_0.10        rstudioapi_0.15.0
## [21] tools_4.3.2       evaluate_0.23     bslib_0.6.1       yaml_2.3.8       
## [25] rlang_1.1.3       jsonlite_1.8.8