### Install ggsignif Package

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/README.md

Install the ggsignif package from CRAN or the development version from GitHub.

```r
install.packages("ggsignif")

# Development version
remotes::install_github("const-ae/ggsignif")
```

--------------------------------

### Install ggsignif Development Version

Source: https://github.com/const-ae/ggsignif/blob/main/README.md

Install the latest development version of ggsignif from GitHub using the remotes package.

```r
install.packages("remotes")
remotes::install_github("const-ae/ggsignif")
```

--------------------------------

### Install ggsignif from CRAN

Source: https://github.com/const-ae/ggsignif/blob/main/README.md

Install the ggsignif package from CRAN using the install.packages function.

```r
install.packages("ggsignif")
```

--------------------------------

### Comparison Vector Examples

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Illustrates common ways to define comparison vectors using group names, numeric indices, or a mix.

```R
# Character group names (most common)
c("GroupA", "GroupB")
```

```R
# Numeric indices (less common, 1-indexed)
c(1, 2)
```

```R
# Mixed (unusual but valid)
c("GroupA", 2)
```

--------------------------------

### Annotation Data Frame Example

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Provides a concrete example of an annotation data frame with sample data for positions, labels, and faceting.

```R
annotation_df <- data.frame(
  start = c("setosa", "versicolor"),
  end = c("versicolor", "virginica"),
  y = c(7.5, 8.0),
  label = c("p<0.001", "p=0.02"),
  species_facet = c("A", "B")
)
```

--------------------------------

### ggplot2 aes() Mapping Examples

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Demonstrates creating aesthetic mappings using ggplot2::aes() for basic and manual mode configurations.

```R
# Basic mapping (standard ggplot2 aesthetics)
mapping = aes(color = "red", linetype = "dashed")
```

```R
# Manual mode mapping (custom columns)
mapping = aes(
  xmin = start_column,
  xmax = end_column,
  y_position = y_col,
  annotations = label_col
)
```

--------------------------------

### Error: Mismatched xmin/xmax Parameters

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

When using `xmin` and `xmax`, both must be provided and have the same length. This example shows incorrect usage with a missing parameter and length mismatch, followed by the correct implementation.

```R
# WRONG: xmin without xmax
geom_signif(xmin = 1, y_position = 10)

# WRONG: length mismatch
geom_signif(
  xmin = c(1, 2),
  xmax = c(2, 3, 4),  # Wrong length!
  y_position = c(10, 12)
)

# CORRECT: both provided with matching length
geom_signif(
  xmin = c(1, 2),
  xmax = c(2, 3),
  y_position = c(10, 12)
)
```

--------------------------------

### Error: Missing Annotations Mapping in Manual Mode

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

In manual mode, the `mapping` must include an `annotations` aesthetic. This example demonstrates the incorrect usage without `annotations` and the correct usage with it.

```R
# WRONG: missing annotations in mapping
geom_signif(
  data = annotation_df,
  mapping = aes(xmin = start, xmax = end, y_position = y),
  manual = TRUE
)

# CORRECT: include annotations
geom_signif(
  data = annotation_df,
  mapping = aes(
    xmin = start, xmax = end, y_position = y,
    annotations = label
  ),
  manual = TRUE
)
```

--------------------------------

### Statistical Test Result Examples

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Shows examples of relevant elements from standard R statistical test outputs (t.test, wilcox.test) and a custom test function.

```R
# t.test result (relevant elements)
t.test(x, y)
# Returns: list(statistic=..., parameter=..., p.value=..., ...)
```

```R
# wilcox.test result
wilcox.test(x, y)
# Returns: list(statistic=..., p.value=..., ...)
```

```R
# Custom test
my_test <- function(x, y) {
  list(p.value = 0.05, custom_stat = 123)
}
```

--------------------------------

### Error: Annotations Length Mismatch

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

The number of `annotations` must match the number of `comparisons` or `xmin` values. This example shows a mismatch and the correct usage with matching lengths, including recycling a single annotation.

```R
# WRONG: 3 comparisons, 2 annotations
geom_signif(
  comparisons = list(c("A", "B"), c("B", "C"), c("A", "C")),
  annotations = c("*", "**")
)

# CORRECT: matching length
geom_signif(
  comparisons = list(c("A", "B"), c("B", "C")),
  annotations = c("*", "**")
)

# CORRECT: single annotation recycled
geom_signif(
  comparisons = list(c("A", "B"), c("B", "C")),
  annotations = "*"
)
```

--------------------------------

### Simple Data Explorer with geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Use geom_signif for basic data exploration, showing significance between multiple group pairs. This example maps significance levels and adjusts step increase and top margin for clarity.

```r
geom_signif(
  comparisons = list(
    c("Group A", "Group B"),
    c("Group B", "Group C")
  ),
  map_signif_level = TRUE,
  step_increase = 0.1,
  margin_top = 0.1
)
```

--------------------------------

### Handling Test Function Failures in geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

Provides examples of scenarios that can cause test functions to fail, such as insufficient data, incorrect data types, or unstable parameters.

```R
# Too few observations for test
geom_signif(
  comparisons = list(c("A", "B")),
  test = "t.test"
  # data with single observation per group
)
```

```R
# Invalid data types
geom_signif(
  comparisons = list(c("A", "B")),
  test = "fisher.test"
  # using continuous data (needs binary counts)
)
```

```R
# Unstable test parameters
geom_signif(
  comparisons = list(c("A", "B")),
  test = "wilcox.test",
  test.args = list(exact = TRUE)
  # with data containing ties (breaks exact test)
)
```

--------------------------------

### Publication-Quality Figure with geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Configure geom_signif for publication-ready figures. This example specifies comparisons, uses a t-test with equal variances assumed, maps significance levels to symbols, and adjusts text size, line thickness, vertical justification, top margin, and tip length.

```r
geom_signif(
  comparisons = list(c("Control", "Treatment")),
  test = "t.test",
  test.args = list(var.equal = TRUE),
  map_signif_level = TRUE,
  textsize = 4,
  size = 0.7,
  vjust = -0.2,
  margin_top = 0.08,
  tip_length = 0.02
)
```

--------------------------------

### Dodged Grouping with geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Configure geom_signif for dodged groupings, specifying manual x-axis limits and y-position. This example also customizes tip lengths for different comparisons.

```r
geom_signif(
  comparisons = list(c("Male", "Female")),
  y_position = 50,
  xmin = 2.2,
  xmax = 2.8,
  tip_length = c(0.15, 0.05)
)
```

--------------------------------

### Ensure Required Columns for Manual Mode in ggsignif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

When using manual mode with aesthetic mappings in ggsignif, ensure that all mapped columns (e.g., 'start', 'end', 'y_pos', 'label') exist in the provided data frame.

```r
# Ensure data has all mapped columns
annotation_df <- data.frame(
  start = c("A", "B"),      # maps to xmin
  end = c("B", "C"),        # maps to xmax
  y_pos = c(10, 15),        # maps to y_position
  label = c("*", "**")      # maps to annotations
)

geom_signif(
  data = annotation_df,
  mapping = aes(
    xmin = start,
    xmax = end,
    y_position = y_pos,
    annotations = label
  ),
  manual = TRUE
)
```

--------------------------------

### Control Significance Bracket Orientation

Source: https://github.com/const-ae/ggsignif/blob/main/README.md

Demonstrates controlling the orientation of significance brackets using the 'orientation' argument in geom_signif. This example plots significance brackets along the y-axis.

```r
p2 <- ggplot(
  data = mpg,
  mapping = aes(
    x = hwy,
    y = class
  )
) + 
  geom_boxplot(
    orientation = "y"
  ) + 
  geom_signif(
    comparisons = list(
      c("compact", "midsize"),
      c("minivan", "suv")
    ),
    map_signif_level = TRUE,
    textsize = 6,
    margin_top = 0.08,
    step_increase = 0.05,
    tip_length = 0.01,
    orientation = "y"
  )
p2
```

--------------------------------

### Manual Mode Data Structure

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

When 'manual = TRUE', a data frame must be provided with specific columns for start, end, y-position, and annotations. This enables per-facet annotations.

```R
annotation_df <- data.frame(
  start = c("A", "B"),        # xmin column (or named xmin)
  end = c("B", "C"),          # xmax column (or named xmax)
  y = c(10, 12),              # y_position column (or named y_position)
  label = c("*", "**")        # annotations column (or named annotations)
)

geom_signif(
  data = annotation_df,
  mapping = aes(
    xmin = start,
    xmax = end,
    y_position = y,
    annotations = label
  ),
  manual = TRUE
)
```

--------------------------------

### StatSignif Definition

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Defines the StatSignif ggproto class, which performs statistical tests to determine significance levels and computes positions for significance brackets. It specifies required aesthetics and methods for parameter setup and computation.

```R
StatSignif <- ggplot2::ggproto(
  "StatSignif",
  ggplot2::Stat,
  required_aes = c("x", "y", "group"),
  extra_params = c("na.rm", "orientation"),
  setup_params = function(data, params) { ... },
  compute_group = function(...) { ... }
)
```

--------------------------------

### R Package File Structure

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/README.md

This illustrates the typical file structure of the ggsignif R package, including directories for API reference, configuration, types, and errors.

```bash
output/
├── README.md                          (this file)
├── api-reference/
│   ├── geom_signif.md                (main layer function)
│   └── stat_signif.md                (statistical transformation)
├── configuration.md                   (parameter reference)
├── types.md                          (data structures)
└── errors.md                         (error conditions)
```

--------------------------------

### Aesthetic Mapping: Using 'mapping' Argument

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Alternatively, specify aesthetic mappings using the 'mapping' argument, which accepts an 'aes()' call. This provides an alternative syntax for setting aesthetics.

```R
geom_signif(
  comparisons = list(c("A", "B")),
  mapping = aes(color = "red")
)
```

--------------------------------

### StatSignif Manual Mode

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/stat_signif.md

Explains and demonstrates the manual mode of stat_signif, where users provide all positioning and annotation data directly.

```APIDOC
## stat_signif() Manual Mode

### Description
In manual mode, `stat_signif` allows users to explicitly define the x-range (`xmin`, `xmax`), y-position (`y_position`), and the significance label (`annotations`) for each bracket. This is useful for precise control or when automatic testing is not desired.

### Method
stat_signif()

### Parameters
- **manual** (logical) - Set to `TRUE` to enable manual mode.
- **data** (data.frame) - A data frame containing the manual annotation information.
- **aes(xmin, xmax, y_position, annotations)** - Mappings within the `aes()` call to link columns from the `data` data frame to the bracket aesthetics.

### Request Example
```r
# Define data for manual annotations
annotation_data <- data.frame(
  manufacturer = c("audi", "ford"),
  y_pos = c(5.5, 6.0),
  x_min = c(1, 2),
  x_max = c(2, 3),
  label = c("p<0.001", "p=0.02")
)

ggplot(mpg, aes(x = manufacturer, y = displ)) +
  geom_boxplot() +
  stat_signif(
    data = annotation_data,
    aes(xmin = x_min, xmax = x_max, y_position = y_pos, annotations = label),
    manual = TRUE
  )
```
```

--------------------------------

### Error: Combining Manual and Automatic Comparisons

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

It is an error to use both 'comparisons' and manual 'xmin'/'xmax' arguments simultaneously. Ensure only one method is used.

```R
geom_signif(
  comparisons = list(c("A", "B")),
  xmin = 1, xmax = 2  # ERROR!
)
```

--------------------------------

### Comparison Vector Usage in 'comparisons' Parameter

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Shows how to structure a list of comparison vectors for the 'comparisons' parameter.

```R
comparisons = list(
  c("compact", "midsize"),       # First comparison
  c("midsize", "suv"),           # Second comparison
  c("compact", "suv")            # Third comparison
)
```

--------------------------------

### test.args Parameter

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Provides a list of arguments to be passed to the specified test function. This allows customization of test parameters like 'alternative', 'var.equal', or 'paired'.

```R
# Named list of arguments
test.args = list(
  alternative = "two.sided",
  var.equal = TRUE,
  paired = FALSE
)

# Passed via do.call(test, c(list(x, y), test.args))
```

--------------------------------

### GeomSignif Definition

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Defines the GeomSignif ggproto class, which is responsible for drawing significance brackets and annotation text. It specifies required and default aesthetics, along with methods for parameter setup and drawing.

```R
GeomSignif <- ggplot2::ggproto(
  "GeomSignif",
  ggplot2::Geom,
  required_aes = c("x", "xend", "y", "yend", "annotation"),
  default_aes = ggplot2::aes(
    shape = 19,
    colour = "black",
    textsize = 3.88,
    angle = 0,
    hjust = 0.5,
    vjust = 0,
    alpha = NA,
    family = "",
    fontface = 1,
    lineheight = 1.2,
    linetype = 1,
    size = 0.5
  ),
  extra_params = c("na.rm", "orientation"),
  setup_params = function(data, params) { ... },
  draw_key = function(...) { ... },
  draw_group = function(...) { ... }
)
```

--------------------------------

### Error: Data Grouping Violation

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

This error occurs when data has non-default grouping and the grouped variable is not on the x-axis. The example shows incorrect global grouping with `geom_signif` and the correct approach using per-geom grouping.

```R
# WRONG: global grouping
ggplot(mtcars, aes(am, mpg, color = factor(cyl))) +
  geom_boxplot() +
  geom_signif(comparisons = list(c(0, 1)))

# CORRECT: per-geom grouping
ggplot(mtcars, aes(am, mpg)) +
  geom_boxplot(aes(fill = factor(cyl))) +
  geom_signif(comparisons = list(c(0, 1)))
```

--------------------------------

### Correct Facetting Usage with geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

Illustrates the correct way to use geom_signif with faceting, ensuring that comparisons are valid within each facet.

```R
# WRONG: Group "X" doesn't exist in facet 2
ggplot(df, aes(x = group, y = value)) +
  geom_boxplot() +
  geom_signif(comparisons = list(c("X", "Y"))) +
  facet_wrap(~facet_var)  # facet 2 may not have group X
```

--------------------------------

### Specifying Test Functions in geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

Illustrates how to correctly specify test functions, including using standard test names as strings or providing custom function objects.

```R
# CORRECT: use standard test
geom_signif(
  comparisons = list(c("A", "B")),
  test = "t.test"
)
```

```R
# CORRECT: define and use custom test
my_test <- function(x, y) list(p.value = 0.05)
geom_signif(
  comparisons = list(c("A", "B")),
  test = my_test
)
```

--------------------------------

### Specify Comparisons with Manual xmin/xmax

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Alternatively, provide manual x-coordinates (xmin, xmax) and y-positions for the significance brackets. This offers precise control over placement.

```R
geom_signif(
  xmin = c(1, 2),
  xmax = c(2, 3),
  y_position = c(10, 12)
)
```

--------------------------------

### Using Annotation Data Frame with geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Demonstrates how to pass a custom annotation data frame to geom_signif using manual = TRUE and aes mapping.

```R
geom_signif(
  data = annotation_df,
  mapping = aes(
    xmin = start,
    xmax = end,
    y_position = y,
    annotations = label
  ),
  manual = TRUE
)
```

--------------------------------

### Error: Conflicting Comparison Specifications

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

You must specify either `comparisons` or `xmin`/`xmax`, but not both. This snippet illustrates the conflict and the correct usage of each method.

```R
# WRONG: specifying both
geom_signif(
  comparisons = list(c("A", "B")),
  xmin = 1, xmax = 2
)

# CORRECT: use one or the other
geom_signif(comparisons = list(c("A", "B")))
# OR
geom_signif(xmin = 1, xmax = 2, y_position = 10)
```

--------------------------------

### Manual Mode with Explicit Facet Specifications

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

Use manual mode with explicit per-facet specifications for annotations. Ensure the annotation data frame includes a facet variable to map annotations to specific facets.

```r
annotation_df <- data.frame(
  facet_var = c("facet_1", "facet_2"),
  start = c("X", "Y"),
  end = c("Y", "Z"),
  y = c(10, 15),
  label = c("*", "**")
)

ggplot(df, aes(x = group, y = value)) +
  geom_boxplot() +
  geom_signif(
    data = annotation_df,
    aes(xmin = start, xmax = end, y_position = y, annotations = label),
    manual = TRUE
  ) +
  facet_wrap(~facet_var)
```

--------------------------------

### Tip Length: Per Comparison

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Provide a vector of 'tip_length' values, one for each comparison, to control tip lengths individually per pair. This allows for varied visual emphasis.

```R
geom_signif(comparisons = list(c("A", "B"), c("B", "C")), tip_length = c(0.02, 0.04))
```

--------------------------------

### Manual Mode with Custom Data Frame

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/stat_signif.md

Demonstrates manual mode for stat_signif, where significance brackets and labels are provided directly via a data frame. This is useful for per-facet control or when pre-computed significance values are available.

```r
# Manual mode for custom per-facet control
annotation_data <- data.frame(
  manufacturer = c("audi", "ford"),
  y_pos = c(5.5, 6.0),
  x_min = c(1, 2),
  x_max = c(2, 3),
  label = c("p<0.001", "p=0.02")
)

ggplot(mpg, aes(x = manufacturer, y = displ)) +
  geom_boxplot() +
  stat_signif(
    data = annotation_data,
    aes(xmin = x_min, xmax = x_max, y_position = y_pos, annotations = label),
    manual = TRUE
  )
```

--------------------------------

### Handling Data and Mapping in geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

Shows correct usage when providing custom data and mappings, either by removing them or setting manual = TRUE.

```R
# Either remove data/mapping (auto-test from plot data):
geom_signif(comparisons = list(c("A", "B")))
```

```R
# Or use manual = TRUE (provide explicit annotations):
geom_signif(
  data = custom_df,
  mapping = aes(...),
  manual = TRUE
)
```

--------------------------------

### P-value Mapping: Standard Asterisks

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Setting 'map_signif_level = TRUE' maps p-values to standard asterisk notation: p < 0.001 → "***", p < 0.01 → "**", p < 0.05 → "*".

```R
geom_signif(comparisons = list(c("A", "B")), map_signif_level = TRUE)
```

--------------------------------

### Add Significance Brackets for Exploratory Analysis

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/README.md

This snippet is suitable for exploratory analysis, allowing for custom comparisons and step increases between significance levels.

```r
geom_signif(
  comparisons = list(...),
  map_signif_level = TRUE,
  step_increase = 0.1,
  margin_top = 0.1
)
```

--------------------------------

### Manual Significance Bar Placement

Source: https://github.com/const-ae/ggsignif/blob/main/README.md

Use this snippet when you need precise control over the location of significance bars, especially with `facet_wrap` or `facet_grid`. Set `manual=TRUE` and provide annotations as a data frame.

```r
annotation_df <- data.frame(
  color = c("E", "H"),
  start = c("Good", "Fair"),
  end = c("Very Good", "Good"),
  y = c(3.6, 4.7),
  label = c("Comp. 1", "Comp. 2")
)

annotation_df

ggplot(diamonds, aes(x = cut, y = carat)) +
  geom_boxplot() +
  geom_signif(
    data = annotation_df,
    aes(xmin = start, xmax = end, annotations = label, y_position = y),
    textsize = 3, vjust = -0.2,
    manual = TRUE
  ) +
  facet_wrap(~color) +
  ylim(NA, 5.3)
```

--------------------------------

### Aesthetic Mapping: Color Override

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Override default aesthetic mappings, such as setting bracket color directly using 'color' within 'aes()'. Note that 'size' is a parameter, not an aesthetic.

```R
geom_signif(
  comparisons = list(c("A", "B")),
  aes(color = "red"),           # bracket color
  size = 1                        # line width (parameter, not aes)
)
```

--------------------------------

### Tip Length: Per Side (Left/Right)

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Specify 'tip_length' as a vector with two values per comparison (left tip, right tip) for asymmetrical bracket styling. This offers fine-grained control over bracket appearance.

```R
geom_signif(comparisons = list(c("A", "B"), c("B", "C")),
            tip_length = c(0.02, 0.04, 0.03, 0.05))
```

--------------------------------

### StatSignif Output Data Frame Structure

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Illustrates the structure of the data frame produced by StatSignif, containing coordinates for significance brackets and annotation information.

```R
data.frame(
  x = numeric,           # Left tip x position
  xend = numeric,        # Right tip x position
  y = numeric,           # Left tip y position
  yend = numeric,        # Right tip y position
  annotation = character, # p-value or custom label
  group = character,     # Comparison identifier
  flipped_aes = logical  # Coordinate system orientation
)
```

--------------------------------

### Accessing Plot Data

Source: https://github.com/const-ae/ggsignif/blob/main/tests/testthat/_snaps/geom_signific_strict.md

Demonstrates how to access the underlying data of a plot object created with ggsignif. This is useful for inspecting the generated data before plotting.

```r
pb$data
```

--------------------------------

### Correct map_signif_level Specification

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

Demonstrates the correct way to specify significance levels using named numeric vectors. Automatic naming is supported for two or fewer elements.

```R
# CORRECT: named numeric vector
geom_signif(
  comparisons = list(c("A", "B")),
  map_signif_level = c("***" = 0.001, "**" = 0.01, "*" = 0.05)
)
```

```R
# CORRECT: automatic naming for ≤3 elements
geom_signif(
  comparisons = list(c("A", "B")),
  map_signif_level = c(0.01, 0.05)  # Auto-named "**", "*"
)
```

--------------------------------

### geom_signif Parameters

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/geom_signif.md

This section outlines the various parameters that can be used to customize the geom_signif layer, including data mapping, statistical tests, annotation styles, and positioning.

```APIDOC
## geom_signif Parameters

This section outlines the various parameters that can be used to customize the geom_signif layer, including data mapping, statistical tests, annotation styles, and positioning.

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| mapping | aes mapping or NULL | NULL | Set of aesthetic mappings created by `aes()`. If specified and `inherit.aes = TRUE` (the default), it is combined with the default mapping at the top level of the plot. |
| data | data.frame or NULL | NULL | The data to be displayed in this layer. If `NULL`, the default, the data is inherited from the plot data. A data.frame will override the plot data. A function will be called with the plot data and must return a data.frame. |
| stat | string or Stat ggproto | "signif" | The statistical transformation to use on the data for this layer. Use "signif" (default) for automatic significance testing. |
| position | string or function | "identity" | A position adjustment to use on the data for this layer. Examples: "jitter", "dodge", "identity". |
| na.rm | logical | FALSE | If `FALSE` (the default), removes missing values with a warning. If `TRUE` silently removes missing values. |
| show.legend | logical or named logical vector | NA | Should this layer be included in the legends? `NA` (default) includes if any aesthetics are mapped. `FALSE` never includes, `TRUE` always includes. |
| inherit.aes | logical | TRUE | If `FALSE`, overrides the default aesthetics rather than combining with them. |
| comparisons | list of length-2 vectors | NULL | A list of length-2 vectors where each vector contains either the names of 2 values on the x-axis or the 2 integers corresponding to the index of the columns of interest. Example: `list(c("group1", "group2"), c("group2", "group3"))`. Cannot be used together with `xmin`/`xmax`. |
| test | string or function | "wilcox.test" | The name of the statistical test applied to the 2 groups (e.g., `"t.test"`, `"wilcox.test"`). The test function must return a list with an entry called `p.value`. Can be a function object or a string. |
| test.args | list | NULL | Additional arguments passed to the test method as a list. Example: `list(alternative = "two.sided")`. |
| annotations | character vector | NULL | Character vector with alternative annotations. If provided, the test is ignored and these annotations are used directly. Length must match comparisons or xmin count. |
| map_signif_level | logical, numeric vector, or function | FALSE | Controls how p-values are mapped to annotations. If `FALSE` (default), p-values are written as numbers. If `TRUE`, uses default mapping `c("***" = 0.001, "**" = 0.01, "*" = 0.05)`. If a named numeric vector, provides custom mappings. If a function, takes p-value and returns annotation string. |
| y_position | numeric vector | NULL | Numeric vector with the y positions of the brackets. If `NULL`, automatically calculated based on the data range. If length 1, is recycled for all comparisons. |
| xmin | numeric vector or character | NULL | Numeric vector (or character for factor levels) with the positions of the left sides of brackets. Must be used together with `xmax` and `y_position`. Cannot be used with `comparisons`. |
| xmax | numeric vector or character | NULL | Numeric vector (or character for factor levels) with the positions of the right sides of brackets. Must be used together with `xmin` and `y_position`. Cannot be used with `comparisons`. |
| margin_top | numeric vector | 0.05 | Numeric vector indicating how much higher than the maximum data value the brackets start, as a fraction of total height. If length 1, recycled for all comparisons. |
| step_increase | numeric vector | 0 | Numeric vector with the increase in fraction of total height for every additional comparison to minimize overlap. If length 1, recycled for all comparisons. |
| extend_line | numeric | 0 | Numeric that allows to shorten (negative values) or extend (positive values) the horizontal line between groups for each comparison. Defaults to 0 (no extension). |
| tip_length | numeric vector | 0.03 | Numeric vector with the fraction of total height that the bracket tips extend down to indicate the precise columns. If length 1, recycled for all comparisons (internally doubled to cover left and right tips). |
| size | numeric | 0.5 | Width of the bracket lines in points. |
| textsize | numeric | 3.88 | Size of the annotation text in points. |
| family | character | "" | Font family used for the annotation text. Empty string uses default. |
| vjust | numeric | 0 | Vertical justification of the annotation text relative to the bracket. |
| parse | logical | FALSE | If `TRUE`, the annotation labels will be parsed into expressions and displayed as described in `?plotmath`. Used for mathematical notation. |
| manual | logical | FALSE | Boolean flag indicating that parameters are provided via a data.frame (for per-facet annotations). If `TRUE`, `data` and `mapping` must be provided with columns `annotations`, `y_position`, `xmin`, and `xmax`. |

```

--------------------------------

### StatSignif with Faceted Data

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/stat_signif.md

Illustrates how stat_signif can be used with faceted plots, automatically calculating comparisons within each facet.

```APIDOC
## stat_signif() with Facets

### Description
This example shows how `stat_signif` integrates with `facet_wrap` to perform significance tests and display results independently for each facet.

### Method
stat_signif()

### Parameters
(See Basic Usage for general parameters. Specific parameters for faceted use are handled automatically by ggplot2's faceting mechanism.)

### Request Example
```r
ggplot(mpg, aes(x = manufacturer, y = displ)) +
  geom_boxplot() +
  stat_signif(
    comparisons = list(c("audi", "ford"), c("hyundai", "nissan")),
    map_signif_level = TRUE,
    test = "wilcox.test",
    test.args = list(alternative = "two.sided"),
    margin_top = 0.02,
    step_increase = 0,
    tip_length = 0.01
  ) +
  facet_wrap(~year)
```
```

--------------------------------

### StatSignif Basic Usage

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/stat_signif.md

Demonstrates the basic usage of stat_signif to add significance brackets between specified comparisons on a boxplot. It maps significance levels automatically.

```APIDOC
## stat_signif()

### Description
Adds significance brackets and labels to a plot, typically used with geom_boxplot or other geoms that display group comparisons. It can automatically perform statistical tests and map p-values to significance levels.

### Method
stat_signif()

### Parameters
#### Aesthetics (Required)
- **x** (factor or numeric) - Grouping variable for the x-axis.
- **y** (numeric) - Response variable.
- **group** (variable) - Grouping identifier, typically same as x.

#### Parameters
- **comparisons** (list of vectors) - Specifies pairs of groups to compare. Example: `list(c("group1", "group2"))`.
- **map_signif_level** (logical or function) - If TRUE, maps p-values to standard significance symbols. Can also be a custom function.
- **test** (character or function) - The statistical test to perform (e.g., "wilcox.test", "t.test").
- **test.args** (list) - Additional arguments to pass to the statistical test function.
- **margin_top** (numeric) - Adds margin above the significance bracket.
- **step_increase** (numeric) - Controls the vertical step increase for multiple brackets.
- **tip_length** (numeric) - Length of the tips on the significance brackets.
- **xmin**, **xmax** (numeric) - Manual specification of bracket x-range (used with `manual = TRUE`).
- **y_position** (numeric) - Manual specification of bracket y-position (used with `manual = TRUE`).
- **annotations** (character) - Manual specification of significance labels (used with `manual = TRUE`).
- **manual** (logical) - If TRUE, uses provided `xmin`, `xmax`, `y_position`, and `annotations`.
- **na.rm** (logical) - If TRUE, silently removes missing values.

### Request Example
```r
library(ggplot2)
library(ggsignif)

ggplot(mpg, aes(class, hwy)) +
  geom_boxplot() +
  stat_signif(
    comparisons = list(c("compact", "pickup")),
    map_signif_level = TRUE,
    test = "wilcox.test"
  )
```

### Response
Computed variables passed to the geom:
- **x**: Left x position of bracket segment.
- **xend**: Right x position of bracket segment.
- **y**: Y position of left tip or middle horizontal line.
- **yend**: Y position of right tip or middle horizontal line.
- **annotation**: Computed or provided significance label.
- **group**: Grouping identifier for each comparison.
```

--------------------------------

### Basic StatSignif Usage

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/stat_signif.md

Demonstrates the basic usage of stat_signif to add significance brackets between two specified groups using a default boxplot. Requires ggplot2 and ggsignif libraries.

```r
library(ggplot2)
library(ggsignif)

# Use stat_signif directly (geom_signif uses this internally)
ggplot(mpg, aes(class, hwy)) +
  geom_boxplot() +
  stat_signif(
    comparisons = list(c("compact", "pickup")),
    map_signif_level = TRUE,
    test = "wilcox.test"
  )
```

--------------------------------

### Basic Comparison with geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/README.md

Add a simple significance bracket between two groups using geom_signif with automatic comparisons and asterisk mapping.

```r
library(ggplot2)
library(ggsignif)

ggplot(mtcars, aes(am, mpg)) +
  geom_boxplot() +
  geom_signif(comparisons = list(c(0, 1)), map_signif_level = TRUE)
```

--------------------------------

### ggplot2 Layer Object Creation

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Shows how GeomSignif and StatSignif are integrated into a ggplot2 pipeline by creating a layer object. This demonstrates how to add significance geoms/stats to an existing ggplot.

```R
# Returned from geom_signif() / stat_signif()
layer_object <- ggplot2::layer(
  stat = StatSignif,
  geom = GeomSignif,
  mapping = mapping,
  data = data,
  position = position,
  show.legend = show.legend,
  inherit.aes = inherit.aes,
  params = list(...)  # All named parameters
)

# Used in ggplot pipeline
p <- ggplot(data, aes(x, y)) +
  geom_boxplot() +
  layer_object  # Can use layer directly
```

--------------------------------

### StatSignif with Faceted Data

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/stat_signif.md

Shows how stat_signif can be used with faceted plots, automatically calculating significance for comparisons within each facet. Includes customization of test arguments, margin, and tip length.

```r
# stat_signif works with facet_wrap
ggplot(mpg, aes(x = manufacturer, y = displ)) +
  geom_boxplot() +
  stat_signif(
    comparisons = list(c("audi", "ford"), c("hyundai", "nissan")),
    map_signif_level = TRUE,
    test = "wilcox.test",
    test.args = list(alternative = "two.sided"),
    margin_top = 0.02,
    step_increase = 0,
    tip_length = 0.01
  ) +
  facet_wrap(~year)
```

--------------------------------

### Error: Missing Required Arguments in Manual Mode

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

When manual mode is enabled (`manual = TRUE`), both `data` and `mapping` parameters must be provided. This snippet shows the incorrect and correct ways to call `geom_signif` in this scenario.

```R
# WRONG: manual=TRUE without data
geom_signif(manual = TRUE, comparisons = list(c("A", "B")))

# CORRECT: provide both data and mapping
geom_signif(
  data = annotation_df,
  mapping = aes(xmin = start, xmax = end, ...),
  manual = TRUE
)
```

--------------------------------

### Custom Comparison with T-test and Custom P-value Mapping

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/stat_signif.md

Illustrates using a different statistical test (t-test) with custom arguments and a user-defined function to map p-values to significance level symbols. This provides fine-grained control over significance reporting.

```r
# Using different statistical test with arguments
ggplot(iris, aes(Species, Sepal.Width)) +
  geom_boxplot() +
  stat_signif(
    comparisons = list(
      c("versicolor", "virginica"),
      c("setosa", "virginica")
    ),
    test = "t.test",
    test.args = list(var.equal = TRUE),
    map_signif_level = function(p) {
      if (p < 0.001) "***"
      else if (p < 0.01) "**"
      else if (p < 0.05) "*"
      else "NS"
    }
  )
```

--------------------------------

### test Parameter: String Function Name

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Specifies the statistical test to use by providing its function name as a string. The function must be resolvable via match.fun().

```R
test = "t.test"      # Must be function name as string
test = "wilcox.test"
test = "ks.test"
# Resolved via match.fun()
```

--------------------------------

### Tip Length: Single Value

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Set a single 'tip_length' value to apply the same length to all significance bracket tips. This provides a uniform appearance.

```R
geom_signif(comparisons = list(c("A", "B"), c("B", "C")), tip_length = 0.03)
```

--------------------------------

### Annotation Data Frame Structure (Manual Mode)

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Defines the required structure for a data frame used in manual mode, including position and annotation columns.

```R
annotation_df <- data.frame(
  # Required columns (names must match aes mapping)
  xmin = numeric_or_character_vector,         # Left bracket position
  xmax = numeric_or_character_vector,         # Right bracket position
  y_position = numeric_vector,                # Bracket y position
  annotations = character_vector,             # Annotation text labels
  
  # Optional columns (for faceting)
  facet_var = factor_vector                   # Facet grouping column(s)
)
```

--------------------------------

### Faceted Plot with Manual Annotations using geom_signif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

This snippet demonstrates how to use geom_signif with faceted plots and manual annotations. It requires a data frame with annotation details and sets `manual = TRUE` to use the provided data for significance markers.

```r
annotation_df <- data.frame(
  facet_var = rep(c("A", "B"), each = 1),
  group1 = c("X", "Y"),
  group2 = c("Y", "Z"),
  y_pos = c(100, 150),
  sig = c("***", "*")
)

geom_signif(
  data = annotation_df,
  aes(xmin = group1, xmax = group2, y_position = y_pos, annotations = sig),
  manual = TRUE
)
```

--------------------------------

### Error: Missing y_position with xmin/xmax

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

If `xmin` and `xmax` are defined, `y_position` must also be specified. This snippet shows the incorrect call missing `y_position` and the correct call including it.

```R
# WRONG: missing y_position
geom_signif(
  xmin = c(1, 2),
  xmax = c(2, 3)
)

# CORRECT: provide y_position
geom_signif(
  xmin = c(1, 2),
  xmax = c(2, 3),
  y_position = c(10, 12)
)
```

--------------------------------

### Specify Comparisons with Automatic Testing

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/configuration.md

Use the 'comparisons' argument to specify pairs of groups for significance testing. This method relies on automatic testing.

```R
geom_signif(comparisons = list(c("A", "B"), c("B", "C")))
```

--------------------------------

### map_signif_level Parameter: TRUE

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

When map_signif_level is set to TRUE, p-values are automatically mapped to significance stars based on default thresholds.

```R
map_signif_level = TRUE
# Auto-converts to: c("***" = 0.001, "**" = 0.01, "*" = 0.05)
```

--------------------------------

### Significance Brackets with Facetting

Source: https://github.com/const-ae/ggsignif/blob/main/README.md

Demonstrates the compatibility of ggsignif with facetting (facet_wrap or facet_grid). Significance labels are calculated per facet, provided the data is not globally grouped by aesthetic mappings like color or fill.

```r
ggplot(diamonds, aes(x = cut, y = carat)) +
  geom_boxplot(aes(fill = color)) +
  geom_signif(comparisons = list(
    c("Fair", "Good"),
    c("Very Good", "Ideal")
  )) +
  facet_wrap(~color) +
  ylim(NA, 6.3)
```

--------------------------------

### Add Significance Brackets for Publication

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/README.md

Use this snippet for publication-quality figures. It specifies comparisons, the statistical test, and maps significance levels.

```r
geom_signif(
  comparisons = list(c("Control", "Treatment")),
  test = "t.test",
  map_signif_level = TRUE,
  textsize = 4,
  size = 0.8,
  vjust = -0.2,
  margin_top = 0.08,
  tip_length = 0.02
)
```

--------------------------------

### Custom Test Function Returning p.value

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

Ensures custom test functions return a list containing the 'p.value' element to avoid 'subscript out of bounds' errors.

```R
# CORRECT: include p.value in returned list
good_test <- function(x, y) {
  result <- t.test(x, y)
  list(p.value = result$p.value)
}

geom_signif(
  comparisons = list(c("A", "B")),
  test = good_test
)
```

--------------------------------

### test Parameter: Function Object

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

Allows direct use of a function object for statistical testing. Custom functions must accept two positional arguments and return a list containing a 'p.value' element.

```R
test = t.test       # Function object directly
test = function(x, y) list(p.value = 0.05)  # Custom function
# Must accept 2 positional arguments, return list with p.value
```

--------------------------------

### StatSignif Layer Parameters

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/api-reference/stat_signif.md

This section details the parameters available for the `stat_signif` function, which is used to add statistical significance annotations to ggplot2 plots. These parameters control data mapping, statistical tests, annotation display, and visual aesthetics.

```APIDOC
## Parameters

This section details the parameters available for the `stat_signif` function, which is used to add statistical significance annotations to ggplot2 plots. These parameters control data mapping, statistical tests, annotation display, and visual aesthetics.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `mapping` | `aes` mapping or `NULL` | `NULL` | Set of aesthetic mappings created by `aes()`. If specified and `inherit.aes = TRUE` (the default), it is combined with the default mapping at the top level of the plot. |
| `data` | `data.frame` or `NULL` | `NULL` | The data to be displayed in this layer. If `NULL`, the default, the data is inherited from the plot data. A data.frame will override the plot data. A function will be called with the plot data and must return a data.frame. |
| `position` | `string` or `function` | `
```

--------------------------------

### Explicitly Specify Orientation in ggsignif

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/errors.md

When auto-detection of bracket orientation fails, especially with non-standard coordinate systems, explicitly set the 'orientation' parameter to 'x' or 'y'.

```r
# Specify orientation explicitly
geom_signif(
  comparisons = list(c("A", "B")),
  orientation = "x"  # or "y" for horizontal
)
```

--------------------------------

### map_signif_level Parameter: FALSE

Source: https://github.com/const-ae/ggsignif/blob/main/_autodocs/types.md

When map_signif_level is set to FALSE, p-values are displayed as formatted numeric strings.

```R
map_signif_level = FALSE
# Output: "0.012", "0.0042", etc. (formatted p-values)
```