---
title: "Full-Form DCEA Tutorial"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Full-Form DCEA Tutorial}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## When to use full-form DCEA

Full-form DCEA is appropriate when subgroup-specific clinical evidence is
available — for example, differential uptake by deprivation, differential
survival benefit by SES, or trial subgroup data stratified by socioeconomic
characteristics.

## The inequality staircase

The five steps of the staircase define how patient-level benefit distributes
across IMD groups:

1. **Disease prevalence** — who gets the disease?
2. **Eligibility** — who meets criteria for the treatment?
3. **Uptake / access** — who actually receives it?
4. **Clinical effect** — what QALY gain does each group achieve?
5. **Opportunity cost** — what health is displaced in each group?

## Worked example: NSCLC with subgroup evidence

```{r baseline}
baseline <- get_baseline_health("england", "imd_quintile")
```

### Subgroup-specific CEA inputs

```{r subgroup-data}
subgroup_data <- tibble::tibble(
  group       = 1:5,
  group_label = paste("IMD Q", 1:5),
  inc_qaly    = c(0.28, 0.36, 0.44, 0.51, 0.57),
  inc_cost    = c(13200, 12800, 12400, 12000, 11600),
  pop_share   = c(0.28, 0.24, 0.20, 0.16, 0.12)
)
subgroup_data
```

### Differential uptake

```{r uptake}
uptake <- c(0.58, 0.63, 0.68, 0.73, 0.77)
```

### Run full-form DCEA

```{r run-full-dcea}
result_full <- run_full_dcea(
  subgroup_cea_results       = subgroup_data,
  baseline_health            = baseline,
  wtp                        = 20000,
  opportunity_cost_threshold = 13000,
  uptake_by_group            = uptake
)
summary(result_full)
```

### Visualise

```{r plane, fig.width = 6, fig.height = 5}
plot_equity_impact_plane(result_full)
```

### Inequality staircase

```{r staircase-data}
sc_data <- build_staircase_data(
  group           = 1:5,
  group_labels    = paste("IMD Q", 1:5),
  prevalence      = c(0.08, 0.07, 0.06, 0.05, 0.04),
  eligibility     = c(0.70, 0.72, 0.74, 0.76, 0.78),
  uptake          = uptake,
  clinical_effect = subgroup_data$inc_qaly,
  opportunity_cost = subgroup_data$inc_cost / 13000
)
```

```{r staircase-plot, fig.width = 7, fig.height = 6}
plot_inequality_staircase(sc_data)
```