Type:	Package
Version:	1.1.1
Title:	A Lightweight Interface Between 'igraph' and 'ggplot2' Graphics
Description:	Interface to integrate 'igraph' and 'ggplot2' graphics in a normalized coordinate system. 'RGraphSpace' implements new geometric objects using 'ggplot2' prototypes, customized for side-by-side visualization of multiple graphs. By scaling shapes and graph elements, 'RGraphSpace' helps to create layered visualizations that stay coherent across multiple graphs.
Depends:	R(≥ 4.4), methods, ggplot2
Imports:	grDevices, scales, grid, igraph, rlang, lifecycle, patchwork, cowplot, gtable, ggrastr, circlize
Suggests:	knitr, rmarkdown, testthat
Enhances:	RedeR
License:	Artistic-2.0
VignetteBuilder:	knitr
URL:	https://github.com/sysbiolab/RGraphSpace
BugReports:	https://github.com/sysbiolab/RGraphSpace/issues
Collate:	gspaceChecks.R gspaceValidation.R gspaceConstructor.R gspaceSupplements.R gspaceGeom.R gspaceClasses.R gspaceGenerics.R gspaceMethods.R gspaceMisc.R
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2026-02-27 18:27:43 UTC; maac
Author:	Victor Apolonio [ctb], Vinicius Chagas [ctb], Mauro Castro [aut, cre]
Maintainer:	Mauro Castro <mauro.a.castro@gmail.com>
Repository:	CRAN
Date/Publication:	2026-02-28 17:10:03 UTC

RGraphSpace: A lightweight package for representing large igraph objects in a normalized coordinate system

Description

RGraphSpace is an R package that integrates igraph and ggplot2 graphics within spatial maps. RGraphSpace implements new geometric objects using ggplot2 protypes, customized for representing large igraph objects in a normalized coordinate system. By scaling shapes and graph elements, RGraphSpace can provide a framework for layered visualizations.

Details

Index

Further information is available in the vignettes by typing vignette('RGraphSpace'). Documented topics are also available in HTML by typing help.start() and selecting the RGraphSpace package from the menu.

Author(s)

Maintainer: Mauro Castro mauro.a.castro@gmail.com (ORCID)

Other contributors:

• Victor Apolonio [contributor]

• Vinicius Chagas [contributor]

References

Castro MAA, Wang X, Fletcher MNC, Meyer KB, Markowetz F. RedeR: R/Bioconductor package for representing modular structures, nested networks and multiple levels of hierarchical associations. Genome Biology 13:R29, 2012.

See Also

Useful links:

• https://github.com/sysbiolab/RGraphSpace

• Report bugs at https://github.com/sysbiolab/RGraphSpace/issues

GeomEdgeSpace: a ggplot2 prototype for GraphSpace-class methods

Description

'GeomEdgeSpace' is the underlying ggproto object used by geom_edgespace to draw edge elements in a 2D graph layout, whose properties are controlled by aesthetics such as 'colour' and 'linewidth'.

This 'geom' is designed for graph/network diagrams, where edge attributes are often already in their final form (e.g., hex colors). When used with identity scales, the appearance of edges can be fully controlled by the input data.

Usage

GeomEdgeSpace

Format

An object of class GeomEdgeSpace (inherits from Geom, ggproto, gg) of length 5.

Aesthetics

'GeomEdgeSpace' understands the following aesthetics:

• 'x' Starting horizontal position in 'npc' unit (required).

• 'y' Starting vertical position in 'npc' unit (required).

• 'xend' Ending horizontal position in 'npc' unit (required).

• 'yend' Ending vertical position in 'npc' unit (required).

• 'colour' Edge colour.

• ‘linewidth' Edge width, using ’lwd' standard graphics unit (see gpar).

• ‘linetype' Line type, using ’lty' standard graphics unit (see gpar).

• 'alpha' Transparency applied to the edge colour.

These aesthetics follow ggplot2's conventions for segment-like 'geoms'.

See Also

geom_edgespace, geom_segment

GeomNodeSpace: a ggplot2 prototype for GraphSpace-class methods

Description

'GeomNodeSpace' is the underlying ggproto object used by geom_nodespace to draw node elements in a 2D graph layout. It produces point-like glyphs (typically circles) whose properties are controlled by aesthetics such as 'x', 'y', 'size' and 'colour'.

This geom is designed for graph/network diagrams, where node attributes are often already in their final form (e.g., hex colors). When used with identity scales, the appearance of nodes can be fully controlled by the input data.

Usage

GeomNodeSpace

Format

An object of class GeomNodeSpace (inherits from Geom, ggproto, gg) of length 5.

Aesthetics

'GeomNodeSpace' understands the following aesthetics:

• 'x' Horizontal position in 'npc' unit (required).

• 'y' Vertical position in 'npc' unit (required).

• 'size' Node size in 'npc' unit (required).

• 'fill' Node fill colour.

• 'colour' Node line colour.

• 'shape' Integer code between 0 and 25 (see points).

• ‘linewidth' Line width, using ’lwd' standard graphics unit (see gpar).

• 'alpha' Transparency applied to fill and line colour.

These aesthetics follow ggplot2's conventions for point-like 'geoms'.

Drawing

The 'draw_panel()' method transforms data into panel coordinates and constructs a 'grid::pointsGrob()' for rendering. Node size is expected to be normalized to the range '[0, 1]', so it can be interpreted in graph space using 'npc' unit.

See Also

geom_nodespace, geom_point

Constructor of GraphSpace-class objects

Description

GraphSpace is a constructor of GraphSpace-class objects.

Usage

GraphSpace(g, mar = 0.1, layout = NULL, image = NULL, verbose = TRUE)

Arguments

Value

A GraphSpace class object.

Author(s)

Sysbiolab.

See Also

plotGraphSpace

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

gs <- GraphSpace(gtoy1)

GraphSpace: An S4 class for igraph objects

Description

GraphSpace: An S4 class for igraph objects

Value

An S4 class object.

Slots

nodes

A data frame with xy-vertex coordinates.

edges

A data frame with edges.

graph

An igraph object.

image

A raster background image matrix.

pars

A list with parameters.

misc

A list with intermediate objects for downstream methods.

Constructor

see GraphSpace constructor.

Draw edge elements in a 2D graph layout

Description

Constructor for GeomEdgeSpace ggproto objects, a variant of geom_segment supporting edge attributes and bidirectional arrows.

This 'geom' is designed to create edge-level aesthetics such as 'colour' and 'linewidth', or any custom aesthetics defined in 'GeomEdgeSpace'.

Usage

geom_edgespace(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  show.legend = NA,
  inherit.aes = FALSE,
  lineend = "butt",
  linejoin = "mitre",
  arrow_type = 0,
  arrow_size = 1,
  offset_start = 0,
  offset_end = 0
)

Arguments

Details

Arrowhead size is a numeric scaling factor controlling arrowhead geometry. The value is interpreted in the same numeric space as line width ('lwd'), ensuring consistent scaling between edge strokes and arrowheads.

Arrowhead types can be specified using either integer or character codes:
- No arrow: 0 or "---"
- Forward arrow: 1 or "-->"
- Backward arrow: 2 or "<--"
- Bidirectional arrow: 3 or "<->"
- Forward arrow with backward bar: 4 or "|->"
- Forward bar: -1 or "--|"
- Backward bar: -2 or "|--"
- Bidirectional bar: -3 or "|-|"
- Backward arrow with forward bar: -4 or "<-|"

Value

A ggplot2 layer that renders edge segments defined by GeomEdgeSpace.

Aesthetics

'geom_edgespace' understands the following aesthetics:

• 'x' Starting horizontal position in 'npc' unit (required).

• 'y' Starting vertical position in 'npc' unit (required).

• 'xend' Ending horizontal position in 'npc' unit (required).

• 'yend' Ending vertical position in 'npc' unit (required).

• 'colour' Edge colour.

• ‘linewidth' Edge width, using ’lwd' standard graphics unit (see gpar).

• ‘linetype' Line type, using ’lty' standard graphics unit (see gpar).

• 'alpha' Transparency applied to the edge colour.

See Also

GeomEdgeSpace, GraphSpace

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a GraphSpace object
gs <- GraphSpace(gtoy1)

## Not run: 

ggplot() + geom_edgespace(aes(x = x, y = y, xend = xend, yend = yend),
  data = gs) + theme(aspect.ratio = 1) + 
  scale_x_continuous(limits = c(0, 1)) +
  scale_y_continuous(limits = c(0, 1))


## End(Not run)

Draw node elements in a 2D graph layout

Description

Constructor for GeomNodeSpace ggproto objects, a variant of geom_point supporting node attributes from GraphSpace objects.

This geom is designed to create node-level aesthetics such as 'size', 'fill', 'colour', or any custom aesthetics defined in 'GeomNodeSpace'.

Usage

geom_nodespace(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = TRUE,
  show.legend = NA,
  inherit.aes = FALSE
)

Arguments

Value

A ggplot2 layer that renders node glyphs defined by 'GeomNodeSpace'.

Aesthetics

'geom_nodespace' understands the following aesthetics:

• 'x' Horizontal position in 'npc' unit (required).

• 'y' Vertical position in 'npc' unit (required).

• 'size' Node size in 'npc' unit (required).

• 'fill' Node fill colour.

• 'colour' Node line colour.

• 'shape' Integer code between 0 and 25 (see points).

• ‘linewidth' Line width, using ’lwd' standard graphics unit (see gpar).

• 'alpha' Transparency applied to fill and line colour.

See Also

GeomNodeSpace, GraphSpace

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a GraphSpace object
gs <- GraphSpace(gtoy1)

## Not run: 

ggplot() + geom_nodespace(aes(x = x, y = y), data = gs)


## End(Not run)

Accessors for fetching slots from a GraphSpace object

Description

getGraphSpace retrives information from individual slots available in a GraphSpace object.

Usage

## S4 method for signature 'GraphSpace'
getGraphSpace(gs, what = "graph")

Arguments

Value

Content from slots in the GraphSpace object.

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a new GraphSpace object
gs <- GraphSpace(gtoy1)

# Get the 'summary' slot in gs
getGraphSpace(gs, what = 'graph')

Accessors for applying essential igraph methods to modify attributes of GraphSpace objects.

Description

Access and modify individual slots of a GraphSpace object. Selected 'igraph' methods are applied to the 'graph' slot and propagated to downstream components.

Usage

## S4 method for signature 'GraphSpace'
gs_nodes(x)

## S4 method for signature 'GraphSpace'
gs_edges(x)

## S4 method for signature 'GraphSpace'
gs_vcount(x)

## S4 method for signature 'GraphSpace'
gs_ecount(x)

## S4 method for signature 'GraphSpace'
names(x)

## S4 replacement method for signature 'GraphSpace'
names(x) <- value

## S4 method for signature 'GraphSpace'
gs_vertex_attr(x, name, ...)

## S4 replacement method for signature 'GraphSpace'
gs_vertex_attr(x, name, ...) <- value

## S4 method for signature 'GraphSpace'
gs_edge_attr(x, name, ...)

## S4 replacement method for signature 'GraphSpace'
gs_edge_attr(x, name, ...) <- value

Arguments

Value

Updated GraphSpace object.

See Also

vertex_attr, edge_attr

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a new GraphSpace object
gs <- GraphSpace(gtoy1)

#--- Usage of GraphSpace attribute accessors:

# Get a data frame with nodes for plotting methods
gs_nodes(gs)

# Get a data frame with edges for plotting methods
gs_edges(gs)

# Get vertex count
gs_vcount(gs)

# Get edge count
gs_ecount(gs)

# Get vertex names
names(gs)

# Access all vertex attributes
gs_vertex_attr(gs)

# Access a specific vertex attribute
gs_vertex_attr(gs, "nodeLabel")

# Modify a single value within a vertex attribute
gs_vertex_attr(gs, "nodeSize")["n1"] <- 10

# Replace an entire vertex attribute
gs_vertex_attr(gs, "nodeSize") <- 10

# Alternative syntax using `$` accessor
gs_vertex_attr(gs)$nodeSize <- 10

# Access a specific edge attribute
gs_edge_attr(gs, "edgeLineColor")

# Replace an entire edge attribute
gs_edge_attr(gs, "edgeLineWidth") <- 1

 # Alternative syntax using `$` for edge attributes
gs_edge_attr(gs)$edgeLineWidth <- 3

Toy 'igraph' objects

Description

Small 'igraph' objects used for workflow demonstrations. All graphs include 'x', 'y', and 'name' vertex attributes.

Usage

data(gtoy1)

Format

igraph

Value

A pre-processed igraph object.

Source

This package.

Examples

data(gtoy1)
data(gtoy2)

Create standalone legends for RGraphSpace's ggplot objects

Description

This accessor builds a standalone legend from a named vector of colors. The resulting legend is returned as a 'grob' object that can be used to add external legends to existing ggplots.

Usage

make_gspace_legend(
  color_palette,
  breaks = NULL,
  legend_title = "Title",
  legend_shape = 21,
  legend_size = 6,
  text_size = 10,
  orientation = c("vertical", "horizontal"),
  justification = c("left", "right"),
  custom_theme = theme()
)

add_gspace_legend(
  plot,
  legend,
  spacer = unit(2, "mm"),
  position = c("right", "top", "bottom", "left")
)

Arguments

Details

The object returned by 'add_gspace_legend()' behaves like a ggplot for saving, combining with patchwork, arranging in grids, and rendering in standard graphics devices. Internally, however, the original ggplot is converted into a static 'grob' embedded inside a blank ggplot. As a result, the returned object cannot accept new layers, scales, or other ggplot modifications; it is no longer an editable ggplot, but a wrapped graphical representation of the composed figure.

Value

The 'make_gspace_legend()' function returns a standalone legend, while the 'add_gspace_legend()' function returns a patchwork object containing a plot combined with the generated legend in the specified position.

Examples

library(ggplot2)
library(patchwork)

p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()

# Add a discrete standalone legend to a plot
leg1 <- make_gspace_legend(c(A="red", B="blue"), legend_size = 5)
p + leg1 + plot_layout(widths = c(1, 0.1))

# Add a continuous standalone legend to a plot
leg2 <- make_gspace_legend(c("blue", "white","red"), breaks = c(0, 1, 2))
p + leg2 + plot_layout(widths = c(1, 0.1))

# Add a legend list to a plot
legs <- list(leg1, leg2)
add_gspace_legend(plot = p, legs, position = "right")

Plot GraphSpace objects

Description

Plot GraphSpace objects

Usage

## S3 method for class 'GraphSpace'
plot(x, ...)

Arguments

See Also

plotGraphSpace

Plotting igraph objects with RGraphSpace

Description

plotGraphSpace is a wrapper function to create dedicated ggplot graphics for igraph- and GraphSpace-class objects.

Usage

## S4 method for signature 'GraphSpace'
plotGraphSpace(
  gs,
  theme = c("th0", "th1", "th2", "th3"),
  xlab = "Graph coordinates 1",
  ylab = "Graph coordinates 2",
  font.size = 1,
  bg.color = "grey95",
  add.labels = FALSE,
  node.labels = NULL,
  label.size = 3,
  label.color = "grey20",
  add.image = FALSE,
  raster = FALSE,
  dpi = 300,
  dev = "cairo_png"
)

## S4 method for signature 'igraph'
plotGraphSpace(gs, ..., mar = 0.1)

Arguments

Value

A ggplot-class object.

Author(s)

Sysbiolab.

See Also

GraphSpace

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Generate a ggplot for igraph
plotGraphSpace(gtoy1)

# Create a GraphSpace object
gs <- GraphSpace(gtoy1)

# Generate a ggplot for gs
plotGraphSpace(gs)