---
title: "Standardized Proximal Effect Size in MRTAnalysis"
author: "Xinyi Song (songx12@uci.edu), John Dziak (dziakj1@gmail.com), Tianchen Qian (t.qian@uci.edu)"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
link-citations: yes
bibliography: mhealth-ref.bib
csl: biostatistics.csl
vignette: >
  %\VignetteIndexEntry{Standardized Proximal Effect Size in MRTAnalysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

This vignette introduces the standardized proximal effect size estimator for
**continuous** proximal outcomes
implemented in `calculate_mrt_effect_size()`. The method generalizes the
standardized effect size in @luers2019standardized by allowing adjustment for
baseline and time-varying covariates to improve efficiency. The goal is to
estimate the time-varying proximal causal excursion effect on a standardized
scale, and optionally smooth the estimate over decision points.

# Data Structure

The input data are in long format, with one row per participant-by-decision point.
The data set must include:

- a participant id,
- a **continuous** proximal outcome,
- a treatment indicator (binary),
- a decision point index,
- a randomization probability,
- and an availability indicator.

Optional time-varying covariates can be included and specified through the
`covariates` argument.

## Example Data
We use the built-in example data `data_example_for_standardized_effect` to
illustrate usage.

### Load the example MRT dataset
```{r load-example-data}
data("data_example_for_standardized_effect")
dat <- data_example_for_standardized_effect
head(dat)
```

---

## Estimate the Standardized Effect

We estimate the effect with a modest number of bootstrap replications (100) for
speed. For stable confidence intervals, use at least 1000 replications. By
default, the function applies LOESS smoothing over decision points; you can
disable this by setting `smooth = FALSE`, or tune the smoother via `loess_span`
and `loess_degree`.
```{r estimate-effect}
ans_ci <- calculate_mrt_effect_size(
  data         = dat,
  id           = "id",
  outcome      = "outcome",
  treatment    = "treatment",
  time         = "decision_point",
  rand_prob    = "prob_treatment",
  availability = "availability",
  covariates   = "covariate1",
  do_bootstrap = TRUE,
  boot_replications = 100
)

head(ans_ci)
```

The returned object is a data frame with:

- `time` — decision point  
- `beta_hat` — raw (unsmoothed) estimated excursion effect  
- `s_hat` — raw (unsmoothed) estimated outcome scale  
- `beta_sm` — smoothed excursion effect (equals `beta_hat` if `smooth = FALSE`)  
- `s_sm` — smoothed outcome scale (equals `s_hat` if `smooth = FALSE`)  
- `estimate` — standardized effect `beta_sm / s_sm`  
- `lower`, `upper` — bootstrap confidence bounds (present when `do_bootstrap = TRUE`)

A simple numerical summary:
```{r summary}
summary(ans_ci)
```

---

## Optional: Increase Bootstrap Replications

To improve CI stability, increase the number of bootstrap replications. For example:

```{r bootstrap-example, eval=FALSE}
ans_ci <- calculate_mrt_effect_size(
  data         = dat,
  id           = "id",
  outcome      = "outcome",
  treatment    = "treatment",
  time         = "decision_point",
  rand_prob    = "prob_treatment",
  availability = "availability",
  covariates   = "covariate1",
  do_bootstrap = TRUE,
  boot_replications = 1000
)
```

## Plot the Estimated Effect

The plot below shows the standardized effect estimate with bootstrap
confidence bounds.

```{r plot-effect, fig.width=6, fig.height=4}
plot(ans_ci)
```