# RGraphSpace: A lightweight interface between ‘igraph’ and ‘ggplot2’ graphics

#### Sysbiolab - Bioinformatics and Systems Biology Laboratory

#### 2026-04-24

Abstract

An interface to integrate ‘igraph’ and ‘ggplot2’ graphics within a normalized coordinate system. ‘RGraphSpace’ implements geometric objects based on ‘ggplot2’ prototypes, optimized for the representation of large networks. The package aims to facilitate side-by-side visualization of multiple graphs spatially aligned with reference maps and images.

Package: RGraphSpace 1.2.0

# Highlights

- Native ggplot2 interface for igraph objects
- Optimized geoms for large-scale network visualization
- Dual-anchor normalization for precise spatial alignment
- Aligns networks with background spatial references

# Overview

RGraphSpace is an R package that generates ggplot2 graphics for igraph objects (Csardi and Nepusz 2006), scaling nodes and edges to a unit space. The package implements new ggplot2 geometric prototypes (Wickham 2016), optimized for representing large networks. This enables extensive customization of aesthetics and visual style, including colors, shapes, and line types. Three specialized `geoms` translate graph data into geometric layers (see using geoms). These `geoms` use a dual-anchor normalization approach to align layers, which is critical for analysis where network elements must be accurately referenced to a spatial map. Section mapping graphs to images illustrates how this alignment achieves pixel-level precision. In what follows, this tutorial demonstrates how to use RGraphSpace for side-by-side visualization of multiple graphs.

# Quick start

This section will create a toy igraph object to demonstrate the RGraphSpace workflow. The graph layout is configured manually to ensure that users can easily view all the relevant arguments needed to prepare the input data. We will use the igraph’s `make_star()` function to create a simple star-like graph and then the `V()` and `E()` functions to set attributes for vertices and edges, respectively. The RGraphSpace package will require that all vertices have `x`, `y`, and `name` attributes.

    #--- Load required packages
    library("igraph")
    library("ggplot2")
    library("RGraphSpace")

    # Make a 'toy' igraph with 5 nodes and 4 edges;
    # ..either a directed or undirected graph
    gtoy1 <- make_star(5, mode="out")

    # Check whether the graph is directed or not
    is_directed(gtoy1)
    ## [1] TRUE

    # Check graph size
    vcount(gtoy1)
    ## [1] 5
    ecount(gtoy1)
    ## [1] 4

    # Assign 'x' and 'y' coordinates to each vertex;
    # ..this can be an arbitrary unit in (-Inf, +Inf)
    V(gtoy1)$x <- c(0, 2, -2, -4, -8)
    V(gtoy1)$y <- c(0, 0,  2, -4,  0)

    # Assign a name to each vertex
    V(gtoy1)$name <- paste0("n", 1:5)

    # Plot the 'gtoy1' using standard R graphics
    plot(gtoy1)

    # Plot the 'gtoy1' using RGraphSpace
    plotGraphSpace(gtoy1, add.labels = TRUE)

# RGraphSpace attributes

Next, we will demonstrate all vertex and edge attributes that can be passed to RGraphSpace methods.

## Vertex attributes

    # Node size (numeric in [0, 100], as '%' of the plot space)
    V(gtoy1)$nodeSize <- c(8, 5, 5, 10, 5)

    # Node shape (integer code between 0 and 25; see 'help(points)')
    V(gtoy1)$nodeShape <- c(21, 22, 23, 24, 25)

    # Node color (Hexadecimal or color name)
    V(gtoy1)$nodeColor <- c("red", "#00ad39", "grey80", "lightblue", "cyan")

    # Node line width (as in 'lwd' standard graphics; see 'help(gpar)')
    V(gtoy1)$nodeLineWidth <- 1

    # Node line color (Hexadecimal or color name)
    V(gtoy1)$nodeLineColor <- "grey20"

    # Node labels ('NA' will omit labels)
    V(gtoy1)$nodeLabel <- c("V1", "V2", "V3", "V4", NA)

    # Node label size (in pts)
    V(gtoy1)$nodeLabelSize <- 8

    # Node label color (Hexadecimal or color name)
    V(gtoy1)$nodeLabelColor <- "black"

    # Node transparency (in [0,1])
    V(gtoy1)$nodeAlpha <- 1

## Edge attributes

Given a list of edges, RGraphSpace represents only one edge for each pair of connected vertices. If there are multiple edges connecting the same vertex pairs, it will display the line attributes of the first edge in the list.

    # Edge width (as in 'lwd' standard graphics; see 'help(gpar)')
    E(gtoy1)$edgeLineWidth <- 0.8

    # Edge color (Hexadecimal or color name)
    E(gtoy1)$edgeLineColor <- c("red","green","blue","black")

    # Edge type (as in 'lty' standard graphics; see 'help(gpar)')
    E(gtoy1)$edgeLineType <- c("solid", "11", "dashed", "2124")

    # Edge transparency (in [0,1])
    E(gtoy1)$edgeAlpha <- 1

## Arrowhead attributes

Arrowhead in directed graphs: By default, an arrow will be drawn for each edge according to its left-to-right orientation in the edge list (e.g. `A -> B`).

    # Arrowhead types in directed graphs (integer code or character)
    ## 0 = "---", 1 = "-->", -1 = "--|"
    E(gtoy1)$arrowType <- 1

Arrowhead in undirected graphs: By default, no arrow will be drawn in undirected graphs.

    # Arrowhead types in undirected graphs (integer or character code)
    ##  0 = "---"
    ##  1 = "-->",  2 = "<--",  3 = "<->",  4 = "|->",
    ## -1 = "--|", -2 = "|--", -3 = "|-|", -4 = "<-|",
    E(gtoy1)$arrowType <- 1
    # Note: in undirected graphs, this attribute overrides the
    # edge's orientation in the edge list

… and plot the updated igraph object with RGraphSpace:

    # Plot the updated 'gtoy1' using RGraphSpace
    plotGraphSpace(gtoy1, add.labels = TRUE)

# Using ggplot2 geoms

## Visual integration and aesthetics mapping

This section illustrates how RGraphSpace integrates with the ggplot2 using `geoms` building blocks. Graph attributes stored within the `GraphSpace` object can be handled in two ways:

- Identity mapping: Graph attributes are interpreted as “identity values” (such as `nodeColor`, `nodeSize`, or `nodeShape`) and are displayed exactly as they are, without further scaling or mapping.

- Dynamic aesthetic mapping: Graph attributes are mapped to aesthetics (such as `colour`, `size`, and `shape`) and rendered through standard ggplot2 scales, which automatically generate synchronized legends.

### The GraphSpace geoms

To facilitate this integration, RGraphSpace implements three specialized `geoms` designed to handle graph data types within a ggplot2 workflow:

1. `geom_graphspace()`: A high-level convenience layer that processes both nodes and edges in a single call.
2. `geom_nodespace()`: Dedicated to rendering nodes. Inherits `GeomPoint` aesthetic mappings, modified to inform the edge layer on node states. It can be used with the `inject_nodespace()` function to adjust edge offsets when the `size` aesthetic is applied to nodes.
3. `geom_edgespace()`: Handles the relational data between nodes. Inherits `GeomSegment` aesthetic mappings; unlike standard segments, it is “node-aware” and dynamically calibrates start and end points to connected nodes.

In the following example, we create a small modular graph containing variables of different types in order to demonstrate these geoms.

    # Make a toy modular graph
    library("igraph")
    gtoy3 <- sample_islands(
      islands.n = 3,       # number of modules
      islands.size = 30,   # nodes per module
      islands.pin = 0.25,  # probability of edges within modules
      n.inter = 2)         # edges between modules

    # Assign module membership to nodes
    V(gtoy3)$module <- rep(1:3, each = 30)

    # Assign colors to nodes
    V(gtoy3)$nodeColor <- rainbow(3)[V(gtoy3)$module]

    # Assign a categorical variable to nodes
    V(gtoy3)$node_group <- c("A", "B", "C")[V(gtoy3)$module]

    # Assign numeric variables to nodes and edges
    V(gtoy3)$node_var <- runif(vcount(gtoy3))
    E(gtoy3)$edge_var <- runif(ecount(gtoy3))

    # Create a GraphSpace from the toy igraph
    gs <- GraphSpace(gtoy3)

## Plotting identity values

In this example, `nodeColor` already contains the final colour values stored in the `GraphSpace` object. The colours will be displayed as-is by the `geom_graphspace()` function. This approach is particularly useful when nodes have been pre-processed with specific color schemes and you want the visual output without further mapping.

    ggplot() +
      geom_graphspace(colour = "grey", data = gs) +
      theme(aspect.ratio = 1)

The trade-off on this approach is that, on one hand, all attributes reflect the original data directly, but no legend is accessible. This is because identity scales bypass the scaling and guide-building process of ggplot2. If a legend is required to explain the meaning of these colors, the attribute should be mapped as a variable (e.g., `aes(fill = attribute)`) using standard discrete or continuous scales.

## Mapping categorical variables

In this example, the node categorical variable `node_group` is mapped to the `fill` aesthetic.

    ggplot() +
      geom_graphspace(aes(fill = node_group),
        colour = "grey", data = gs) +
      scale_fill_viridis_d(option = "viridis") +
      theme_gspace_coords()

## Mapping numeric variables

In this example, node and edge numeric variables are mapped to `fill` and `colour` aesthetics, respectively.

    # Map aesthetics to numeric variables
    ggplot() +
      geom_edgespace(aes(colour = edge_var), data = gs) +
      geom_nodespace(aes(fill = node_var),
        colour = "grey", data = gs) +
      scale_colour_continuous(palette = c("cyan","blue")) +
      scale_fill_continuous(palette = c("white","purple")) +
      theme_gspace_coords()

## Using separate colour scales

When multiple geoms use the same aesthetic (for example `colour`) but require mapping to different variables with independent scales, the ggnewscale package can be used to introduce a new scale (Campitelli 2025).

    if (!require("ggnewscale", quietly = TRUE)) {
      install.packages("ggnewscale")
    }
    library("ggnewscale")
    ggplot() +
      geom_edgespace(aes(colour = edge_var), data = gs) +
      scale_colour_continuous(palette = c("cyan","blue")) +
      ggnewscale::new_scale_colour() +
      geom_nodespace(aes(colour = node_var),
        data = gs, stroke = 2, fill = NA) +
      scale_colour_continuous(palette = c("white","purple")) +
      theme_gspace_coords()

# Mapping graphs to images

Images can be used as spatial references for graphs. When a raster image is provided, pixel coordinates define where nodes are positioned, supporting the construction of graphs from image features.

As an example, topographic features extracted from the `volcano` matrix are mapped to graph nodes and visualized over a raster image.

    # Extract pixel coordinates for a specific intensity quantile.
    coords <- which(volcano == quantile(volcano, 0.85), arr.ind = TRUE)

    # Mark target pixels with '0'; it will appear as black in the background.
    # This creates a visual anchor to verify the alignment precision.
    volcano2 <- volcano
    volcano2[coords] <- 0

    # Create an igraph object from the pixel coordinates;
    # note that at this stage, 'y' represents matrix row indices.
    gtoy2 <- igraph::make_empty_graph(n = nrow(coords))
    igraph::V(gtoy2)$y <- coords[,1]
    igraph::V(gtoy2)$x <- coords[,2]

    # Highlight the bottom-row vertex (max 'y' index) to demonstrate alignment;
    # since matrix indexing is top-down, this accounts for the default flip
    # between matrix and plot coordinate systems.
    igraph::V(gtoy2)$nodeColor <- NA
    bottom_row <- which.max(igraph::V(gtoy2)$y)
    igraph::V(gtoy2)$nodeColor[bottom_row] <- adjustcolor("red", 0.4)

    # Initialize a GraphSpace object
    gs <- GraphSpace(gtoy2)

    # Map graph coordinates to the image space; by default,
    # 'y' row indices will be flipped (see comments below).
    gs <- normalizeGraphSpace(gs, image = as_colorraster(volcano2) )

    # Render the graph with the raster as background
    plotGraphSpace(gs, add.image = TRUE)

Note on image alignment: Proper spatial alignment between nodes and the background image requires consistent coordinate conventions. Spatial misalignment may occur if the input image and node coordinates differ in axis orientation (e.g., top-left versus bottom-left origins). To accommodate these differences, `normalizeGraphSpace()` provides orientation controls through the `rotate.xy`, `flip.x`, and `flip.y` arguments. If the nodes appear misaligned with the input image, try combinations of these parameters to correct the alignment. Alternatively, `flip.v` and `flip.h` arguments can be used to apply flipping directly to the background image.

# Interoperability with other packages

## Geospatial data

The following example demonstrates interoperability between RGraphSpace and sf, a well-established infrastructure package for spatial data analysis (Pebesma and Bivand 2023). We will use a spatial network of cities to show how RGraphSpace geoms can be plugged into sf workflows.

    if(!require("sf", quietly = TRUE)){
      install.packages("sf")
    }
    if(!require("rnaturalearth", quietly = TRUE)){
      install.packages("rnaturalearth")
    }
    if(!require("maps", quietly = TRUE)){
      install.packages("maps")
    }
    if(!require("geometry", quietly = TRUE)){
      install.packages("geometry")
    }
    library("RGraphSpace")
    library("igraph")
    library("sf")
    library("maps")
    library("geometry")
    library("rnaturalearth")

    # Load and project map
    map_sf <- ne_countries(country = "Brazil", returnclass = "sf")
    map_proj <- st_transform(map_sf)

    # Filter major cities by regional capitals
    data(world.cities, package = "maps")
    r_capitals <- c(
      "Aracaju", "Belem", "Belo Horizonte", "Boa Vista", "Brasilia",
      "Campo Grande", "Cuiaba", "Curitiba", "Florianopolis", "Fortaleza",
      "Goiania", "Joao Pessoa", "Macapa", "Maceio", "Manaus", "Natal",
      "Palmas", "Porto Alegre", "Porto Velho", "Recife", "Rio Branco",
      "Rio de Janeiro", "Salvador", "Sao Luis", "Sao Paulo", "Teresina",
      "Vitoria"
    )
    cities <- subset(world.cities, country.etc == "Brazil" &
        name %in% r_capitals & pop > 1000000)

    # Create Delaunay triangulation edges
    # Note: the edges hold no particular meaning beyond
    # demonstrating integration between coordinate systems
    tri <- delaunayn(cities[,c("lat","long")])
    edges <- unique(rbind(tri[,c(1,2)], tri[,c(2,3)], tri[,c(1,3)] ))

    # Build igraph with coordinates
    gtoy1 <- igraph::graph_from_edgelist(edges, directed = FALSE)
    igraph::V(gtoy1)$x <- cities$long
    igraph::V(gtoy1)$y <- cities$lat
    igraph::V(gtoy1)$Cities <- cities$name
    igraph::V(gtoy1)$`Population (M)` <- cities$pop/1000000
    igraph::E(gtoy1)$arrowType <- 3

    # Make a GraphSpace
    gs1 <- GraphSpace(gtoy1)

    # Plot
    ggplot() +
      geom_sf(data = map_proj, fill = "grey95", color = "grey60") +
      geom_edgespace(color = "grey40", arrow_size = 0.5,
        arrow_offset = 0.01, data = gs1) +
      geom_nodespace(aes(fill = Cities, size = `Population (M)`),
        data = gs1) +
      scale_size(range = c(3,9)) +
      scale_fill_discrete() +
      inject_nodespace() +
      theme_gspace_legend(key_fill = TRUE)

## Interactive visualization

The following example demonstrates interoperability between RGraphSpace and RedeR, an R/Bioconductor package for interactive network visualization and manipulation.

    # Load RedeR, a graph package for interactive visualization
    ## Note: this example requires Bioc >= 3.19
    if(!require("BiocManager", quietly = TRUE)){
      install.packages("BiocManager")
      #BiocManager::install(version = "3.19")
    }
    if(!require("RedeR", quietly = TRUE)){
      BiocManager::install("RedeR")
    }

    # Launch the RedeR application
    library("RedeR")
    startRedeR()
    resetRedeR()
    data(gtoy1, package = "RGraphSpace")

    # Send 'gtoy1' to the RedeR interface
    addGraphToRedeR(gtoy1, unit="npc")
    relaxRedeR()

    # Fetch 'gtoy1' with a fresh layout
    gtoy2 <- getGraphFromRedeR(unit="npc")

    # Check the round trip...
    plotGraphSpace(gtoy2, add.labels = TRUE)

    ## Note that for the round trip, shapes and line types are
    ## partially compatible between ggplot2 and RedeR.

    # ...alternatively, just update the graph layout
    gtoy2 <- updateLayoutFromRedeR(g=gtoy1)

    # ...check the updated layout
    plotGraphSpace(gtoy2, add.labels = TRUE)

## Other examples

The following vignettes illustrate how RGraphSpace can be used in combination with PathwaySpace to project network signals on landscape images.

Projection of network signals

# Citation

If you use RGraphSpace, please cite:

- Sysbiolab Team. “RGraphSpace: A lightweight interface between igraph and ggplot2 graphics.” R package, 2023. Doi: 10.32614/CRAN.package.RGraphSpace

- Castro MA, Wang X, Fletcher MN, Meyer KB, Markowetz F (2012). “RedeR: R/Bioconductor package for representing modular structures, nested networks and multiple levels of hierarchical associations.” Genome Biology, 13(4), R29. Doi: 10.1186/gb-2012-13-4-r29

# Session information

    #> R version 4.5.3 (2026-03-11)
    #> Platform: x86_64-pc-linux-gnu
    #> Running under: Ubuntu 24.04.4 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    #> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    #>
    #> locale:
    #>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    #>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C
    #>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    #>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    #>  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    #> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    #>
    #> time zone: America/Sao_Paulo
    #> tzcode source: system (glibc)
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] RGraphSpace_1.2.0  ggplot2_4.0.2.9000 igraph_2.3.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] gtable_0.3.6       jsonlite_2.0.0     dplyr_1.2.1        compiler_4.5.3
    #>  [5] tidyselect_1.2.1   ggbeeswarm_0.7.3   dichromat_2.0-0.1  jquerylib_0.1.4
    #>  [9] scales_1.4.0       yaml_2.3.12        fastmap_1.2.0      R6_2.6.1
    #> [13] labeling_0.4.3     generics_0.1.4     knitr_1.51         tibble_3.3.1
    #> [17] bslib_0.10.0       pillar_1.11.1      RColorBrewer_1.1-3 rlang_1.2.0
    #> [21] cachem_1.1.0       xfun_0.57          sass_0.4.10        S7_0.2.1-1
    #> [25] otel_0.2.0         viridisLite_0.4.3  cli_3.6.6          withr_3.0.2
    #> [29] magrittr_2.0.5     digest_0.6.39      grid_4.5.3         rstudioapi_0.17.1
    #> [33] beeswarm_0.4.0     lifecycle_1.0.5    vipor_0.4.7        ggrastr_1.0.2
    #> [37] vctrs_0.7.3        evaluate_1.0.5     glue_1.8.1         farver_2.1.2
    #> [41] rmarkdown_2.31     tools_4.5.3        pkgconfig_2.0.3    htmltools_0.5.9

# References

Campitelli, Elio. 2025. Ggnewscale: Multiple Fill and Colour Scales in ’Ggplot2’. https://doi.org/10.32614/CRAN.package.ggnewscale.
Csardi, Gabor, and Tamas Nepusz. 2006. “The Igraph Software Package for Complex Network Research.” InterJournal Complex Systems: 1695. https://igraph.org/.
Pebesma, Edzer, and Roger Bivand. 2023. Spatial Data Science: With Applications in R. Chapman; Hall/CRC. https://doi.org/10.1201/9780429459016.
Wickham, Hadley. 2016. Ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York. https://ggplot2.tidyverse.org.