16  Sigma.js: low-level S7 API

library(rtemis.draw)

Attaching package: 'rtemis.draw'

The following object is masked from 'package:graphics':

    Axis

The high-level draw_network() covers matrix and edge-list inputs. To assemble the model and its styling explicitly, use the S7 classes:

1. Build a GraphModel from GraphNode and GraphEdge objects.
2. Combine the model and styling in a SigmaOption.
3. Render with draw().

The graph classes are the renderer-agnostic R counterparts of the graph model used in rtemis.live.

16.1 The same collaboration network

We will use the synthetic network from the high-level chapter: 150 researchers in five teams, with strong collaborations within teams and a few weaker connections between them. The following code recreates it independently, so you can run this chapter on its own. Edge weights are simulated joint-project counts, not observations.

set.seed(42)
team <- rep(LETTERS[1:5], each = 30)
id <- sprintf("%s%02d", team, rep(seq_len(30), 5))
n <- length(id)

# Collaborations are more likely within a team than between teams.
same_team <- outer(team, team, "==")
weights <- matrix(0, n, n, dimnames = list(id, id))
linked <- matrix(runif(n * n), n) < ifelse(same_team, 0.12, 0.002)
linked <- linked & upper.tri(weights)

# A chain connects every researcher, including adjacent teams.
linked[cbind(seq_len(n - 1), 2:n)] <- TRUE
within_team <- linked & same_team
between_teams <- linked & !same_team
weights[within_team] <- sample(3:8, sum(within_team), replace = TRUE)
weights[between_teams] <- sample(1:2, sum(between_teams), replace = TRUE)
weights <- weights + t(weights)

16.2 Building the S7 graph

A GraphModel holds a list of nodes, a list of edges, and a directed flag. Create one GraphNode per researcher and one GraphEdge per collaboration. Use only the upper triangle of the symmetric matrix to avoid duplicate edges:

weighted_degree <- rowSums(weights)
endpoints <- which(upper.tri(weights) & weights > 0, arr.ind = TRUE)

model <- GraphModel(
  nodes = lapply(seq_along(id), function(i) {
    GraphNode(
      id = id[i],
      label = id[i],
      value = unname(weighted_degree[i]),
      group = team[i]
    )
  }),
  edges = lapply(seq_len(nrow(endpoints)), function(i) {
    source <- endpoints[i, 1]
    target <- endpoints[i, 2]
    GraphEdge(
      source = id[source],
      target = id[target],
      weight = weights[source, target],
      sign = 1
    )
  }),
  directed = FALSE
)

• GraphNode: id identifies the node, label supplies its display text, value drives its size, and group retains categorical metadata. Here the size value is weighted degree: the sum of joint-project counts across a researcher’s collaborations.
• GraphEdge: source and target reference node identifiers, weight controls thickness, and sign (1 or -1) controls color when edges are colored by sign.
• GraphModel: nodes, edges, and directed describe the complete graph.

16.3 Rendering a model with draw_graph()

draw_graph() accepts a GraphModel and styling arguments, then builds the render spec. Community coloring uses Louvain communities inferred from the connections; it does not use the supplied group metadata as a color assignment. Small nodes and translucent edges keep the 150-node network readable:

draw_graph(
  model,
  color_by_group = TRUE,
  blend_edges = TRUE,
  node_size = 5,
  edge_scale = 2,
  edge_opacity = 0.35,
  show_labels = FALSE,
  title = "Research collaborations from an S7 model",
  height = 600
)

Hover a node to identify it and highlight its neighbors; scroll to zoom and drag to pan.

16.4 The SigmaOption render spec

draw_graph() builds a SigmaOption internally. Construct it directly to keep the graph and its presentation in one validated object, then pass it to draw(). Here the circular layout places nodes from the same detected community together:

opt <- SigmaOption(
  model = model,
  layout = "circular",
  color_by_group = TRUE,
  blend_edges = TRUE,
  node_size = 4,
  edge_scale = 1.5,
  edge_opacity = 0.3,
  show_labels = FALSE,
  title = "Connections within and between communities"
)

draw(opt, height = 600)

draw() dispatches on the option object, so draw(SigmaOption(...)) selects the Sigma backend just as draw(EChartsOption(...)) selects ECharts. Theme handling is identical across backends: pass theme = NULL (the default) for light/dark auto-detection, a Theme object to force one, or theme = NA for none.

The fields available on SigmaOption (and as arguments to draw_network() / draw_graph()):

• model — the GraphModel to render.
• layout — "force" (ForceAtlas2), "circular", "circlepack", or "random".
• resolution — Louvain resolution; higher values favor more, smaller communities.
• node_size, scale_by_degree — base node radius in pixels, and whether each node is scaled by its value (weighted degree in this example).
• edge_scale — stroke width per unit of normalized weight.
• node_opacity, edge_opacity — transparency.
• show_labels — node labels.
• color_by_group, palette — color nodes by detected community, and the palette to color them with.
• node_color — single node color when not coloring by community.
• positive_color, negative_color, blend_edges — edge colors by sign, or each edge as the blend of its two endpoint colors.
• title — chart title.