OmicClaw 图文教程#
目录#
安装
启动服务
界面概览
上传数据
预处理
降维与可视化
聚类
细胞注释
差异基因分析
差异细胞组成分析
轨迹分析
代码执行器
AI Agent
文件管理与终端
远程服务器部署
1. 安装#
OmicClaw 提供两种安装方式。
方式一：PyPI 安装（推荐）#
pip install omicclaw
方式二：从源码仓库安装#
适合需要最新开发版本或希望参与贡献的用户：
git clone https://github.com/Starlitnightly/omicclaw.git
cd omicclaw
pip install -e .
推荐：在独立的 conda 环境中安装，避免依赖冲突。
conda create -n omicverse python=3.10 conda activate omicverse pip install omicclaw
2. 启动服务#
安装完成后，在终端执行：
omicclaw
服务默认在 http://localhost:5050 启动（端口被占用时自动顺延至 5051、5052 …）。看到以下输出即表示启动成功：
* OmicClaw running on http://localhost:5050
在浏览器中打开该地址即可进入平台。
可选参数#
omicclaw --port 8080 # 指定端口
omicclaw --no-debug # 关闭调试模式（生产环境推荐）
omicclaw --remote # 远程模式（配合 SSH 隧道）
3. 界面概览#
打开 http://localhost:5050 后，点击首页的 Launch Analysis 按钮进入主分析界面。
主分析界面分为三个区域：
左侧边栏
📁 文件浏览器：管理本地文件，支持右键菜单操作
🧬 变量查看器：实时查看内核中的变量
💻 终端面板：浏览器内置 shell
📊 内存监控：实时查看内存占用
顶部选项卡 按分析流程排列：预处理 → 可视化 → 聚类 → 注释 → DEG → DCT → 轨迹
右侧主区域 当前选项卡的操作面板和结果展示区
4. 上传数据#
点击顶部工具栏的 Upload 按钮（或将文件拖入文件浏览器），选择本地的 .h5ad 文件。
上传成功后，状态栏会显示数据基本信息：
✓ 数据已加载
细胞数：8,542 | 基因数：33,538
支持格式：标准 AnnData
.h5ad文件。 如需从其他格式转换，可先在代码执行器中使用scanpy读取后保存为.h5ad。
5. 预处理#
切换到 Preprocessing 选项卡，按以下顺序依次执行各步骤。
5.1 过滤细胞和基因#
点击 Filter Cells / Filter Genes 工具卡，设置过滤阈值：
参数 |
含义 |
推荐值 |
|---|---|---|
Min genes per cell |
每个细胞最少检测到的基因数 |
200 |
Max genes per cell |
上限（去除潜在双细胞） |
5000 |
Min cells per gene |
每个基因至少在几个细胞中表达 |
3 |
Max mito % |
线粒体基因比例上限 |
0.2 |
点击 Run 执行，右侧会展示过滤前后的细胞/基因数量对比。
5.2 标准化#
点击 Normalize，将每个细胞的总 UMI 计数归一化到统一基数（默认 10,000）。
5.3 对数变换#
点击 Log1p，执行 log(1+x) 变换，压缩数据分布。
5.4 高变基因选择#
点击 HVG，选取信息量最丰富的基因用于后续分析：
参数 |
推荐值 |
|---|---|
Top genes |
2000 |
Flavor |
seurat_v3 |
5.5 数据缩放#
点击 Scale，对每个基因做 z-score 标准化，max_value 默认为 10。
6. 降维与可视化#
切换到 Visualization 选项卡。
6.1 PCA#
点击 PCA，设置主成分数（默认 50），点击 Run。
6.2 构建邻居图#
点击 Neighbors：
参数 |
推荐值 |
说明 |
|---|---|---|
n_neighbors |
15 |
近邻数，影响 UMAP 的局部/全局结构权衡 |
n_pcs |
40 |
使用前 N 个 PC |
6.3 UMAP#
点击 UMAP，执行后在右侧画布中即可看到嵌入图。
6.4 调整可视化参数#
在图表上方的控制栏可以：
切换 Color by：按基因表达量、细胞元数据或聚类着色
调整 点大小 和 透明度
切换渲染模式（标准 / 栅格化 / GPU）
GPU 渲染模式：细胞数超过 10 万时推荐开启，基于 WebGL 实现实时流畅交互。
7. 聚类#
切换到 Clustering 选项卡。
Leiden 聚类（推荐）#
参数 |
说明 |
|---|---|
Resolution |
分辨率，值越大聚类越细（推荐 0.3–1.0） |
点击 Run 后，聚类结果自动写入 adata.obs['leiden']，UMAP 图同步更新着色。
8. 细胞注释#
切换到 Annotation 选项卡，提供三种注释方式。
8.1 CellTypist（推荐，基于预训练模型）#
选择与样本类型匹配的模型：
模型 |
适用场景 |
|---|---|
Immune_All_Low.pkl |
免疫细胞细粒度分类 |
Immune_All_High.pkl |
免疫细胞粗粒度分类 |
Human_Lung_Atlas.pkl |
人肺细胞 |
勾选 Majority Voting（邻域投票，提升一致性），点击 Run。
8.2 SCSA（数据库匹配）#
选择物种（Human / Mouse），指定聚类列（leiden），点击 Run。
8.3 AI 辅助注释（GPT-4）#
填写 OpenAI API Key，设置每个 cluster 展示的 marker 基因数（默认 10），点击 Run。AI 会根据 marker 基因推断细胞类型并生成文字解释。
9. 差异基因分析#
切换到 DEG 选项卡。
9.1 设置对比#
Group by：选择分组依据列（如
cell_type或leiden）Group 1：选择实验组
Group 2：选择对照组（或选
rest代表其余所有细胞）Method：选择统计方法（wilcoxon / t-test / mannwhitney）
点击 Analyze。
9.2 查看结果#
分析完成后自动展示：
火山图：横轴 Log2FC，纵轴 -log10(p-value)，点击数据点高亮该基因
结果表格：列出所有差异基因及统计量，可按 FDR 或 Log2FC 排序
Violin 图：在表格中点击任意基因，右侧自动展示该基因在两组中的表达分布
10. 差异细胞组成分析#
切换到 DCT 选项卡，分析不同样本条件下各细胞类型比例的变化。
配置参数#
参数 |
说明 |
|---|---|
Cell type column |
细胞类型列名（如 |
Sample column |
样本标识列名 |
Condition column |
条件列名（如 |
Reference cell type |
参照细胞类型（sccoda 必填） |
Method |
sccoda 或 Milo |
点击 Run 后展示：
组成条形图：各样本的细胞类型比例堆叠图
效应量图：显示各细胞类型在条件间的显著变化
12. 代码执行器#
如需自定义分析，点击右上角 Code 按钮打开内置代码编辑器。
内核预注入以下变量，可直接使用：
sc # scanpy
pd # pandas
np # numpy
plt # matplotlib.pyplot
odata # 当前 AnnData 对象
示例：
# 查看数据结构
print(odata)
# 查看某个基因的表达分布
import matplotlib.pyplot as plt
sc.pl.violin(odata, keys='CD3D', groupby='leiden')
plt.show()
# 保存当前分析结果
odata.write_h5ad('result.h5ad')
按 Shift+Enter 执行代码，输出实时显示在编辑器下方。
13. AI Agent#
AI Agent 可以理解自然语言，自动生成并执行分析代码。
13.1 配置#
点击侧边栏 Agent 图标，展开配置面板：
字段 |
说明 |
|---|---|
API Key |
Claude / OpenAI API Key |
Model |
如 |
Endpoint |
自定义 API 端点（可选，兼容 OpenAI 格式） |
13.2 使用方式#
在对话框中输入任务描述，按 Send：
示例提示词：
对当前数据做 leiden 聚类（分辨率 0.5），然后用 UMAP 展示结果，按聚类着色
分析 CD4 T cells 和 CD8 T cells 之间的差异基因，找出 top 20，画火山图
我的数据有多个批次（batch 列），请用 Harmony 做批次校正并重新计算 UMAP
Agent 会逐步展示：思考过程 → 生成代码 → 执行 → 返回结果图表。
14. 文件管理与终端#
14.1 文件浏览器#
点击左侧边栏 📁 图标展开文件浏览器。
支持操作（右键菜单）：
新建文件夹 / 文件
重命名 / 删除 / 复制 / 粘贴
双击打开
.h5ad、.ipynb、文本文件和图片
📷 [截图：文件浏览器和右键菜单]
14.2 内置终端#
点击左侧边栏 💻 图标，创建 shell 会话（bash / zsh），可执行任意命令：
# 安装额外包
pip install harmonypy
# 查看 GPU 状态
nvidia-smi
# 运行自定义脚本
python my_analysis.py
14.3 包管理#
在 Environment 面板中搜索并安装 Python 包，无需切换到终端：
15. 远程服务器部署#
如需在远程服务器上运行，通过 SSH 隧道在本地浏览器访问。
服务器端#
# 安装
pip install omicclaw
# 启动（远程模式，仅监听本地回环）
omicclaw --remote --no-debug
本地建立 SSH 隧道#
ssh -L 5050:127.0.0.1:5050 username@your-server.com -N
然后在本地浏览器打开 http://localhost:5050 即可。
后台持久运行#
nohup omicclaw --remote --no-debug > omicclaw.log 2>&1 &
参考资料#
PyPI 包：
omicclaw论文：OmicVerse: a framework for bridging and deepening insights across bulk and single-cell sequencing, Nature Communications (2024), 15:5983