---
title: "TransHDM: High-Dimensional Mediation Analysis via Transfer Learning"
author: "Huer Gao"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{TransHDM: High-Dimensional Mediation Analysis via Transfer Learning}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

`TransHDM` provides a framework for high-dimensional mediation analysis using transfer learning. It integrates external source datasets to improve the detection power of potential mediators in small-sample target studies, addressing data heterogeneity via transfer regularization and debiased estimation.

## Built-in Data

The package includes the simulated inflammatory mediation benchmark dataset with
one target cohort and two external cohorts:

- `inflam_target` — target cohort (*n* = 50)
- `inflam_external1` — transferable external cohort (*n* = 200)
- `inflam_external2` — non-transferable external cohort (*n* = 100)
- `inflam_effect` — ground-truth mediation effects

The exposure is an inflammatory biomarker (`IB`) and the outcome is a disease
severity index (`DSI`); the 20 candidate mediators are molecular markers across
five functional groups. The mediator columns were randomly permuted during
generation, so the identity of the truly active mediators is hidden.

```{r}
library(TransHDM)

data(inflam_target)
data(inflam_external1)
data(inflam_external2)
data(inflam_effect)

target    <- inflam_target
source    <- inflam_external1
source_nt <- inflam_external2

outcome_var  <- "DSI"    # disease severity index (outcome)
exposure_var <- "IB"     # inflammatory biomarker (exposure)
X_vars       <- c("BIS", "PRS", "BRS")
M_vars       <- setdiff(colnames(target),
                        c(outcome_var, exposure_var, X_vars))

## ground truth effect (target cohort)
inflam_effect
```

## Source Detection

Identify which source datasets are transferable to the target population.
`print()` gives a concise one-line summary, while `summary()` provides
the detailed decision table:

```{r}
set.seed(123)
detect <- source_detection(target_data = target,
                           source_data = list(source, source_nt),
                           Y = outcome_var, D = exposure_var, M = M_vars, X = X_vars)
print(detect)
summary(detect)
```

Visualization of the source detection results can be done using the `plot()` function:

```{r, fig.width=6, fig.height=3.5}
plot(detect)
```

## Integrated Workflow: `TransHDM()`

The `TransHDM()` function provides an end-to-end analysis in one call:

```{r}
# With transfer learning
set.seed(123)
result_tl <- TransHDM(
  target_data = target,
  source_data = source,
  Y = outcome_var, D = exposure_var,
  M = M_vars, X = X_vars,
  transfer = TRUE,
  topN = 10, p_cutoff = 0.01
)
print(result_tl)
# summary(result_tl)
```

```{r}
# Without transfer learning (target only)
set.seed(123)
result_nt <- TransHDM(
  target_data = target,
  Y = outcome_var, D = exposure_var,
  M = M_vars, X = X_vars,
  transfer = FALSE,
  topN = 10, p_cutoff = 0.01
)
print(result_nt)
summary(result_nt)
```

## Visualization

```{r, fig.width=6, fig.height=3.5}
# Mediator-wise effect plot
plot(result_tl, type = "mediator")
```

```{r, fig.width=6, fig.height=3.5}
# P-value visualization
plot(result_tl, type = "pvalue")
```

```{r, fig.width=6, fig.height=3.5}
# Overall effect decomposition
plot(result_tl, type = "overall")
```

```{r, fig.width=6, fig.height=3.5}
# Alpha-beta effect plot
plot(result_tl, type = "alpha_beta")
```

## Modular Workflow

### Sure Independence Screening (SIS)

Reduce dimensionality by filtering candidate mediators:

```{r}
set.seed(123)
sis <- SIS(
  target_data = target, source_data = source,
  Y = outcome_var, D = exposure_var, M = M_vars, X = X_vars,
  transfer = TRUE, topN = 10, ncore = 1
)
print(sis)
summary(sis)
```

### Mediation Effect Inference

Estimate exposure-mediator and mediator-outcome effects:

```{r}
med_effect <- mediation_inference(
  screen_result = sis,
  transfer = TRUE
)
print(med_effect)
summary(med_effect, top = 10)
```

Do effect estimation and inference directly from the source and target data without SIS:

```{r, eval=FALSE}
mediation_inference(
  source_data = source, target_data = target,
  Y = outcome_var, D = exposure_var, M = M_vars, X = X_vars,
  transfer = TRUE, ncore = 1
)
```

### Joint Significance Testing

Identify significant mediators through joint multiple testing:

```{r}
jt <- joint_test(
  inference_result = med_effect,
  p_cutoff = 0.05
)
print(jt)
summary(jt)
```