mageck

MAGeCK 混合筛选分析

使用时机

使用此技能将现有测序读段与提供的引导文库进行计数，或比较已经计数的混合筛选。交付计数矩阵、QC、引导和基因结果、对比来源，以及对富集/耗竭的简短解读。此工作流用于分析筛选；它不设计引导，也不仅凭一个命中推断基因功能。

运行时

经测试的源安装和外部运行时注意事项见 references/runtime.md。在分析前请验证 mageck --version 和 mageck test --help。随附的 Python 辅助程序仅使用标准库。 MAGeCK 本身还需要 NumPy、SciPy 和 RRA 二进制文件。PDF/R 报告是可选的，辅助程序不需要它。

官方发布目录 仍将 0.5.9.5 列为最新的 MAGeCK 版本。上游现在链接到单独的 MAGeCK2 项目；这些命令和辅助程序针对 MAGeCK 0.5.9.5，而不是可互换的 MAGeCK2 安装。这是一个本地命令行工作流，没有 服务 API 或身份验证。

工作流

1. 确认文库版本、扰动方式、样本名称、选择方向、 生物学重复、基线材料、时间点和批次。将测序 lane 与独立的生物学重复区分开。质粒基线和细胞第零天基线 回答的是不同问题。要求明确指定处理/对照对比；该辅助工具 绝不会默默将所有未使用的样本分配给对照组。
2. 验证一个无表头 TSV 文库，其中包含 guide ID、DNA 序列、基因。ID 和 序列必须唯一。该辅助工具要求计数表表头以 sgRNA、Gene 开头， 后跟唯一的非数字样本名称，例如 c1。MAGeCK 可能会将数字名称 解释为列索引或计数值；请在分析前重命名它们。Guide/基因 ID 不得包含 空白字符。该辅助工具会拒绝有歧义的序列，以及任何计数/文库 ID 或基因不匹配； 请在上游显式解决有意的多靶标 guide。这些是该辅助工具有意设置的 限制；原生 MAGeCK 也接受其他输入变体。
3. 对于 FASTQ，检查读段结构和已知 guide 序列，以确定修剪和 方向。使用 MAGeCK count，每个生物学样本对应一个以空格分隔的参数； 仅当这些 lane 是同一生物学样本的技术重复时，才用逗号连接。当比对效果较差时， 保留未比对读段和计数汇总证据。零计数的 guide 仍保留 在文库中；不要为了改善 QC 而将其丢弃。
4. 在统计检验之前运行 QC。检查文库代表性、每个 guide 的中位读段数、 零值比例、Gini 系数以及同一条件内重复样本间的相关性。该 辅助工具的 10% 零值和 0.8 相关性标记是审查提示，而非通用的可接受 阈值。高相关性可能与系统性伪影并存。读段深度并不等于 实验细胞覆盖度。该辅助工具使用原始计数的总体 Gini；MAGeCK 原生 计数汇总 Gini 使用带有限样本校正的 log(count + 1)。不要将它们 的值或阈值当作同一种统计量进行比较。
5. 根据筛选选择归一化方法。中位数归一化假设大多数 guide 是 稳定的。对于强烈的全局偏移，提供的经验证阴性对照 guide 可能支持 --normalization control。这些必须是guide ID，每行一个；基因列表不能 替代它们。生物学对照样本和阴性对照 guide 扮演不同 角色。必须至少有两个对照，并且每个被分配至对照基因的 guide 都必须被指定为对照。提供 --control-guides 也会改变 RRA 零分布， 即使使用中位数归一化也是如此。记录它们的来源并检查其计数分布。 MAGeCK 0.5.9.5 会在任一选定样本的中位数 为零或 零值 guide 超过 45% 时，将中位数归一化切换为总计数缩放；对于对照归一化，它会评估 对照 guide 子集。检查报告中应用的方法、大小因子和警告。
6. 使用 test 进行两组比较。--paired 要求两个列表按对应的 生物学顺序排列且长度相等；仅长度匹配并不能确立配对关系。 该辅助工具报告双向达到所请求 FDR 的基因，并保留完整排名。 对于多因素设计，请参见 references/design.md；不要将 批次或时间序列强行合并为缺乏依据的两组检验。
7. 检查主要基因的 guide 一致性、适用情况下的必需基因恢复情况、 阴性对照、重复样本一致性，以及核酸酶敲除筛选中的拷贝数伪影。 在报告 FDR 的同时报告效应量。富集的 guide 可能表明抗性、 生长优势或采样伪影，具体取决于选择方式；耗竭并不一定 意味着普遍必需性。缺乏重复或低计数 guide 会削弱推断。

命令

运行路径相对于已安装的技能目录。输入和输出路径指用户的分析目录。该辅助工具拒绝复用已存在的结果目录。

# Single-end guide reads; trim and orientation must match the user's library preparation.
mageck count -l library.tsv --fastq c1.fastq.gz c2.fastq.gz t1.fastq.gz t2.fastq.gz \
  --sample-label c1,c2,t1,t2 --trim-5 0 --norm-method none -n counts

python scripts/screen_analysis.py qc --counts counts.count.txt --library library.tsv \
  --control c1 c2 --treatment t1 t2 --output qc.json

python scripts/screen_analysis.py test --counts counts.count.txt --library library.tsv \
  --control c1 c2 --treatment t1 t2 --normalization median --fdr 0.05 --output result

FASTQ 命令结构已使用合成的双 guide 文库进行验证：30 和 12 的计数被精确恢复。一个单独的经过修剪、反向互补、双 lane 的测试样本恢复了 15、7 和 0 条读段。双组辅助工具已在非配对和配对模式下使用 500 个 guide 和每个条件两个重复进行验证；已知的耗竭和富集基因分别在各自方向上排名第一，并通过了 FDR 0.05。稀疏测试样本验证了总量归一化的回退机制。这些测试确立了执行和信号方向，而非真实筛选的统计校准。上述真实文件路径仅为示例。

result/report.json 记录 count/library/control-guide SHA-256、control-guide ID、MAGeCK 版本、实际参数、QC、应用的归一化、警告、命中方向、FDR、log2 倍数变化和排名。该辅助工具显式选择中位数 guide LFC 聚合和 --remove-zero both：全零 guide 保留在输入/QC 中，但被排除在排名之外。原生 MAGeCK 默认也会跳过 NA/na 基因标签。该辅助工具的 --fdr 过滤已完成的基因结果；它不设置 MAGeCK 的 --gene-test-fdr-threshold，后者控制 RRA guide 选择截断值。负向和正向 FDR 是独立的族；它们的并集并不能确立跨方向或跨多个对比的联合 FDR 控制。screen.gene_summary.txt、screen.sgrna_summary.txt、归一化计数和执行日志保留了完整证据。在分析交接中包含原始文库、样本表和阴性对照列表；计数校验和无法重建它们。

主要参考

• MAGeCK 用法和命令语义
• 官方安装指南
• 输入格式
• 输出字段含义