ggpubr

repository·master·Indexed 22 days ago

https://github.com/kassambara/ggpubr

An R package providing high-level functions for creating and customizing publication-ready plots based on the ggplot2 framework. It simplifies complex visualization tasks with specialized functions for ROC curves (ggrocplot), volcano plots (ggvolcano), raincloud plots (ggraincloud), forest plots (ggestimates), and group comparisons (ggcompare), as well as tools for statistical annotations and p-value formatting.

Tokens
4.3K
Snippets
8
Records
15
Agent score
79%

What's inside ggpubr

  1. New features in ggpubr 1.1.0

    master

    Version 1.1.0 introduces several new functions for publication-ready figures and common analysis workflows:

    • ggrocplot(): Generates ROC curves including AUC, confidence intervals, optional optimal cut-point markers, and multi-marker overlays.
    • ggcompare(): Creates one- and two-way group-comparison figures with adjusted-p brackets and omnibus test labels (including simple main effects).
    • ggvolcano(): Volcano plots.
    • ggestimates(): Forest and estimation plots.
    • ggraincloud(): Raincloud plots.
    • stat_cld(): Compact letter display.
    • add_test_label(): Adds statistical test labels to plots.
    • geom_pwc(pack = "auto"): Automatic bracket packing for pairwise comparisons.
  2. New plot types and statistical helpers in version 1.1.0

    master

    Version 1.1.0 introduced several new publication-ready plot types and statistical annotation tools:

    New Plot Types:

    • ggcompare(): One-call group-comparison figures (box/violin/strip plots with points, means, and adjusted-p brackets).
    • ggrocplot(): ROC curves with AUC, confidence intervals, and optional cut-point markers.
    • ggestimates(): Forest and estimation plots (odds/hazard/risk ratios, regression coefficients).
    • ggraincloud(): Raincloud plots (half-violin + box + jittered points).
    • ggvolcano(): Volcano plots for differential expression.

    Statistical Helpers:

    • stat_cld(): Compact letter display.
    • add_test_label(): Adds an omnibus test subtitle.
    • geom_pwc(pack = "auto"): Automatic bracket packing for p-values.

    P-value Formatting:

    • New helpers: format_p_value(), get_p_format_style(), and list_p_format_styles().
    • Extended parameters in statistical layers: p.format.style, p.digits, p.leading.zero, p.min.threshold, and p.decimal.mark.
  3. Using select and remove arguments in ggpubr builders

    master

    The select = and remove = arguments (used in 14 different functions) have been updated to ensure correct filtering:

    • Correct Filtering: When used together, they now correctly filter to the requested groups. Previously, the remove argument could cause the removed group to survive or introduce NA rows because the row mask was built before select subset the data.
    • Column Name Safety: The filter no longer uses subset(), meaning if your data contains a column named select, remove, or x, it will no longer interfere with the function arguments.
    • Warning on Overlap: If you name the same item in both select = and remove =, a warning will be issued stating that the item will be dropped (since remove is applied after select).
  4. Install ggpubr from CRAN or GitHub

    master

    You can install the stable version of ggpubr from CRAN using install.packages(). For the latest development version, use devtools::install_github() from the kassambara/ggpubr repository.

    # Install from CRAN
    install.packages("ggpubr")
    
    # Install latest version from GitHub
    if(!require(devtools)) install.packages("devtools")
    devtools::install_github("kassambara/ggpubr")
  5. Create Cleveland's dot plot with ggdotchart()

    master

    Cleveland's dot plot can be created by using ggdotchart() with rotate = TRUE and y.text.col = TRUE to color the y-axis text by groups. You can enhance the plot with theme_cleveland() to add dashed grids.

    ggdotchart(dfm, x = "name", y = "mpg",
               color = "cyl",                                # Color by groups
               palette = c("#00AFBB", "#E7B800", "#FC4E07"), # Custom color palette
               sorting = "descending",                       # Sort value in descending order
               rotate = TRUE,                                # Rotate vertically
               dot.size = 2,                                 # Large dot size
               y.text.col = TRUE,                            # Color y text by groups
               ggtheme = theme_pubr()                        # ggplot2 theme
               )+
      theme_cleveland()                                      # Add dashed grids
  6. Create density and histogram plots

    master

    Use ggdensity() and gghistogram() to create distribution plots. You can add mean lines, marginal rugs, and customize colors by group using the color, fill, and palette arguments.

    library(ggpubr)
    
    # Density plot with mean lines and marginal rug
    ggdensity(wdata, x = "weight",
       add = "mean", rug = TRUE,
       color = "sex", fill = "sex",
       palette = c("#00AFBB", "#E7B800"))
    
    # Histogram plot with mean lines and marginal rug
    gghistogram(wdata, x = "weight",
       add = "mean", rug = TRUE,
       color = "sex", fill = "sex",
       palette = c("#00AFBB", "#E7B800"))
  7. Create deviation graphs (horizontal or vertical)

    master

    Deviation graphs show the deviation of quantitative values to a reference value. Use ggbarplot() with rotate = TRUE to create horizontal deviation plots.

    # Vertical deviation graph
    ggbarplot(dfm, x = "name", y = "mpg_z",
              fill = "mpg_grp",
              color = "white",
              palette = "jco",
              sort.val = "asc",
              sort.by.groups = FALSE,
              x.text.angle = 90,
              ylab = "MPG z-score",
              xlab = FALSE,
              legend.title = "MPG Group")
    
    # Horizontal deviation graph
    ggbarplot(dfm, x = "name", y = "mpg_z",
              fill = "mpg_grp",
              color = "white",
              palette = "jco",
              sort.val = "desc",
              sort.by.groups = FALSE,
              x.text.angle = 90,
              ylab = "MPG z-score",
              legend.title = "MPG Group",
              rotate = TRUE,
              ggtheme = theme_minimal())
  8. Create box plots and violin plots with statistical comparisons

    master

    Use ggboxplot() and ggviolin() to create distribution plots. You can add jittered points, boxplots, and statistical significance annotations using stat_compare_means().

    Note on P-values: stat_compare_means() with the comparisons argument displays unadjusted p-values. For adjusted p-values, use geom_pwc() or stat_pvalue_manual().

    # Box plots with jittered points and pairwise comparisons
    my_comparisons <- list( c("0.5", "1"), c("1", "2"), c("0.5", "2") )
    
    p <- ggboxplot(df, x = "dose", y = "len",
                    color = "dose", palette =c("#00AFBB", "#E7B800", "#FC4E07"),
                    add = "jitter", shape = "dose")
    
    p + stat_compare_means(comparisons = my_comparisons) +
      stat_compare_means(label.y = 50)
    
    # Violin plots with box plots inside and significance levels
    ggviolin(df, x = "dose", y = "len", fill = "dose",
             palette = c("#00AFBB", "#E7B800", "#FC4E07"),
             add = "boxplot", add.params = list(fill = "white"))+
      stat_compare_means(comparisons = my_comparisons, label = "p.signif")+
      stat_compare_means(label.y = 50)
  9. Create a Deviation graph using ggdotchart()

    master

    To create a deviation graph, use a standardized variable (e.g., y = "mpg_z") and customize the segment appearance using add.params. You can also add a horizontal reference line using standard ggplot2 functions like geom_hline().

    ggdotchart(dfm, x = "name", y = "mpg_z",
               color = "cyl",                                # Color by groups
               palette = c("#00AFBB", "#E7B800", "#FC4E07"), # Custom color palette
               sorting = "descending",                       # Sort value in descending order
               add = "segments",                             # Add segments from y = 0 to dots
               add.params = list(color = "lightgray", size = 2), # Change segment color and size
               group = "cyl",                                # Order by groups
               dot.size = 6,                                 # Large dot size
               label = round(dfm$mpg_z,1),                        # Add mpg values as dot labels
               font.label = list(color = "white", size = 9,
                                 vjust = 0.5),               # Adjust label parameters
               ggtheme = theme_pubr()                        # ggplot2 theme
               )+
      geom_hline(yintercept = 0, linetype = 2, color = "lightgray")
  10. Create ordered and grouped bar plots

    master

    Use ggbarplot() to create bar charts. You can control sorting and grouping with the following arguments:

    • sort.val: Sorting order ("asc" or "desc").
    • sort.by.groups: If TRUE, sorts bars inside each group. If FALSE, sorts globally.
    • fill: Grouping variable for colors.
    • palette: Color palette (e.g., "jco").
    • x.text.angle: Rotation for x-axis text.
    # Ordered bar plot (global sort, not by group)
    ggbarplot(dfm, x = "name", y = "mpg",
              fill = "cyl",
              color = "white",
              palette = "jco",
              sort.val = "desc",
              sort.by.groups = FALSE,
              x.text.angle = 90)
    
    # Ordered bar plot (sort inside each group)
    ggbarplot(dfm, x = "name", y = "mpg",
              fill = "cyl",
              color = "white",
              palette = "jco",
              sort.val = "asc",
              sort.by.groups = TRUE,
              x.text.angle = 90)
  11. Customize Lollipop charts with ggdotchart()

    master

    To create a more advanced Lollipop chart, you can use several parameters in ggdotchart():

    • rotate = TRUE: Rotates the plot vertically.
    • group: Specifies the variable used to order values inside each group.
    • dot.size: Sets the size of the dots.
    • label: Adds labels to the dots (e.g., label = "mpg" or label = round(dfm$mpg)).
    • font.label: A list to adjust label parameters like color, size, and vjust.
    • add = "segments": Adds segments from the baseline to the dots.
    • palette: A vector of colors for the groups.
    • ggtheme: The ggplot2 theme to apply (e.g., theme_pubr()).
    ggdotchart(dfm, x = "name", y = "mpg",
               color = "cyl",                                # Color by groups
               palette = c("#00AFBB", "#E7B800", "#FC4E07"), # Custom color palette
               sorting = "descending",                       # Sort value in descending order
               add = "segments",                             # Add segments from y = 0 to dots
               rotate = TRUE,                                # Rotate vertically
               group = "cyl",                                # Order by groups
               dot.size = 6,                                 # Large dot size
               label = round(dfm$mpg),                        # Add mpg values as dot labels
               font.label = list(color = "white", size = 9,
                                 vjust = 0.5),               # Adjust label parameters
               ggtheme = theme_pubr()                        # ggplot2 theme
               )