EGAnet-plot — EGAnet

Description

General usage for plots created by EGAnet's S3 methods. Plots across the EGAnet package leverage GGally's ggnet2 and ggplot2's ggplot.

Most plots allow the full usage of the gg* series functionality and therefore plotting arguments should be referenced through those packages rather than here in EGAnet.

The sections below list the functions and their usage for the S3 plot methods. The plot methods are intended to be generic and without many arguments so that nearly all arguments are passed to ggnet2 and ggplot.

There are some constraints placed on certain plots to keep the EGAnet style throughout the (network) plots in the package, so be aware that if some settings are not changing your plot output, then these settings might be fixed to maintain the EGAnet style

General Usage

plot(x, ...)

plot.dynEGA(x, base = 1, id = NULL, ...)

plot.dynEGA.Group(x, base = 1, ...)

plot.dynEGA.Individual(x, base = 1, id = NULL, ...)

plot.hierEGA(
  x, plot.type = c("multilevel", "separate"),
  color.match = FALSE, ...
)

plot.invariance(x, p_type = c("p", "p_BH"), p_value = 0.05, ...)

plot.TEFI.compare(x, base.name, comparison.name, base.color, comparison.color, ...)

Argument Passing

All plot.* methods forward unrecognized arguments to ggnet2 in full – every one of ggnet2's own arguments (see ?GGally::ggnet2) can be set directly. EGAnet also provides a few shorter, friendlier names for some of the most commonly used ggnet2 arguments (see Examples below):

Shortcut	Real `ggnet2` Argument	Example
`layout`	`mode`	`plot(x, layout = "circle")`
`alpha`	`node.alpha`	`plot(x, alpha = 0.8)`
`color`	`node.color`	`plot(x, color = "blue")`
`shape`	`node.shape`	`plot(x, shape = 15)`
`vsize`	`node.size`	`plot(x, vsize = 10)`

label is deliberately not one of these shortcuts, even though it looks like a natural fit for setting custom node text. Methods that compose multiple networks into one figure (see below) also forward arguments to ggarrange, which has its own, unrelated labels (plural) argument for panel captions – label vs. labels is exactly the kind of mistake that's easy to make and easy to miss. To avoid that ambiguity, set node text with node.label instead (e.g., node.label = c("A", "B")), and remove node labels with label.size = 0. Passing label directly issues a warning and is otherwise ignored – it does not change node text.

A few extra cosmetic arguments are also available: title (plot title), legend.title, and legend.names (custom legend text).

Setting arguments = TRUE changes what plot() returns: instead of the rendered plot, you get back list(network_plot = <plot>, ARGS = <resolved arguments>) – the plot itself, plus the fully-resolved ggnet2 argument list actually used to build it (including, e.g., the node layout/positions). This is mainly useful for advanced, programmatic use – for example, reusing the exact same node positions and colors across multiple networks when building your own composite figure (this is how compare.EGA.plots keeps multiple networks aligned internally).

Methods that compose more than one network into a single figure – bootEGA, hierEGA (with plot.type = "separate"), invariance, dynEGA.Group, dynEGA.Individual (with multiple ids), and compare.EGA.plots – also forward the same arguments to ggarrange in full (e.g., ncol, nrow, legend, common.legend; see ?ggpubr::ggarrange), so the panel layout for these plots can be adjusted directly from plot().

If an argument name is not recognized by ggnet2, ggarrange, or one of the shortcuts/extras above, EGAnet throws an error naming the unrecognized argument(s) – most often the result of a typo – rather than silently ignoring it.

model.args, algorithm.args, and plot.args (each a named list()) are also still accepted, for backwards compatibility with older EGAnet versions that required arguments to be grouped this way. These are legacy – passing the same arguments directly (e.g., plot(x, node.size = 6) instead of plot(x, plot.args = list(node.size = 6))) is preferred going forward.

General Arguments

x — EGAnet object with available S3 plot method (see full list below)
color.palette — Character (vector). Either a character (length = 1) from the pre-defined palettes in color_palette_EGA or character (length = total number of communities) using HEX codes (see Color Palettes and Examples sections)
layout — Character (length = 1). Layouts can be set using gplot.layout and the ending layout name; for example, gplot.layout.circle can be set in these functions using layout = "circle" or mode = "circle" (see Examples)
base — Numeric (length = 1). Plot to be used as the base for the configuration of the networks. Uses the number of the order in which the plots are input. Defaults to 1 or the first plot
id — Numeric index(es) or character name(s). IDs to use when plotting dynEGA level = "individual". Defaults to NULL or 4 IDs drawn at random
plot.type — Character (length = 1). Whether hierEGA networks should plotted in a stacked, "multilevel" fashion or as "separate" plots. Defaults to "multilevel"
color.match — Boolean (length = 1). Whether lower order community colors in the hierEGA plot should be "matched" and used as the border color for the higher order communities. Defaults to FALSE
p_type — Character (length = 1). Type of p-value when plotting invariance. Defaults to "p" or uncorrected p-value. Set to "p_BH" for the Benjamini-Hochberg corrected p-value
p_value — Numeric (length = 1). The p-value to use alongside p_type when plotting invariance. Defaults to 0.05
base.name — Character (length = 1). A string to label the base structure in the plot. Defaults to "Base"
comparison.name — Character (length = 1). A string to label the comparison structure in the plot. Defaults to "Comparison"
base.color — Character (length = 1). A string to specifying the color of the base structure in the plot. Hex codes can be used. Defaults to "blue"
comparison.color — Character (length = 1). A string to specifying the color of the comparison structure in the plot. Hex codes can be used. Defaults to "red"
... — Additional arguments to pass on to ggnet2 and gplot.layout (and, for methods that compose multiple networks, ggarrange); see Argument Passing above and Examples below

`*EGA` Plots

bootEGA, dynEGA, EGA, EGA.estimate, EGA.fit, hierEGA, invariance, riEGA

All Available S3 Plot Methods

boot.ergoInfo, bootEGA, dynEGA, dynEGA.Group, dynEGA.Individual, dynEGA.Population, EGA, EGA.estimate, EGA.fit, hierEGA, infoCluster, invariance, itemStability, riEGA

Color Palettes

color_palette_EGA will implement some color palettes in EGAnet. The main EGAnet style palette is "polychrome". This palette currently has 40 colors but there will likely be a need to expand it further (e.g., hierEGA demands a lot of colors).

The color.palette argument will also accept HEX code colors that are the same length as the number of communities in the plot.

In any network plots, the color.palette argument can be used to select color palettes from color_palette_EGA as well as those in the color scheme of RColorBrewer

For more worked examples than below, see Plots in {EGAnet}

Examples


# Using different arguments in {GGally}'s `ggnet2`
plot(ega.wmt, node.size = 6, edge.size = 4)

# Using a different layout in {sna}'s `gplot.layout`
plot(ega.wmt, layout = "circle") # 'layout' argument
plot(ega.wmt, mode = "circle") # 'mode' argument

# Using different color palettes with `color_palette_EGA`

## Pre-defined palette
plot(ega.wmt, color.palette = "blue.ridge2")

## University of Virginia colors
plot(ega.wmt, color.palette = c("#232D4B", "#F84C1E"))

## Vanderbilt University colors
## (with additional {GGally} `ggnet2` argument)
plot(
  ega.wmt, color.palette = c("#FFFFFF", "#866D4B"),
  label.color = "#000000"
)

EGAnet-plot()