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

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

# Use a wider console width for readable tabular output, while preserving and
# restoring the user's original option at the end of the vignette.
old_options <- options(width = 140)

library(twoPhaseSens)
```

# Overview

`twoPhaseSens` compares analytic approaches for a linear-regression exposure
coefficient when important continuous adjustment covariates are observed only in
a Phase-2 subsample. This vignette documents version 0.1.0, the package's first
public release.

Version 0.1.0 focuses on the setting in which:

- the outcome is continuous;
- the primary exposure is numeric;
- ordinary Phase-1 covariates are fully observed;
- continuous Phase-2 covariates are observed together as a block;
- Phase-2 membership is recorded by a 0/1 indicator.

The package implements six approaches:

1. Naive Phase-1 analysis
2. Complete-case analysis (CCA)
3. Fully conditional specification multiple imputation (FCS-MI)
4. Joint-model multiple imputation (JM-MI)
5. Inverse probability weighting (IPW)
6. Augmented inverse probability weighting (AIPW)

The main purpose is **method-comparison sensitivity analysis**. The package does
not automatically decide which method is best for a given dataset.

# Example data

The package provides a fully synthetic example-data generator. The generated
data are not derived from MIDUS or any other participant-level study data.

```{r example-data}
dat <- twophase_example_data(
  n = 300,
  seed = 2026
)

head(dat)
```

The example contains:

- `outcome1` and `outcome2`: continuous outcomes;
- `exposure`: the primary exposure;
- `age` and `sex`: fully observed Phase-1 covariates;
- `marker1`, `marker2`, and `marker3`: continuous Phase-2 covariates;
- `phase2`: the binary Phase-2 indicator.

Check the Phase-2 structure:

```{r phase2-structure}
table(dat$phase2)

with(
  dat,
  table(
    phase2 = phase2,
    complete_marker_block = complete.cases(marker1, marker2, marker3)
  )
)
```

For the supported design, the Phase-2 covariates are observed together when
`phase2 = 1` and missing together when `phase2 = 0`.

# Run a one-outcome analysis

A single outcome is fully supported.

To keep the vignette quick to build, the example below uses only Naive, CCA, and
IPW. In substantive work, users can request all six methods.

```{r one-outcome}
fit_one <- twophase_sensitivity(
  data = dat,
  outcome = "outcome1",
  exposure = "exposure",
  covariates = c("age", "sex"),
  phase2_covariates = c("marker1", "marker2", "marker3"),
  phase2 = "phase2",
  methods = c("naive", "cca", "ipw"),
  seed = 1001
)

fit_one
```

The returned object stores the estimates, analysis specification, settings, and
available diagnostics.

```{r one-outcome-summary}
summary(fit_one)
```

# Create the sensitivity-analysis table

The default output is a publication-ready `gtsummary` table.

```{r one-outcome-table}
tbl_sensitivity(
  fit_one,
  outcome_labels = c(outcome1 = "Outcome 1"),
  caption = "**Sensitivity analysis for Outcome 1**"
)
```

A plain data frame is also available:

```{r one-outcome-data-frame}
tbl_sensitivity(
  fit_one,
  outcome_labels = c(outcome1 = "Outcome 1"),
  output = "data.frame"
)
```

# Customize displayed precision

By default, coefficients and confidence limits are displayed to three decimal places, and p values are displayed to three decimal places. Formatting does not change the underlying model estimates.

```{r decimals}
tbl_sensitivity(
  fit_one,
  outcome_labels = c(outcome1 = "Outcome 1"),
  estimate_digits = 2,
  p_digits = 4,
  output = "data.frame"
)
```

Users can also add a separate SE column:

```{r se-column}
tbl_sensitivity(
  fit_one,
  outcome_labels = c(outcome1 = "Outcome 1"),
  include_se = TRUE,
  output = "data.frame"
)
```

# Run multiple outcomes

Multiple outcomes are analyzed separately using the same exposure, covariates,
Phase-2 variables, and requested methods.

```{r multiple-outcomes}
fit_two <- twophase_sensitivity(
  data = dat,
  outcome = c("outcome1", "outcome2"),
  exposure = "exposure",
  covariates = c("age", "sex"),
  phase2_covariates = c("marker1", "marker2", "marker3"),
  phase2 = "phase2",
  methods = c("naive", "cca", "ipw"),
  seed = 2001
)
```

A scalar seed is expanded sequentially across outcomes. In this example, the
two outcomes use seeds 2001 and 2002.

```{r inspect-seeds}
unique(fit_two$results[c("outcome", "analysis_seed")])
```

The combined comparison table is:

```{r multiple-outcome-table}
tbl_sensitivity(
  fit_two,
  outcome_labels = c(
    outcome1 = "Outcome 1",
    outcome2 = "Outcome 2"
  )
)
```

# Supply explicit outcome-specific seeds

Users may instead provide one seed per outcome. Named seed vectors can be
supplied in any order.

```{r explicit-seeds}
fit_seeded <- twophase_sensitivity(
  data = dat,
  outcome = c("outcome1", "outcome2"),
  exposure = "exposure",
  covariates = c("age", "sex"),
  phase2_covariates = c("marker1", "marker2", "marker3"),
  phase2 = "phase2",
  methods = c("naive", "cca"),
  seed = c(
    outcome2 = 9002,
    outcome1 = 9001
  )
)

unique(fit_seeded$results[c("outcome", "analysis_seed")])
```

# Choose which methods to run

All six methods are requested by default, but users may analyze any subset.

```{r method-subset}
fit_subset <- twophase_sensitivity(
  data = dat,
  outcome = "outcome1",
  exposure = "exposure",
  covariates = c("age", "sex"),
  phase2_covariates = c("marker1", "marker2", "marker3"),
  phase2 = "phase2",
  methods = c("cca", "fcs_mi", "ipw"),
  n_imputations = 5,
  mice_maxit = 5,
  seed = 3001
)

tbl_sensitivity(
  fit_subset,
  outcome_labels = c(outcome1 = "Outcome 1")
)
```

The small imputation settings above are used only to keep the vignette fast.
Substantive analyses should choose computational settings appropriate to the
application.

# Control multiple-imputation settings

When FCS-MI or JM-MI is requested, users can control the main computational
settings.

```{r mi-settings, eval=FALSE}
fit_full <- twophase_sensitivity(
  data = dat,
  outcome = "outcome1",
  exposure = "exposure",
  covariates = c("age", "sex"),
  phase2_covariates = c("marker1", "marker2", "marker3"),
  phase2 = "phase2",
  n_imputations = 50,
  mice_maxit = 20,
  jomo_nburn = 2000,
  jomo_nbetween = 1000,
  seed = 4001
)
```

The arguments mean:

- `n_imputations`: number of completed datasets for FCS-MI and JM-MI;
- `mice_maxit`: maximum FCS iterations;
- `jomo_nburn`: JM-MI burn-in iterations;
- `jomo_nbetween`: iterations between saved JM-MI imputations.

Version 0.1.0 intentionally fixes the FCS imputation method for Phase-2
covariates to normal linear regression because that is the implementation
validated for this release.

# Change the confidence level

The default interval is 95%, but users may request another confidence level.

```{r confidence-level}
fit_90 <- twophase_sensitivity(
  data = dat,
  outcome = "outcome1",
  exposure = "exposure",
  covariates = c("age", "sex"),
  phase2_covariates = c("marker1", "marker2", "marker3"),
  phase2 = "phase2",
  methods = c("naive", "cca"),
  conf_level = 0.90
)

tbl_sensitivity(
  fit_90,
  outcome_labels = c(outcome1 = "Outcome 1"),
  output = "data.frame"
)
```

# Inspect diagnostics

Method-level status and available diagnostics can be extracted with
`diagnostics()`.

The default view combines general status information with method-specific
diagnostics:

```{r diagnostics}
diagnostics(fit_one)
```

A compact status view is available with:

```{r diagnostics-status}
diagnostics(fit_one, type = "status")
```

For IPW and AIPW, request weight diagnostics directly:

```{r diagnostics-weights}
diagnostics(fit_one, type = "weights")
```

These include the minimum weight, 99th percentile, maximum weight, coefficient
of variation, effective sample size, and effective sample size as a fraction of
the Phase-2 sample size.

For FCS-MI and JM-MI, use:

```{r diagnostics-mi, eval=FALSE}
diagnostics(fit_full, type = "mi")
```

This reports the number of imputations and relevant iteration settings. For
FCS-MI, the number of logged `mice` events is also retained.

Diagnostics can be filtered to particular outcomes or methods:

```{r diagnostics-filter}
diagnostics(
  fit_two,
  outcome = "outcome2",
  method = "ipw"
)
```

The package reports diagnostic quantities but does not automatically label them
as acceptable or unacceptable. Interpretation should reflect the study design,
sampling mechanism, and substantive context.

# Plot the sensitivity analysis

The fitted object can also be displayed as a publication-style forest plot of
method-specific coefficients and confidence intervals. The default styling
uses the same six-method color palette and open-symbol scheme as the manuscript
figures and adds right-side columns for the formatted coefficient (95% CI) and
p value.

For a single outcome:

```{r one-outcome-forest}
plot_sensitivity(
  fit_one,
  outcome_labels = c(outcome1 = "Outcome 1")
)
```

The base R plotting generic is also supported:

```{r one-outcome-forest-generic, eval=FALSE}
plot(fit_one)
```

For multiple outcomes, the plot uses separate facets. Free x-axis scales are
used by default because outcomes may have different units. The package reserves
dedicated horizontal space within each facet for the coefficient/CI and p-value
annotations so the numeric columns remain readable without overlapping the next
outcome panel.

```{r multiple-outcome-forest, fig.width=12.5, fig.height=5.4}
plot_sensitivity(
  fit_two,
  outcome_labels = c(
    outcome1 = "Outcome 1",
    outcome2 = "Outcome 2"
  ),
  annotate = TRUE
)
```

If the outcomes are on a common scale and direct visual comparison is desired,
users can request fixed axes:

```{r multiple-outcome-forest-fixed, fig.width=12.5, fig.height=5.4}
plot_sensitivity(
  fit_two,
  outcome_labels = c(
    outcome1 = "Outcome 1",
    outcome2 = "Outcome 2"
  ),
  facet_scales = "fixed",
  annotate = TRUE
)
```

The default reference line is 0. It can be changed or removed with
`reference_line`. The right-side annotation columns are controlled with
`annotate`. For multiple outcomes, a wider graphics device is recommended so
the forest region and the two annotation columns remain comfortably readable.
Their decimal precision can be controlled with `estimate_digits` and
`p_digits`. The estimate-column label can be changed
with `estimate_label`; for example, a manuscript reporting adjusted regression
coefficients can use `estimate_label = "Adjusted beta"`. An optional overall
plot title can be supplied with `title`.

Because the annotated figure contains a forest region, numeric result columns,
outcome strips, and a legend, a small RStudio Plots pane can compress the
display. This does not change the plotted estimates. For interactive viewing,
use RStudio's **Zoom** control, enlarge the Plots pane, or use
`annotate = FALSE` for a compact preview.

For manuscript or presentation output, save the plot at an explicit size.
Single-outcome annotated figures generally work well at about 9--10 inches
wide, while two-outcome figures benefit from a wider device.

```{r save-forest-examples, eval=FALSE}
p_one <- plot_sensitivity(
  fit_one,
  outcome_labels = c(outcome1 = "Primary outcome"),
  estimate_label = "Adjusted beta"
)

ggplot2::ggsave(
  "sensitivity_single_outcome.png",
  p_one,
  width = 9.5,
  height = 6,
  dpi = 320,
  bg = "white"
)

p_two <- plot_sensitivity(
  fit_two,
  outcome_labels = c(
    outcome1 = "Outcome 1",
    outcome2 = "Outcome 2"
  ),
  estimate_label = "Adjusted beta",
  facet_scales = "fixed"
)

ggplot2::ggsave(
  "sensitivity_two_outcomes.png",
  p_two,
  width = 14,
  height = 6,
  dpi = 320,
  bg = "white"
)
```

These dimensions are practical starting points rather than required settings;
users can adjust them for journal, slide, or document specifications. Because
the function returns a `ggplot` object, additional `ggplot2` layers can also
be added by the user.

# Relabel methods and outcomes

Display labels can be customized without changing the stored results.

```{r custom-labels}
tbl_sensitivity(
  fit_one,
  method_labels = c(
    Naive = "Phase-1 naive",
    CCA = "Complete case"
  ),
  outcome_labels = c(
    outcome1 = "Primary outcome"
  ),
  output = "data.frame"
)
```

# What the package currently assumes

The initial release is intentionally constrained to the design that has been
methodologically and numerically validated.

Version 0.1.0 assumes:

- continuous outcomes;
- a linear-regression target model;
- a numeric primary exposure;
- fully observed Phase-1 covariates;
- continuous Phase-2 covariates;
- Phase-2 covariates observed or missing together as a block;
- FCS-MI using normal linear-regression imputation;
- the package's validated selection-model, marker-model, IPW, and AIPW
  structures.

The initial release does not yet support logistic, count, survival, or
multilevel outcome models; partially observed Phase-2 blocks; categorical
Phase-2 variables requiring different imputation models; arbitrary nuisance
models; or automatic method selection.

# Interpreting the comparison table

The methods rely on different modeling and missing-data assumptions. Therefore,
the table should be used to examine how the estimated exposure coefficient
changes across analytic approaches.

The package does not label one row as the "best" method and does not interpret
statistical significance on the user's behalf. Method selection should reflect
the study design, scientific assumptions, and the methodological properties of
the estimators.

# Methodological references

The methods implemented in `twoPhaseSens` are grounded in the following
references. These are also cited in the package `DESCRIPTION` metadata where
appropriate.

- Little RJA, Rubin DB (2019). *Statistical Analysis with Missing Data*, 3rd ed.
  <https://doi.org/10.1002/9781119482260>
- White IR, Carlin JB (2010). "Bias and efficiency of multiple imputation
  compared with complete-case analysis for missing covariate values."
  *Statistics in Medicine*, 29(28), 2920--2931.
  <https://doi.org/10.1002/sim.3944>
- White IR, Royston P, Wood AM (2011). "Multiple imputation using chained
  equations: issues and guidance for practice." *Statistics in Medicine*,
  30(4), 377--399. <https://doi.org/10.1002/sim.4067>
- van Buuren S, Groothuis-Oudshoorn K (2011). "mice: Multivariate imputation
  by chained equations in R." *Journal of Statistical Software*, 45(3), 1--67.
  <https://doi.org/10.18637/jss.v045.i03>
- Quartagno M, Grund S, Carpenter J (2019). "jomo: A flexible package for
  two-level joint modelling multiple imputation." *The R Journal*, 11(2),
  205--228. <https://doi.org/10.32614/RJ-2019-028>
- Robins JM, Rotnitzky A, Zhao LP (1994). "Estimation of regression
  coefficients when some regressors are not always observed." *Journal of the
  American Statistical Association*, 89(427), 846--866.
  <https://doi.org/10.1080/01621459.1994.10476818>
- Bang H, Robins JM (2005). "Doubly robust estimation in missing data and
  causal inference models." *Biometrics*, 61(4), 962--973.
  <https://doi.org/10.1111/j.1541-0420.2005.00377.x>

# Reproducibility

For analyses that involve stochastic imputation:

- save the analysis seed;
- save the imputation and iteration settings;
- report the package version;
- retain the full-precision result object, not only the formatted table.

The table's decimal controls affect display only. They do not round or overwrite
the underlying estimates stored in the fitted object.


```{r restore-options, include=FALSE}
options(old_options)
```