---
title: "1. Quick Start: miRNA-oriented enrichment analysis with miREA"
author: "Zhesi Zhang, Xin Lai"
date: "`r Sys.Date()`"
package: miREA
output:
  BiocStyle::html_document:
    toc: true
    toc_float: true
vignette: >
  %\VignetteIndexEntry{1. Quick Start}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

`r BiocStyle::Biocpkg("miREA")` performs microRNA-oriented enrichment analysis
by modeling miRNA-gene interaction (MGI) networks directly, rather than
collapsing them to miRNA- or gene-level sets. Conventional node-centric
enrichment approaches treat miRNAs and genes as independent units, which
discards the inherent many-to-many structure of miRNA-gene regulation and can
bias functional interpretation. miREA instead models the regulatory edges
themselves.

The package implements:

* **Four node-based methods**: `TG_ORA`, `TG_Score` (target-gene-based),
  `MiR_ORA`, `MiR_Score` (miRNA-based).
* **Five edge-based methods**: `Edge_ORA`, `Edge_Score1D`, `Edge_Score2D`,
  `Edge_Topology`, `Edge_Network`, spanning over-representation,
  scoring-based, topology-aware, and network-propagation approaches.

All nine methods share a common workflow: prepare method-specific input data
with `getAllInputData()`, run the selected methods with `miREA()`, and
visualize results with `plotSummary()`, `plotHeatmap()`, or
`plotHeatmapSankey()`.

## Relation to existing packages

Several Bioconductor/CRAN packages address related but distinct questions.
`r BiocStyle::Biocpkg("clusterProfiler")` performs over-representation and
gene set enrichment analysis, but for gene enrichment analysis. It tests a 
list of genes against pathway gene sets, with no special focus on miRNAs. 
`r BiocStyle::CRANpkg("CePa")` incorporates pathway topology via node
centrality measures but operates purely on gene-level and node-level, with 
no focus on miRNAs as well.
`r BiocStyle::Biocpkg("multiMiR")` and similar miRNA-target database
packages retrieve curated or predicted miRNA-gene interactions but do not
provide an enrichment/significance-testing framework over them.
`r BiocStyle::Biocpkg("miRNApath")` performs over-representation analysis
by expanding each miRNA-gene pair into its own hypergeometric test unit,
using a single ORA-style method.
`r BiocStyle::Biocpkg("MIRit")` is a comprehensive, actively maintained
framework for integrative miRNA-mRNA analysis, covering differential
expression, correlation-based integration, and gene-set enrichment of
miRNA targets.
Here, we present miREA, to our knowledge the first miRNA-oriented
enrichment package that adopts an MGI (miRNA-gene interaction)
edge-centric enrichment. It spans over-representation, scoring,
topology-aware, and network-propagation methods, and uses
expression-informed edge scores rather than a plain membership test to
characterize miRNA function at the pathway level. Internally, its ORA and
GSEA-style methods (`TG_ORA`, `MiR_ORA`, `Edge_ORA`, `TG_Score`,
`MiR_Score`, `Edge_Score1D`) reuse `r BiocStyle::Biocpkg("clusterProfiler")`'s
`enricher()`/`GSEA()` rather than reimplementing them.

# Installation

```{r install, eval = FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("miREA")
```

# Example data

This vignette uses a small, self-contained example dataset bundled with the
package (see `?miREA_example_data`), derived from the real bladder urothelial
carcinoma (BLCA) data used in the miREA manuscript. It covers 16
bladder-cancer-specific MSigDB gene sets and 99 TCGA samples (80 tumor and 19
normal, used for differential expression). The 80 tumor samples are also used
for miRNA-gene correlation. For the full datasets used in the manuscript, see
the [Zenodo deposit](https://zenodo.org/records/18803209).

```{r load-data}
library(miREA)
data(toy_pathway)
data(toy_gene_DEdata)
data(toy_mir_DEdata)
data(toy_gene_mat)
data(toy_mir_mat)
data(toy_background_MGI)
data(toy_background_GGI)

head(toy_pathway)
dim(toy_gene_mat)
dim(toy_mir_mat)
```

# Step 1: Prepare input data

`getAllInputData()` builds the method-specific input formats (DE gene/miRNA
lists, ranked score vectors, MGI dictionaries, GGI networks, etc.) from the raw
expression and differential-expression tables. Here we request all nine
methods at once. See `?default_method_list` for the full list of supported
method names.

```{r get-input-data}
input_data <- getAllInputData(
  methods = default_method_list,
  pathway = toy_pathway,
  mir_DEdata = toy_mir_DEdata,
  gene_DEdata = toy_gene_DEdata,
  background_MGI = toy_background_MGI,
  background_GGI = toy_background_GGI,
  GGI_source = "Omnipath",
  gene_mat = toy_gene_mat,
  mir_mat = toy_mir_mat,
  scoreFun = "rank"
)
names(input_data)
```

## Interoperability with standard Bioconductor classes

`gene_mat`/`mir_mat` also accept a `r BiocStyle::Biocpkg("SummarizedExperiment")`
object in place of a raw matrix/dataframe (the first assay is used), and
`pathway` accepts a `r BiocStyle::Biocpkg("GSEABase")` `GeneSetCollection` in
place of the two-column dataframe. This lets miREA plug directly into
analyses that already represent expression data and gene sets in these
standard classes, instead of requiring a manual conversion step.

```{r interop-demo}
library(SummarizedExperiment)
library(GSEABase)

gene_se <- SummarizedExperiment(assays = list(expr = as.matrix(toy_gene_mat)))
mir_se <- SummarizedExperiment(assays = list(expr = as.matrix(toy_mir_mat)))
pathway_gsc <- GeneSetCollection(Map(function(genes, name) GeneSet(genes, setName = name),
  split(toy_pathway$gene, toy_pathway$pathway),
  names(split(toy_pathway$gene, toy_pathway$pathway))
))

input_data_bioc <- getAllInputData(
  methods = "Edge_ORA", pathway = pathway_gsc,
  mir_DEdata = toy_mir_DEdata, gene_DEdata = toy_gene_DEdata,
  background_MGI = toy_background_MGI,
  gene_mat = gene_se, mir_mat = mir_se
)
identical(input_data_bioc$data$Edge_ORA, input_data$data$Edge_ORA)
```

# Step 2: Run enrichment analysis

`miREA()` requires a `background` for each target (`TG`, `MiR`, `Edge`) unless
you already supplied one via `getAllInputData()`'s `background_MGI`. miREA
does not ship a bundled default background. Build one from your own
background_MGI/background_GGI, or download the full background used in the
manuscript from the Zenodo deposit linked above.

```{r run-miREA}
background <- list(
  TG = unique(toy_pathway$gene),
  MiR = unique(input_data$pathway$MiR$miRNA),
  Edge = unique(paste0(toy_background_MGI$miRNA, ":", toy_background_MGI$gene))
)

result <- miREA(
  methods = default_method_list,
  input_data = input_data,
  background = background,
  minSize = NULL,
  maxSize = NULL,
  pvalueType = list(TG = "std", MiR = "std", Edge = "neg"),
  pAdjMethod = "BH",
  pvalueCutoff = 1,
  iter = 20,
  ncores = 1
)
result$valid_methods
```

`miREA()` returns a `miREAResult` object, a lightweight S4 container for the
per-method result tables, elapsed times, and call parameters, with `$` access
kept for the four fields above for convenience.

```{r show-result-overview}
result
```

`result$result` is a named list with one data.frame per method. For example,
the `TG_ORA` result:

```{r show-result}
head(result$result$TG_ORA)
```

All per-method results can also be flattened into a single dataframe (with a
`method` column) via `as.data.frame()`:

```{r show-result-flat}
head(as.data.frame(result))
```

Each method only reports pathways with pvalue and padj below `pvalueCutoff`.
We use `pvalueCutoff = 1` throughout this vignette so every pathway is
returned. The exception is the ORA methods (`TG_ORA`, `MiR_ORA`, `Edge_ORA`).
These methods only report pathways with at least one overlapping
differentially expressed gene, miRNA, or edge, so some pathways can still be
missing even at `pvalueCutoff = 1`. For example, `Edge_ORA` returns 9 of 16
pathways here.

# Step 3: Visualize results

`plotSummary()` compares results across all requested methods: positive
enrichment rates, a PCA of per-method pathway rankings, pairwise overlap
between methods, and a p-value density plot.

```{r plot-summary, fig.width = 10, fig.height = 6}
plotSummary(result, penrichCutoff = 0.05)
```

`plotHeatmap()` and `plotHeatmapSankey()` visualize a single edge-based
method's result as a miRNA-by-gene heatmap (optionally combined with a Sankey
diagram showing the miRNA-gene-pathway flow). Only the five edge-based methods
are supported, one at a time. 

```{r plot-heatmap, fig.width = 18, fig.height = 8.5}
plotHeatmap(method = "Edge_Score1D", result = result, input_data = input_data,
             penrichCutoff = 0.05, n_pathway = 5, n_mir_heatmap = 10)
```

```{r plot-sankey, fig.width = 18, fig.height = 12}
plotHeatmapSankey(method = "Edge_Score1D", result = result, input_data = input_data,
                     penrichCutoff = 0.05, n_pathway = 5, n_mir_heatmap = 10,
                     n_mir_sankey = 5)
```

# Choosing methods for your own data

miREA supports 4 node-based and 5 edge-based methods. You do not need to run
all nine. Select the method(s) most appropriate for your dataset and research
question. See the method performance comparisons in the miREA manuscript
(`r BiocStyle::Biocpkg("miREA")`'s companion
[bioRxiv preprint](https://doi.org/10.64898/2026.02.27.708509)) for guidance.
`Edge_Topology` in particular can be computationally expensive on large,
real-sized pathway/background data. Consider excluding it or increasing
`ncores` for large analyses.

# Session info

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