Package 'vbracket' reference manual

Title:	Custom Legends with Statistical Comparison Brackets
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.
Authors:	Yoshiaki Sato [aut, cre] (ORCID: <https://orcid.org/0000-0003-3375-5189>)
Maintainer:	Yoshiaki Sato <[email protected]>
License:	MIT + file LICENSE
Version:	1.4.0
Built:	2026-05-25 07:10:56 UTC
Source:	https://github.com/h20gg702/vbracket

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)
add_bracket_comparisons(..., groups1 = NULL, groups2 = NULL, labels = NULL)

Arguments

...

Named arguments or list of comparisons. Each comparison can be:

A character vector of length 3: c(group1, group2, label)
A named list: list(from = "A", to = "B", label = "***")

groups1

Character vector of first groups to compare.

groups2

Character vector of second groups to compare.

labels

Character vector of significance labels.

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")
)
# 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 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,
  line_length = NULL,
  line_width = NULL,
  item_spacing = NULL,
  bracket_layer_spacing = NULL
)
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,
  line_length = NULL,
  line_width = NULL,
  item_spacing = NULL,
  bracket_layer_spacing = NULL
)

Arguments

labels

Character vector of group names

colors

Character vector of colors for each group

comparisons

Data frame with columns: group1, group2, label

x

Numeric. X position of legend (0-1, in npc units)

y

Numeric. Y position of legend (0-1, in npc units)

width

Numeric. Width of legend box

height

Numeric. Height of legend box

title

Character. Legend title (optional)

text_size

Numeric. Font size for legend labels (default 10)

text_family

Character. Font family (e.g., "sans", "serif", "mono", "Helvetica", "Times")

text_face

Character. Font face: "plain", "bold", "italic", "bold.italic" (default "plain")

title_size

Numeric. Font size for title (default 11)

title_face

Character. Font face for title (default "bold")

sig_size

Numeric. Font size for significance symbols (default 11)

sig_face

Character. Font face for significance symbols (default "plain")

output_width

Numeric. Output figure width in inches (optional, for METHOD 2)

output_height

Numeric. Output figure height in inches (optional, for METHOD 2)

line_length

Numeric. Manual override for legend symbol line length (default NULL = auto-scaled by text_size)

line_width

Numeric. Manual override for legend symbol line width (default NULL = auto-scaled by text_size)

item_spacing

Numeric. Manual override for vertical spacing between legend items (default NULL = auto-scaled by text_size)

bracket_layer_spacing

Numeric. Manual override for horizontal spacing between bracket layers (default NULL = auto-calculated)

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)

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, ...)
## S3 method for class 'vbracket_legend'
ggplot_add(object, plot, ...)

Arguments

object

A vbracket_legend object

plot

A ggplot object

...

Additional arguments (not used)

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,
  ...
)
ggsave_vbracket(
  filename,
  plot,
  device = NULL,
  width = NA,
  height = NA,
  units = c("in", "cm", "mm", "px"),
  dpi = 300,
  ...
)

Arguments

filename

File name to save plot to

plot

Plot to save (must have legend_bracket)

device

Device to use (default auto-detects from filename)

width

Width in units

height

Height in units

units

Units for width and height ("in", "cm", "mm", "px")

dpi

DPI for raster devices

...

Additional arguments passed to ggsave()

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)

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,
  line_length = NULL,
  line_width = NULL,
  item_spacing = NULL,
  bracket_layer_spacing = NULL
)
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,
  line_length = NULL,
  line_width = NULL,
  item_spacing = NULL,
  bracket_layer_spacing = NULL
)

Arguments

labels

Character vector of group names (in order)

colors

Character vector of colors matching the groups

comparisons

Data frame with columns: group1, group2, label

x

Numeric. X position of legend (0-1 scale or with unit)

y

Numeric. Y position of legend (0-1 scale or with unit)

width

Numeric. Width of legend box (default NULL = auto)

height

Numeric. Height of legend box (default NULL = auto)

unit

Character. Unit for width and height: "npc" (0-1 scale), "in", "cm", "mm" (default "npc")

position

Character. Preset position: "topleft", "topright", "bottomleft", "bottomright", or NULL for manual x/y

title

Character. Legend title (optional)

text_size

Numeric. Font size for labels (default 10)

text_family

Character. Font family (default "sans")

text_face

Character. Font face (default "plain")

title_size

Numeric. Title font size (default 11)

title_face

Character. Title font face (default "bold")

sig_size

Numeric. Significance symbol size (default 11)

sig_face

Character. Significance symbol face (default "plain")

output_width

Numeric. Output figure width in inches (for accurate bracket positioning)

output_height

Numeric. Output figure height in inches (for accurate bracket positioning)

bracket_margin

Numeric. Custom horizontal spacing between legend text and brackets (default NULL = auto-adaptive)

legend_x

Numeric. Custom X position for legend box (0-1 scale, overrides adaptive positioning)

legend_y

Numeric. Custom Y position for legend box (0-1 scale, overrides adaptive positioning)

line_length

Numeric. Manual override for legend symbol line length (default NULL = auto-scaled by text_size)

line_width

Numeric. Manual override for legend symbol line width (default NULL = auto-scaled by text_size)

item_spacing

Numeric. Manual override for vertical spacing between legend items (default NULL = auto-scaled by text_size)

bracket_layer_spacing

Numeric. Manual override for horizontal spacing between bracket layers (default NULL = auto-calculated)

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)

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)
)
p_to_symbol(
  p_values,
  symbols = c("***", "**", "*", "ns"),
  breaks = c(0, 0.001, 0.01, 0.05, 1)
)

Arguments

p_values

Numeric vector of p-values

symbols

Character vector of symbols for different significance levels. Default: c("***", "**", "*", "ns")

breaks

Numeric vector of p-value thresholds. Default: c(0, 0.001, 0.01, 0.05, 1)

Value

Character vector of significance symbols

Examples

p_to_symbol(c(0.0001, 0.005, 0.03, 0.15))
# Returns: "***"  "**"   "*"    "ns"
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
)
plot_with_custom_legend(
  plot,
  labels,
  colors,
  comparisons = NULL,
  legend_x = 0.05,
  legend_y = 0.95,
  legend_width = 0.25,
  title = NULL
)

Arguments

plot

A ggplot object

labels

Character vector of group names (in order)

colors

Character vector of colors matching the groups

comparisons

Data frame with columns: group1, group2, label

legend_x

X position (0-1)

legend_y

Y position (0-1)

legend_width

Width of legend

title

Legend title

Value

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)

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, ...)
## S3 method for class 'gg'
print(x, newpage = is.null(vp), vp = NULL, ...)

Arguments

x

A ggplot object

newpage

Draw on new page (default TRUE)

vp

Viewport to draw in

...

Additional 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.

Package 'vbracket'

Help Index

Create comparison specification for vbracket

Description

Usage

Arguments

Value

Examples

Create a custom legend with vertical brackets

Description

Usage

Arguments

Value

Examples

Add vbracket legend to ggplot

Description

Usage

Arguments

Value

Save a ggplot with vbracket legend

Description

Usage

Arguments

Value

Examples

Add legend with brackets to a ggplot object

Description

Usage

Arguments

Value

Examples

Get standard significance symbols from p-values

Description

Usage

Arguments

Value

Examples

Add custom legend with brackets to a ggplot

Description

Usage

Arguments

Value

Examples

Print method for ggplot objects with vbracket legend

Description

Usage

Arguments

Value