Skip to contents

R Programming Guide for jjstatsplot

ClinicoPath Development Team

2025-07-29

Source: vignettes/14-r-programming-guide.Rmd
14-r-programming-guide.Rmd

Using jjstatsplot Functions in R

This guide demonstrates how to use jjstatsplot functions directly in R for programmatic statistical visualization. While these functions are designed for jamovi integration, they can be powerful tools in R workflows.

Installation and Setup 

# Install from GitHub
if (!require(devtools)) install.packages("devtools")
devtools::install_github("sbalci/jjstatsplot")

# Install dependencies if needed
install.packages(c("ggplot2", "ggstatsplot", "dplyr", "jmvcore"))
library(jjstatsplot)
library(ggplot2)
library(dplyr)

# Load example data
data(mtcars)
data(iris)

Understanding jjstatsplot Function Structure

Return Objects

All jjstatsplot functions return jamovi results objects with: - $plot - The main ggplot2 object - $plot2 - Secondary plot (when grouping variables are used) - Statistical results and metadata

Basic Pattern 

# General function signature
result <- jj[function_name](
  data = your_data,
  dep = dependent_variable(s),
  group = grouping_variable,
  grvar = grouping_for_separate_plots,
  # Additional options...
)

# Extract the plot
plot <- result$plot
print(plot)

Function-by-Function Guide

1. Histogram Analysis - jjhistostats() 

# Basic histogram
hist_result <- jjhistostats(
  data = mtcars,
  dep = "mpg",
  grvar = NULL
)

# Extract and display plot
hist_result$plot
# Histogram with grouping
hist_grouped <- jjhistostats(
  data = mtcars,
  dep = "mpg",
  grvar = "cyl"
)

# Multiple plots created
hist_grouped$plot2

2. Scatter Plots - jjscatterstats() 

# Basic scatter plot
scatter_result <- jjscatterstats(
  data = mtcars,
  dep = "mpg",
  group = "hp",
  grvar = NULL
)

scatter_result$plot
# Scatter plot with grouping variable
scatter_grouped <- jjscatterstats(
  data = mtcars,
  dep = "mpg", 
  group = "hp",
  grvar = "cyl"
)

scatter_grouped$plot2

3. Box-Violin Plots - jjbetweenstats() 

# Between-groups comparison
between_result <- jjbetweenstats(
  data = iris,
  dep = "Sepal.Length",
  group = "Species"
)

between_result$plot
# Multiple dependent variables
between_multi <- jjbetweenstats(
  data = iris,
  dep = c("Sepal.Length", "Petal.Length"),
  group = "Species"
)

between_multi$plot

4. Correlation Matrix - jjcorrmat() 

# Correlation matrix
corr_result <- jjcorrmat(
  data = mtcars,
  dep = c("mpg", "hp", "wt", "qsec"),
  grvar = NULL
)

corr_result$plot

5. Dot Plots - jjdotplotstats() 

# Dot plot for group comparisons
dot_result <- jjdotplotstats(
  data = mtcars,
  dep = "mpg",
  group = "cyl",
  grvar = NULL
)

dot_result$plot

6. Bar Charts - jjbarstats() 

# Bar chart for categorical data
bar_result <- jjbarstats(
  data = mtcars,
  dep = "cyl",
  group = "am",
  grvar = NULL
)

bar_result$plot

7. Pie Charts - jjpiestats() 

# Pie chart
pie_result <- jjpiestats(
  data = mtcars,
  dep = "cyl",
  group = NULL,
  grvar = NULL
)

pie_result$plot1

8. Within-Subjects Analysis - jjwithinstats() 

# For repeated measures data
# Note: This requires appropriate data structure
# Creating example with iris data (not true repeated measures)
within_result <- jjwithinstats(
  data = iris,
  dep1 = "Sepal.Length",
  dep2 = "Sepal.Width",
  dep3 = NULL,
  dep4 = NULL
)

within_result$plot

Advanced Usage Patterns

Working with Multiple Variables 

# Analyze multiple dependent variables simultaneously
multi_hist <- jjhistostats(
  data = iris,
  dep = c("Sepal.Length", "Sepal.Width", "Petal.Length"),
  grvar = NULL
)

# This creates a combined plot
multi_hist$plot

Combining with dplyr Workflows 

# Preprocessing with dplyr, then plotting
mtcars_processed <- mtcars %>%
  mutate(
    cyl_factor = factor(cyl, labels = c("4-cyl", "6-cyl", "8-cyl")),
    am_factor = factor(am, labels = c("Automatic", "Manual"))
  ) %>%
  filter(hp > 100)

# Use processed data
result <- jjbetweenstats(
  data = mtcars_processed,
  dep = "mpg",
  group = "cyl_factor"
)

result$plot

Extracting Statistical Information 

# jjstatsplot functions return rich statistical information
corr_analysis <- jjcorrmat(
  data = mtcars[, c("mpg", "hp", "wt")],
  dep = c("mpg", "hp", "wt"),
  grvar = NULL
)

# The plot contains statistical annotations
print(corr_analysis$plot)

# Access underlying data if needed (structure varies by function)
str(corr_analysis, max.level = 2)

Customization and Theming

Plot Modifications 

# Extract base plot and modify
base_plot <- jjscatterstats(
  data = mtcars,
  dep = "mpg",
  group = "hp",
  grvar = NULL
)$plot

# Add custom modifications
tryCatch({
  custom_plot <- base_plot +
    labs(
      title = "Fuel Efficiency vs Horsepower",
      subtitle = "Modified jjstatsplot output",
      caption = "Data: mtcars dataset"
    ) +
    theme_minimal() +
    theme(
      plot.title = element_text(size = 16, face = "bold"),
      plot.subtitle = element_text(size = 12)
    )
  
  print(custom_plot)
}, error = function(e) {
  cat("Plot customization temporarily unavailable due to compatibility issues.\n")
  print(base_plot)
})

Integration with R Markdown

Chunk Options for Optimal Display 

# Recommended chunk options for jjstatsplot in R Markdown:

# ```{r plot-name, fig.width=8, fig.height=6, dpi=300}
# result <- jjhistostats(data = mydata, dep = "variable")
# result$plot
# ```

Creating Function Wrappers 

# Create convenience wrappers for common analyses
quick_histogram <- function(data, variable, group_by = NULL) {
  result <- jjhistostats(
    data = data,
    dep = variable,
    grvar = group_by
  )
  
  if (is.null(group_by)) {
    return(result$plot)
  } else {
    return(result$plot2)
  }
}

# Usage
tryCatch({
  quick_histogram(mtcars, "mpg", "cyl")
}, error = function(e) {
  cat("Function wrapper example temporarily unavailable due to data compatibility issues.\n")
  cat("Error:", e$message, "\n")
})

Batch Analysis Functions 

# Function to create multiple plots
analyze_variables <- function(data, variables, group_var = NULL) {
  plots <- list()
  
  for (var in variables) {
    result <- jjhistostats(
      data = data,
      dep = var,
      grvar = group_var
    )
    
    plots[[var]] <- if (is.null(group_var)) result$plot else result$plot2
  }
  
  return(plots)
}

# Create multiple histograms
numeric_vars <- c("mpg", "hp", "wt")
tryCatch({
  plot_list <- analyze_variables(mtcars, numeric_vars, "cyl")
  # Display first plot
  print(plot_list$mpg)
}, error = function(e) {
  cat("Batch analysis example temporarily unavailable due to data compatibility issues.\n")
  cat("Error:", e$message, "\n")
})

Error Handling and Debugging

Common Issues and Solutions 

# Safe function wrapper with error handling
safe_jjhistostats <- function(data, dep, ...) {
  tryCatch({
    result <- jjhistostats(data = data, dep = dep, ...)
    return(result$plot)
  }, error = function(e) {
    message("Error creating histogram: ", e$message)
    return(NULL)
  })
}

# Usage with potential problematic data
plot_result <- safe_jjhistostats(mtcars, "nonexistent_variable")

Data Validation 

# Function to check data before analysis
validate_data <- function(data, variables) {
  issues <- list()
  
  # Check if variables exist
  missing_vars <- variables[!variables %in% names(data)]
  if (length(missing_vars) > 0) {
    issues$missing_variables <- missing_vars
  }
  
  # Check for sufficient data
  for (var in variables) {
    if (var %in% names(data)) {
      non_missing <- sum(!is.na(data[[var]]))
      if (non_missing < 10) {
        issues$insufficient_data <- c(issues$insufficient_data, var)
      }
    }
  }
  
  return(issues)
}

# Example usage
issues <- validate_data(mtcars, c("mpg", "hp", "nonexistent"))
print(issues)

Performance Considerations

Large Datasets 

# For large datasets, consider sampling
large_data_plot <- function(data, dep, sample_size = 1000) {
  if (nrow(data) > sample_size) {
    sampled_data <- data[sample(nrow(data), sample_size), ]
    message("Sampling ", sample_size, " rows from ", nrow(data), " total rows")
    data <- sampled_data
  }
  
  jjhistostats(data = data, dep = dep, grvar = NULL)$plot
}

Best Practices Summary

1. Function Usage

  • Always check return structure: $plot vs $plot2
  • Handle missing data appropriately
  • Validate variable names before analysis

2. Data Preparation

  • Use meaningful variable names and factor labels
  • Ensure appropriate data types (numeric, factor)
  • Consider data transformations when needed

3. Workflow Integration

  • Combine with dplyr for data preprocessing
  • Create wrapper functions for repeated analyses
  • Use error handling for robust scripts

4. Output Management

  • Extract plots with result$plot
  • Modify plots using standard ggplot2 syntax
  • Save plots with appropriate dimensions and resolution

5. Documentation

  • Document your analysis choices
  • Include variable descriptions
  • Report statistical assumptions and violations

This guide provides a foundation for using jjstatsplot functions programmatically in R. The functions offer a convenient way to create publication-ready statistical visualizations with minimal code while maintaining access to the underlying ggplot2 objects for further customization.