---
title: "Getting Started with drmeta"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with drmeta}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  fig.width  = 7,
  fig.height = 5
)
```

## Overview

**drmeta** implements Design-Robust Meta-Analysis (DR-Meta; Hait, 2025), a
variance-function random-effects framework that embeds causal design
robustness directly into the heterogeneity structure of meta-analysis.

The key idea: between-study variance $\tau^2(\text{DR}_i)$ is modelled as a
monotone-decreasing function of a study-level design robustness index
$\text{DR}_i \in [0,1]$.  Studies with stronger causal identification receive
greater weight through the total variance
$$\sigma_i^2 = v_i + \tau^2(\text{DR}_i;\,\psi),$$
rather than through ad-hoc quality multipliers.

DR-Meta nests classical fixed-effects (when $\tau_0^2 = 0$) and random-effects
(when $\text{DR}_i = c$ constant) meta-analysis as special cases.

## Installation

```r
# From GitHub (once released):
# devtools::install_github("subirhait/drmeta")

# Local install (development):
# devtools::install("path/to/drmeta")
```

## Step 1: Build the Design Robustness Index

The DR index $\text{DR}_i \in [0,1]$ summarises causal identification strength
per study.  The **drmeta** package provides two helpers.

### From design type labels

```{r dr-from-design}
library(drmeta)

designs <- c("RCT", "IV", "DiD", "matching", "OLS", "OLS", "RCT", "DiD")
dr <- dr_from_design(designs)
data.frame(Design = designs, DR = dr)
```

### From continuous sub-scores

```{r dr-from-subscores}
k <- 8
balance  <- c(0.95, 0.80, 0.60, 0.70, 0.30, 0.25, 0.90, 0.65)
overlap  <- c(0.90, 0.75, 0.55, 0.80, 0.40, 0.35, 0.85, 0.70)
design_s <- dr_from_design(designs)   # reuse labels from above

dr_composite <- dr_score(
  balance  = balance,
  overlap  = overlap,
  design   = design_s,
  weights  = c(2, 2, 3)   # design quality weighted most
)
round(dr_composite, 3)
```

## Step 2: Fit the DR-Meta Model

```{r fit-drmeta}
set.seed(42)
k  <- 20
dr <- runif(k, 0.1, 0.95)
vi <- runif(k, 0.008, 0.055)

# True data-generating model (Sections 3–4, Hait 2025):
#   tau0sq = 0.04, gamma = 2, mu = 0.30
tau2_true <- 0.04 * exp(-2 * dr)
yi <- rnorm(k, mean = 0.30, sd = sqrt(vi + tau2_true))

# Fit DR-Meta (exponential variance function, REML)
fit <- drmeta(yi = yi, vi = vi, dr = dr)
print(fit)
```

```{r summary-drmeta}
summary(fit)
```

### Compare exponential vs linear variance function

```{r compare-vfun}
fit_lin <- drmeta(yi, vi, dr, vfun = "linear")
cat("Exponential AIC:", round(AIC(fit), 2), "\n")
cat("Linear      AIC:", round(AIC(fit_lin), 2), "\n")
```

## Step 3: Visualise

### Forest plot

```{r forest-plot, fig.height=7}
dr_forest(fit, main = "DR-Meta Forest Plot — Simulated Data")
```

### Variance function

```{r vfun-plot}
dr_plot_vfun(fit, main = "Estimated Variance Function")
```

### Weight vs DR (Lemma 3)

```{r weight-plot}
dr_plot(fit, main = "DR-Meta Weights vs Design Robustness")
```

## Step 4: Heterogeneity Decomposition (Proposition 6)

```{r heterogeneity}
het <- dr_heterogeneity(fit)

cat("--- Heterogeneity Summary ---\n")
print(het$summary)

cat("\n--- Proposition 6 Decomposition ---\n")
print(het$decomposition)
cat(sprintf("\n%.1f%% of total heterogeneity is design-explained (R2_DR).\n",
            het$decomposition$R2_DR * 100))

cat("\n--- Per-Study Q Contributions (top 5) ---\n")
top5 <- head(het$contributions[order(-het$contributions$pct_Q), ], 5)
print(top5)
```

## Step 5: Influence Diagnostics (LOO)

```{r loo}
loo <- dr_loo(fit)
cat("Influential studies:\n")
print(subset(loo$summary, influential == TRUE))
cat("\nFull LOO summary (first 5 rows):\n")
print(head(loo$summary, 5))
```

## Step 6: Publication Bias

```{r pub-bias}
pb <- dr_pub_bias(fit)
cat("--- PET ---\n");   print(pb$PET)
cat("\n--- PEESE ---\n"); print(pb$PEESE)
cat("\n--- Recommendation ---\n"); cat(pb$recommendation, "\n")
```

```{r funnel}
dr_funnel(fit, main = "DR-Meta Funnel Plot")
```

## Connection to the Literature

DR-Meta is closely related to the **meta-analytic location-scale model**
(Viechtbauer & Lopez-Lopez, 2022), in which both the mean and variance of the
true effect distribution can depend on study-level covariates.  DR-Meta
contributes a specific causal motivation for the scale component: the variance
function is an index of susceptibility to confounding, grounded in design
robustness theory (Rubin, 2008; Rosenbaum, 2010).

It is complementary to **bias-model** frameworks (Turner et al., 2009;
Rhodes et al., 2015; Mathur & VanderWeele, 2020), which adjust the *location*
(mean) for anticipated confounding.  DR-Meta adjusts the *scale* (variance),
so the two families can be combined in future extensions.

## References

- Hait, S. (2025). *Design-Robust Meta-Analysis: A Variance-Function
  Framework for Causal Credibility*.
- Viechtbauer, W., & Lopez-Lopez, J. A. (2022). Location-scale models for
  meta-analysis. *Research Synthesis Methods, 13*, 697–715.
- Turner, R. M., et al. (2009). Bias modelling in evidence synthesis.
  *JRSS-A, 172*, 21–47.
- Rhodes, K. M., et al. (2015). Predictive distributions for heterogeneity.
  *JRSS-A, 178*, 641–666.
- Mathur, M. B., & VanderWeele, T. J. (2020). Sensitivity analysis for
  unmeasured confounding in meta-analyses. *JASA, 115*, 1190–1204.
- Rubin, D. B. (2008). For objective causal inference, design trumps analysis.
  *Annals of Applied Statistics, 2*, 808–840.