---
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 by g-computation from the fitted mediator and outcome models. It adds balance diagnostics, two sensitivity analyses, and a reporting helper (`diagnose()`).

## 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       = 50,    # use >= 500 in practice
  verbose = FALSE
)
print(fit)
```

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

The love plot shows standardised mean differences (SMDs) before and after
weighting by stabilised treatment-model weights. The mediator panel is a rough
screening check. The dashed lines mark the common |SMD| < 0.10 rule of thumb.

```{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 — `sensitivity_rho()` and `plot_sensitivity()`

The indirect effect is identified only if no unmeasured variable confounds the
mediator-outcome relationship. Following Imai, Keele, and Yamamoto (2010),
`rho` is the correlation between the errors of the mediator and outcome
models; `rho = 0` under that assumption. The plot shows the indirect effect as
`rho` moves away from zero, and the dashed line marks where it reaches zero.

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

The analysis uses a closed-form result for linear models. It is skipped when
the mediator or outcome model is not a Gaussian identity-link model, or when
the treatment or mediator enters through an interaction or transformation.

## 4. Diagnose — `diagnose()`

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

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

## Path-wise robustness — `sensitivity_paths()`

`sensitivity_paths()` gives robustness values in the partial R-squared metric
of Cinelli and Hazlett (2020) for the a-path, the b-path, and the indirect
effect. For the indirect effect it reports two values: one for the joint
significance test (equal to the smaller path value) and one for the Sobel
test, which is always smaller because one confounder weakens both paths.

```{r paths}
sp <- sensitivity_paths(fit)
sp
plot_paths(sp)
```

## Clustered data

Supply `cluster_var` and the bootstrap resamples whole clusters:

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