Visualize higher-order pathways as smooth blobs overlaid on a network layout. Source nodes are blue, target nodes are red.
plot_simplicial(
x = NULL,
pathways = NULL,
method = "hon",
max_pathways = 10L,
pathway_index = NULL,
anomaly = c("all", "over", "under"),
layout = "circle",
labels = NULL,
node_color = "#4A7FB5",
target_color = "#E8734A",
ring_color = "#F5A623",
node_size = 22,
label_size = 5,
label_color = "#e8e8e8",
target_label_color = NULL,
label_halo = TRUE,
label_halo_color = NULL,
label_halo_width = 0.035,
label_halo_alpha = 0.6,
blob_alpha = 0.25,
blob_colors = NULL,
blob_linetype = NULL,
blob_linewidth = 0.7,
blob_line_alpha = 0.8,
shadow = TRUE,
title = NULL,
dismantled = FALSE,
ncol = NULL,
ordered = NULL,
direction = NULL,
direction_cues = c("shade", "ring", "arrows"),
node_radius = NULL,
legend = NULL,
...
)Invisibly, a ggplot object for the combined overlay. With
dismantled = TRUE the arranged grid is returned instead: a
gtable when gridExtra is available, otherwise a plain list
of the per-pathway ggplot objects. NULL is returned when
there is nothing to draw (no pathways could be extracted). Called for the
side effect of drawing.
A network object: tna, netobject, matrix,
igraph, cograph_network, net_hon,
net_hypa, or simplicial_complex (an unordered
complex — see ordered). When x is a tna or
netobject with sequence data and pathways is
NULL, higher-order pathways are built automatically
using the method parameter.
Character vector of pathway strings, a list of
character vectors, a net_hon / net_hypa object, or
any data.frame with a path column (e.g., the output of
Nestimate::mogen_transitions()). If a data.frame with a
path column is passed as x and pathways is
NULL, it is auto-promoted to pathways and the state
set is derived from the path strings — plot_simplicial(mgt)
works directly. String separators:
"A B -> C", "A -> B -> C", "A, B, C",
"A - B - C", "A B C". Last state is the target.
When a data.frame is passed and a count column is present,
rows are sorted by count descending before max_pathways is
applied. When NULL and x is a model with sequence
data, pathways are built automatically.
Pathway source when auto-building from a
tna/netobject: "hon" (default, higher-order
network), "hypa" (anomalous paths via hypergeometric null),
or "rules" (association-rule itemsets via
Nestimate::association_rules; rules are rendered as
single-colored blobs because itemsets are undirected).
Maximum number of pathways to display. HON
pathways are ranked by count, HYPA by anomaly ratio.
NULL shows all. Default 10.
Optional positive integer vector selecting
ranked pathways after extraction and ranking, before
max_pathways is applied. For example, 2 plots the
second-ranked pathway and 2:4 plots pathways ranked second
through fourth.
HYPA anomaly type to display when plotting a
net_hypa object or auto-building HYPA pathways via
method = "hypa". One of "all", "over", or
"under". Default "all". Ignored (with a warning) for
non-HYPA inputs such as net_hon, net_association_rules,
net_link_prediction, character pathway vectors, or
method = "hon" / "rules", which have no anomaly concept.
"circle" (default) or a coordinate matrix.
Display labels. NULL uses state names.
Source node fill color.
Target node fill color.
Donut ring color.
Node point size.
Label text size.
Label text color (default "#e8e8e8",
very light grey). Light grey reads on both white and dark fills
when the auto-contrast halo is enabled (it is by default).
Applied to both source and target labels unless
target_label_color overrides for targets.
Target-node label color. NULL
(default) reuses label_color.
Logical. Draw a contrasting halo behind each
label so it stays readable on any fill — node disc, blob, or
the white canvas. Default TRUE. The halo is the only
reliable way to keep, e.g., white labels legible when
node_color is also light.
Halo color. NULL (default)
auto-picks black or white based on the luminance of
label_color, so a white label gets a dark halo and vice
versa.
Halo thickness in plot units. Default
0.035; raise for chunkier outlines, lower for subtler
ones, or set to 0 to disable without touching
label_halo.
Halo opacity (0–1). Default 0.6
reads as a soft glow rather than a hard outline; raise toward
1 for sharper contrast on very busy backgrounds.
Blob fill transparency.
Blob fill colors (recycled).
Blob border line styles (recycled).
Blob border line width.
Blob border line transparency.
Draw soft drop shadows?
Plot title.
If TRUE, one panel per pathway arranged
in a grid layout.
Number of columns in the grid when dismantled = TRUE.
Default NULL auto-selects based on the number of pathways.
Is each higher-order structure a PATH or a SET?
TRUE treats the last state of every pathway as its target
(HON / HYPA / MOGen). FALSE treats every member as co-equal:
there is no target, so no node is painted with target_color,
no direction cue is drawn, and the panel title is a member list
rather than an arrow. NULL (default) reads it off the input
— net_association_rules and simplicial_complex are
sets, everything else is a path.
Draw the traversal inside each per-pathway panel:
a light-to-dark core ramp along the path, a ring whose gold peaks
on the side facing the next state, and an arrowhead just outside
each node aimed at its successor. NULL (default) enables
them exactly when dismantled = TRUE. A simplex is a set of
vertices, so the combined overlay — where blobs overlap and a state
can sit in several pathways at once — cannot express direction;
direction = TRUE with dismantled = FALSE is an
error rather than a silent no-op. Also forced off when the caller
has collapsed the source/target two-tone (undirected input such as
net_association_rules).
Which cues to draw, any of "shade",
"ring", "arrows". Default all three.
Node core radius in data units, used only on the
directed path (rings and cores become polygons there so the ring
gradient and the arrow offset are expressible; geom_point()
sizes are device millimeters and cannot answer either).
NULL (default) scales it to the panel extent so the nodes
keep the size they have today.
Draw the in-figure legend strip beneath a dismantled
grid. Default TRUE when direction is on.
Additional arguments passed to
Nestimate::build_hon() or Nestimate::build_hypa()
when auto-building.
Supports direct use with tna and netobject models:
when x has sequence data, HON or HYPA pathways are built
automatically (requires the Nestimate package). Pathways can
also be passed as net_hon or net_hypa objects, with
labels auto-translated when x is a tna/netobject.
set.seed(1)
mat <- matrix(runif(16), 4, 4,
dimnames = list(LETTERS[1:4], LETTERS[1:4]))
diag(mat) <- 0
plot_simplicial(mat, c("A B -> C", "B C -> D"))
Run the code above in your browser using DataLab