Draw node elements in a 2D graph layout

Constructor for GeomNodeSpace ggproto objects.

A wrapper around geom_point that bridges GraphSpace node attributes with ggplot2 rendering via two distinct aesthetic interfaces that coexist without collision (see Two aesthetic interfaces section).

Usage

geom_nodespace(
  mapping = NULL,
  data = NULL,
  stat = StatNodeSpace,
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE,
  raster = FALSE,
  dpi = NULL,
  dev = "cairo",
  scale = 1
)

nodespace_handler(mapping = NULL)

Arguments

mapping: Set of aesthetic mappings created by ggplot2::aes(). These mappings override global aesthetics and are not inherited from the top-level plot.
data: The data to be displayed in this layer. It can be a GraphSpace object, an igraph object, or the nodespace_handler() closure. When NULL (default), a handler is created internally from the mapping argument.
stat: The statistical transformation to use on the data. Defaults to identity.
position: Position adjustment, either as a string or the result of a call to a position adjustment function.
...: Additional parameters passed to the underlying drawing function in GeomNodeSpace.
na.rm: Logical. Should missing values be removed? Defaults to FALSE.
show.legend: Logical or a named logical vector indicating whether this layer should be included in legends.
inherit.aes: Logical. If FALSE (default), the layer will use aesthetics defined in mapping.
raster: Logical. Should node glyphs be rasterized? Rasterization support is based on rasterise.
dpi: Numeric. Rasterization resolution.
dev: Character. Rasterization backend. One of 'cairo', 'ragg', 'ragg_png', or 'cairo_png'.
scale: Numeric. Rasterization scaling factor (see rasterise).

Value

A ggplot2 layer that renders node glyphs defined by GeomNodeSpace.

Details

The interpretation of size depends on how it is provided:

As an aesthetic: When mapped within aes(), size follows the behavior of geom_point, using absolute units to ensure consistency with the plot legends.
As a parameter: When set outside aes(), size is treated as a percentage of the viewport ([0, 100]), scaling in npc units. This allows nodes to resize dynamically with viewport changes.

Aesthetics

geom_nodespace() understands geom_point aesthetics.

If these aesthetics are not explicitly provided in aes(), they are automatically retrieved from the GraphSpace object.

`x`, `y`	Node coordinates (required; automatically supplied).
`fill`	Node interior colour (see aes_colour_fill_alpha).
`colour`	Node border colour (see aes_colour_fill_alpha).
`alpha`	Transparency (see aes_colour_fill_alpha).
`shape`	Node shape (see points and aes_linetype_size_shape).
`size`	Node size (see drawing section and aes_linetype_size_shape).
`stroke`	Node line width (see gg_par and aes_linetype_size_shape).

Required aesthetics are supplied from the GraphSpace object and do not need to be manually mapped.

Fixed identity values can also be passed directly as parameters, bypassing both graph attributes and scale training. For example: fill = "red", stroke = 3, alpha = 0.5, or shape = 21.

Two aesthetic interfaces

geom_nodespace() supports two interfaces that coexist without collision: graph attributes (camelCase names such as nodeColor, nodeSize) and ggplot2 mappings (via aes()). See comments in the vignette.

When multiple sources provide the same aesthetic, priority follows: aes() mapping > fixed parameter > graph attribute.

Label aesthetics

When label is mapped via aes(), a text label is drawn at each node's position using geom_text, rendered on top of the node glyph. Nodes with NA labels are silently skipped.

The label_size and label_colour aesthetics are automatically retrieved from the GraphSpace object when not explicitly provided in aes(). All other label_* aesthetics default to geom_text when not set.

`label`	Required to activate label rendering.
`label_size`	Font size (see `geom_text`).
`label_colour`	Label colour (see `geom_text`).
`label_alpha`	Label transparency (see `geom_text`).
`label_angle`	Rotation angle (see `geom_text`).
`label_hjust`	Horizontal justification (see `geom_text`).
`label_vjust`	Vertical justification (see `geom_text`).
`label_family`	Font family (see `geom_text`).
`label_fontface`	Font face (see `geom_text`).
`label_lineheight`	Line height (see `geom_text`).

Examples

library(RGraphSpace)
library(igraph)
library(ggplot2)

# Make a demo igraph
gtoy1 <- make_star(15, mode="out")

# Set some node attributes
V(gtoy1)$nodeSize <- runif(vcount(gtoy1), 1, 20)
V(gtoy1)$nodeColor <- rainbow(vcount(gtoy1))

# Set some variables
V(gtoy1)$user_var1 <- runif(vcount(gtoy1), 1, 3)^3
V(gtoy1)$user_var2 <-  rep(c(1, 2, 3), each = 5)

# Create a GraphSpace object
gs <- GraphSpace(gtoy1, layout = layout_in_circle(gtoy1))
#> Validating the 'igraph' object...
#> Vertex attribute 'name' missing; assigning names... 
#> Ignoring graph-level attributes: 'name', 'mode', 'center'
#> Creating a 'GraphSpace' object...

if (FALSE) { # \dontrun{

# Example 1: Nodes scaling with the legend
# When 'size' is mapped inside aes(), it follows
# ggplot2 default behavior: size is translated 
# to absolute units (mm) via 'scale_size()'.

ggplot(gs) + 
geom_edgespace(arrow_offset = 0.01) +
geom_nodespace(mapping = aes(size = nodeSize, fill = user_var2)) + 
scale_size(range = c(1, 12)) + 
theme(aspect.ratio = 1)
  
# Example 2: Nodes scaling with the viewport
# When 'size' is passed as a node attribute, 
# inherited from the igraph object, it is 
# interpreted as a percentage of the plotting 
# area and translated to NPC units.

ggplot(gs) + 
geom_edgespace(arrow_offset = 0.01) +
geom_nodespace(mapping = aes(fill = user_var2)) +
theme(aspect.ratio = 1)
  
# Example 3: Node labels
ggplot(gs) +
  geom_edgespace() +
  geom_nodespace(aes(label = nodeLabel)) +
  theme(aspect.ratio = 1)
  
} # }