The R package igraph has kept us busy for a while now, and we are happy that this will stay like that for a while. After successfully finishing the project “Setting up igraph for success in the next decade”, we are now starting a new project funded by the R Consortium’s ISC: “Bridging Worlds: Enhancing R igraph with C Core Innovations”. After many maintenance tasks, we are now looking forward to bringing new features to the R package igraph. In this post, we will give you a short overview of the project, what we hope to achieve and what you can expect in the next months.
Project overview
The workhorse of the igraph R package is the igraph C library (“C core”). The R package re-distributes the source of the C core, that we regularly update. The project will focus on strengthening the bridge between the high-performance C library and the R package. Although some steps have already been automated to bring new features (or improvements) from C to R, there always remains manual work to make everything run as intended. This manual work has created a backlog of new features that are not yet available in the R package which we will tackle in this project. Ideally, this backlog is cleared by extended automation, so that new features can be included in the R package with minimal manual intervention.
Alongside this tooling improvement, the project will also revisit how
functionality is distributed between the C library and the R layer.
Features like sparse matrix support, which is currently implemented in
R, should be moved to the C library to improve performance and
consistency. Better separation of concerns will help reduce duplication
and ensure that the growing R package remains aligned with other igraph
interfaces.
In a perfect world, the R package would just provide automatic bindings
to the C core, with minimal additional logic in R. We hope to make
significant steps towards this ideal state during the project.
Exposing C functionality to R
A sketch of how new features from the C core are currently introduced to the R package is shown in the diagram below.
The whole C code is vendored into (distributed with) the R package via Github Actions, commit by commit. This approach provides better control, stability, and maintainability than simply copying the library from time to time or when a new release is made.
Vendoring the C library is one thing but actually exposing the
functionality to R is a whole different story. The igraph project uses a
code generator called stimulus
which automates much of the connection between R and C by exposing C
functions to R in the file R/aaa-auto.R.
The code below shows an example of a function definition which was
automatically generated with stimulus. All these functions are generated
in R/aaa-auto.R.
is_clique_impl <- function(graph, candidate, directed=FALSE) {
# Argument checks
ensure_igraph(graph)
candidate <- as_igraph_vs(graph, candidate)
directed <- as.logical(directed)
on.exit( .Call(R_igraph_finalizer) )
# Function call
res <- .Call(R_igraph_is_clique, graph, candidate-1, directed)
res
}
While this autogeneration is an immense help for exposing new
functionality, it does not include some of the necessary steps to make
the function usable in R. For example, the autogenerated function does
not include any documentation, examples (or tests). This part still
needs to be done manually. The manually annotated function of the
autogenerated code can be found in R/clique.R and looks like this:
#' @rdname cliques
#'
#' @description
#' Tests if all pairs within a set of vertices are adjacent, i.e. whether they
#' form a clique. An empty set and singleton set are considered to be a clique.
#'
#' @param graph The input graph.
#' @param candidate The vertex set to test for being a clique.
#' @param directed Whether to consider edge directions.
#' @return `is_clique()` returns `TRUE` if the candidate vertex set forms
#' a clique.
#' @keywords graphs
#' @export
#' @cdocs igraph_is_clique
is_clique <- is_clique_impl
A key part of the project is to explore ways to also automate the documentation and examples for these autogenerated functions. If this is successful, then there is essentially no manual intervention necessary to bring new C functionality to R.
Current Status
As of July 2025, there are 19 open issues about exposing existing
features from the C library. However, since the C library is
automatically vendored and new functions aautomatically included in
R/aaa-auto.R via stimulus, the actual number of functions that are not
yet exposed in the R package is much higher. A crude script exposed that
89 functions defined in aaa-auto.R are not used in any other file
R/*.R. While this number certainly contains some false positives, it
still points to a significant amount of unused functionality that needs
to be exposed to the user.
Extending the Documentation
A smaller but still important part of the project is to improve the documentation of the R package igraph, mainly by providing beginner-friendly vignettes. Vignettes are an essential part of R packages, providing users with practical examples and explanations of how to use the package effectively. The igraph package currently lacks comprehensive vignettes and only provides a rudimentary “getting started” guide. Our goal is to significantly improve the documentation by adding new vignettes that cover various aspects of network analysis, such as centrality, community detection and visualization.
Outlook
We are excited to work on this new project and the potential it has to improve the R package igraph. We hope that by spring 2026, we will have a much more stable and feature-rich R package that is better aligned with the C library and easier to extend via new automated tooling.
Contributing
If you are interested in contributing to the project or the R package igraph in general, we welcome your help! Be that suggesting topics for vignettes, directly writing a vignette for a specific topic, or fixing an open issues on GitHub. All efforts are welcome and appreciated!
To get started, check out our coontribution guidelines for more information.