---
title: "Introduction to mlumr"
output: rmarkdown::html_vignette
bibliography: ../inst/REFERENCES.bib
link-citations: yes
vignette: >
  %\VignetteIndexEntry{Introduction to mlumr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## What mlumr does

**mlumr** implements **multilevel unanchored meta-regression (ML-UMR)** for
population-adjusted single-arm indirect treatment comparisons. It is for the
situation where two treatments have never been compared in the same trial and
there is **no common comparator arm** to anchor the comparison (single-arm
trials, i.e., *fully disconnected* evidence), you hold individual patient data
(IPD) for one treatment and only published aggregate data (AgD) for the other.

ML-UMR fits an outcome model to the IPD and **integrates it over the comparator
study's covariate distribution**, transporting the comparison to a
decision-relevant population while adjusting for cross-trial covariate
imbalance. It extends multilevel network meta-regression (ML-NMR)
[@Phillippo2020] to the unanchored, two-treatment case; the method and its
assumptions are developed by Chandler and Ishak for binary [@ChandlerIshak2025]
and survival [@ChandlerIshak2026] outcomes.

The current package is two-treatment: one index treatment (IPD) versus one
comparator (AgD). Multi-treatment unanchored networks are out of scope.

ML-UMR should only be used for fully unanchored, single-arm comparisons. The
worked examples in these vignettes use data from randomized trials, and to
illustrate the method they create hypothetical single-arm trials by dropping a
common reference arm (or by treating a trial's randomized arms as separate
sources), which leaves fully disconnected evidence. In practice, randomized
trials should never be analyzed this way: ML-NMR [@Phillippo2020] (for example
with the `multinma` package) or another appropriate method should be used for
them.

## Supported outcome families

| Family | Outcome | Worked-example vignette |
|--------|---------|-------------------------|
| binomial | binary (0/1) response | `vignette("binary-outcomes")` |
| normal | continuous | `vignette("continuous-outcomes")` |
| poisson | counts with exposure | `vignette("count-outcomes")` |
| survival | time-to-event | `vignette("survival-outcomes")` |

## The four methods

mlumr provides four estimators behind one data interface, so you can run them
side by side as a sensitivity analysis:

| Method | Adjusts covariates? | Effect modification? | Inference |
|--------|---------------------|----------------------|-----------|
| ML-UMR SPFA | yes | no (shared coefficients) | Bayesian |
| ML-UMR relaxed | yes | yes (treatment-specific) | Bayesian |
| STC | yes (outcome model) | no | frequentist |
| Naive | no | n/a | frequentist (benchmark) |

## What "unanchored" does and does not buy you

Removing the common-arm requirement is what makes single-arm comparisons
possible, but it does **not** remove the need for assumptions. Unanchored
ML-UMR still relies on **conditional constancy of the absolute outcome**: that,
conditional on the modelled covariates, the index outcome model transports to the
comparator population (and, under the default SPFA, that prognostic effects are
shared across treatments). These assumptions are strong and largely untestable,
so always report the naive benchmark and sensitivity analyses
(`vignette("choosing-a-method")`).

## Installation

Install the released version from CRAN, or the development version from GitHub:

```{r}
install.packages("mlumr")            # from CRAN
# remotes::install_github("choxos/mlumr")   # development version
```

## The workflow at a glance

Every analysis follows the same four steps, then a fit:

```{r}
library(mlumr)

ipd <- set_ipd(...)                  # individual patient data (index)
agd <- set_agd(...)                  # aggregate data (comparator)
dat <- combine_data(ipd, agd)        # combine
dat <- add_integration(dat, ...)     # quasi-Monte Carlo integration points
fit <- mlumr(dat, model = "spfa")    # fit the Bayesian model
```

The exact `set_ipd()` / `set_agd()` arguments depend on the outcome family;
each per-outcome vignette shows a complete, runnable example.

## Where to go next

1. `vignette("data-preparation")`, the four-step pipeline and the numerical
   integration that powers population adjustment (covariate distributions,
   correlation, diagnostics).
2. **One outcome-family worked example**, `vignette("binary-outcomes")`,
   `vignette("continuous-outcomes")`, `vignette("count-outcomes")`, or
   `vignette("survival-outcomes")`.
3. `vignette("fitting-and-diagnostics")`, sampler control, priors, and MCMC
   diagnostics.
4. `vignette("choosing-a-method")`, assumptions, model comparison, and a
   decision guide for which estimate to report.