Plot a psychHypergraph Object

Visualize psychometric hypergraphs using the HyperG package. Hyperedges can be selected from the complete hypergraph or from the redundant/synergistic sub-hypergraphs, and may be filtered according to their O-information values.

Usage

# S3 method for class 'psychHypergraph'
plot(
  x,
  type = c("full", "redundant", "synergistic"),
  top_n = NULL,
  oinfo_threshold = NULL,
  groups = NULL,
  labels = NULL,
  vertex.color = NULL,
  vertex.size = 15,
  vertex.label.cex = 1,
  vertex.label.color = "black",
  vertex.shape = "circle",
  edge.color = NA,
  edge.width = 1,
  edge.lty = 1,
  edge.alpha = 0.2,
  layout = NULL,
  main = NULL,
  seed = 123,
  ...
)

Arguments

x

A psychHypergraph object produced by build_hypergraph.

type

Character string specifying which hypergraph to visualize:

"full"

All significant hyperedges.

"redundant"

Only hyperedges with positive O-information.

"synergistic"

Only hyperedges with negative O-information.

top_n

Optional integer specifying the number of strongest hyperedges (based on absolute O-information) to display. If NULL, all available hyperedges are plotted.

oinfo_threshold

Optional minimum absolute O-information value. Hyperedges with |O| < threshold are excluded.

groups

Optional grouping vector indicating node membership. Must have length equal to the number of variables in the hypergraph. Used for automatic node coloring.

labels

Optional character vector of node labels. Must have length equal to the number of variables. If NULL, original variable names are used.

vertex.color

Node colors.

Can be:

• a single color applied to all nodes;

• a vector of length equal to the number of variables;

• when groups is supplied, a vector of length equal to the number of groups.

If NULL, colors are automatically generated from group membership (if available) or set to white.

vertex.size

Numeric scalar or vector specifying node sizes.

vertex.label.cex

Numeric scaling factor for node labels.

vertex.label.color

Color of node labels.

vertex.shape

Shape of nodes passed to HyperG::plot.hypergraph().

edge.color

Color of graph edges.

edge.width

Width of hyperedge boundaries.

edge.lty

Line type of hyperedge boundaries.

edge.alpha

Transparency level used for hyperedge regions. Values range from 0 (fully transparent) to 1 (fully opaque).

layout

Optional layout matrix. If NULL, a spring layout is generated automatically from the projected adjacency matrix.

main

Optional plot title. If NULL, a title is generated automatically.

seed

Random seed used for layout generation.

...

Additional arguments passed to HyperG::plot.hypergraph().

Value

A list containing:

hypergraph

The HyperG hypergraph object used for plotting.

layout

The layout matrix used for node positions.

incidence_matrix

The incidence matrix of the plotted hypergraph.

oinfo

The O-information values corresponding to the plotted hyperedges.

Details

Hyperedge colors are automatically mapped to O-information values using a red-white-blue gradient:

• Red = synergistic hyperedges (negative O-information)

• White = weak higher-order interaction

• Blue = redundant hyperedges (positive O-information)

When node groups are provided, node colors can be automatically assigned according to group membership.

Hyperedges are represented as shaded regions surrounding their member nodes. The color of each hyperedge reflects the sign and magnitude of its O-information value.

The plotting procedure consists of:

1. Selecting a hypergraph (full, redundant, or synergistic);

2. Filtering hyperedges using top_n and/or oinfo_threshold;

3. Constructing a HyperG hypergraph object;

4. Computing a force-directed layout;

5. Rendering nodes and hyperedges.

Large hypergraphs may be difficult to interpret visually. Using top_n or oinfo_threshold is recommended when the number of hyperedges is large.

See also

build_hypergraph

Examples

if (FALSE) { # \dontrun{
library(psych)
data(bfi)

hg <- build_hypergraph(
  data = bfi[,1:25],
  k = 3:5,
  candidate_method = "all",
  cor_method = "pearson",
  parallel = TRUE
)

# Full hypergraph
plot(hg)

# Only synergistic hyperedges
plot(hg, type = "synergistic")

# Top 20 strongest hyperedges
plot(hg, top_n = 20)

# Threshold-based filtering
plot(hg, oinfo_threshold = 0.05)

# Group coloring
groups <- rep(c("A","C","E","N","O"), each = 5)
plot(hg, groups = groups)

} # }