Add a SEM group to the visualization

Description

Add a SEM group to the visualization

Usage

add_group(
  builder,
  name,
  model = NULL,
  object = NULL,
  level = NULL,
  x = 0,
  y = 0,
  width = NULL,
  height = NULL,
  type = NULL
)

Arguments

Value

Updated ggsem_builder object

Adjust Axis Range of a Plot of a ggplot2 Plot

Description

This function modifies the axis ranges of a ggplot object, with optional user-specified ranges, additional buffers, and the ability to enforce a fixed aspect ratio. This is a modified version of adjust_axis_space().

Usage

adjust_axis_range(
  plot,
  x_range = NULL,
  y_range = NULL,
  buffer_percent = 0,
  fixed_aspect_ratio = TRUE
)

Arguments

Details

- If 'x_range' or 'y_range' are provided, these values will override the current axis ranges. - The 'buffer_percent' parameter adds proportional space to the axis ranges, calculated as a percentage of the range's width or height. - When 'fixed_aspect_ratio' is 'TRUE', the function adjusts either the x-axis or y-axis to ensure the plot maintains a fixed aspect ratio.

Value

A modified ggplot object with adjusted axis ranges.

Examples

# CSV files from ggsem app
points_data <- data.frame(
x = 20, y = 20, shape = 'rectangle', color = '#D0C5ED', size = 50,
border_color = '#9646D4', border_width = 2, alpha = 1,
width_height_ratio = 1.6, orientation = 45, lavaan = FALSE,
network = FALSE, locked = FALSE, group = 1
)

lines_data <- data.frame(
x_start = 2, y_start = -2, x_end = 10, y_end = -2, ctrl_x = NA, ctrl_y = NA,
ctrl_x2 = NA, ctrl_y2 = NA, curvature_magnitude = NA, rotate_curvature = NA,
curvature_asymmetry = NA, type = 'Straight Line', color = '#000000',
end_color = NA, color_type = 'Single',
gradient_position = NA, width = 1.5, alpha = 1, arrow = FALSE,
arrow_type = NA, arrow_size = NA, two_way = FALSE, lavaan = FALSE,
network = FALSE, line_style = 'solid', locked = FALSE, group = 1
)

p <- csv_to_ggplot(graphics_data = list(points_data, lines_data),
              zoom_level = 1.2, # Value from the ggsem app
              horizontal_position = 0, # Value from the ggsem app
              element_order = c('lines', 'points')) # order priority: lines < points


adjust_axis_range(p, x_range = c(-30,30), y_range= c(-30,30))

Adjust Surrounding White Space of a ggplot2 Plot

Description

This function allows users to remove or manage whitespace around graphical elements. It supports asymmetrical adjustments for each boundary (left, right, bottom, and top). Users can also maintain a fixed aspect ratio if required.

Usage

adjust_axis_space(
  plot,
  x_adjust_left_percent = 0,
  x_adjust_right_percent = 0,
  y_adjust_bottom_percent = 0,
  y_adjust_top_percent = 0,
  fixed_aspect_ratio = TRUE
)

Arguments

Details

- **Percentage Adjustments:** The percentages provided for each axis boundary are calculated based on the current axis range. For example, x_adjust_left_percent = 10 expands the left boundary by 10 - **Fixed Aspect Ratio:** When fixed_aspect_ratio = TRUE, the function adjusts either the x-axis or y-axis to maintain a 1:1 aspect ratio. The larger adjustment determines the scaling for both axes.

Value

A ggplot2 object with adjusted axis ranges. The adjusted plot retains its original attributes and is compatible with additional ggplot2 layers and themes.

Examples

# CSV files from ggsem app
points_data <- data.frame(
x = 20, y = 20, shape = 'rectangle', color = '#D0C5ED', size = 50,
border_color = '#9646D4', border_width = 2, alpha = 1,
width_height_ratio = 1.6, orientation = 45, lavaan = FALSE,
network = FALSE, locked = FALSE, group = 1
)

lines_data <- data.frame(
x_start = 2, y_start = -2, x_end = 10, y_end = -2, ctrl_x = NA, ctrl_y = NA,
ctrl_x2 = NA, ctrl_y2 = NA, curvature_magnitude = NA, rotate_curvature = NA,
curvature_asymmetry = NA, type = 'Straight Line', color = '#000000',
end_color = NA, color_type = 'Single',
gradient_position = NA, width = 1.5, alpha = 1, arrow = FALSE,
arrow_type = NA, arrow_size = NA, two_way = FALSE, lavaan = FALSE,
network = FALSE, line_style = 'solid', locked = FALSE, group = 1
)


p <- csv_to_ggplot(graphics_data = list(points_data, lines_data),
              zoom_level = 1.2, # Value from the ggsem app
              horizontal_position = 0, # Value from the ggsem app
              element_order = c('lines', 'points')) # order priority: lines < points


adjust_axis_space(p, x_adjust_left_percent = 10, x_adjust_right_percent = 10,
             y_adjust_bottom_percent = 5, y_adjust_top_percent = 5)

Convert CSV Files (from ggsem Shiny App) to a ggplot Object

Description

This function converts the CSV files exported from the ggsem Shiny app into a customizable ggplot object. The resulting plot is compatible with ggplot2 functions, allowing users to modify it further (e.g., adding titles or annotations).

Usage

csv_to_ggplot(
  graphics_data = NULL,
  element_order = c("lines", "points", "loops", "annotations"),
  zoom_level = 1,
  horizontal_position = 0,
  vertical_position = 0,
  n = 100
)

Arguments

Details

- The function uses 'coord_fixed' to ensure square plotting space and uniform scaling. - The 'element_order' parameter determines the layering of graphical elements, with later elements appearing on top. - The 'axis_ranges' attribute is attached to the plot for additional programmatic access.

Value

A ggplot object with an axis_ranges attribute specifying the x and y axis ranges after adjustments.

Examples

# CSV files from ggsem app
points_data <- data.frame(
x = 20, y = 20, shape = 'rectangle', color = '#D0C5ED', size = 50,
border_color = '#9646D4', border_width = 2, alpha = 1,
width_height_ratio = 1.6, orientation = 45, lavaan = FALSE,
network = FALSE, locked = FALSE, group = 1
)

lines_data <- data.frame(
x_start = 2, y_start = -2, x_end = 10, y_end = -2, ctrl_x = NA, ctrl_y = NA,
ctrl_x2 = NA, ctrl_y2 = NA, curvature_magnitude = NA, rotate_curvature = NA,
curvature_asymmetry = NA, type = 'Straight Line', color = '#000000',
end_color = NA, color_type = 'Single',
gradient_position = NA, width = 1.5, alpha = 1, arrow = FALSE,
arrow_type = NA, arrow_size = NA, two_way = FALSE, lavaan = FALSE,
network = FALSE, line_style = 'solid', locked = FALSE, group = 1
)

csv_to_ggplot(graphics_data = list(points_data, lines_data),
              zoom_level = 1.2, # Value from the ggsem app
              horizontal_position = 0, # Value from the ggsem app
              element_order = c('lines', 'points')) # order priority: lines < points

Draw Text Annotations to a ggplot Object

Description

This function overlays text annotations onto any ggplot object. It is particularly useful for adding annotations from CSV files generated by the ggsem Shiny app but can also be used with custom annotation data.

Usage

draw_annotations(annotations_data, zoom_level = 1)

Arguments

Value

ggplot2 annotation layers

Examples

library(ggplot2)

annotations_data <- data.frame(
text = 'x1', x = 9.5, y = 21, font = 'sans',
size = 16, color = '#FFFFFF', fill = NA, angle = 0,
alpha = 1, fontface = 'plain', math_expression = FALSE,
lavaan = FALSE, network = FALSE, locked = FALSE,
group_label = FALSE, loop_label = FALSE, group = 1
)

p <- ggplot()

p + draw_annotations(annotations_data, zoom_level = 1.2)

Draw Lines on a ggplot Object from Line Data

Description

This function overlays lines or arrows to a ggplot object based on line data. It supports straight lines, curved lines, gradient color transitions, and one-way or two-way arrows. The data can come from a CSV file generated by the ggsem Shiny app or custom input.

Usage

draw_lines(lines_data, zoom_level = 1, n = 100)

Arguments

Value

ggplot2 line layers

Examples

library(ggplot2)

lines_df <- data.frame(
x_start = 11, y_start = -2.3, x_end = 21, y_end = 3.5,
ctrl_x = NA, ctrl_y = NA, ctrl_x2 = NA, ctrl_y2 = NA,
curvature_magnitude = NA, rotate_curvature = NA,
curvature_asymmetry = NA, type = 'Straight Line',
color = '#000000', end_color = NA, color_type = 'Single',
gradient_position = NA, width = 1, alpha = 1, arrow = TRUE,
arrow_type = 'closed', arrow_size = 0.1, two_way = FALSE,
lavaan = FALSE, network = FALSE, line_style = 'solid',
locked = FALSE, group = 1
)

p <- ggplot()

p + draw_lines(lines_data = lines_df, zoom_level = 1.2, n = 200)

Draw Self-loop Arrows on a ggplot Object

Description

This function overlays self-loop arrows to a ggplot object based on data describing their positions, sizes, orientations, and styles. Self-loop arrows can be drawn in one direction or bidirectionally with customizable parameters such as color, width, and arrow type. The data can come from a CSV file generated by the ggsem Shiny app or custom input.

Usage

draw_loops(loops_data, zoom_level = 1)

Arguments

Value

ggplot2 loop layers

Examples

library(ggplot2)

loops_data <- data.frame(
x_center = -5, y_center = 5, radius = 2, color = '#000000',
width = 1, alpha = 1, arrow_type = 'closed', arrow_size = 0.1,
gap_size = 0.2, loop_width = 5, loop_height = 5, orientation = 0,
lavaan = TRUE, two_way = FALSE, locked = FALSE, group = 1
)

p <- ggplot()

p + draw_loops(loops_data, zoom_level = 1.2)

Draw Points on a ggplot Object

Description

This function overlays points to a ggplot object using data from a CSV file generated by the ggsem Shiny app or any custom dataset. Points can be styled with various shapes, colors, sizes, and orientations.

Usage

draw_points(points_data, zoom_level = 1)

Arguments

Value

ggplot2 point layers

Examples

library(ggplot2)

points_data <- data.frame(
x = 0, y = 0, shape = 'square', color = '#1262B3', size = 12,
border_color = '#FFFFFF', border_width = 1, alpha = 1,
width_height_ratio = 1.6, orientation = 0,
lavaan = FALSE, network = FALSE, locked = FALSE,
group = 1
)

p <- ggplot()

p + draw_points(points_data, zoom_level = 1.2) +
scale_x_continuous(limits = c(0,50)) +
scale_y_continuous(limits = c(0,50))

Get axis range of a ggplot object

Description

A function to calculate the range of x- and y- axes.

Usage

get_axis_range(plot)

Arguments

Value

A list object that has two elements, each of which has two vector values. The first element stores the minimum and maximum values of the plot's x-axis range, while the second element stores the minimum and maximum values of the plot's y-axis range.

Examples

library(ggplot2)
ggplot(mtcars) + geom_point(aes(mpg, disp)) -> p1
get_axis_range(p1)

Launch ggsem Shiny Application

Description

Main function to launch the ggsem Shiny application for interactive network and structural equation modeling visualization. The app can be started with pre-existing objects or used to create visualizations from scratch.

Usage

ggsem(
  object = NULL,
  model_obj = NULL,
  model = NULL,
  type = "sem",
  session = "sem",
  center_x = NULL,
  center_y = NULL,
  width = NULL,
  height = NULL,
  random_seed = NULL,
  group_id = NULL,
  group_level = NULL
)

Arguments

Details

The ggsem Shiny application provides an interactive interface for: - Visualizing and customizing SEM path diagrams - Creating and modifying network visualizations - Adjusting node/edge aesthetics, layouts, and annotations - Exporting high-quality publication-ready graphics

When starting with an object, the app will pre-load the visualization and allow further customization. When starting without an object, users can upload data or use built-in examples.

Value

Launches a Shiny application. Does not return a value.

Supported Object Types

SEM Objects:

• lavaan: Fitted lavaan models

• qgraph: semPaths objects from lavaan models

• sem_graph: tidySEM objects

• MxRAMModel: OpenMx models

• mplusObject: Mplus models

• grViz: diagrammeR objects from lavaanPlot

Network Objects:

• igraph: igraph network objects

• network: network package objects

• qgraph: qgraph network objects

Examples

## Not run: 
# Launch app without pre-existing objects
ggsem()

# Launch app with a lavaan model
library(lavaan)
model <- ' visual  =~ x1 + x2 + x3
           textual =~ x4 + x5 + x6
           speed   =~ x7 + x8 + x9 '
fit <- cfa(model, data = HolzingerSwineford1939)
ggsem(object = fit)

# Launch app with an igraph network
library(igraph)
g <- make_ring(10)
ggsem(object = g, type = "network", session = "network")

# Launch app with custom dimensions
ggsem(object = g, type = "network", center_x = 10, center_y = 10, width = 30, height = 30)


# Launch app with no input
ggsem()

## End(Not run)

Create multi-group SEM visualizations

Description

Build and launch multi-group SEM visualizations with an intuitive API. Ideal for comparing multiple groups from the same or different models.

Usage

ggsem_builder(type = "sem")

Arguments

Value

A ggsem_builder object

Launch ggsem Shiny application

Description

Launches the ggsem Shiny application for interactive SEM and network visualization.

Usage

ggsem_launch(x = NULL, ...)

Arguments

Value

Runs Shiny application

Launch ggsem Shiny application from objects

Description

Launch ggsem Shiny application from objects

Usage

## Default S3 method:
ggsem_launch(x, center_x = NULL, center_y = NULL, ...)

Arguments

Value

Runs Shiny application

Launch ggsem Shiny application from builder

Description

Launch ggsem Shiny application from builder

Usage

## S3 method for class 'ggsem_builder'
ggsem_launch(x, session = NULL, ...)

Arguments

Value

Runs Shiny application

Run ggsem silently (without launching the app) and get the visualization outputs

Description

This function processes a saved ggsem workflow metadata file and extracts all visualization data (points, lines, annotations, loops) that would be displayed in the Shiny app. It reproduces both SEM and network visualizations from the saved session state.

Usage

ggsem_silent(metadata)

Arguments

Value

A list of four data frames:

• points - Data frame containing point coordinates and properties

• lines - Data frame containing line coordinates and properties

• annotations - Data frame containing text annotations

• loops - Data frame containing loop coordinates and properties

Examples

## Not run: 
# Load a saved ggsem workflow
workflow_metadata <- readRDS("ggsem_workflow_20240101_120000.rds")

# Extract visualization data
viz_data <- ggsem_silent(workflow_metadata)

# Access the different components
points <- viz_data$points
lines <- viz_data$lines
annotations <- viz_data$annotations
loops <- viz_data$loops

## End(Not run)

Launch method for ggsem_builder objects

Description

Convenience method for builder pattern: builder |> launch()

Usage

launch(builder, ...)

Arguments

Value

Runs Shiny application

Convert ggsem workflow metadata directly to a ggplot object

Description

This function is a convenient wrapper that takes ggsem workflow metadata, extracts the visualization data silently, and converts it to a ggplot object in one step.

Usage

metadata_to_ggplot(
  metadata,
  element_order = c("lines", "points", "loops", "annotations"),
  zoom_level = 1,
  horizontal_position = 0,
  vertical_position = 0,
  n = 100
)

Arguments

Details

This function combines the functionality of ggsem_silent and csv_to_ggplot into a single convenient call. It's useful when you want to go directly from saved workflow metadata to a ggplot object without intermediate steps.

Value

A ggplot object with an axis_ranges attribute specifying the x and y axis ranges after adjustments.

Examples

## Not run: 
# Load a saved ggsem workflow
workflow_metadata <- readRDS("ggsem_workflow_metadata.rds")

# Convert directly to ggplot
p <- metadata_to_ggplot(
  metadata = workflow_metadata
)

# Customize the plot further
p + ggtitle("My SEM Visualization")

## End(Not run)

Reproduce a network visualization from metadata

Description

This function recreates a network visualization using stored metadata from a Shiny app session. It can handle various network object types including igraph, qgraph, ggnet2 objects, and adjacency matrices.

Usage

reproduce_network(
  metadata = NULL,
  group_id = NULL,
  object = NULL,
  zoom_level = 1.2
)

Arguments

Value

A ggplot object containing the reproduced network visualization.

Examples

## Not run: 
# Reproduce network from saved metadata
network_plot <- reproduce_network(
  metadata = "path/to/metadata.rds",
  group_id = "network1"
)

# Reproduce with custom data
network_plot <- reproduce_network(
  metadata = metadata_object,
  data = "path/to/edges.csv",
  group_id = "network1"
)

## End(Not run)

Reproduce a SEM (Structural Equation Modeling) visualization from metadata

Description

This function recreates a SEM path diagram using stored metadata from a Shiny app session. It supports various SEM object types including lavaan, semPlot, qgraph, and diagrammeR objects.

Usage

reproduce_sem(
  metadata = NULL,
  lavaan_syntax = NULL,
  group_id = NULL,
  object = NULL,
  zoom_level = 1.2
)

Arguments

Value

A ggplot object containing the reproduced SEM path diagram.

Examples

## Not run: 
# Reproduce SEM from saved metadata
sem_plot <- reproduce_sem(
  metadata = "path/to/metadata.rds",
  group_id = "sem1"
)

# Reproduce with custom lavaan syntax
sem_plot <- reproduce_sem(
  metadata = metadata_object,
  lavaan_syntax = "y ~ x1 + x2",
  group_id = "sem1"
)

## End(Not run)

Save a ggplot Object with Adjusted Dimensions

Description

This function saves a ggplot object (created from 'csv_to_ggplot()' function) to a file with dimensions automatically determined based on the x-axis and y-axis ranges of the plot. The size of the output can be further controlled using addtional arguments.

Usage

save_figure(
  filename,
  plot,
  units = "in",
  dpi = 300,
  aspect_ratio = NULL,
  scale_factor = 0.122,
  zoom_level = 1,
  ...
)

Arguments

Value

Saves the ggplot object to the specified file and does not return a value.

Examples

## Not run: 
# CSV files from ggsem app
points_data <- data.frame(
x = 20, y = 20, shape = 'rectangle', color = '#D0C5ED', size = 50,
border_color = '#9646D4', border_width = 2, alpha = 1,
width_height_ratio = 1.6, orientation = 45, lavaan = FALSE,
network = FALSE, locked = FALSE, group = 1
)

lines_data <- data.frame(
x_start = 2, y_start = -2, x_end = 10, y_end = -2, ctrl_x = NA, ctrl_y = NA,
ctrl_x2 = NA, ctrl_y2 = NA, curvature_magnitude = NA, rotate_curvature = NA,
curvature_asymmetry = NA, type = 'Straight Line', color = '#000000',
end_color = NA, color_type = 'Single',
gradient_position = NA, width = 1.5, alpha = 1, arrow = FALSE,
arrow_type = NA, arrow_size = NA, two_way = FALSE, lavaan = FALSE,
network = FALSE, line_style = 'solid', locked = FALSE, group = 1
)

p1 <- csv_to_ggplot(graphics_data = list(points_data, lines_data),
              zoom_level = 1.2, # Value from the ggsem app
              horizontal_position = 0, # Value from the ggsem app
              element_order = c('lines', 'points')) # order priority: lines < points

# Save with default scaling
save_figure("p1.png", p1)

## End(Not run)

Set default type for the builder

Description

Change the default type for subsequent add_group() calls

Usage

set_type(builder, type = "sem")

Arguments

Value

Updated ggsem_builder object