---
title: "Quick Start Guide"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Quick Start Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

**SecAct** (Secreted protein Activity inference) is an R package for inferring intercellular signaling activity mediated by secreted proteins. This quick start guide will help you get up and running in minutes.

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

## Basic Usage

### 1. Load Example Data

SecAct includes example data from a clinical cohort study:

```{r load-data}
# Load expression matrix
data_path <- system.file("extdata/GSE100093.IFNG.expr.gz", package = "SecAct")
expr <- read.table(gzfile(data_path), sep = "\t", header = TRUE, row.names = 1)

cat("Expression matrix dimensions:", dim(expr)[1], "genes x", dim(expr)[2], "samples\n")
```

### 2. Infer Secreted Protein Activity

```{r basic-inference}
# Run activity inference (~30 seconds with nrand=100)
result <- SecAct.activity.inference(
  inputProfile = expr[, 1:5],  # Use first 5 samples for demo
  lambda = 5e5,
  nrand = 100
)

# View result structure
cat("\nResult contains:\n")
cat("  beta (coefficients):", dim(result$beta), "\n")
cat("  se (standard errors):", dim(result$se), "\n")
cat("  zscore:", dim(result$zscore), "\n")
cat("  pvalue:", dim(result$pvalue), "\n")
```

### 3. Explore Results

```{r explore-results}
# Top 10 most active secreted proteins in sample 1
top_sp <- head(sort(result$zscore[, 1], decreasing = TRUE), 10)
print(round(top_sp, 2))
```

## Visualization

### Activity Heatmap

```{r heatmap, fig.cap="Secreted protein activity heatmap"}
# Select top variable secreted proteins
var_sp <- apply(result$zscore, 1, var)
top_var <- names(sort(var_sp, decreasing = TRUE))[1:15]

# Create heatmap
SecAct.heatmap.plot(result$zscore[top_var, ], 
                    title = "Top Variable Secreted Proteins")
```

### Bar Plot

```{r barplot, fig.cap="Top secreted proteins by activity"}
# Get activities for sample 1
activities <- result$zscore[, 1]

# Select top up and down regulated
n <- 8
top_up <- names(sort(activities, decreasing = TRUE))[1:n]
top_down <- names(sort(activities))[1:n]
selected <- c(top_up, top_down)

# Create bar plot
SecAct.bar.plot(activities[selected], title = "Sample 1 Activity")
```

### Lollipop Plot

```{r lollipop, fig.cap="Lollipop visualization"}
SecAct.lollipop.plot(activities[selected], title = "Sample 1 Activity")
```

## Compare Treatment vs Control

A common use case is comparing two conditions:

```{r compare-conditions}
# Load metadata
meta_path <- system.file("extdata/GSE100093.IFNG.meta", package = "SecAct")
meta <- read.table(meta_path, sep = "\t", header = TRUE, row.names = 1)

# Split by treatment
expr_treatment <- expr[, meta$Treatment == "Anti-IFNG"]
expr_control <- expr[, meta$Treatment == "Control"]

cat("Treatment samples:", ncol(expr_treatment), "\n")
cat("Control samples:", ncol(expr_control), "\n")
```

```{r differential-analysis}
# Infer differential activity
diff_result <- SecAct.activity.inference(
  inputProfile = expr_treatment,
  inputProfile_control = expr_control,
  is.singleSampleLevel = FALSE,
  nrand = 100
)

# View IFNG activity change (should be negative due to anti-IFNG treatment)
cat("\nIFNG activity change:", round(diff_result$zscore["IFNG", "Change"], 2), "\n")
cat("(Negative = reduced activity in treatment group)\n")
```

## R vs GSL Implementation

SecAct provides two implementations:

```{r compare-impl}
# Pure R implementation (works everywhere)
set.seed(123)
r_result <- SecAct.inference.r(expr[, 1:3], nrand = 50)

# GSL implementation (faster, requires GSL)
set.seed(123)
gsl_result <- SecAct.inference.gsl(expr[, 1:3], nrand = 50)

# They produce highly correlated results
cat("Beta correlation:", round(cor(as.vector(r_result$beta), 
                                    as.vector(gsl_result$beta)), 4), "\n")
```

## Workflow Summary

```
┌─────────────────────────────────────────────────────────────┐
│                    SecAct Workflow                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Load Data ──────────────────────────────────────────►  │
│     (Expression matrix: genes × samples)                    │
│                                                             │
│  2. Activity Inference ─────────────────────────────────►  │
│     SecAct.activity.inference()                             │
│     SecAct.inference.r() or SecAct.inference.gsl()          │
│                                                             │
│  3. Visualization ──────────────────────────────────────►  │
│     SecAct.heatmap.plot()                                   │
│     SecAct.bar.plot()                                       │
│     SecAct.lollipop.plot()                                  │
│                                                             │
│  4. Downstream Analysis ────────────────────────────────►  │
│     SecAct.coxph.regression() (survival)                    │
│     SecAct.CCC.scRNAseq() (cell-cell communication)         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## Next Steps

Explore more advanced tutorials:

- **Spatial Transcriptomics**: `vignette("stPattern")`, `vignette("stCCC")`
- **Single-cell RNA-seq**: `vignette("scCCC")`, `vignette("scState")`
- **Bulk RNA-seq**: `vignette("bulkChange")`, `vignette("bulkCohort")`
- **Algorithm Details**: `vignette("algorithm")`

## Getting Help

- **Documentation**: `?SecAct.activity.inference`
- **GitHub Issues**: https://github.com/Zaoqu-Liu/SecAct/issues
- **Contact**: liuzaoqu@163.com

## Session Info

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