plot_grapht: Easily animate dynamic networks with sensible defaults

plot_graphtR Documentation

Easily animate dynamic networks with sensible defaults

Description

This function provides users with an easy way to graph dynamic network data for exploration and presentation.

It builds upon this package's graphr() function, and inherits all the same features and arguments. See graphr() for more. However, it uses the {gganimate} package to animate the changes between successive iterations of a network. This is useful for networks in which the ties and/or the node or tie attributes are changing, including networks whose node composition changes over time: every node that ever appears is assigned a stable position, and nodes fade in and out in place as they enter and exit the network.

By default node positions transition smoothly between waves using the dynamic stress layout from {graphlayouts} (graphlayouts::layout_as_dynamic()), which anchors each wave's layout to a reference layout of the aggregate network. The alpha argument controls this trade-off: 0 lets each wave's layout follow that wave's structure freely, while 1 freezes every node at its aggregate position. When another layout is requested, a single static layout is computed on the aggregate (union of waves) network instead, so that positions remain constant. Unlike graphr(), grapht() uses this dynamic stress layout by default even for two-mode networks (rather than a layered layout, which would collapse many nodes onto a line); the two modes remain distinguishable by node shape. For networks with more than 30 nodes, node labels are suppressed by default to keep frames legible; pass labels = TRUE to force them.

grapht() returns a {ggplot2}-compatible object that can be extended with additional layers such as ggplot2::labs(), ggplot2::theme(), scale functions, and others, just like plots produced by graphr() and graphs(). The animation is rendered when the object is printed or displayed. Users who want more control over animation parameters can call gganimate::animate() directly on the returned object.

The visual appearance is consistent with graphr(): nodes use fillable shapes with the fill aesthetic, the same colour palettes are applied, directed networks receive arrowheads (see edge_arrows), signed networks distinguish positive from negative ties by linetype, and labels use the current theme font. Legends transition along with the mapped aesthetics.

A progress bar is shown if it takes some time to encode all the .png files into a .gif.

Usage

grapht(
  tlist,
  layout = NULL,
  labels = TRUE,
  node_color,
  node_shape,
  node_size,
  edge_color,
  edge_size,
  isolates = c("keep", "fade"),
  alpha = 0.5,
  label_repel = TRUE,
  edge_arrows = NULL,
  keep_isolates = NULL,
  ...,
  node_colour,
  edge_colour,
  label_dist
)

## S3 method for class 'grapht'
print(x, ...)

Arguments

tlist

A manynet-compatible network listed according to a time attribute, waves, or slices. This can also be a single manynet network object that encodes time, which is split automatically by manynet::to_times() into the network as it stood at each moment it records: longitudinal or changing networks into waves, dynamic (time-stamped, event-based) networks such as manynet::irps_nuclear into the state accumulated by each moment, and interval (spell) networks that record tie begin/end lifespans, such as manynet::irps_wwi, into one snapshot per change point showing the ties active in that spell. It can also be a diffusion model result from e.g. manynet::play_diffusion().

layout

An igraph, ggraph, or manynet layout algorithm. If not declared, defaults to "configuration" for networks of up to six nodes, "levels" for connected multilevel networks, "layered" for other two mode networks, and "stress" for all other networks. The "stress" layout of a network of more than 1000 nodes is run at a looser tolerance (tolerance = 1e-3) to save time; give tolerance = 1e-4 for the finer layout. For "layered" layout, one can further split graph by declaring the "center" argument as the "events", "actors", or by declaring a node name. For "concentric" layout algorithm please declare the "membership" as an extra argument. The "membership" argument expects either a quoted node attribute present in data or vector with the same length as nodes to draw concentric circles. For "levels" layout algorithm one may declare the "level" as extra argument. The "level" argument expects either a quoted node attribute present in data or vector with the same length as nodes to hierarchically order categories. If "level" is missing, the levels are taken from a 'lvl' node attribute where there is one, or else from the two modes of a two mode network. The layered layouts ("layered", "lineage", "railway" and "ladder") accept a "ranks" argument, which takes either one of the methods named at ?layout_layered or a numeric node attribute to lay the layers out by, as a quoted attribute name or a vector with one value for each node. A "lineage" ranked by such values, such as ranks = "year", is drawn as a timeline, as a historiograph of citations is: the x axis is broken at the values, with light vertical gridlines, the ties are curved, and the labels are repelled. Every "lineage" draws its ties curved and its mapped node sizes by area over a wider range. The "scaling" layout places the nodes by multidimensional scaling, so that the distance between two nodes approximates the number of steps between them. Since those coordinates can be read, this layout is drawn with labelled axes on one scale, and captioned with how well two dimensions hold the distances; see ?layout_scaling and check_stress(). Note that those axes carry distances rather than named dimensions: the drawing can be turned or mirrored without fitting the network any better or any worse. The "correspondence" layout places the nodes by correspondence analysis, so that two nodes with similar ties are drawn together, whether or not they are tied to each other. It is the usual way to draw a two mode network, since it places both modes against the same pair of axes, and it accepts a "direction" argument for a directed network and a "double" argument for a signed one; see ?layout_correspondence. Each axis names the share of the network's inertia that it holds.

labels

Which nodes to label, if the network is labelled. TRUE (the default) labels every node and FALSE none. A selection of the nodes can be given as in graphr(): a number of ranks, a measure to rank by, the name of a logical node attribute, a logical vector, or the names or positions of the nodes. The selection is made once over all the waves, so that the same nodes stay labelled from frame to frame. For networks of more than 30 nodes, labels defaults to no labels at all; pass labels = TRUE for all of them. Unlike graphr(), no selection is made for a concept lattice.

node_color, node_colour

Node variable to be used for coloring the nodes. It is easiest if this is added as a node attribute to the graph before plotting. A categorical variable gives one colour to each category. A measure, such as a centrality or coreness score, is drawn instead as a gradient from the theme's base colour to its highlight colour, with a colourbar in place of the legend. Nodes can also be colored by declaring a color instead.

node_shape

Node variable to be used for shaping the nodes. It is easiest if this is added as a node attribute to the graph before plotting. Nodes can also be shaped by declaring a shape instead.

node_size

Node variable to be used for sizing the nodes. This can be any continuous variable on the nodes of the network. Since this function expects this to be an existing variable, it is recommended to calculate all node-related statistics prior to using this function. Nodes can also be sized by declaring a numeric size or vector instead.

edge_color, edge_colour

Tie variable to be used for coloring the nodes. It is easiest if this is added as an edge or tie attribute to the graph before plotting. Edges can also be colored by declaring a color instead.

edge_size

Tie variable to be used for sizing the edges. This can be any continuous variable on the nodes of the network. Since this function expects this to be an existing variable, it is recommended to calculate all edge-related statistics prior to using this function. Edges can also be sized by declaring a numeric size or vector instead.

isolates

One of "keep" (the default) or "fade". "keep" retains isolated nodes at their layout positions in every wave in which they are present. "fade" fades nodes out during waves in which they are isolates, and fades them back in when they regain ties. Nodes that are absent from a wave altogether (composition change) always fade out.

alpha

A number between 0 and 1 controlling the stability of node positions across waves when the default dynamic (stress) layout is used. 0 computes each wave's layout freely, 1 fixes all nodes at their aggregate-network positions. By default 0.5. Passed to graphlayouts::layout_as_dynamic().

label_repel

Where to put the labels.

  • TRUE (the default) repels the labels away from each other and from the nodes using ggrepel (via ggraph's repel argument), leaving a small gap from each node's border: 5pt where every node is labelled, and 2pt where only a selection is, so that each label stays against the node it names. Node size is always accounted for.

  • A number, e.g. label_repel = 10, repels the labels with a gap of that many points instead, similar to igraph's vertex.label.dist. Set to 0 for labels right at the node border.

  • FALSE places each label at a fixed offset from its node, in the direction the layout suits (outward in "circle" and "concentric", to the right in "lineage"), without the repelling algorithm, which can be slow and, for some layouts, differs between runs.

  • A direction, "outside", "above", "below", "left", or "right", places every label at a fixed offset in that direction, whatever the layout. "outside" points away from the middle of the layout. A gap can be given with it, as in label_repel = c(above = 3).

The layered layouts ("layered", "lineage", "railway" and "ladder") place each node in a layer, which is where the reader looks for it, so a repelled label there would say less about which node it labels than a fixed offset does. They offset the labels instead, unless a direction is given.

edge_arrows

Whether, and at what size, to draw arrowheads on the ties of a directed network. By default (NULL) this is decided by the network: a directed network is drawn with arrowheads, except for a concept lattice from manynet::to_concepts() in the "layered" (its default) or "railway" layout. That is read as a Hasse diagram, where the direction of each tie is already given by which of its ends is drawn higher. In any other layout a concept lattice keeps its arrowheads. TRUE draws arrowheads whatever the network, and FALSE none. Arrowheads follow the width the ties are drawn at: 2mm long at the default edge_size of 0.5, and longer on wider ties, up to 4mm. Where the widths vary, as when they are mapped from a tie attribute, one size is chosen for all of the arrowheads from the mean width drawn. A number, e.g. edge_arrows = 3, draws arrowheads of that length in millimetres instead, whatever the width of the ties. This is the unit that {ggplot2} sizes are given in, as node_size is, so an arrowhead of 3 is a little longer than a node of 3 is wide. Ties that are not drawn, as with edge_size = 0, have no arrowheads. An undirected network has no direction to show, so the argument is ignored there.

keep_isolates

Deprecated. Use isolates = "keep" or isolates = "fade" instead.

...

Extra arguments to pass on to the layout algorithm, if necessary.

label_dist

Deprecated. Give the gap to label_repel instead.

x

A grapht object to print.

Details

Unlike graphr(), grapht() does not use ggrepel-based label repelling (there is no straightforward way to repel labels consistently across animation frames), so label_repel here instead gives a fixed offset nudging labels away from their nodes: above them for TRUE, none for FALSE, and in the direction named for a direction. A gap in points scales the size of that nudge rather than being used as repel padding.

labels can select which nodes to label here too, and the selection is resolved once over all the waves so that the same nodes stay labelled from frame to frame. Unlike graphr(), though, animations of more than 30 nodes default to no labels at all rather than to a selection of them.

Some further graphr() features are not available in animations: node_group hulls, edge bundling, curved arcs for reciprocated ties, and self-loops (loops are not drawn; a note is printed if present). Note too that, where no layout is named, grapht() defaults to the "stress" layout for every network rather than choosing one by the network's shape as graphr() does, so that nodes move smoothly from one wave to the next. A layout named explicitly is still used, computed on the aggregate network.

Value

A {ggplot2}-compatible object with {gganimate} animation layers. This object can be extended with additional {ggplot2} layers (e.g. + labs(subtitle = "My subtitle")). When printed or displayed, the animation is rendered as a .gif. For more control over animation parameters, pass the result to gganimate::animate() directly.

Source

https://blog.schochastics.net/posts/2021-09-15_animating-network-evolutions-with-gganimate/

See Also

Other mapping: check_layout, completion, layout_concentric(), layout_configuration(), layout_correspondence(), layout_layered(), layout_levels(), layout_matching(), layout_scaling(), layout_spatial(), layout_valence(), plot_graphr, plot_graphs

Examples

# A dynamic signed network of shifting European alliances 1872-1918,
# split automatically into snapshots of the ties active in each spell.
# Wrapped in \donttest{} because rendering the animation to a .gif is
# slow, not because the code is unsafe to run.

grapht(irps_wwi)


autograph documentation built on Nov. 16, 2026, 5:08 p.m.