Type:	Package
Title:	Custom Legends with Statistical Comparison Brackets
Version:	1.0.2
Description:	Add publication-quality custom legends with vertical brackets. Designed for displaying statistical comparisons between groups, commonly used in scientific publications for showing significance levels. Features include adaptive positioning, automatic bracket spacing for overlapping comparisons, font family inheritance, and support for asterisks, p-values, or custom labels. Compatible with 'ggplot2' graphics.
License:	MIT + file LICENSE
Encoding:	UTF-8
Depends:	R (≥ 3.5.0)
Imports:	ggplot2 (≥ 3.0.0), grid
Suggests:	knitr, rmarkdown
URL:	https://github.com/h20gg702/vbracket
BugReports:	https://github.com/h20gg702/vbracket/issues
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2025-12-22 05:51:00 UTC; yoshiakisato
Author:	Yoshiaki Sato [aut, cre]
Maintainer:	Yoshiaki Sato <h20gg702@outlook.jp>
Repository:	CRAN
Date/Publication:	2026-01-07 08:20:02 UTC

Create comparison specification for vbracket

Description

Helper function to create a properly formatted comparison data frame for use with guide_legend_bracket().

Usage

add_bracket_comparisons(..., groups1 = NULL, groups2 = NULL, labels = NULL)

Arguments

Value

A data frame with columns: group1, group2, label

Examples

# Using individual vectors
add_bracket_comparisons(
  groups1 = c("A", "C"),
  groups2 = c("B", "D"),
  labels = c("***", "ns")
)

# Using ... with vectors
add_bracket_comparisons(
  c("A", "B", "***"),
  c("C", "D", "ns")
)

Create a self-contained vbracket legend grob for annotation_custom

Description

This creates a grob that can be used with annotation_custom() in ggplot2. Unlike draw_legend_with_brackets(), this creates a single grob that handles its own viewport setup internally.

Usage

create_annotation_legend_grob(
  labels,
  colors,
  comparisons = NULL,
  x = 0.1,
  y = 0.9,
  width = 0.25,
  height = NULL,
  title = NULL,
  text_size = 10,
  text_family = "sans",
  text_face = "plain",
  title_size = 11,
  title_face = "bold",
  sig_size = 11,
  sig_face = "plain",
  output_width = 8,
  output_height = 6,
  bracket_margin = NULL
)

Create a custom legend with vertical brackets

Description

This function draws a completely custom legend outside of ggplot2's system, with vertical brackets showing comparisons.

Usage

draw_legend_with_brackets(
  labels,
  colors,
  comparisons = NULL,
  x = 0.1,
  y = 0.9,
  width = 0.2,
  height = NULL,
  title = NULL,
  text_size = 10,
  text_family = "sans",
  text_face = "plain",
  title_size = 11,
  title_face = "bold",
  sig_size = 11,
  sig_face = "plain",
  output_width = NULL,
  output_height = NULL
)

Arguments

Value

A gTree object containing the custom legend

Examples

labels <- c("WT", "WT/Dox", "CH3+5")
colors <- c("green", "orange", "blue")
comps <- data.frame(group1 = "WT", group2 = "WT/Dox", label = "*")
legend_grob <- draw_legend_with_brackets(labels, colors, comps,
                                         text_family = "sans",
                                         text_size = 12)
grid::grid.draw(legend_grob)

Add vbracket legend to ggplot

Description

Add vbracket legend to ggplot

Usage

## S3 method for class 'vbracket_legend'
ggplot_add(object, plot, ...)

Arguments

Value

A ggplot object (classes "gg" and "ggplot") with the vbracket legend incorporated. The plot's default legend is typically suppressed and a custom vbracket legend showing statistical comparison brackets is added.

Save a ggplot with vbracket legend

Description

This function is a wrapper around ggsave() that properly handles vbracket legends. Use this instead of ggsave() when your plot has a legend_bracket().

Usage

ggsave_vbracket(
  filename,
  plot,
  device = NULL,
  width = NA,
  height = NA,
  units = c("in", "cm", "mm", "px"),
  dpi = 300,
  ...
)

Arguments

Value

No return value, called for its side effects. Saves the plot (including the vbracket legend, if present) to the file specified by filename.

Examples

library(ggplot2)
data <- data.frame(x = 1:10, y = 1:10, group = rep(c("A", "B"), each = 5))
labels <- c("A", "B")
colors <- c("A" = "red", "B" = "blue")
comparisons <- add_bracket_comparisons(groups1 = "A", groups2 = "B", labels = "*")

p <- ggplot(data, aes(x, y, color = group)) +
  geom_point() +
  legend_bracket(labels, colors, comparisons,
                 position = "topleft", output_width = 6, output_height = 4)

ggsave_vbracket(file.path(tempdir(), "plot.pdf"), p, width = 6, height = 4)

Add legend with brackets to a ggplot object

Description

This function allows you to add a custom legend with brackets using the + operator, similar to ggplot2 layers.

Usage

legend_bracket(
  labels,
  colors,
  comparisons = NULL,
  x = NULL,
  y = NULL,
  width = NULL,
  height = NULL,
  unit = "npc",
  position = "topleft",
  title = NULL,
  text_size = 10,
  text_family = "sans",
  text_face = "plain",
  title_size = 11,
  title_face = "bold",
  sig_size = 11,
  sig_face = "plain",
  output_width = NULL,
  output_height = NULL,
  bracket_margin = NULL,
  legend_x = NULL,
  legend_y = NULL
)

Arguments

Value

A vbracket_legend object

Examples

library(ggplot2)
data <- data.frame(x = 1:10, y = 1:10, group = rep(c("A", "B"), each = 5))
labels <- c("A", "B")
colors <- c("A" = "red", "B" = "blue")
comparisons <- add_bracket_comparisons(groups1 = "A", groups2 = "B", labels = "*")

p <- ggplot(data, aes(x, y, color = group)) + geom_point() +
  legend_bracket(labels, colors, comparisons,
                 position = "topleft",
                 output_width = 6, output_height = 4)

# Then use regular ggsave with same dimensions
ggsave(file.path(tempdir(), "plot.pdf"), p, width = 6, height = 4)

Get standard significance symbols from p-values

Description

Convert p-values to standard significance symbols

Usage

p_to_symbol(
  p_values,
  symbols = c("***", "**", "*", "ns"),
  breaks = c(0, 0.001, 0.01, 0.05, 1)
)

Arguments

Value

Character vector of significance symbols

Examples

p_to_symbol(c(0.0001, 0.005, 0.03, 0.15))
# Returns: "***"  "**"   "*"    "ns"

Add custom legend with brackets to a ggplot

Description

Remove ggplot2's legend and add a custom legend with brackets

Usage

plot_with_custom_legend(
  plot,
  labels,
  colors,
  comparisons = NULL,
  legend_x = 0.05,
  legend_y = 0.95,
  legend_width = 0.25,
  title = NULL
)

Arguments

Value

A ggplot object (classes "gg" and "ggplot") with the vbracket legend incorporated. The plot's default legend is typically suppressed and a custom vbracket legend showing statistical comparison brackets is added.

Examples

library(ggplot2)
data <- data.frame(x = 1:10, y = 1:10, group = rep(c("A", "B"), each = 5))
p <- ggplot(data, aes(x, y, color = group)) + geom_line()
comps <- add_bracket_comparisons(groups1 = "A", groups2 = "B", labels = "*")
plot_with_custom_legend(p, c("A", "B"), c("red", "blue"), comps)

Print method for ggplot objects with vbracket legend

Description

This overrides the default ggplot print method to add brackets automatically

Usage

## S3 method for class 'gg'
print(x, newpage = is.null(vp), vp = NULL, ...)

Arguments

Value

Invisibly returns the input ggplot object (classes "gg" and "ggplot"). Called for its side effects: rendering the plot to the current graphics device with the vbracket legend overlay if present.

Print a ggplot with vbracket overlay

Description

Print a ggplot with vbracket overlay

Usage

print_vbracket_plot(x, ...)

Arguments

Validate comparison data frame

Description

Check if comparison data frame has required columns and valid data

Usage

validate_comparisons(comparisons)

Arguments

Value

TRUE if valid, otherwise throws error