这是一个接受用户转录组表达数据、预测基因敲除后网络影响的开源项目。
当前版本是 v0.4.1：高清交互补丁。它提供无需代码的 Windows 图形界面，可以直接读取
.h5ad、10x MTX/ZIP 和文本表达矩阵；单细胞/单核数据使用 scTenifoldKnk，bulk
多样本数据使用独立的稳健关联网络扰动后端。输出是候选影响基因排序，不是真实敲除后
的表达矩阵。
开发环境安装完成后，直接双击：
启动虚拟敲除Agent.cmd
也可以运行：
uv run vk-agent-guiv0.4 采用三栏单屏布局：左侧显示四步工作流，中间显示动态基因网络，右侧完成数据导入、 敲除设置和结果查看。右栏会在低分辨率窗口中自动滚动；不常用参数集中在“高级设置” 弹窗内。界面按系统可用字体自动回退，避免中文或基因名显示异常。
动态网络用 待机、读取、运行、完成、错误 五种状态反馈任务进度；可勾选右上角 “减少动画”停用持续动画。结果完成后网络节点来自结果表中的候选基因。动画只负责展示 当前状态和已有结果，不会进行额外生物学推断，也不会改变 v0.3 的科学计算算法。
在中间网络中可按住任意节点（包括目标基因）单独拖动，按住空白区域可平移整个网络， 双击空白区域可恢复默认布局。窗口缩放后会保留节点的相对位置。Windows 版会按当前 显示器的真实 DPI 绘制界面，避免系统缩放造成文字、线条和圆环模糊。
操作流程只有四步：
- 选择表达数据文件、10x 文件夹或 10x ZIP；
- 确认自动识别的数据类型和矩阵方向；
- 输入目标基因并选择快速、标准或稳健方案；
- 点击“开始虚拟敲除”，完成后查看结果或导出 ZIP。
若 bulk 的非负整数矩阵其实已经是 TPM/FPKM 等连续表达，可在“高级设置”中把表达尺度 从“自动识别”改为“连续表达”，防止被当作原始 counts 再次归一化。
支持的数据入口：
| 数据 | 格式 | 后端 |
|---|---|---|
| 单细胞/单核转录组 | .h5ad |
scTenifoldKnk |
| 10x 表达矩阵 | MTX 三件套目录、ZIP 或直接选择 matrix.mtx[.gz] |
scTenifoldKnk |
| 单细胞文本矩阵 | .csv/.tsv/.txt[.gz] |
scTenifoldKnk |
| bulk RNA-seq/芯片多样本矩阵 | .csv/.tsv/.txt[.gz] |
bulk 关联网络扰动 |
本版“原始数据”指原始计数矩阵或 10x 输出，不直接读取 FASTQ/BAM。FASTQ 必须先经过 物种和参考基因组匹配、比对/伪比对及定量。空间转录组和单个 bulk 样本暂不支持。
- A0：数据审计（已完成）
检查 Perturb-seq
.h5ad数据契约，为后续真实扰动基准保留入口。 - B0：普通数据应用（当前） 使用 scTenifoldKnk 从未扰动数据构建 GRN，执行零样本虚拟敲除并输出候选影响排序。
- B1：可靠性增强（下一步） 增加重采样稳定性、负对照和真实 Perturb-seq 外部验证。
- B2：多后端比较 在同一报告中比较 GRN、简单基线和单细胞基础模型。
- v0.3 桌面与多输入层（已完成） 加入本地无代码界面、10x/文本统一导入和 bulk 多样本关联网络扰动。
- v0.4 动态实验台（当前） 加入三栏单屏、五状态动态网络、减少动画、字体回退、右栏滚动和高级设置弹窗； v0.4.1 增加高 DPI 清晰绘制、节点拖动、空白平移和视图复位；科学计算算法保持不变。
vk-agent predict 会自动执行：
- 读取普通单细胞
.h5ad，无需扰动或对照标签； - 可按
.obs中的细胞类型筛选； - 默认优先使用
countslayer，否则使用X； - 自动识别整数计数并执行 library-size 10000 +
log1p； - 限制最大细胞数和基因数，控制运行时间与内存；
- 检查目标基因是否存在、是否有足够表达与变异；
- 调用 scTenifoldKnk 构建 WT GRN 并执行虚拟敲除；
- 输出影响基因排序、机器可读运行记录和中文报告。
原有 vk-agent audit 命令仍可用于 Perturb-seq A0 数据审计。
bulk 后端接受 gene × sample 或 sample × gene 表达矩阵，界面会自动判断方向； 判断不明确时必须由用户确认。它会执行：
- counts 的文库大小归一化和
log1p，或沿用已归一化连续表达； - 低表达/零方差过滤和 MAD 高变基因选择；
- 固定随机种子的 bootstrap Spearman 关联网络；
- 同时清零目标节点的行和列，比较网络传播结构变化；
- 输出全精度效应距离、直接相关、95% bootstrap 区间和 Top-k 稳定性。
标准模式要求至少 20 个独立生物学样本；少于 15 个拒绝运行，15–19 个只能显式启用 低可信实验模式。技术重复不能当作独立样本。这个保守门槛参考 WGCNA 官方 FAQ 的样本量建议。
bulk 结果只能解释为“当前队列关联网络中依赖目标节点的候选基因”，不能解释为因果关系、
真实上调/下调或表达 logFC。
- Python 3.11
- uv
安装开发环境：
uv sync --dev运行测试：
uv run pytest
uv run ruff check .最小命令：
uv run vk-agent predict D:\data\pbmc.h5ad --target TP53只分析指定细胞类型：
uv run vk-agent predict D:\data\pbmc.h5ad `
--target TP53 `
--cell-type-key cell_type `
--cell-type T_cell `
--output-dir artifacts\pbmc_tp53显式选择表达来源并缩短试运行：
uv run vk-agent predict D:\data\pbmc.h5ad `
--target TP53 `
--layer counts `
--max-genes 500 `
--max-cells 2000 `
--n-networks 3 `
--seed 42表达来源可以是任意 layer 名、X 或 raw。重复运行时默认保护已有结果；
只有显式添加 --overwrite 才会覆盖三个同名 B0 输出文件。
每次成功运行都会在结果父目录下创建独立时间戳子目录，并写出：
| 文件 | 内容 |
|---|---|
predicted_effects.csv |
基因、网络效应距离、排名和模型内部统计量 |
run.json |
输入摘要、参数、随机种子、版本、警告和科学边界 |
report.md |
Top 候选影响基因和面向用户的中文说明 |
- 非空、非负的细胞 × 基因表达矩阵；
- 唯一的细胞和基因标识；
- 筛选后至少 50 个有效细胞和 20 个有信息量的基因；
- 目标基因至少在 5 个细胞中被检测到，并且具有表达变异；
- 基因名必须与
.var_names一致；当前不自动转换 gene symbol 和 Ensembl ID。
若 .h5ad 很大，Agent 最终仍需把筛选后的 GRN 输入转为稠密矩阵。默认最多使用
5000 个细胞和 1000 个基因；建议先用较小的 --max-genes 和 --n-networks
做试运行。
默认约定：
| 含义 | .obs 列名 |
|---|---|
| 扰动标签 | perturbation |
| 对照标记 | control |
| 细胞类型 | cell_type |
运行：
uv run vk-agent audit D:\data\example.h5ad如果数据使用其他列名：
uv run vk-agent audit D:\data\example.h5ad `
--perturbation-key gene_target `
--control-key is_control `
--cell-type-key cell_line `
--json-output artifacts\audit.json审计结果中的退出码：
0：满足 A0 必需数据契约；1：文件无法读取或参数错误；2：文件可读取，但缺少 A0 必需信息。
一个可用于首轮基准的数据集至少需要：
- 非空的细胞 × 基因表达矩阵；
- 唯一的细胞和基因标识；
- 至少两个扰动标签；
- 能区分对照与扰动细胞的字段。
细胞类型和明确的原始计数层目前属于推荐项，缺少时会产生警告。
大型 .h5ad、原始测序文件和模型产物不会提交到 Git。仓库只保存代码、数据来源、校验值、预处理配置和实验结果摘要。
计划使用的公开资源：
虚拟敲除结果是计算预测，不等同于真实 CRISPR 实验：
- B0 使用观察性表达相关结构推断 GRN，不能单独识别因果效应；
effect_distance表示 WT 与伪 KO 网络中的差异调控距离，不是表达 fold change；p_value和adjusted_p_value是模型内部网络差异统计量；- 关键生物学结论必须结合 Perturb-seq、CRISPR、独立数据和领域知识验证。
方法与实现：