---
title: "BioTransition: Dynamic Network Biomarker Analysis for Critical Transition Detection"
author:
  - name: Zaoqu Liu
    affiliation: Chinese Academy of Medical Sciences and Peking Union Medical College
    email: liuzaoqu@163.com
date: "`r Sys.Date()`"
output:
  BiocStyle::html_document:
    toc: true
    toc_depth: 3
    toc_float: true
vignette: >
  %\VignetteIndexEntry{BioTransition: Dynamic Network Biomarker Analysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

**BioTransition** is a comprehensive R/Bioconductor package for detecting 
critical transitions in biological systems using Dynamic Network Biomarker 
(DNB) theory. Critical transitions—abrupt shifts between alternative stable 
states—are ubiquitous in complex biological processes, including:
  
- Disease onset and progression
- Cellular differentiation
- Developmental transitions
- Treatment response

Identifying the pre-transition state (tipping point) before an irreversible 
shift occurs is crucial for early warning and therapeutic intervention.

## Theoretical Background

The DNB theory, proposed by Chen et al. (2012), provides a model-free approach 
to detect early warning signals of critical transitions. The core principle is 
that a dominant group of molecules (DNB module) exhibits three key 
characteristics near the tipping point:

1. **Increased variation**: Standard deviation (SD) of DNB members increases 
   dramatically
2. **Enhanced correlation**: Pearson correlation coefficient (PCC) among DNB 
   members strengthens
3. **Decreased correlation**: PCC between DNB members and non-DNB molecules 
   weakens

The composite index (CI) quantifies the transition signal:

$$CI = \frac{\overline{SD_{in}} \cdot \overline{|PCC_{in}|}}{\overline{|PCC_{out}|}}$$

# Installation

## From Bioconductor

```{r install-bioc, eval=FALSE}
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("BioTransition")
```
## From GitHub

```{r install-github, eval=FALSE}
devtools::install_github("SolvingLab/BioTransition")
```

# Quick Start

```{r load-package}
library(BioTransition)
```

## Prepare Example Data

For demonstration, we'll create a simulated expression matrix with three 
biological states: Normal, Pre-disease, and Disease.

```{r example-data}
set.seed(42)

# Simulate expression data
n_genes <- 500
n_samples <- 30

# Create expression matrix
expr <- matrix(
  rnorm(n_genes * n_samples, mean = 10, sd = 2),
  nrow = n_genes,
  ncol = n_samples
)
rownames(expr) <- paste0("Gene", 1:n_genes)
colnames(expr) <- paste0("Sample", 1:n_samples)

# Define sample states
sample_info <- data.frame(
  sample_id = colnames(expr),
  state = rep(c("Normal", "PreDisease", "Disease"), each = 10)
)

head(sample_info)
```

## Run cDNB Analysis

The conventional DNB (cDNB) method is the fastest approach for initial 
screening:

```{r cdnb-analysis, eval=FALSE}
result_cdnb <- cDNB(
  expr = expr,
  state = sample_info,
  state.levels = c("Normal", "PreDisease", "Disease"),
  cor.method = "pearson",
  variation.method = "sd"
)

# View DNB scores across states
result_cdnb$DNB.score
```

## Run tDNB Analysis

The topological DNB (tDNB) method, developed in this package, leverages 
network topology and scale-free properties for more robust detection:

```{r tdnb-analysis, eval=FALSE}
result_tdnb <- tDNB(
  expr = expr,
  state = sample_info,
  state.levels = c("Normal", "PreDisease", "Disease"),
  cor.method = "pearson",
  variation.method = "sd",
  min.size = 10,
  max.size = 200
)

# View results
result_tdnb$DNB.score
result_tdnb$DNB.genes
```

# Available Methods

BioTransition implements seven complementary DNB methodologies:

| Method | Description | PPI Required | Reference |
|:-------|:------------|:------------:|:----------|
| `cDNB` | Conventional DNB | No | Chen et al., 2012 |
| `tDNB` | Topological DNB | No | Liu Z. (this package) |
| `LcDNB` | Local DNB | Yes | — |
| `LDNB` | Landscape DNB | Yes | Liu et al., 2019 |
| `MDNB` | Module-based DNB | Yes | Li et al., 2022 |
| `TSNMB` | Time-series network module | Yes | Zhong et al., 2022 |
| `TSLE` | Time-series leading edge | Yes | Liu et al., 2020 |

## Methods Requiring PPI Networks

For methods that require protein-protein interaction (PPI) networks, 
BioTransition provides built-in networks from STRING database:

```{r ppi-data}
# Human PPI network
data(ppi_h)
head(ppi_h)

# Mouse PPI network
data(ppi_m)
head(ppi_m)
```

## Example: LcDNB with PPI Network

```{r lcdnb-example, eval=FALSE}
result_lcdnb <- LcDNB(
  expr = expr,
  state = sample_info,
  state.levels = c("Normal", "PreDisease", "Disease"),
  ppi = ppi_h,  # Use human PPI network
  cor.method = "pearson"
)
```

# Interpreting Results

All DNB methods return a list containing:

- `DNB.score`: Composite index (CI) values across all states
- `DNB.genes`: Genes identified in the DNB module
- Additional method-specific outputs

## Identifying the Critical State

The state with the highest CI value is identified as the critical 
(pre-transition) state:

```{r interpret, eval=FALSE}
# Find critical state
critical_state <- result_cdnb$DNB.score$State[
  which.max(result_cdnb$DNB.score$CI)
]
print(paste("Critical state:", critical_state))

# Number of DNB genes
print(paste("Number of DNB genes:", length(result_cdnb$DNB.genes)))
```

# Performance Optimization

BioTransition uses C++ implementations via Rcpp for computationally intensive 
operations:

- Correlation matrix calculation
- P-value computation
- Module scoring

This provides 2-20x speedup compared to pure R implementations.

# Session Information

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

# References

1. Chen L, Liu R, Liu ZP, Li M, Aihara K. (2012). Detecting early-warning 
   signals for sudden deterioration of complex diseases by dynamical network 
   biomarkers. *Scientific Reports*, 2:342. 
   doi: [10.1038/srep00342](https://doi.org/10.1038/srep00342)

2. Liu R, Chen P, Chen L. (2019). Single-sample landscape entropy reveals 
   the imminent phase transition during disease progression. 
   *National Science Review*, 7(7):1175-1185. 
   doi: [10.1093/nsr/nwy162](https://doi.org/10.1093/nsr/nwy162)

3. Li M, Zeng T, Liu R, Chen L. (2022). Detecting tissue-specific early 
   warning signals for complex diseases based on dynamical network biomarkers. 
   *The Innovation*, 3(5):100364. 
   doi: [10.1016/j.xinn.2022.100364](https://doi.org/10.1016/j.xinn.2022.100364)

4. Zhong J, Han C, Wang Y, Chen P, Liu R. (2022). Identifying the critical 
   state of complex diseases by the novel concept of sample-specific network 
   module biomarker. *Journal of Molecular Cell Biology*, 14(6):mjac052. 
   doi: [10.1093/jmcb/mjac052](https://doi.org/10.1093/jmcb/mjac052)

5. Liu X, Chang X, Liu R, Yu X, Chen L, Aihara K. (2020). Quantifying 
   critical states of complex diseases using single-sample dynamic network 
   biomarkers. *Bioinformatics*, 36(4):1068-1074. 
   doi: [10.1093/bioinformatics/btz758](https://doi.org/10.1093/bioinformatics/btz758)