---
title: "Introduction to scaper: Cytokine Activity Estimation in Single Cells"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{Introduction to scaper}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

**scaper** (Single-Cell transcriptomics-level Cytokine Activity Prediction and Estimation) is an R package developed by **Zaoqu Liu** for quantifying cytokine signaling activity at single-cell resolution. The package integrates curated gene sets from the CytoSig and Reactome databases with the Variance-Adjusted Mahalanobis (VAM) scoring methodology.

### Key Features

- **Bidirectional Scoring**: Accounts for both up-regulated and down-regulated target genes
- **Two Database Options**: CytoSig (41 cytokines) and Reactome (30 cytokines)
- **Seurat Integration**: Seamless workflow with Seurat objects
- **Scientific Accuracy**: Mathematically validated scoring algorithm

## Installation

```{r install, eval=FALSE}
# From R-universe (recommended)
install.packages("scaper", repos = "https://zaoqu-liu.r-universe.dev")

# From GitHub
remotes::install_github("Zaoqu-Liu/scaper")
```

## Supported Cytokines

### CytoSig Database (n = 41)

```{r cytosig}
library(scaper)

cytosig_list <- supportedCytokines(database = "cytosig")
cat("Total:", length(cytosig_list), "cytokines\n\n")
print(cytosig_list)
```

### Reactome Database (n = 30)

```{r reactome}
reactome_list <- supportedCytokines(database = "reactome")
cat("Total:", length(reactome_list), "cytokines\n\n")
print(reactome_list)
```

## Quick Start

The main functions in scaper are:

1. **`scapeForSeurat()`**: For Seurat object input
2. **`scape()`**: For expression matrix input
3. **`genesetCytoSig()`**: Construct gene sets from CytoSig
4. **`genesetReactome()`**: Construct gene sets from Reactome

### Basic Usage with Seurat

```{r seurat_example, eval=FALSE}
library(scaper)
library(Seurat)
library(SeuratObject)

# Load your Seurat object
data(pbmc_small)

# Compute cytokine activity scores for all cytokines
result <- scapeForSeurat(
  seurat.object = pbmc_small,
  database = "cytosig",
  cytokine = "all",
  normalize = TRUE
)

# Extract scores from scape assay
scores <- GetAssayData(result, assay = "scape", slot = "data")
dim(scores)  # cytokines x cells
```

### Basic Usage with Matrix

```{r matrix_example, eval=FALSE}
library(scaper)

# Prepare normalized expression matrix (cells × genes)
# expression_data should be a data.frame with:
# - rows: cells
# - columns: genes
# - values: log-normalized expression

# Compute cytokine activity scores
activity_scores <- scape(
  counts.matrix = expression_data,
  database = "cytosig",
  cytokine = c("IL6", "IL4", "IFNG")
)

# Result: cells x cytokines matrix
dim(activity_scores)
```

## Gene Set Construction

### CytoSig Gene Set Example

```{r geneset_cytosig}
# Load IL6 gene set from CytoSig
file_path <- system.file("extdata", "IL6_output.csv", package = "scaper")
il6_genes <- genesetCytoSig(cytokine.eval = "IL6", file.name = file_path)

cat("IL6 gene set contains", nrow(il6_genes), "genes\n\n")
head(il6_genes, 10)
```

### Reactome Gene Set Example

```{r geneset_reactome}
# Load IL6 gene set from Reactome
file_path <- system.file("extdata", "IL6_Interleukin6_signaling.xml", package = "scaper")
il6_reactome <- genesetReactome(cytokine.eval = "IL6", file.name = file_path)

cat("IL6 pathway contains", nrow(il6_reactome), "genes\n\n")
head(il6_reactome, 10)
```

## Score Interpretation

**Activity Score Range**: [0, 1] (CDF values)

| Score Range | Interpretation |
|-------------|----------------|
| > 0.7 | Strong evidence of cytokine pathway activation |
| 0.3 - 0.7 | Moderate or basal signaling activity |
| < 0.3 | Minimal cytokine pathway activity |

## Session Information

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

---

**Author**: Zaoqu Liu  
**Email**: liuzaoqu@163.com  
**GitHub**: [Zaoqu-Liu/scaper](https://github.com/Zaoqu-Liu/scaper)