normalizeGraphSpace,GraphSpace-method: Normalize node coordinates to graph and image spaces

Description

Accessory function to normalize node coordinates of a GraphSpace object, either by centering nodes within the plot boundaries or by mapping nodes to pixel coordinates of a background image.

Usage

# S4 method for GraphSpace
normalizeGraphSpace(
  gs,
  mar = 0.1,
  image.space = .has_image(gs),
  flip.x = FALSE,
  flip.y = image.space,
  flip.v = FALSE,
  flip.h = FALSE,
  swap.xy = FALSE,
  equal.mar = FALSE,
  verbose = TRUE
)

Value

A GraphSpace object with updated nodes

and image slots.

Arguments

gs: A GraphSpace object to be normalized.
mar: A single numeric value in [0, 0.5] setting the margins around the graph, as a fraction of the final normalized space. For example, mar = 0.1 leaves a margin of 0.1 on each side, so the graph occupies the central 0.8 of the space. With an image, the image is cropped to the same proportions; if the graph lies close to an image border, the crop is shifted or truncated to stay within the image, and the requested margin may not be reached.
image.space: Logical; if an image is available, whether to use it as a background reference map. When enabled, x and y graph coordinates are interpreted as pixel coordinates in the image matrix. Images can be inspected and assigned with gs_image.
flip.x: Logical; whether to flip the node coordinates along the x-axis.
flip.y: Logical; whether to flip the node coordinates along the y-axis. Useful for aligning nodes with image backgrounds, which often use an inverted coordinate system. Defaults to image.space.
flip.v: Logical; whether to vertically flip the background image matrix (top-to-bottom) to align with the graph coordinate system.
flip.h: Logical; whether to horizontally flip the background image matrix (left-to-right) to align with the graph coordinate system.
swap.xy: Logical; whether to swap x and y node coordinates. Useful when the graph coordinate system is transposed relative to the image or reference map.
equal.mar: Logical; when an image is available, whether to fit the image with equal margins around the graph, resulting in a tighter crop of the image. If FALSE (default), the image is fitted to the full square figure area, resulting in unequal margins when the graph aspect ratio differs from 1. Both methods preserve the aspect ratios of the image and graph.
verbose: A single logical value specifying to display detailed messages (when verbose=TRUE) or not (when verbose=FALSE).

Details

This function re-scales node coordinates to a [0, 1] unit square based on the graph's bounding box when image.space = FALSE or, when an image is provided and image.space = TRUE, it maps nodes to pixel coordinates. It handles image-to-graph alignment via flip.\* and swap.\* arguments, used to adjust the graph origin with the image matrix layout. Users should be aware of the potential discrepancy between image matrix orientation (top-down) and graph coordinates (bottom-up). The function attempts to automatically adjust the y-axis to align the graph's bottom-up coordinates with the image's top-down layout, but further manual adjustments might be required.

Examples

Run this code

library(RGraphSpace)
library(igraph)

# Create a star graph
gtoy1 <- make_full_graph(30)

# Create a GraphSpace
gs <- GraphSpace(gtoy1)

gs <- normalizeGraphSpace(gs)

plotGraphSpace(gs, add.labels = TRUE)