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

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

## Overview

**RobustMediate** estimates natural direct and indirect effects (NDE/NIE) for continuous treatments using inverse probability weighting (IPW). It embeds three publication-ready visualisations and a paper-writing helper (`diagnose()`) directly into the package workflow.

## Simulated data

```{r data}
set.seed(42)
n  <- 600
Z1 <- rnorm(n)
Z2 <- rbinom(n, 1, 0.5)
X  <- 0.5 * Z1 + 0.3 * Z2 + rnorm(n)  # continuous treatment
M  <- 0.4 * X  + 0.2 * Z1 + rnorm(n)  # mediator
Y  <- 0.3 * X  + 0.5 * M  + 0.1 * Z1 + rnorm(n)  # outcome
dat <- data.frame(Y, X, M, Z1, Z2)
```

## Fitting the model

```{r fit, message = FALSE}
library(RobustMediate)

fit <- robustmediate(
  treatment_formula = X ~ Z1 + Z2,
  mediator_formula  = M ~ X + Z1 + Z2,
  outcome_formula   = Y ~ X + M + Z1 + Z2,
  data    = dat,
  R       = 200,   # use >= 500 in practice
  verbose = FALSE
)
print(fit)
```

## 1. Love Plot — `plot_balance()`

The love plot shows standardised mean differences (SMDs) before and after IPW
weighting for **both** the treatment and mediator pathways. Reviewers require
|SMD| < 0.10; the dashed lines mark this threshold.

```{r love-plot}
plot_balance(fit)
```

## 2. Dose-Response Curve — `plot_mediation()`

NDE and NIE as smooth curves over the full treatment range, with pointwise
bootstrap confidence bands. The dotted vertical line marks the reference dose.

```{r mediation-plot}
plot_mediation(fit, estimands = c("NDE", "NIE", "TE"))
```

## 3. Sensitivity Contour — `plot_sensitivity()`

The novel bivariate robustness map. The x-axis is the E-value (how strongly
an unmeasured confounder would need to be associated with both treatment and
outcome to explain away the NIE). The y-axis is Imai's ρ (sequential
ignorability violation). The bold dashed contour marks where the NIE = 0.

```{r sensitivity-plot}
plot_sensitivity(fit)
```

## 4. Diagnose — `diagnose()`

Prints a formatted report with a ready-to-paste Results paragraph.

```{r diagnose}
diagnose(fit)
```

## Clustered data

Supply `cluster_var` to account for clustering:

```{r cluster, eval = FALSE}
fit_clus <- robustmediate(
  treatment_formula = X ~ Z1 + Z2,
  mediator_formula  = M ~ X + Z1 + Z2,
  outcome_formula   = Y ~ X + M + Z1 + Z2,
  data        = dat,
  cluster_var = "school_id",
  R           = 500
)
```

## Theoretical note on the sensitivity contour

The E-value × ρ surface is a *bivariate robustness display*, not a joint
causal model. For each pair (E-value, ρ), the surface shows the estimated
NIE if **that single violation** were present. The dimensions should be
interpreted separately: researchers can ask how large each violation would
need to be—on its own—to overturn the finding.