Skip to contents

Plot 3D trajectories as variable-width lines

Source: R/plot_group_trajectories_lines_3d.R
plot_group_trajectories_lines_3d.Rd

Creates an interactive 3D plot showing research trajectories with time on the x-axis, route separation on the y-axis, and cumulative paper counts on the z-axis. Highlighted trajectories are displayed as growing-thickness lines, with optional background trajectories and network context in lowlight style.

Usage

plot_group_trajectories_lines_3d(
  traj_data,
  traj_filtered,
  width_range_hi = c(4, 12),
  width_range_lo = c(1.2, 3),
  use_raw_papers = TRUE,
  connect_only_existing_edges = TRUE,
  show_labels = TRUE,
  show_only_highlighted = FALSE,
  label_size = 18,
  hover_font_size = 12,
  lowlight_width = 1,
  lowlight_alpha = 0.9,
  lowlight_color = "#9AA5B1"
)

Arguments

traj_data

List containing trajectory data generated by detect_main_trajectories() with components:

  • graph: igraph object containing nodes and edges across years

  • trajectories: tibble of all candidate trajectories (traj_id + nodes list)

traj_filtered

Filtered trajectories tibble from filter_trajectories() containing the subset to emphasize. Must contain columns:

  • traj_id: trajectory identifiers

  • nodes: list of character vectors (ordered by time or orderable)

width_range_hi

Width range for highlighted trajectory segments (default: c(4, 12)). Segment widths scale with cumulative paper counts.

width_range_lo

Baseline width range used to compute constant lowlight width (default: c(1.2, 3)). The mean of this range determines lowlight width.

use_raw_papers

Whether to use raw paper counts for z-axis scaling (default: TRUE). If TRUE, uses raw quantity_papers; if FALSE, uses weighted size: quantity_papers * prop_tracked_intra_group.

connect_only_existing_edges

Whether to draw only edges that exist in the graph (default: TRUE). If FALSE, draws all consecutive node pairs in trajectories regardless of graph edges.

show_labels

Whether to add end-of-trajectory labels inside the 3D plot (default: TRUE)

show_only_highlighted

Whether to show only highlighted trajectories (default: FALSE). If TRUE, hides all background network and lowlight trajectories.

label_size

Font size for trajectory end labels (default: 18)

hover_font_size

Font size for hover tooltips (default: 12)

lowlight_width

Line width for lowlight trajectories and background network (default: 1)

lowlight_alpha

Transparency for lowlight elements (default: 0.9)

lowlight_color

Color for lowlight elements (default: "#9AA5B1" - neutral gray)

Value

A plotly interactive 3D plot object

Details

This function creates an interactive 3D visualization of research trajectories:

  • X-axis: Publication year (parsed from vertex names like "y2007g05")

  • Y-axis: "Route" (Sugiyama layout coordinate to separate trajectories vertically)

  • Z-axis: Cumulative documents (raw or weighted) along each trajectory

Key features:

  • Highlighted trajectories (traj_filtered) are colored lines with widths that grow proportionally to cumulative paper counts

  • Lowlight trajectories (when show_only_highlighted = FALSE) show other trajectories as constant-width lines

  • Background network (when show_only_highlighted = FALSE) provides context with thin gray edges

  • Hover tooltips show detailed information at each trajectory point

  • End labels identify highlighted trajectories (when show_labels = TRUE)

  • Edge validation (when connect_only_existing_edges = TRUE) ensures only actual graph edges are drawn

The function uses a Sugiyama layout for the y-axis coordinates and cumulative sums of paper counts for the z-axis values. Colors for highlighted trajectories are assigned using RColorBrewer's Set2 palette (for ≤8 trajectories) or a hue-based palette (for more trajectories).

Examples

if (FALSE) { # \dontrun{
# Detect main trajectories first
traj_data <- detect_main_trajectories(your_graph_data)

# Filter trajectories of interest
filtered_traj <- filter_trajectories(traj_data$trajectories, 
                                     min_papers = 10)

# Create interactive 3D plot
plot_group_trajectories_lines_3d(
  traj_data = traj_data,
  traj_filtered = filtered_traj,
  width_range_hi = c(3, 10),
  use_raw_papers = FALSE,
  show_labels = TRUE
)

# Minimal view with only highlighted trajectories
plot_group_trajectories_lines_3d(
  traj_data = traj_data,
  traj_filtered = filtered_traj,
  show_only_highlighted = TRUE,
  label_size = 16
)
} # }