---
title: "Statistical Testing"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Statistical Testing}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    eval = FALSE
)
```

The **BoxPlot**, **ViolinPlot**, and **yPlot** modules include a **Stats** tab that adds pairwise statistical test results as bracket annotations directly on the plotly figure. The same helpers are exported so you can add bracket annotations to any custom plotly figure.

## Using the Stats tab

Enable testing from the Stats tab in any supported module app:

```{r stats-app}
library(VizModules)
plotthis_BoxPlotApp()
```

The Stats tab exposes these controls:

| Control | Default | Description |
|---------|---------|-------------|
| Enable Stats | OFF | Master toggle |
| Test | Wilcoxon | `wilcox.test`, `t.test`, `kruskal.test`, or `anova` |
| P-value Adjustment | holm | Any `p.adjust` method |
| Display | Adjusted P-value | `p.adj`, `p.value`, or `symbol` (`*`/`**`/`***`/`****`) |
| Significance Threshold | 0.05 | Boundary for `*` vs `ns` |
| Hide Non-Significant | OFF | Suppress `ns` brackets |
| Paired Test | OFF | Paired Wilcoxon or paired t-test |
| Comparisons | (all pairs) | Restrict to specific pairs |
| Bracket Style | Capped | `capped` (ticked) or `flat` |
| Bracket Spacing / Text Offset / Bracket Inset | — | Fine layout control (fractions of y-range) |
| Per Facet Panel | ON | Test independently per facet, or across the full dataset |

### Supported tests

- **Pairwise**: Wilcoxon rank-sum, t-test (paired or unpaired) — draw a bracket per pair.
- **Omnibus**: Kruskal-Wallis, ANOVA — draw a single draggable text annotation with the overall p-value.

### Paired tests

When **Paired Test** is enabled, each group must have the same number of observations, sorted so paired samples align row-by-row within each group.

### Downloading statistics

The **Download Summary** button (Source Data, at the bottom of the controls panel) includes a statistics CSV with a metadata header (correction method, threshold, symbol legend) alongside the plot HTML and source data.

## Using the stat helpers in a custom module

The pipeline is fully exported:

1. `compute_pairwise_stats()` — run the tests, return a data frame.
2. `create_stat_annotations()` — convert results to plotly shapes and annotations.
3. `apply_stat_annotations()` — append them to a plotly figure.

```{r stat-helpers-basic}
library(VizModules)
library(ggplot2)
library(plotly)

stats_df <- compute_pairwise_stats(
    df   = example_iris,
    x    = "Species",
    y    = "Sepal.Length",
    test = "wilcox.test",
    p.adjust.method = "holm"
)

# Build the figure with ggplot2 + ggplotly(), matching how the plot modules
# construct their figures. This matters for bracket placement: ggplotly()
# categorical axes are 1-based (the first factor level sits at x = 1), which
# is the convention create_stat_annotations() expects.
p <- ggplot(example_iris, aes(x = Species, y = Sepal.Length)) +
    geom_boxplot()
fig <- ggplotly(p)

stat_result <- create_stat_annotations(
    stats_df = stats_df,
    fig      = fig,
    df       = example_iris,
    x        = "Species",
    y        = "Sepal.Length",
    display  = "symbol"
)

apply_stat_annotations(fig, stat_result)
```

> **Axis coordinates.** `create_stat_annotations()` positions brackets using
> 1-based categorical x-coordinates, matching figures built with `ggplotly()`
> (as every VizModules plot module does). If you build the figure with a raw
> `plot_ly(type = "box")` call instead, plotly uses 0-based category positions
> and the brackets will appear shifted one category to the right — prefer
> `ggplotly()` for a `ggplot` object to stay consistent with the modules.

### Restricting comparisons

By default all pairwise combinations are tested. Pass a list of length-2 character vectors to `pairs`, or convert to/from the UI's `"A vs B"` strings with `generate_pair_strings()` / `parse_pair_strings()`:

```{r pairs}
choices <- generate_pair_strings(example_iris, x = "Species")
pairs   <- parse_pair_strings(choices[1:2])

stats_df <- compute_pairwise_stats(
    df    = example_iris,
    x     = "Species",
    y     = "Sepal.Length",
    test  = "wilcox.test",
    pairs = pairs
)
```

### Faceted plots and nested grouping

Pass `facet.by` with `per.facet = TRUE` to test independently within each panel, or `group.by` to compare group levels within each x category:

```{r faceted}
compute_pairwise_stats(
    df        = example_rnaseq,
    x         = "condition",
    y         = "expression",
    test      = "wilcox.test",
    facet.by  = "gene",
    per.facet = TRUE
)
```

Pass the same `facet.by`/`group.by` values to `create_stat_annotations()` so brackets land on the correct subplot axes.

### `compute_pairwise_stats()` return value

| Column | Description |
|--------|-------------|
| `group1`, `group2` | Groups compared (`"all"` for omnibus) |
| `p.value`, `p.adj` | Raw and adjusted p-values |
| `p.signif` | Significance symbol (`ns`, `*`, `**`, `***`, `****`) |
| `test` | Test name |
| `facet_level`, `x_level` | Facet panel / nested x level (NA when not applicable) |