Plotting method for netify objects

Creates customizable network visualizations from netify objects using ggplot2. Supports cross-sectional and longitudinal networks with extensive options for mapping network attributes to visual properties.

Usage

# S3 method for class 'netify'
plot(x, ...)

Arguments

x

A 'netify' object containing network data to visualize.

...

Additional arguments controlling plot appearance:

Value

A ggplot2 object that can be further customized with additional layers, scales, themes, etc. For longitudinal networks, includes facets for each time period.

If return_components = TRUE, returns a list of plot components that can be manually assembled or modified.

Details

Naming Conventions:

The function supports two naming styles for parameters:

• Recommended: Use node_* for node attributes and *_by for variable mappings (e.g., node_size_by = "degree")

• Legacy: Use point_* for nodes and *_var for variables (e.g., point_size_var = "degree")

Default Behaviors:

• For weighted networks, edge transparency maps to weight by default

• For directed networks, arrows are added automatically

• For longitudinal networks, time periods are shown as facets

• Isolates are removed by default (set remove_isolates = FALSE to keep)

Customization Tips:

• Use weight_transform to handle skewed weight distributions

• Combine fixed and variable aesthetics (e.g., fixed color with variable size)

• Add ggplot2 layers after the plot call for further customization

• Use select_text for selective labeling in dense networks

Layout Parameters

layout

Character string specifying the igraph layout algorithm. Options include: "nicely" (default), "fr" (Fruchterman-Reingold), "kk" (Kamada-Kawai), "circle", "star", "grid", "tree", "bipartite" (for bipartite networks), "randomly", and others. See get_node_layout for full list.

point_layout

Optional data.frame or list of data.frames containing pre-computed node positions with columns 'actor', 'x', and 'y'. Overrides layout if provided.

static_actor_positions

Logical. For longitudinal networks, should node positions remain constant across time? Default is FALSE.

which_static

Integer. When static_actor_positions = TRUE, which time period's layout to use as template? If NULL (default), creates composite layout from all time periods.

seed

Integer for reproducible layouts. Default is 6886.

Display Control

add_edges

Logical. Display edges? Default is TRUE.

add_points

Logical. Display nodes as points? Default is TRUE.

add_text

Logical. Add text labels to nodes? Default is FALSE.

add_label

Logical. Add boxed labels to nodes? Default is FALSE.

remove_isolates

Logical. Remove unconnected nodes? Default is TRUE.

curve_edges

Logical. Use curved edges? Default is FALSE.

use_theme_netify

Logical. Apply netify theme? Default is TRUE.

Subsetting Parameters

node_filter

An expression to filter nodes. The expression can reference any nodal attribute. For example: node_filter = degree_total > 5 to show only nodes with total degree greater than 5. The expression is evaluated in the context of the nodal data, so any node-level variable can be used.

edge_filter

An expression to filter edges. The expression can reference any edge attribute (including 'weight' for weighted networks). For example: edge_filter = weight > 0.5 to show only edges with weight greater than 0.5. The expression is evaluated in the context of the edge data, so any edge-level variable can be used.

time

For longitudinal networks, a vector of time periods to include in the plot. Can be numeric indices or character labels matching the time dimension. If NULL (default), all time periods are plotted. For cross-sectional networks, this parameter is ignored.

Node Aesthetics

Fixed aesthetics (same for all nodes):

node_size or point_size

Numeric. Size of all nodes.

node_color or point_color

Color of node borders.

node_fill or point_fill

Fill color of nodes (note that fill will only work with certain shapes).

node_shape or point_shape

Shape of nodes (see ?pch).

node_alpha or point_alpha

Transparency (0-1).

node_stroke or point_stroke

Width of node borders.

Variable aesthetics (mapped to data):

node_size_by or point_size_var

Column name for size mapping.

node_color_by or point_color_var

Column name for border color.

node_fill_by or point_fill_var

Column name for fill color (note that fill will only work with certain shapes).

node_shape_by or point_shape_var

Column name for shape.

node_alpha_by or point_alpha_var

Column name for transparency.

Edge Aesthetics

Fixed aesthetics:

edge_color

Color for all edges. Default is "black".

edge_linewidth

Width for all edges. Default is 0.5.

edge_linetype

Line type (1=solid, 2=dashed, etc.).

edge_alpha

Transparency (0-1).

edge_curvature

Curvature amount when curve_edges = TRUE.

edge_arrow

Arrow specification for directed networks. Example: arrow(length = unit(0.2, "cm")).

adjust_arrow_endpoints

Logical. Should arrow endpoints be adjusted to stop at node boundaries? Default is FALSE. Only affects directed networks.

edge_arrow_gap

Numeric. Additional gap between arrow tip and node boundary as a proportion of node radius (0-1). Default is 0.2. Only used when adjust_arrow_endpoints = TRUE.

edge_arrow_size_scale

Numeric. Scale factor for converting node sizes to coordinate units. If NULL (default), automatically calculated based on plot range.

Variable aesthetics:

edge_color_by or edge_color_var

Column name for color mapping.

edge_linewidth_by or edge_linewidth_var

Column name for width.

edge_linetype_by or edge_linetype_var

Column name for line type.

edge_alpha_by or edge_alpha_var

Column name for transparency. For weighted networks, defaults to the weight variable if not specified.

Text and Label Options

Selective labeling:

select_text

Character vector of node names to show as text.

select_text_display

Alternative text to display (same length as select_text).

select_label

Character vector of node names to show with boxes.

select_label_display

Alternative labels (same length as select_label).

Text aesthetics:

text_size

Fixed size for all text. Default is 3.88.

text_color

Fixed color for all text. Default is "black".

text_alpha

Fixed transparency for text.

text_size_by

Variable to map to text size.

text_color_by

Variable to map to text color.

Label (boxed text) aesthetics have similar parameters with label_ prefix.

Scale Labels

Customize legend titles:

node_size_label or point_size_label

Legend title for size.

node_color_label or point_color_label

Legend title for color.

edge_alpha_label

Legend title for edge transparency.

edge_color_label

Legend title for edge color.

Highlighting Parameters

highlight

Character vector of node names to highlight with different colors. Non-highlighted nodes will be colored grey. Highlighted nodes can also be automatically enlarged if highlight_size_increase is greater than 1.

highlight_colors

Named vector of colors for highlighted nodes. If NULL, uses default distinct colors (red, blue, green for up to 3 nodes, or a color palette for more). Names should match the values in the highlight parameter. Example: c('USA' = 'blue', 'China' = 'red', 'Russia' = 'green').

highlight_legend_title

Title for the highlight legend. Default is "Highlighted".

highlight_size_increase

Numeric factor to increase size of highlighted nodes. Default is 1.5 (50% larger). Set to 1 for no size change. The size increase is applied multiplicatively to any existing size mapping.

show_other_in_legend

Logical. Include "Other" category in legend? Default is FALSE. When FALSE, only highlighted nodes appear in the legend.

Special Parameters

weight_transform

Function to transform edge weights before plotting. Example: log1p for log(x+1) transformation. Applied before mapping to aesthetics.

check_overlap

Logical. Avoid text overlap? Default is TRUE.

return_components

Logical. Return plot components instead of assembled plot? Useful for manual customization. Default is FALSE.

palette

Character string for color palette, see list_palettes().

style

A style function (e.g., style_budapest) or its name as a string. Applies a complete visual style including colors, shapes, and layout preferences.

Examples

# Load example data
data(icews)

# Basic cross-sectional network
icews_10 <- icews[icews$year == 2010,]
net_10 <- netify(
  icews_10,
  actor1 = 'i', actor2 = 'j',
  symmetric = FALSE,
  weight = 'verbCoop'
)

# Simple plot
plot(net_10)


# add nodal stats to netlet
net_10 <- add_node_vars(
  net_10, 
  summary_actor(net_10), 
  'actor'
)

# Customized plot with new naming convention
plot(net_10,
  edge_color = 'lightgrey',
  node_size_by = 'degree_total',          # Instead of point_size_var
  node_color = 'steelblue',
  edge_alpha_by = 'verbCoop',       # Instead of edge_alpha_var
  node_size_label = 'Degree',
  edge_alpha_label = 'Verbal Cooperation'
)


# Longitudinal network example
net_longit <- netify(
  icews,
  actor1 = 'i', actor2 = 'j',
  time = 'year',
  symmetric = FALSE,
  weight = 'verbCoop',
  nodal_vars = c('i_polity2', 'i_log_gdp')
)

# Add network statistics
net_longit <- add_node_vars(
  net_longit,
  summary_actor(net_longit),
  actor = 'actor', 
  time = 'time'
)

# Plot with multiple aesthetics
plot(net_longit,
  # Edges
  edge_color = 'grey70',
  weight_transform = log1p,         # Transform weights
  # Nodes  
  node_size_by = 'degree_total',
  node_color_by = 'i_polity2',
  # Labels
  node_size_label = 'Total Degree',
  node_color_label = 'Polity Score',
  edge_alpha_label = 'Log(Verbal Coop.)',
  # Layout
  static_actor_positions = TRUE     # Keep positions constant
)


# Selective labeling example
plot(net_10,
  node_size_by = 'degree_total',
  select_text = c('United States', 'China', 'Russian Federation'),
  text_size = 3,
  text_color = 'darkred'
)
#> Warning: Removed 149 rows containing missing values or values outside the scale range
#> (`geom_text()`).


# choose alternative labels for selected text
plot(net_10,
  node_size_by = 'degree_total',
  select_text = c('United States', 'China', 'Russian Federation'),
  select_text_display = c('USA', 'CHN', 'RUS'),
  text_size = 3,
  text_color = 'darkred'
)
#> Warning: Removed 149 rows containing missing values or values outside the scale range
#> (`geom_text()`).



# Time subsetting example
plot(net_longit,
  time = c('2010', '2011', '2012')
)


# Node subsetting example
# democracies with high GDP
plot(net_longit, node_filter = ~ i_polity2 > 6 & i_log_gdp > 25)


# use return_components=TRUE
# to get back ggplot2 pieces of plot
g10 <- plot(
  net_10, 
  node_alpha=.8,
  arrow = ggplot2::arrow(length = ggplot2::unit(0.01, "inches")),  
  node_size_by = 'log(degree_total)',
  node_size_label = 'Log(Degree)',
  edge_alpha_label='Log(Verbal Coop.)',
  remove_isolates = TRUE,
  weight_transform = log1p,
  return_components = TRUE )

# Manually assemble with custom modifications
# to scale aesthetics such as edges
g10$base +
  netify_edge(g10) +
  ggplot2::scale_alpha_continuous(range = c(0.01, 0.2)) +
  netify_node(g10) +
  theme_netify()