---
title: "Introduction to METAFLUX"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{Introduction to METAFLUX}
  %\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
)
```

## Overview

**METAFLUX** is a high-performance R package for genome-scale metabolic flux analysis (MFA) from transcriptomic data. This package implements the METAFlux algorithm (Huang et al., *Nature Communications*, 2023) with significant computational optimizations.

### Key Features

- **Genome-scale modeling**: Utilizes Human-GEM with 13,082 metabolic reactions
- **Dual-mode analysis**: Supports both bulk and single-cell RNA-seq data
- **High performance**: Optimized algorithms with parallel computing and C++ acceleration
- **Community modeling**: Captures metabolic interactions in tumor microenvironment

### Author

**Zaoqu Liu** (Maintainer)
- Email: liuzaoqu@163.com
- ORCID: [0000-0002-0452-742X](https://orcid.org/0000-0002-0452-742X)
- GitHub: [Zaoqu-Liu](https://github.com/Zaoqu-Liu)

## Installation

### From R-universe (Recommended)

```{r install-runiverse, eval=FALSE}
install.packages("METAFLUX", repos = "https://zaoqu-liu.r-universe.dev")
```

### From GitHub

```{r install-github, eval=FALSE}
# install.packages("remotes")
remotes::install_github("Zaoqu-Liu/METAFlux")
```

## Quick Start

### Load Package

```{r load-package, eval=FALSE}
library(METAFLUX)
```

### Bulk RNA-seq Analysis

```{r bulk-quick, eval=FALSE}
# Load example data
data("bulk_test_example")
data("human_blood")

# Step 1: Calculate Metabolic Reaction Activity Scores (MRAS)
mras <- calculate_reaction_score(bulk_test_example)

# Step 2: Compute metabolic fluxes
flux <- compute_flux(mras = mras, medium = human_blood)

# View results
dim(flux)  # 13082 reactions × n samples
```

### Single-Cell Analysis

```{r sc-quick, eval=FALSE}
# Load data
data("sc_test_example")
data("human_blood")

# Step 1: Bootstrap aggregation
avg_expr <- calculate_avg_exp(
  myseurat = sc_test_example,
  myident = "Cell_type",
  n_bootstrap = 100,
  seed = 42
)

# Step 2: Calculate MRAS
mras <- calculate_reaction_score(avg_expr)

# Step 3: Community flux calculation
fractions <- as.numeric(table(sc_test_example$Cell_type) / ncol(sc_test_example))
flux <- compute_sc_flux(
  num_cell = length(unique(sc_test_example$Cell_type)),
  fraction = fractions,
  fluxscore = mras,
  medium = human_blood
)
```

## Workflow Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                      METAFLUX Workflow                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Gene Expression Data                                          │
│         │                                                       │
│         ▼                                                       │
│   ┌─────────────────────────────┐                              │
│   │ calculate_reaction_score()  │  → MRAS (13,082 reactions)   │
│   └─────────────────────────────┘                              │
│         │                                                       │
│         ▼                                                       │
│   ┌─────────────────────────────┐                              │
│   │      compute_flux()         │  → Bulk RNA-seq              │
│   │    compute_sc_flux()        │  → Single-cell               │
│   └─────────────────────────────┘                              │
│         │                                                       │
│         ▼                                                       │
│   Metabolic Flux Matrix                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Data Requirements

| Data Type | Format | Requirements |
|-----------|--------|--------------|
| Bulk RNA-seq | Matrix | Rows: HGNC symbols, Columns: samples |
| Single-cell | Seurat object | RNA assay with cell type annotations |
| Medium | Data frame | Columns: `metabolite`, `reaction_name` |

## Citation

If you use METAFLUX in your research, please cite:

> Huang Y, et al. Characterizing cancer metabolism from bulk and single-cell RNA-seq data using METAFlux. *Nature Communications* 14, 4883 (2023). https://doi.org/10.1038/s41467-023-40457-w

## Session Info

```{r session, eval=FALSE}
sessionInfo()
```