Cactus输入避坑清单seqfile、Contig命名与软掩膜的7个常见问题【免费下载链接】cactusOfficial home of genome aligner based upon notion of Cactus graphs项目地址: https://gitcode.com/gh_mirrors/cact/cactusCactus 是一款无参考系全基因组比对与泛基因组图构建工具输入准备是否得当直接决定运行速度与结果质量。本文整理了 Cactus 输入环节最常见的 7 个坑seqfile 格式与命名错误、Contig 序列头命名不规范、软掩膜缺失或过度掩膜并给出运行前自查清单帮助新手一次跑通 Cactus 基因组比对。1️⃣ seqfile 怎么写先搞懂它的两种形态Cactus 有两条主流流水线它们的 seqfile 并不相同Progressive Cactus跨物种比对第一行是 NEWICK 系统发育树后面每行一个基因组名 序列路径对Minigraph-Cactus同物种泛基因组两列样本名 序列路径不需要树。官方示例 seqfile 见examples/evolverMammals.txt格式规则如名称唯一性、路径不含空格的解析逻辑在 seqFile.py 中实现可对照检查自己的文件。2️⃣ 坑一系统发育树不在同一行 / 有多分叉现象报错Failed to parse newick tree或比对该快的地方很慢、覆盖率下降。Cactus 要求 NEWICK 树必须写在一行内所有叶节点必须有标签且标签唯一且不再支持多分叉polytomy——因为多分叉会导致连锁覆盖下降。分支长度未给出时默认为 1。建议从已发表的树上复制时先删掉换行符物种太多时把多分叉拆成二叉结构。seqfile 中的树定义了渐进式分解Cactus 从树的底部开始把兄弟基因组两两比对、向上推断祖先每个新基因组挂到树上的过程如下图所示这也是为什么树写错整个比对拓扑都会跟着错。3️⃣ 坑二基因组名称重复或树与名称行不匹配这是新手最高频的报错解析器会直接抛错终止Duplicate name found: xxx—— 同一个基因组名在 name-path 行里出现了两次No sequence specified for xxx—— 树里有这个叶节点但下面没有对应的名称-路径行树叶节点少于 2 个At least two valid leaf genomes required——通常是某个名字拼写不一致导致被剔除。技巧树中的名字必须与 name-path 行逐字符一致区分大小写。另外名称行前可加*表示该组装是参考级质量、可用作外群*只能加在名称上不能加在树里。4️⃣ 坑三路径或名称里含空格seqfile 按空白符切分字段名称取第一个字段路径是剩余字段的拼接。因此序列路径本身不能含空格否则路径会被静默重组基因组名称里也不能有空格。如果你的 FASTA 文件路径带空格先移动文件或改用目录路径一个目录可包含多个 FASTA会被自动合并。5️⃣ 坑四Contig 序列头带空格、Tab 或首词重复Cactus 预处理阶段会执行严格的序列头检查逻辑见 checkUniqueHeaders.py每个序列头第一词内不能有空格或 Tab——因为 MAF 等按空格分隔的下游格式会直接解析错乱每个基因组内第一词必须唯一——两个chr1会在预处理早期直接报错。遇到不符合要求的头可以用仓库内置工具快速修复preprocessor/cactus_makeAlphaNumericHeaders.py把序列头压缩为纯字母数字preprocessor/cactus_sanitizeFastaHeaders.c按空白截断描述、把 IUPAC 歧义碱基如R/Y/S/W归一为N并丢弃空序列src/cactus/preprocessor/cutHeaders.py按指定字符切割前后缀。6️⃣ 坑五泛基因组样本名里的小数点 . 有特殊含义Minigraph-Cactus 中.用来表示单倍型命名规范是样本名.单倍型编号单倍体样本CHM13 ./chm13.fa不要带点二倍体样本HG002.1 ./HG002.paternal.fa/HG002.2 ./HG002.maternal.fa。如果你给单倍体样本随便命名成HG002.1但并非单倍型语义后续 VCF、GFA 路径命名都会错乱。另外注意 Contig 名规则详见 pangenome.md 的 Contig Names 一节名字形如HG002#0#chr1时cactus-pangenome会自动丢弃最后一个#之前的部分只留chr1:start-end后缀会被识别为区间1-based名字中非区间用途的:会在输出中被替换为_第一个空格之后的内容一律忽略且同名 Contig 允许跨文件重复、但同一文件内不能出现两次。输入 Contig 最终会以嵌入路径的形式出现在泛基因组图中下图是酵母 I 号染色体区段的 Cactus 泛基因组图图中的每条路径正对应一个输入组装的 Contig。7️⃣ 坑六没做软掩膜soft masking——最贵的一个坑Progressive Cactus 要求输入是软掩膜基因组推荐 RepeatMasker哺乳动物通常应有 40% 以上碱基被掩膜小写字母即被掩膜部分。后果非常直接未掩膜的重复序列会让 lastz 产出海量比对运行时间可长几十倍官方 FAQ 明确指出paf_tile、paf_to_bed等工具内存爆炸、崩溃几乎都是输入未软掩膜导致的。Cactus 自带基础掩膜作为兜底默认 red可用--maskMode fastan或 lastz 模式但兜底不能替代 RepeatMasker。运行前可用cactus_analyseAssembly工具见preprocessor/cactus_analyseAssembly.c检查掩膜比例。8️⃣ 坑七硬掩膜hard masking或全小写序列两个过度掩膜方向同样危险硬掩膜把重复整段替换成 N会强烈丢失比对——官方文档明确强烈不建议。Cactus 启动时会检查 N 比例若超过 30% 会警告你可能硬掩膜了全小写基因组Cactus 把所有小写字母都视为被掩膜若掩膜比例超过 70% 会警告你可能给了一个全小写基因组那样什么也比对不上去。解析器中对应检查逻辑在 seqFile.py 的sanityCheckSequence。注意Minigraph-Cactus 会忽略软掩膜信息做泛基因组不需要预先掩膜但同样不建议硬掩膜。输入准备充分时Cactus 能完整捕获重复与结构变异下图即为基于良好输入构建的 GRCh38 MHC 区域替代泛基因组图。9️⃣ 运行前 7 项自查清单 ✅#检查项出错信号1NEWICK 树在同一行、无多分叉、叶标签唯一Failed to parse newick tree2树中每个叶都有对应的 name-path 行No sequence specified for xxx3基因组名无重复、与树逐字符一致Duplicate name found4名称与路径不含空格路径被静默拼接错5序列头无空格/Tab第一词文件内唯一预处理阶段 RuntimeError6泛基因组样本按SAMPLE.1/2规范命名单倍型VCF/GFA 路径错乱7Progressive 输入已软掩膜≥40%哺乳类非硬掩膜慢几十倍、内存溢出、N 比例警告1️⃣0️⃣ 延伸资料渐进式比对的完整输入规范与掩膜选项doc/progressive.md泛基因组输入规范Sample Names / Contig Names 章节doc/pangenome.md预处理器主流程含掩膜、过滤小 Contigsrc/cactus/preprocessor/cactus_preprocessor.py小 Contig 过滤脚本preprocessor/cactus_filterSmallFastaSequences.py把这份清单贴在跑任务之前过一遍可以避开 Cactus 输入环节绝大多数报错。【免费下载链接】cactusOfficial home of genome aligner based upon notion of Cactus graphs项目地址: https://gitcode.com/gh_mirrors/cact/cactus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
