---
title: "PERCEPTION-shiny 使用教程"
description: "交互式 Shiny 仪表盘完整教程：数据加载、模型训练、药物敏感性预测与结果可视化。"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{PERCEPTION-shiny 使用教程}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# PERCEPTION-shiny 使用教程

**PERCEPTION-shiny** 是 **PERCEPTIONx** R 包的交互式网页应用（Shiny）。它把完整的分析流水线——数据加载、模型训练、药物敏感性预测、结果可视化——封装成点选式界面，无需写代码即可完成从"患者单细胞表达矩阵"到"克隆级杀伤分数 + 患者级响应分层"的全流程分析。

> 方法学基础：PERCEPTION（PERsonalized single-Cell Expression-based Planning for Treatments In ONcology），在 DepMap 细胞系数据上训练弹性网络模型，预测患者对药物的响应与耐药。

---

## 目录

- [0. 环境要求与启动](#0-环境要求与启动)

- [1. 界面总览](#1-界面总览)

- [2. Data 页：加载数据](#2-data-页加载数据)

- [3. Train 页：训练模型（可选）](#3-train-页训练模型可选)

- [4. Predict 页：预测杀伤值](#4-predict-页预测杀伤值)

- [5. Visualize 页：可视化](#5-visualize-页可视化)

- [6. Help 页](#6-help-页)

- [7. 常见问题（FAQ）](#7-常见问题faq)

- [8. 引用与联系](#8-引用与联系)

---

## 0. 环境要求与启动

---

### 0.1 环境要求

- **R** ≥ 4.1.0

- 主要依赖包：`remotes`、`shiny`、`bslib`、`Seurat`、`ggplot2`、`ggiraph`、`glmnet`、`caret`、`DT`、`plotly`、`waiter`、`thematic`、`callr`、`readxl`（缺失时应用会在相应功能处提示安装）

---

### 0.2 启动方式

安装包之后，打开 R/RStudio，运行：

```{r, eval = FALSE}
library(PERCEPTIONx)          # 安装后加载 PERCEPTIONx（详见 pipeline 教程）
run_perception_app()          # 启动应用（自动打开浏览器）
```

或直接运行源码目录中的应用：

```{r, eval = FALSE}
shiny::runApp("inst/shiny/app")
```

---

### 0.3 整体流程

```
DepMap 参考数据 ──► 模型训练 ──► 克隆/患者预测 ──► 可视化与验证
      ▲               ▲             ▲                 ▲
   Data 页         Train 页     Predict 页        Visualize 页
（或直接加载     （或直接用    （选模型后
  预训练模型）    44 药预训练   一键预测）
                 模型，跳过）
```

> 提示：想最快看到效果，按 **Load Demo →  Predict → Visualize** 的顺序点击即可，全程不需要训练。

> **异步架构（多用户友好）**：训练、聚类（prepare_data）、预测、绘图等**耗时计算全部在后台独立进程（worker）中执行**，界面进程只负责显示和收发文件，因此一个用户运行大任务时，其他用户的操作完全不受影响。
>
> - **训练**：标准 DepMap 走**共享 master**（全局一个后台进程，加载一份 DepMap，Linux 上并行任务共享同一份内存，空闲 12 小时自动退出释放内存）；用户上传的 DepMap 走**专属隔离 worker**，互不污染。
>
> - **聚类 / 预测 / 绘图 / Load Demo**：每个会话一个轻量 worker 处理，计算结果写回文件后界面自动刷新。
>
> - **环境变量**（部署时可选）：`PERCEPTION_WORKERS`（共享池并行任务数，默认 16）、`PERCEPTION_WORKER_IDLE_MINUTES`（master 空闲退出分钟数，默认 720）。

---

## 1. 界面总览

![PERCEPTION-shiny 首页](../man/figures/shiny-home.png)

顶部导航栏包含 6 个标签页：**Home、Data、Train、Predict、Visualize、Help**。数据从左向右流动：先加载数据（Data），再训练/加载模型（Train），然后预测（Predict），最后可视化与验证（Visualize）。

首页包含：介绍、四步引导（Load Data → Train Model → Predict → Visualize，点击可跳转到对应页面）、数据加载状态一览、功能特性与引用信息。页面上的 **Quick Start** 与 **Load Demo** 按钮可一键加载演示数据。

---

## 2. Data 模块：加载数据

Data 页是分析的起点，负责加载四种数据：**演示数据 / DepMap 参考数据 / 用户表达矩阵 / 临床响应**。每一项加载成功后，左侧状态徽章会变绿。

> **Load Demo**：
>
> 点击 **Load Demo** 一键生成合成演示数据：**49 个基因 × 400 个细胞 × 20 例患者**，并自动完成 Seurat 聚类、秩归一化，随后训练演示模型。用于快速测试整个流程，感受各功能页的交互方式。

---

### 2.1 加载 DepMap 参考数据（训练必需）

两种方式：

1. **Download & Load**：点击按钮自动从官方镜像下载 DepMap 参考集（约 567 MB，1.5 万+ 基因 × 1,000+ 细胞系），下载完成后自动加载。这是标准训练/参考输入，也是内存和磁盘占用最大的步骤。

2. **本地上传 .RDS**：如果本地已有 DepMap 文件（`DepMap.RDS` 格式），直接 Browse 选中即自动加载。

> **关于内存（重要）**：界面进程只读取 DepMap 的**元数据**（基因名、药物列表、各组件维度，几百 KB）；完整的多 GB 对象由后台 worker 在**独立进程**中加载，专供模型训练使用。因此多个用户同时使用也不会每个会话各占一份 8 GB 内存（参考架构说明见 0.3 节）。

---

### 2.2 加载模型

两种方式：

1. **Download & Load**：一键下载 44 种 FDA 批准药物的预训练模型（如 `abemaciclib`、`erlotinib`、`osimertinib`），多选时每项右侧有 × 可单独删除

2. **本地上传 .RDS**：选择训练好的模型文件（`train_models()` 或 Train 页导出的 RDS），选中即自动加载

---

### 2.3 上传表达矩阵（患者 scRNA-seq）

- **支持的格式**：CSV / TSV / TXT / Excel（.xlsx/.xls）/ RDS

- **支持的 R 对象**（RDS）：需为数值矩阵或 data.frame（基因 × 细胞）；不支持直接传入 Seurat 对象，请先导出为矩阵

- **矩阵方向**：基因 × 细胞（行为基因、列为细胞）；若第一列是基因名字符列（Excel/csv 导出常见），会自动转为行名

- **关于归一化**：表达数据需要是**秩归一化**（rank-normalized）后使用。若上传的是原始计数，勾选后由应用在聚类流程中自动归一化。

---

### 2.4 上传细胞-患者映射（Mapping）

- **支持的格式**：CSV / TSV / TXT / Excel / RDS

- **必须包含两列**：`cell_id`（细胞名，与表达矩阵列名一致）和 `patient_id`（细胞所属患者）。列名大小写均可（`Patient`、`PATIENT` 都能识别）

- **RDS 命名列表**：若 RDS 是"患者 → 细胞名向量"的命名列表（如论文 demo 的 `PRJNA591860_sample_cell_names.RDS`），会自动转换为长格式；无细胞的空样本自动丢弃

---

### 2.5 上传临床响应（Response，可选但推荐）

- **支持的格式**：CSV / TSV / TXT / Excel / RDS

- **必须包含两列**：`patient`（与 Mapping 的 `patient_id` 完全一致）和 `response`（患者对药物的真实临床结局）

- **响应值自动归一化**：`responder` / `responsive` / `r` / `sensitive` → **Responder**；`non-responder` / `nr` / `resistant` → **Non-responder**

- 上传时会自动检查 patient 是否与 Mapping 对齐；若完全不重叠会发出警告

- **为什么需要**：只有知道真实结局，才能验证预测准不准（画 ROC、响应者/非响应者箱线图）。只想看预测分数可以不传

---

### 2.6 聚类分群（Seurat）

*Don't Forget to Run Seurat!*

可选择分群方法：UMAP / tSNE。

| 参数 | 说明 | 建议 |
|---|---|---|
| Seurat Resolution | 聚类分辨率，越大分群越细 | 0.5–1.0 |
| Seurat Dims | PCA 降维使用的维度数 | 10–30 |
| Seurat NFeatures | 高变基因数（用于聚类），应用中固定为 2000（不可调） | — |

> Notes：聚类用于定义clone（细胞亚群），后续预测会以克隆为单位进行。

![Data 标签页聚类](../man/figures/shiny-data-clustering.png)

---

## 3. Train 模块：训练模型（可选）

**前置条件**：需先在 Data 页加载 DepMap 参考数据（若缺失，页面顶部会提示）。

> 如果只是想用现有模型预测，**完全可以不训练**——直接用 Data 页加载的 44 个预训练模型即可。Train 页适合：换药物、换癌症类型、自定义基因集、想查看模型在三种数据验证集上的表现。

---

### 3.1 参数说明

| 参数 | 说明 |
|---|---|
| **Drug Name** | 自由文本输入框，每行一个药名或用逗号/空格分隔（支持组合用药） |
| **Cancer Type (include)** | 训练包含的癌种，默认 PanCan（泛癌） |
| **Cancer Type (exclude)** | 排除的癌种（防止自我验证） |
| **Gene Symbols** | 基因列表，留空 = 使用 DepMap 全部基因（推荐）；可粘贴文本或上传 .txt/.csv |
| **Top k Features** | 特征排名取前 k 个基因进入模型 |
| **Algorithm** | 弹性网络 `glmnet`（推荐）或随机森林 `rf` |
| **CPU Cores** | 并行核数 |

---

### 3.2 结果解读

- **Model Summary**：每个药物的模型类型与超参数（glmnet 的 alpha/lambda，或 rf 的 ntree/RMSE）

- **Performance Plot**：模型性能曲线（阈值-相关关系）

- **Performance Metrics**：模型在 **Bulk / Pseudo-bulk / Single-cell** 三个层面上的预测-真实相关系数与 p 值。相关系数越高、p 值越小 = 模型越好

- **Download Model (.RDS)**：导出训练好的模型，可日后在 Data 页直接上传复用

![模型 Validation ROC 曲线（Train 页）](../man/figures/shiny-validation-roc.png)

**Validation ROC** 展示训练好的模型在三个验证数据集（Bulk / Pseudo-bulk / Single-cell）上区分 Responder 与非 Responder 的能力，含各数据集 AUC——AUC 越高说明临床分层能力越强。与 Performance Plot 一样，仅对 Train 页训练 / `train_models()` 产出的模型可用。

---

## 4. Predict 模块：预测杀伤值

选择已加载的模型（Data 页加载的预训练模型或 Train 页训练出的模型），点击预测：

1. **Clone-level（克隆级）**：每个克隆 × 每个药物的活力分数。分数语义：模型输出的是 **viability（存活度）**，**值越高 = 越耐药、越低 = 越敏感**；预测热图展示的是模型原始预测值（未归一化）；棒棒糖图和 UMAP Drug Viability 使用 z-score（以 0 为中心，可负）

2. **Patient-level（患者级）**：按克隆占比把克隆分数聚合到患者（默认 `weighted_max`），得到每例患者的药物敏感性分层

输出包括交互式热图（克隆 × 药物，plotly）与可下载的预测表格。

![Predict 标签页克隆×药物热图](../man/figures/shiny-predict-heatmap.png)

---

## 5. Visualize 模块：可视化

此模块用于将预测结果进一步可视化，故而必须先进行预测。

所有图表均为**交互式 SVG**（基于 ggiraph）：鼠标悬停任意点/条即可看到详细信息（克隆 ID、杀伤分数、占比、FPR/TPR 等）。图内工具栏禁用了缩放；导出为 PNG/PDF 使用页面顶部的下载按钮。

---

### 5.1 Clone Distribution（stackplot）

![克隆分布堆叠条形图](../man/figures/shiny-clone-distribution.png)

展示每例患者内部各克隆的占比构成，一个色带 = 一个克隆（≤15 个克隆时使用内置协调色板）。

> 注意：克隆身份取决于数据来源——全局聚类路径下，同一克隆（同色）确实跨患者共享；克隆级输入（如按患者编号的 c1/c2/c3）时，**跨患者颜色相同不代表同一克隆来源**，它只是共享的类别标签。

---

### 5.2 Clone Viability（lolliplot）

![克隆活力棒棒糖图](../man/figures/shiny-lollipop.png)

- **展示规则**：全样本、全克隆展示，一例患者一个分面，一根棒 = 一个克隆

- **颜色**：蓝-白-红发散——蓝 = 预测敏感（低活力），红 = 预测耐药（高活力）。色标范围随数据自适应，极端 z-score 仍有真实颜色（不会变灰/无色）

- **点大小**：克隆占比（占比大的克隆点大）

- **排序**：患者内按占比降序；有响应数据时 Responder 排在前面

- **y 轴**：Predicted Viability（z-score），0 线为中位参考

> **Combination（联合）模式**：Drug Name 下拉框默认选中 **Combination**，用于多药联合（如论文的 DARA–KRD 骨髓瘤队列）。合成规则与论文 Fig. 2 完全一致——克隆级：先把每个药的克隆级 viability 跨全部克隆做全局 z-score，再逐克隆取 `min`（IDA 原则：联合疗效由组合中**最有效**的那一药决定，对应论文 `pmin(z_carfilzomib, z_lenalidomide)`）；患者级：取**最耐药克隆 × 其丰度占比**的加权最大值（`weighted_max`，论文 5 种策略中 AUC 最高的第 5 种）。棒棒糖图中每根棒 = 一个克隆的**联合** z-viability。

---

### 5.3 ROC Curve

![ROC 曲线](../man/figures/shiny-roc.png)

使用真实临床响应（Data 页上传的 Response）与患者级预测分数绘制 ROC 曲线，AUC 越接近 1 说明预测分层能力越强。Drug Name 选 **Combination**（默认）时使用患者级**联合分数**（`weighted_max`，对应论文 Fig. 2e）；选单个药物时查看该药的 ROC（对应各单药视图）。

---

### 5.4 Response Boxplot（R vs NR）

![响应箱线图（R vs NR）](../man/figures/shiny-boxplot.png)

分组展示 Responder 与 Non-responder 的预测分数分布，附带显著性检验结果。同样地，选 **Combination**（默认）即展示联合分数的 R/NR 分布（对应论文 Fig. 2d）。

---

### 5.5 Model Performance

![模型性能图](../man/figures/shiny-model-performance.png)

该图位于 **Train 页**（对应 3.2 节 Performance Plot），不属于 Visualize 页。展示训练模型的验证性能曲线（需 Train 页训练的模型；预训练模型不适用，页面会提示）。

---

### 5.6 空间图（UMAP / t-SNE）

![UMAP 基因表达](../man/figures/shiny-gene-expression.png)

基因表达视图按每个细胞的单基因表达量着色。数值经 5th–95th 百分位压缩到 [0, 1]，再以灰→红渐变显示：灰色表示无或低表达，红色表示高表达。用来查看基因在哪些细胞群中高表达。

![UMAP 药物活力](../man/figures/shiny-drug-viability.png)

药物活力视图按每个细胞所属克隆的预测活力分数着色，形成拼接色块：红色块为预测耐药（高活力），蓝色块为预测敏感（低活力）。它显示耐药与敏感亚克隆在嵌入空间中的位置。

![UMAP 克隆身份（全局聚类）](../man/figures/shiny-clone-identity.png)

克隆身份视图按克隆（聚类）着色，展示分群结构。它是连接前两张图的参照：当某个克隆区域在活力图中呈红色、在基因表达图中也呈红色时，该基因与该耐药在空间上对应。

三张图对照读法：若某群细胞基因表达高、在活力图中也呈暖色（高活力），说明该基因高表达与预测耐药正相关；反之则与敏感相关。注意两张图色标刻度不同，只比较空间分布模式，不要比较绝对值。

---

### 5.7 高清下载

| 格式 | 分辨率 |
|---|---|
| PNG | 600 dpi（Cairo 抗锯齿），默认约 6000 × 4200 像素 |
| PDF / SVG | 矢量格式，无限缩放，推荐投稿使用 |

---

## 6. Help 页

内置帮助文档，包含各页功能说明、FAQ 与使用建议。遇到问题时请优先查看。

---

## 7. 常见问题（FAQ）

**Q1：上传提示 "Maximum upload size exceeded"，或返回 HTTP 413？**
两者不同。应用侧上限是 1 GB；而 **413 是应用前面的反向代理**在请求到达 R 之前返回的，通常是 nginx 的 `client_max_body_size` 默认值 1 MB —— 所以表现为**表达矩阵传不上去（几十到几百 MB），而 mapping / response 两张小表正常**。若服务器由你管理，在代理配置里放开：

```nginx
server {
    client_max_body_size 1024m;   # 默认是 1m
    client_body_timeout  600s;
    location /shinyapps/ {
        proxy_pass http://127.0.0.1:3838/;
        proxy_request_buffering off;   # 大文件直接透传，不落盘缓冲
        proxy_read_timeout 3600s;
    }
}
```

另外，减少需要传输的字节数同样有效：把矩阵存成 `.csv.gz` / `.tsv.gz` / `.txt.gz` 上传（gzip 通常能压到 1/3 ~ 1/5），或用本身就是压缩格式的 `.rds`。DepMap 优先用 "Download & Load" 按钮（服务器直下，不经浏览器）。

**Q2：Model Performance 图提示缺少 performance 字段？**
该图需要训练流程产生的验证指标，预训练模型（`load_model`）不携带。请先用 Train 页训练，或在 Data 页加载演示模型。

**Q3：response 标签怎么构造？**
构造两列 `patient` / `response`。`patient` 必须与 Mapping 的 `patient_id` 完全一致；`response` 取值会自动归一化（responder → Responder 等）。响应标签保留多组（如 TN/RD/PD），不做时间点折叠；ROC 需要二分类时，由用户在可视化页选择两组进行比较。

**Q4：预测分数和我想的不一样？**
预测分数是模型基于 DepMap 训练得到的相对排名（未归一化）：预测热图展示的是模型原始预测值，棒棒糖图与 UMAP Drug Viability 使用 z-score（以 0 为中心，可负）。数值越高表示在该批次克隆中越耐药（活力越高），不代表绝对杀伤比例。多克隆异质性、耐药通路激活都会拉高分数（活力升高）。

**Q5：关闭应用后数据会留下吗？**
会保留。DepMap 数据缓存在持久化目录（Windows：用户数据目录，Linux 可用环境变量 `PERCEPTIONX_DEPMAP_CACHE_DIR` 指定）。应用关闭后文件仍留在磁盘，且**永远不会被自动删除**——服务器管理员预先下载好的缓存会被所有用户直接复用，约 567 MB 的下载只会发生一次。

**Q6：为什么点训练/聚类/预测/画图时界面不卡？**
训练、聚类、预测、绘图都在**后台独立进程（worker）**中运行，界面只做轮询和显示进度，因此大任务执行期间仍可正常操作其他页面。若后台进程意外中断（极少数情况），页面会提示 "Background worker stopped" 而非一直转圈；重新点击提交即可。

---

## 8. 引用与联系

若使用本应用/包，请同时引用包本身与原始方法学论文：

- **Jia Ding**. PERCEPTIONx: Personalized Drug Response Prediction from Single-Cell Transcriptomics. R package version 0.3.0. <https://github.com/WangLabCSU/PERCEPTIONx>
- **Sinha, S., Vegesna, R., Mukherjee, S.** *et al.* PERCEPTION predicts patient response and resistance to treatment using single-cell transcriptomics of their tumors. *Nature Cancer* 5, 938–952 (2024). DOI: [10.1038/s43018-024-00756-7](https://doi.org/10.1038/s43018-024-00756-7)

**仓库**：[github.com/WangLabCSU/PERCEPTIONx](https://github.com/WangLabCSU/PERCEPTIONx)

**问题反馈**：jiading682@qq.com

---

*PERCEPTION-shiny © PERCEPTIONx authors. 本文档为使用教程，具体界面以实际版本为准。*