---
title: "Likelihood-Based Evidence Ratios for Classical Statistical Tests"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Likelihood-Based Evidence Ratios for Classical Statistical Tests}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
library(evidenceratio)
library(ggplot2)

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6,
  fig.height = 4
)
```

## Overview

Clinical studies routinely analyse heterogeneous endpoints using different statistical models. Continuous outcomes, binary endpoints, and regression based associations are typically summarised using different reporting conventions, which complicates interpretation and comparison across endpoints and studies.

The `evidenceratio` package provides a unified reporting framework. Each analysis reports three quantities derived from a single likelihood based model:

* an effect estimate
* a corresponding uncertainty interval
* a likelihood based evidence ratio on the log10 scale

This vignette demonstrates how a single evidential structure can be applied across common clinical trial endpoints, and how results can be visualised and compared coherently.

Read the SGA-ERRS standard at <https://www.swissgenomicsassociation.ch/pages/sga_errs/>.

---

## Motivating example: a clinical trial with multiple endpoints

Consider a clinical study with the following endpoints:

* a continuous primary endpoint measuring change from baseline
* a secondary continuous endpoint comparing treatment groups
* a binary safety endpoint
* a continuous biomarker associated with outcome

Each endpoint requires a different statistical model, but all are analysed and reported using the same evidential summary.

---

## A. one sample mean: primary endpoint
```{r chunk-1}
x <- sleep$extra[sleep$group == 1]
res_a <- evidence_test(x)
res_a
```

---

## B. two sample comparison: secondary endpoint
```{r chunk-2}
y <- sleep$extra[sleep$group == 2]
res_b <- evidence_test(x, y)
res_b
```
---

## C. binary clinical endpoint: safety outcome
```{r chunk-3}
tbl <- matrix(
c(30, 70,
20, 80),
nrow = 2,
byrow = TRUE
)
res_c <- evidence_test(tbl)
res_c
```
---

## D. continuous biomarker association
```{r chunk-4}
res_d <- evidence_test(
mpg ~ wt,
data = mtcars,
coef = "wt"
)
res_d
```
---

## A unified evidential summary
```{r chunk-5}
joint_df <- data.frame(
panel = factor(
c("A", "B", "C", "D"),
levels = rev(c("A", "B", "C", "D"))
),
label = c(
"One sample mean",
"Two sample comparison",
"Binary endpoint",
"Biomarker association"
),
estimate = c(
res_a$estimate,
res_b$estimate,
res_c$estimate,
res_d$estimate
),
lower = c(
res_a$interval[1],
res_b$interval[1],
res_c$interval[1],
res_d$interval[1]
),
upper = c(
res_a$interval[2],
res_b$interval[2],
res_c$interval[2],
res_d$interval[2]
),
log10_er = c(
res_a$log10_er,
res_b$log10_er,
res_c$log10_er,
res_d$log10_er
)
)

ggplot(joint_df, aes(y = panel, x = estimate)) +
geom_vline(xintercept = 0, linetype = "dashed") +
geom_errorbarh(aes(xmin = lower, xmax = upper), height = 0.25) +
geom_point(size = 2) +
geom_text(
aes(x = upper, label = paste0("log10 ER = ", round(log10_er, 2))),
hjust = -0.1,
size = 3
) +
geom_text(
aes(x = max(upper) * 4, label = label),
hjust = 0,
size = 3
) +
scale_x_continuous(expand = expansion(mult = c(0.05, 0.6))) +
labs(
x = "Effect estimate",
y = ""
)
```
---

## Reporting multiple endpoints
```{r chunk-6}
results <- list(
primary_endpoint   = res_b,
secondary_endpoint = res_a,
safety_endpoint    = res_c,
biomarker_model    = res_d
)

forest_df <- data.frame(
endpoint = factor(names(results), levels = rev(names(results))),
estimate = sapply(results, function(r) r$estimate),
lower = sapply(results, function(r) r$interval[1]),
upper = sapply(results, function(r) r$interval[2]),
log10_er = sapply(results, function(r) r$log10_er)
)

ggplot(forest_df, aes(y = endpoint, x = estimate)) +
geom_vline(xintercept = 0, linetype = "dashed") +
geom_errorbarh(aes(xmin = lower, xmax = upper), height = 0.2) +
geom_point(size = 2) +
geom_text(
aes(x = upper, label = paste0("log10 ER = ", round(log10_er, 2))),
hjust = -0.1,
size = 3
) +
labs(
x = "Effect estimate",
y = ""
) +
xlim(-7, 7)
```
---

## Interpretation

Each result should be interpreted using the same three steps:

1. The effect estimate describes magnitude and direction.
2. The uncertainty interval describes precision.
3. The evidence ratio describes the strength of support for the fitted model relative to the null.

Because all endpoints share the same evidential scale, results can be compared directly without translating between test specific summaries or thresholds.

---

## Scope

The package does not introduce new statistical models or decision rules. It provides a consistent evidential summary derived from standard likelihood based analyses, supporting coherent reporting across endpoints, studies, and research settings.

---

## References

Swiss Genomics Association. (2026). *Evidence Ratio Reporting Standard* (SGA-ERRS-1.0.0). Zenodo. [https://doi.org/10.5281/zenodo.18261076](https://doi.org/10.5281/zenodo.18261076)