Package {dumbbell}

Type: Package
Title: Displaying Changes Between Two Points Using Dumbbell Plots
Version: 0.2
Description: Creates dumbbell plots to visualize changes between two measurements for the same observations. The package provides customization options for labels, colors, arrows, delta values, and paired statistical test annotations.
License: MIT + file LICENSE
Encoding: UTF-8
Imports: dplyr, ggplot2, grid, rlang, tidyr, utils
URL: https://github.com/foocheung/dumbbell
BugReports: https://github.com/foocheung/dumbbell/issues
NeedsCompilation: no
RoxygenNote: 7.3.3
Collate: 'global.R' 'dumbbell.R'
Suggests: knitr, rmarkdown
VignetteBuilder: knitr
Packaged: 2026-07-06 19:13:58 UTC; cheungf
Author: Foo Cheung [aut, cre]
Maintainer: Foo Cheung <foocheung@yahoo.com>
Repository: CRAN
Date/Publication: 2026-07-06 19:40:02 UTC

Dumbbell Plot

Description

Draws a dumbbell plot, essentially a dot plot with two series of data.

Usage

dumbbell(
  xdf,
  id,
  key,
  column1,
  column2,
  lab1 = "Addlab1",
  lab2 = "Addlab2",
  title = "",
  pointsize = 1,
  textsize = 2,
  segsize = 1,
  expandx = 0.05,
  expandy = 1,
  p_col1 = "red",
  p_col2 = "blue",
  leg = "",
  col_seg1 = "gray80",
  col_seg2 = "gray80",
  col_lab1 = "black",
  col_lab2 = "black",
  pt_alpha = 1,
  arrow_size = 0.2,
  arrow = 0,
  pt_val = 0,
  delt = 0,
  pval = 0
)

Arguments

xdf

A data frame containing at least four columns: an id column, a key/grouping column, and two numeric columns to compare.

id

Name of the column containing the id variable used to label the y axis, e.g. id = "id".

key

Name of the column containing the key/facet variable, e.g. key = "key".

column1, column2

Names of the first and second numeric columns, e.g. column1 = "Control", column2 = "Test".

lab1, lab2

Labels for the two data series, e.g. lab1 = "Control", lab2 = "Test".

title

Plot title, e.g. title = "This is a plot title".

pointsize

Point size, e.g. pointsize = 3.

textsize

Numeric value specifying the text size, e.g. textsize = 3.

segsize

Numeric value specifying the segment width, e.g. segsize = 1.

expandx

Add space to both ends of the x axis, e.g. expandx = 0.6.

expandy

Add space to both ends of the y axis, e.g. expandy = 1.

p_col1, p_col2

Colors for the first and second points, e.g. p_col1 = "red".

leg

Legend title, e.g. leg = "Group".

col_seg1, col_seg2

Colors for segments in each direction, e.g. col_seg1 = "red".

col_lab1, col_lab2

Colors for text labels below each dumbbell, e.g. col_lab1 = "red".

pt_alpha

Point transparency, e.g. pt_alpha = 0.6.

arrow_size

Size of arrows, e.g. arrow_size = 0.2.

arrow

Add an arrow to one end of the dumbbell. Use arrow = 1 to show arrows.

pt_val

Add point-value labels to the plot. Use pt_val = 1 to show values.

delt

Add a delta column to the plot. Use delt = 1 to show the difference.

pval

Add p-value to the key/facet label. Use pval = 1 for a paired Wilcoxon test or pval = 2 for a paired t-test.

Value

A ggplot object.

Author(s)

Foo Cheung, foocheung@yahoo.com

Examples

library(dumbbell)
library(ggplot2)
z <- data.frame(
  Group = c(rep("A", 20), rep("B", 20)),
  Subject = c(paste0("sub_", 1:20), paste0("sub_", 1:20)),
  result = sample(1:100000, 40, replace = TRUE),
  analysis = c(rep("a", 10), rep("b", 10), rep("b", 10), rep("a", 10))
)
b <- z[z$Group == "A", ]
c <- z[z$Group == "B", ]
d <- merge(b, c, by = "Subject")
dumbbell(xdf = d, id = "Subject", key = "analysis.x", column1 = "result.x", column2 = "result.y")