tooluniverse-microbial-genome-characterization

微生物基因组组装特征分析与质量控制

使用关键字免除的 NCBI Datasets 基因组工具，发现、质量控制并绘制任意生物的基因组组装结构图。输入生物/分类单元，输出组装清单、质量控制指标以及染色体/质粒图谱。

查数据，不要猜测

如果不确定登录号、组装级别、复制子数量或 N50，请调用工具。切勿凭记忆报告组装统计数据——每次 RefSeq 版本发布后，登录号和指标都会变化。实时查询 NCBI Datasets 始终比猜测可靠。

计算，不要描述

比较多个组装或按质量排名时，先用工具获取每个组装的数据，再编写并运行 Python（pandas）处理返回的 JSON，进行排序、评分和制表。不要只描述准备如何计算——实际执行并报告具体数值。

何时使用此技能

触发条件：

• “[生物]有哪些基因组可用？”/“查找 [分类单元] 的参考基因组”
• “GCF_000005845.2 的组装统计数据”/“[登录号] 的 N50 / GC 含量是多少？”
• “[菌株]有多少个质粒？”/“列出 [登录号] 中的复制子”
• “比较 [物种] 的组装——哪个质量最好？”
• “[登录号] 是完整基因组还是草图？”

使用场景：

1. 发现组装：列出某分类单元的可用组装，可选择仅包含参考级组装
2. 组装质量控制：获取某登录号的长度、N50、重叠群数量、GC%、级别和 RefSeq 类别
3. 复制子映射：列出染色体和质粒及其 RefSeq/GenBank 登录号与长度
4. 组装比较：按完整度和连续性对某物种的候选组装进行排名
5. 选择参考基因组：确定某分类单元指定的参考/代表基因组

不适用于此技能（请转至其他工具）：

• 基因层面的直系同源关系、共线性、保守性 → tooluniverse-comparative-genomics
• 植物基因结构/注释 → tooluniverse-plant-genomics
• 从测序读段进行从头组装 → 没有可用的 ToolUniverse 工具；请说明这一点
• 仅查询分类名称、不涉及基因组问题的谱系查询 → 直接使用 NCBI 分类工具

---

工具（均无需密钥，已通过实时验证）

工具	关键参数	返回内容
NCBIDatasets_suggest_taxonomy	query（生物名称字符串）	候选匹配项：scientific_name、tax_id、rank、group_name
NCBIDatasets_get_taxonomy	tax_id（字符串/整数）	organism_name、rank、lineage、children
NCBIDatasets_list_genomes_by_taxon	taxon（名称或 taxid）、limit、reference_only（布尔值）	组装列表（登录号、组装级别、refseq_category、total_sequence_length、contig_n50、gc_percent、number_of_chromosomes、number_of_contigs）；metadata.total_available = 总数
NCBIDatasets_get_genome_assembly	accession（GCF_/GCA_）	完整质量控制数据：total_sequence_length、number_of_chromosomes、number_of_contigs、contig_n50、scaffold_n50、gc_percent、assembly_level、assembly_status、refseq_category、release_date、submitter、annotation_provider
NCBIDatasets_get_sequence_reports	accession（GCF_/GCA_）	按复制子列出的清单：chr_name、role、refseq_accession、genbank_accession、length、gc_percent

参数说明：get_taxonomy 需要 tax_id（不是 taxon）。list_genomes_by_taxon 的 taxon 字段接受名称或 taxid。使用组装/序列报告工具时，始终传入登录号。

---

工作流

阶段 0 — 确认生物（如果已有登录号，则跳过）

如果用户提供了生物名称，请先将其解析为 tax id：

NCBIDatasets_suggest_taxonomy {"query": "Escherichia coli"}

选择 scientific_name/rank 与用户意图（物种或特定菌株）相符的候选项。也可以使用 NCBIDatasets_get_taxonomy {"tax_id": "562"} 确认谱系/子级分类单元。

如果用户已经提供 GCF_/GCA_ 登录号，请跳至阶段 2。

阶段 1 — 盘点组装

列出该分类单元的现有组装。先将 reference_only: true，以显示精选的参考/代表基因组；设为 false 则查看完整集合。

NCBIDatasets_list_genomes_by_taxon {"taxon": "562", "limit": 5, "reference_only": true}

读取 metadata.total_available 获取准确数量（大型分类单元会返回数千条记录——data 数组只包含前 limit 条记录）。记录每个候选组装的 assembly_level、refseq_category、contig_n50 和 number_of_contigs。

阶段 2 — 选择组装

按以下顺序优先选择：

1. refseq_category == "reference genome"（NCBI 指定的唯一参考基因组）
2. refseq_category == "representative genome"
3. 最高的 assembly_level（Complete Genome > Chromosome > Scaffold > Contig）
4. 同级候选中最高的 contig_n50 和最低的 number_of_contigs
5. 若 GCF_（RefSeq）和配对的 GCA_（GenBank）都存在，则优先选择 GCF_——RefSeq 是经过精选的副本

阶段 3 — 获取组装 QC 指标

NCBIDatasets_get_genome_assembly {"accession": "GCF_000005845.2"}

报告：总长度、染色体数、contig 数、contig N50、scaffold N50、GC 含量、组装级别、RefSeq 类别、发布日期、注释提供方。

阶段 4 — 映射复制子（染色体 + 质粒）

NCBIDatasets_get_sequence_reports {"accession": "GCF_000005845.2"}

每一行代表一个复制子。根据 chr_name / role 区分染色体和质粒：名称类似 pO157、pOSAK1 或其他质粒格式名称的行是质粒；chromosome 行是染色体。要回答“有多少个质粒”，请统计非染色体的已组装分子行。

阶段 5 — 比较候选组装（可选）

用户想从多个组装中选出最佳项时，获取每个登录号，构建 pandas 表，并按（组装级别排名、然后 contig_n50 降序、再然后 number_of_contigs 升序）排序。报告胜出的组装及决定胜出的指标。

---

解读表

组装级别（连续性，从好到差）：

级别	含义
Complete Genome	每个复制子（每条染色体 + 每个质粒）都已完整解析为一条无缺口序列。金标准。
Chromosome	染色体已组装至接近完整，但可能含有缺口；质粒/细胞器可能不完整。
Scaffold	使用跨越缺口的证据对 contig 进行排序和定向，组成 scaffold；仍有缺口。草图组装。
Contig	仅包含连续片段；未构建 scaffold。碎片化程度最高的草图组装。

连续性指标（典型细菌基因组大小为 2–6 Mb）：

• Contig N50：组装中有 50% 的序列位于长度 ≥ 此值的 contig 中。越高越好。完整基因组的 contig N50 等于其最长复制子的长度（例如，E. coli K-12 的 contig N50 为 4.64 Mb——整条染色体就是一个 contig）。优质的细菌草图组装通常有数百 kb 的 N50；N50 只有几 kb 表明组装碎片化。
• Contig 数量：越少越好。完整基因组的每个复制子对应一个 contig（因此，单染色体且无质粒的基因组有 1 个 contig）。数百至数千个 contig 表明草图组装碎片化。
• Scaffold N50 始终 ≥ contig N50；二者差距较大，意味着 scaffold 构建跨越了许多 contig 之间的缺口。

RefSeq 类别：

值	含义
reference genome	NCBI 为该分类单元指定的唯一、经过最精心筛选的组装——引用时的默认选择。
representative genome	未指定正式参考基因组时，选作物种代表的高质量组装。
(null / none)	普通提交的组装，没有特别指定。

GCF_ 与 GCA_：GCF_ = RefSeq（由 NCBI 筛选，注释一致）。GCA_ = GenBank（由作者提交）。二者共享相同的数字核心（例如，GCF_000005845.2 / GCA_000005845.2）；若两者都存在，则优先选择 GCF_。

---

示例 1 — E. coli 参考基因组（单条染色体，无质粒）

1. NCBIDatasets_suggest_taxonomy {"query":"Escherichia coli"} → 物种分类 ID 为 562。
2. NCBIDatasets_list_genomes_by_taxon {"taxon":"562","limit":5,"reference_only":true} → 排名第一的结果是 GCF_000005845.2（E. coli str. K-12 substr. MG1655），assembly_level 为 Complete Genome，refseq_category 为 reference genome，总计 4,641,652 bp，contig_n50 为 4,641,652，GC 为 51%。metadata.total_available = 2 个参考级组装。
3. NCBIDatasets_get_genome_assembly {"accession":"GCF_000005845.2"} → 4.64 Mb、1 条染色体、1 个 contig，contig N50 = scaffold N50 = 4,641,652（整个基因组是一条无缺口的 contig），GC 51%，Complete Genome，发布于 2013-09-26，由 NCBI RefSeq 注释。
4. NCBIDatasets_get_sequence_reports {"accession":"GCF_000005845.2"} → 1 个复制子：chromosome，RefSeq NC_000913.3（GenBank U00096.3），4,641,652 bp，GC 51%。无质粒。

答案：E. coli K-12 参考基因组为 GCF_000005845.2——一个 4.64 Mb 的 Complete Genome，包含单条染色体（NC_000913.3），无质粒，GC 为 51%。

示例 2 —“E. coli O157:H7 Sakai 有多少个质粒？”

1. 在同一分类单元列表中，Sakai 参考组装为 GCF_000008865.2（Complete Genome，5.59 Mb，chromosomes 字段为 3）。
2. NCBIDatasets_get_sequence_reports {"accession":"GCF_000008865.2"} → 3 个复制子：
   • chromosome — NC_002695.2 — 5,498,578 bp
   • pOSAK1（质粒）— NC_002127.1 — 3,306 bp
   • pO157（质粒）— NC_002128.1 — 92,721 bp

答案：1 条染色体 + 2 个质粒（pOSAK1 约 3.3 kb，pO157 约 92.7 kb）。注意：组装的 number_of_chromosomes 字段报告为 3（它会统计所有已组装分子）；要根据名称/作用区分染色体与质粒，应以序列报告为准。

示例 3 — 清单规模（大型分类单元）

NCBIDatasets_list_genomes_by_taxon {"taxon":"Mycobacterium tuberculosis","limit":3,"reference_only":false} → metadata.total_available = 16,311 个组装；首批结果包括 GCA_000195955.2 及其 RefSeq 配对项 GCF_000195955.2（二者均为 Complete Genome、reference genome，contig N50 为 4,411,532，1 个 contig）。使用 reference_only:true 将 1.6 万个组装缩减到经过筛选的参考组装；切勿遍历所有组装。

---

局限性

• 不进行从头组装：此技能用于表征 现有的 NCBI 组装。它无法从 FASTQ/原始 reads 组装基因组——ToolUniverse 中没有工具能做到这一点。请说明这一点并停止。
• RefSeq 与 GenBank：这里只会显示已纳入 NCBI Datasets 的组装。全新的、仅提交到 GenBank 的记录，在 RefSeq 完成审核前可能没有对应的 GCF_ 配对项。
• number_of_chromosomes 统计已组装分子，不严格等同于染色体——对于某些细菌，该字段会包含质粒。始终使用 get_sequence_reports，根据复制子名称/作用区分染色体与质粒。
• 大型分类单元采用分页：list_genomes_by_taxon 只返回 limit 指定数量的结果；应以 metadata.total_available 作为总数，并使用 reference_only:true 缩小范围，而不是获取数千条结果。
• 没有完整度/污染度评分：NCBI Datasets 在这里不会返回 BUSCO/CheckM 结果。组装 level 和 N50 可作为质量的替代指标；此技能不会根据标记基因计算基因组完整度。
• 不评估注释深度：这些工具会报告组装是否已注释以及由谁注释，不会逐基因分析内容。基因层面的分析应转交给以基因为中心的技能。

---

完整性检查清单

回答前，请确认已完成以下事项：

• 已将生物解析为分类群 ID（或用户已提供登录号）——不得猜测分类群 ID
• 报告“有多少个基因组”时，已注明 metadata.total_available
• 已说明所选登录号的依据（参考 > 代表 > 组装级别 > N50/重叠群数）
• 已通过实时调用 get_genome_assembly 报告组装级别、长度、N50、重叠群数和 GC%
• 已使用 get_sequence_reports（而非 number_of_chromosomes）统计染色体与质粒
• 如果 GCF_ 登录号与对应的 GCA_ 登录号均存在，已优先选择 GCF_ 登录号
• 如果请求涉及直系同源分析、植物基因结构、从头组装或仅分类学信息，已引导用户前往其他资源