---
title: "dumbbell R Package"
author: "Foo Cheung"
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_depth: 2
    theme: united
    df_print: paged
vignette: >
  %\VignetteIndexEntry{dumbbell}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, echo=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4,
  message = FALSE,
  warning = FALSE
)
```

## Overview

The **dumbbell** package creates dumbbell plots in **ggplot2**. A dumbbell plot compares two numeric values for the same item and connects them with a line segment. This is useful when you want to show before/after values, treatment/control values, male/female values, or any paired comparison.

The main function is `dumbbell()`. It expects a data frame with at least four columns:

1. an ID column for the y-axis labels,
2. a grouping or facet key,
3. the first numeric value,
4. the second numeric value.

The function returns a `ggplot` object, so you can add standard `ggplot2` layers such as `facet_wrap()`, `labs()`, `theme()`, or `coord_cartesian()`.

## Installation

Install the package from CRAN with:

```{r install-cran, eval=FALSE}
install.packages("dumbbell")
```

Or install a development version from a local source directory:

```{r install-local, eval=FALSE}
devtools::install("path/to/dumbbell")
```

## Load packages

```{r load-packages}
suppressPackageStartupMessages({
  library(dumbbell)
  library(dplyr)
  library(ggplot2)
})
```

## Example data

The example below creates paired measurements for two groups. Each subject has a value for group A and group B. The data are then reshaped into the format expected by `dumbbell()`.

```{r example-data}
set.seed(123)

raw_data <- data.frame(
  Group = rep(c("A", "B"), each = 10),
  Subject = rep(paste0("sub_", 1:10), times = 2),
  result = sample(1:100000, 20, replace = TRUE),
  analysis = rep(rep(c("a", "b"), each = 5), times = 2)
)

group_a <- raw_data %>% filter(Group == "A")
group_b <- raw_data %>% filter(Group == "B")

plot_data <- merge(
  group_a,
  group_b,
  by = c("Subject", "analysis")
)

plot_data <- plot_data %>%
  mutate(diff = result.x - result.y) %>%
  arrange(diff)

plot_data$Subject <- factor(plot_data$Subject, levels = plot_data$Subject)

head(plot_data)
```

## Basic dumbbell plot

Use `id` for the labels on the y-axis, `key` for the grouping variable, and `column1`/`column2` for the paired numeric values.

```{r basic-plot}
dumbbell(
  xdf = plot_data,
  id = "Subject",
  key = "analysis",
  column1 = "result.x",
  column2 = "result.y",
  lab1 = "Group A",
  lab2 = "Group B"
)
```

## Add a delta column

Set `delt = 1` to add the difference between the two values at the right side of the plot.

```{r delta-column}
dumbbell(
  xdf = plot_data,
  id = "Subject",
  key = "analysis",
  column1 = "result.x",
  column2 = "result.y",
  lab1 = "Group A",
  lab2 = "Group B",
  delt = 1,
  expandx = 0.1
)
```

## Add value labels

Set `pt_val = 1` to print the numeric values next to the points. Use `col_lab1` and `col_lab2` to control the label colors.

```{r value-labels}
dumbbell(
  xdf = plot_data,
  id = "Subject",
  key = "analysis",
  column1 = "result.x",
  column2 = "result.y",
  lab1 = "Group A",
  lab2 = "Group B",
  pt_val = 1,
  expandx = 0.05,
  col_lab1 = "blue",
  col_lab2 = "red"
)
```

## Add arrows

Set `arrow = 1` to draw arrows along the connecting segments. Use `arrow_size`, `segsize`, `pointsize`, `pt_alpha`, `col_seg1`, and `col_seg2` to customize the display.

```{r arrows}
dumbbell(
  xdf = plot_data,
  id = "Subject",
  key = "analysis",
  column1 = "result.x",
  column2 = "result.y",
  lab1 = "Group A",
  lab2 = "Group B",
  arrow = 1,
  arrow_size = 0.2,
  segsize = 0.7,
  pointsize = 1.5,
  pt_alpha = 0.6,
  col_seg1 = "#A9A9A9",
  col_seg2 = "#A9A9A9"
)
```

## Facet by group

Because `dumbbell()` returns a `ggplot` object, you can add `facet_wrap()` directly.

```{r facets}
dumbbell(
  xdf = plot_data,
  id = "Subject",
  key = "analysis",
  column1 = "result.x",
  column2 = "result.y",
  lab1 = "Group A",
  lab2 = "Group B"
) +
  facet_wrap(~ analysis, ncol = 1, scales = "free_y")
```

## Add paired p-values

The `pval` argument adds a paired test result to the facet label:

- `pval = 1` uses a paired Wilcoxon test.
- `pval = 2` uses a paired t-test.

The current implementation uses base R functions from the `stats` package, so the package does not need to depend on `rstatix` for these tests.

```{r pvalues}
dumbbell(
  xdf = plot_data,
  id = "Subject",
  key = "analysis",
  column1 = "result.x",
  column2 = "result.y",
  lab1 = "Group A",
  lab2 = "Group B",
  pval = 1
) +
  facet_wrap(~ analysis, ncol = 1, scales = "free_y")
```

## Complete customized example

This example combines facets, arrows, highlighted segment colors, point transparency, and delta labels.

```{r complete-example}
dumbbell(
  xdf = plot_data,
  id = "Subject",
  key = "analysis",
  column1 = "result.x",
  column2 = "result.y",
  lab1 = "Group A",
  lab2 = "Group B",
  delt = 1,
  col_seg2 = "red",
  col_seg1 = "blue",
  arrow = 1,
  pt_alpha = 0.6,
  pointsize = 2,
  expandx = 0.2,
  segsize = 0.5,
  textsize = 2,
  pval = 1
) +
  facet_wrap(~ analysis, ncol = 1, scales = "free_y")
```

## Working with axis limits

Because `dumbbell()` already adds an x-axis scale, `xlim()` will replace that scale and may remove data outside the requested range. To zoom without dropping observations, use `coord_cartesian()`:

```{r axis-limits, eval=FALSE}
dumbbell(
  xdf = plot_data,
  id = "Subject",
  key = "analysis",
  column1 = "result.x",
  column2 = "result.y",
  lab1 = "Group A",
  lab2 = "Group B"
) +
  coord_cartesian(xlim = c(0, 100000))
```

## Main arguments

| Argument | Description |
|---|---|
| `xdf` | Input data frame. |
| `id` | Column used for the y-axis labels. |
| `key` | Grouping variable, commonly used with `facet_wrap()`. |
| `column1`, `column2` | Paired numeric columns to compare. |
| `lab1`, `lab2` | Labels for the two compared values. |
| `delt` | Set to `1` to display the difference between the two values. |
| `pt_val` | Set to `1` to display point value labels. |
| `pval` | Set to `1` for paired Wilcoxon test or `2` for paired t-test. |
| `arrow` | Set to `1` to add arrows to the connecting segments. |
| `pointsize`, `textsize`, `segsize` | Control point, label, and segment sizes. |
| `p_col1`, `p_col2` | Colors for the two point groups. |
| `col_seg1`, `col_seg2` | Segment colors by direction. |
| `expandx`, `expandy` | Expansion around the x- and y-axes. |

## Notes for package maintainers

- The p-value functionality should rely on `stats::wilcox.test()` and `stats::t.test()` to avoid an unnecessary dependency on `rstatix`.
- If the roxygen comments are changed, run `devtools::document()` to regenerate `NAMESPACE` and help files.
- If a `docs/` website is used, regenerate it from the source vignette/R Markdown rather than editing generated HTML by hand.