---
title: "Univariable Functional Mendelian Randomization"
author: "Nicole Fontana"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Univariable Functional Mendelian Randomization}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

This vignette demonstrates **Univariable Functional Mendelian Randomization (U-FMR)** for estimating the time-varying causal effect of a **single longitudinal exposure** on a health outcome.

### When to Use U-FMR

Use univariable estimation (`mvfmr_separate()` with a `G_list` of length 1) when:

- You have a **single exposure** of interest
- No need to adjust for other exposures

## Installation

```{r install, eval=FALSE}
# Install from CRAN
install.packages("mvfmr")

# Or, for the development version:
# devtools::install_github("NicoleFontana/mvfmr")
```

```{r load}
library(mvfmr)
library(fdapace)
library(ggplot2)
```

## Example: Single Exposure Analysis

### Step 1: Simulate Data

```{r simulate}
set.seed(12345)

# Generate exposure data with a single exposure (m = 1)
sim_data <- getX_multi_exposure(
  N = 300,
  J = 25,
  nSparse = 10,
  n_exposures = 1
)

cat("Data simulated:\n")
cat("  Sample size:", nrow(sim_data$details$G), "\n")
cat("  Instruments:", ncol(sim_data$details$G), "\n")
```

### Step 2: Generate Outcome

We create an outcome where **the exposure has a linear causal effect**:

```{r outcome}
outcome_data <- getY_multi_exposure(
  sim_data,
  XYmodels = "2",     # Linear effect: beta(t) = 0.02*t
  X_effects = TRUE,
  outcome_type = "continuous"
)

cat("Outcome summary:\n")
summary(outcome_data$Y)
```

### Step 3: FPCA for the Single Exposure

```{r fpca}
fpca1 <- FPCA(
  sim_data$exposures[[1]]$Ly_sim,
  sim_data$exposures[[1]]$Lt_sim,
  list(dataType = 'Sparse', error = TRUE, verbose = FALSE)
)

cat("FPCA completed:\n")
cat("  Components selected:", fpca1$selectK, "\n")
cat("  Variance explained:",
    round(sum(fpca1$lambda[1:fpca1$selectK]) / sum(fpca1$lambda) * 100, 1), "%\n")
```

### Step 4: Univariable Estimation

Estimate the causal effect using `mvfmr_separate()` with a `G_list` of length 1:

```{r estimation}
result <- mvfmr_separate(
  G_list = list(sim_data$details$G),
  fpca_results = list(fpca1),
  Y = outcome_data$Y,
  outcome_type = "continuous",
  method = "gmm",
  max_nPC = 4,
  n_cores = 1,
  true_effects = "2",
  verbose = FALSE
)

print(result)
```

### Step 5: Visualize Time-Varying Effect

```{r plot_effect, fig.width=7, fig.height=5}
plot(result)
```

The solid colored line shows the estimated time-varying causal effect, with a shaded band representing the 95% confidence interval. The dashed red line (when present) indicates the true time-varying effect used in the simulation.

### Step 6: Extract Results

```{r extract}
# Coefficients for basis functions
cat("Estimated coefficients:\n")
print(round(coef(result, exposure = 1), 4))

# Time-varying effect curve
cat("\nFirst 10 time points of beta(t):\n")
head(result$exposures[[1]]$effect, 10)
```

### Step 7: Performance Metrics

```{r performance}
cat("Performance:\n")
cat("  MISE:", round(result$exposures[[1]]$performance$MISE, 6), "\n")
cat("  Coverage:", round(result$exposures[[1]]$performance$Coverage, 3), "\n")
cat("  Components used:", result$exposures[[1]]$nPC_used, "\n")
```

## Binary Outcomes

U-FMR also works with binary outcomes:

```{r binary, eval=FALSE}
# Generate binary outcome
outcome_binary <- getY_multi_exposure(
  sim_data,
  XYmodels = "2",
  X_effects = TRUE,
  outcome_type = "binary"
)

# Estimate with control function
result_binary <- mvfmr_separate(
  G_list = list(sim_data$details$G),
  fpca_results = list(fpca1),
  Y = outcome_binary$Y,
  outcome_type = "binary",
  method = "cf",      # Control function for binary
  max_nPC = 3,
  n_cores = 1,
  verbose = FALSE
)

print(result_binary)
cat("Cases:", sum(outcome_binary$Y == 1), "\n")
cat("Controls:", sum(outcome_binary$Y == 0), "\n")
```

## Advanced Topics

### Available Effect Models

The package includes 10 pre-defined time-varying effect shapes:

- `"0"`: No effect (null)
- `"1"`: Constant (beta = 0.1)
- `"2"`: Linear increasing
- `"3"`: Linear decreasing
- `"4"`: Early life effect
- `"5"`: Late life effect
- `"6"`: Early decreasing
- `"7"`: Late increasing
- `"8"`: Quadratic (U-shape)
- `"9"`: Cubic

### Bootstrap Inference

```{r bootstrap, eval=FALSE}
# Get robust confidence intervals via bootstrap
result_boot <- mvfmr_separate(
  G_list = list(sim_data$details$G),
  fpca_results = list(fpca1),
  Y = outcome_data$Y,
  outcome_type = "continuous",
  bootstrap = TRUE,
  n_bootstrap = 100,
  max_nPC = 4,
  verbose = FALSE
)

# Bootstrap CIs are stored in result_boot$exposures[[1]]$...
```

### Two-Sample Design

If you have GWAS summary statistics instead of individual-level outcome data:

```{r twosample, eval=FALSE}
# Simulate GWAS summary statistics
by_outcome <- rnorm(25, 0.02, 0.01)
sy_outcome <- runif(25, 0.005, 0.015)

result_2sample <- fmvmr_separate_twosample(
  G_list = list(sim_data$details$G),
  fpca_results = list(fpca1),
  by_outcome_list = list(by_outcome),
  sy_outcome_list = list(sy_outcome),
  ny_outcome = 50000,
  max_nPC = 3,
  verbose = FALSE
)

print(result_2sample)
```

## Next Steps

### Learn More

- **Multivariable FMR**: See `vignette("multivariable-fmr")` for joint estimation
- **Complete examples**: Check `inst/examples/test_U-FMR.R` for all scenarios
- **Manuscript**: See paper for methodological details

## Citation

If you use this package, please cite:

> Fontana, N., Ieva, F., Zuccolo, L., Di Angelantonio, E., & Secchi, P. (2025). Unraveling time-varying causal effects of multiple exposures: integrating Functional Data Analysis with Multivariable Mendelian Randomization. *arXiv preprint arXiv:2512.19064*.


## Session Info

```{r session}
sessionInfo()
```