add_network: Add a network to an ENA plot

Description

Adds a network (set of edges) to an existing ENA plot or ENA set. The network can be specified in several ways, including as an unevaluated expression, a numeric matrix, or a language object. This function is typically used to visualize group means, differences between groups, or custom networks on an ENA plot.

Usage

add_network(
  x,
  wh = NULL,
  ...,
  with.mean = F,
  edge.multiplier = 1,
  colors = NULL
)

Value

The modified ENAplot object with the new network added.

Arguments

x

An `ENAplot` object or an ENA set containing plots.

wh

Specifies the network to plot. Can be:

An unevaluated expression (e.g., `Condition$FirstGame - Condition$SecondGame`)
A numeric matrix or data.frame of edge weights
A language object
NULL (defaults to the mean network)

...

Additional parameters passed to the plotting functions.

with.mean

Logical; if `TRUE`, also plots the mean for the points in the network. Default is `FALSE`.

edge.multiplier

Numeric scalar to multiply the edge weights. Useful for scaling the network visualization. Default is 1.

colors

Optional vector of colors for the network. If not specified, colors are chosen from the plot palette.

Examples

See `inst/examples/example-plot-piping.R` for usage examples.

Details

The function determines the type of the `wh` parameter and processes it accordingly:

If `wh` is an unevaluated expression, it is captured and evaluated in the parent frame. This allows for flexible specification of group means or differences.
If `wh` is a numeric matrix or data.frame, it is used directly as the network data.
If `wh` is a language object, it is processed to extract the relevant network information.
If `wh` is NULL, the mean network is plotted.

The function updates the plot with the new network and returns the modified plot object. The ENA set is not modified in-place.