# MultiOmicsBridge — inst/ directory

This directory contains real-data validation scripts and pre-built
example data for the MultiOmicsBridge package.

---

## inst/scripts/

### `make_example_data.R`
**Run this first.** Creates `inst/extdata/example_multiomics.rds`, a small
(~300 KB) pre-built paired multi-omics dataset used in package examples,
tests, and the vignette.

```r
source("inst/scripts/make_example_data.R")
```

**Generates:**
- 30 samples (15 UC, 15 Control)
- 800 host genes with known IBD signal
- 60 microbial taxa with known IBD dysbiosis
- Deliberate CXCL8 ↔ Ruminococcus_gnavus cross-omics correlation

---

### `run_ibdmdb_demo.R` ★ PRIMARY VALIDATION SCRIPT
Full end-to-end validation on the IBDMDB dataset (Franzosa et al. 2019).

- **Microbiome**: REAL data from `curatedMetagenomicData` (Bioconductor)
  — HMP_2019_ibdmdb, 220 stool metagenomics samples, UC/CD/nonIBD
- **Host RNA-seq**: Biologically realistic simulation using published IBD
  transcriptional signatures (CXCL8, S100A8, MUC2, TFF3, etc.)

```r
source("inst/scripts/run_ibdmdb_demo.R")
# Runtime: ~10-15 minutes (first run downloads ~50 MB from ExperimentHub)
```

**Tests all 5 modules:**
- `loadMicrobiomeData` with real metagenomics data
- `loadHostData` with simulated IBD RNA-seq
- `matchSamples` → `MultiAssayExperiment`
- `jointDimReduction` (DIABLO)
- `biomarkerDiscovery` (known IBD genes recovered?)
- `diagnosticClassifier` (host vs microbiome vs joint AUC)
- All 5 plot functions
- `generateReport`

**Expected output:**
- Joint AUC > 0.70 on UC vs nonIBD classification
- Known IBD genes (CXCL8, S100A8, MUC2) in top host biomarkers
- Faecalibacterium_prausnitzii, Ruminococcus_gnavus in top mb biomarkers
- 5 PNG plots in man/figures/

---

### `run_geo_host_data.R`
Extends the IBDMDB demo by substituting **real GEO RNA-seq** (GSE87466,
Vanhove et al. 2018) for the simulated host data. Requires `GEOquery`.

```r
source("inst/scripts/run_geo_host_data.R")
# Runtime: ~15-25 minutes (GEO download + processing)
```

**Dataset:** GSE87466 — RNA-seq from rectal biopsies (45 UC, 45 Control)

Note: GSE87466 and HMP_2019_ibdmdb do not share the same individuals.
This script demonstrates **condition-matched** integration (same disease
status, different subjects) — a common practical scenario. For truly
paired integration, use `run_ibdmdb_full_paired.R` with the IBDMDB
portal download (see instructions in that script).

---

### `run_disease_context.R`
Validates MultiOmicsBridge in two complex disease contexts:

**Context A — Tuberculosis**
- Host: GEO GSE79362 (Maertzdorf et al. 2016, TB clinical cohort)
  — 298 blood transcriptomics samples (Active TB, Latent TB, Healthy)
- Microbiome: Simulated TB gut dysbiosis (Luo et al. 2017, Lu et al. 2021)
- Tests: Active TB vs Healthy classification

**Context B — HIV / ART Response**
- Both layers simulated from published HIV host-microbiome signatures
  (Monaco et al. 2016, Dinh et al. 2015)
- Tests: ART Responder vs Non-Responder classification

```r
source("inst/scripts/run_disease_context.R")
# Runtime: ~20-30 minutes (GEO download for TB + analyses)
```

---

### `run_benchmark.R`
Performance and reproducibility benchmark:

1. **AUC consistency** across 5 random seeds
2. **Runtime scaling** with sample size (N=20, 40, 80, 120)
3. **Biomarker stability** (Jaccard overlap across seeds)
4. **Signal recovery** (precision/recall of injected features)

```r
source("inst/scripts/run_benchmark.R")
# Full benchmark: ~30-45 minutes
# Quick check (set RUN_FULL_BENCHMARK=FALSE): ~5 minutes
```

---

## inst/extdata/

### `example_multiomics.rds`
Pre-built example dataset (auto-generated by `make_example_data.R`).

**Load in R:**
```r
ex <- readRDS(system.file("extdata", "example_multiomics.rds",
                            package = "MultiOmicsBridge"))
mae     <- ex$mae       # MultiAssayExperiment (30 samples)
outcome <- ex$outcome   # c("UC","UC",...,"Control","Control",...)
host_se <- ex$host_se   # SummarizedExperiment (800 genes)
mb_se   <- ex$mb_se     # SummarizedExperiment (60 taxa)
metadata <- ex$metadata # data.frame (condition, age, sex, BMI)

# Ground truth for validation
gt <- ex$ground_truth
gt$ibd_up_genes    # genes expected in host biomarkers
gt$uc_up_taxa      # taxa expected in microbiome biomarkers
gt$correlated_pair # CXCL8 ↔ Ruminococcus_gnavus
```

**Quick full pipeline from example data:**
```r
library(MultiOmicsBridge)
ex     <- readRDS(system.file("extdata","example_multiomics.rds",
                               package = "MultiOmicsBridge"))
result <- MultiOmicsBridgeAnalysis(ex$mae, ex$outcome,
                                    n_components = 2,
                                    n_features_host = 15,
                                    n_features_mb = 8,
                                    n_biomarkers = 12,
                                    cv_folds = 3)
result
plotClassifierComparison(result, type = "bar")
```

---

## Recommended order of execution

```
1. make_example_data.R         # Always run first — creates extdata
2. run_ibdmdb_demo.R           # Primary real-data validation
3. run_disease_context.R       # Complex disease context validation
4. run_geo_host_data.R         # Full real-data (both layers from public repos)
5. run_benchmark.R             # Performance characterization
```

## Package dependencies for scripts

All required Bioconductor packages:

```r
BiocManager::install(c(
    "MultiOmicsBridge",           # this package
    "curatedMetagenomicData",     # for run_ibdmdb_demo.R
    "GEOquery",                   # for run_geo_host_data.R + run_disease_context.R
    "SummarizedExperiment",
    "MultiAssayExperiment",
    "limma", "edgeR", "mixOmics", # core dependencies
    "ranger", "pROC"              # classifier dependencies (CRAN)
))
```
