pathogen-variant-surveillance

病原体变异株监测

适用场景

凡是答案取决于病原体群体当前情况的场景：哪些谱系正在传播、某个谱系是否在增长、某个谱系名称目前代表什么，或者某个检测靶标是否仍然匹配。

规则

绝不根据记忆陈述正在传播的谱系，也绝不凭记忆写出谱系名称。

会同时出现三个问题，只有第一个属于普通的知识截止问题：

1. 名称出现得晚于训练数据。 Pango 命名列表已有 6,200 多个名称，并且还在不断增长。
2. 命名系统是实时数据结构，而非约定。 XFG 是一个只能通过 alias_key.json 解析的重组谱系；PQ.17 取消别名后对应 XDV.1.5.1.1.8.1.17。这两种扩展都无法通过推理得出——映射关系存储在一个会变化的文件中。
3. 既有知识会被撤销，而不只是过时。 当前 lineage_notes.txt 中有 294 个名称已撤销或重新指定。PC.2 现在是 LF.7.9；XFG.20 则被直接撤销。记忆中的谱系信息不只是过时，还可能完全错误。

此技能报告的每个数字，都是由实时实例返回的计数，并标注了对应的数据版本。

范围

用于研究的监测数据分析。此技能描述已采集并提交的序列；不提供临床解读、疫情响应建议或公共卫生指导，且序列计数不等于病例数。

实例

所有病原体都使用同一种 API 结构。--instance 用于指定已验证的部署；--base-url 可连接任何其他 LAPIS 实例。

实例	主机	谱系列	已建立索引
sars-cov-2	lapis.cov-spectrum.org（公开的 GenBank 数据）	pangoLineage	是
h5n1、h3n2、h1n1pdm、influenza-a	lapis.genspectrum.org	clade	否
rsv-a、rsv-b、mpox、measles、dengue、west-nile、hmpv、ebola-zaire、ebola-sudan、cchf	lapis.pathoplexus.org	不一	不一

各实例的字段名称不同，绝不预先假定。 每个脚本都会在运行时读取 /sample/databaseConfig，并根据实例实际声明的内容选择采样日期、提交日期和谱系字段。dateFrom= 在 SARS-CoV-2 上有效，但在 H5N1 上会返回 400 错误；H5N1 的采样日期字段是 sampleCollectionDateRangeLower。

脚本

cd skills/pathogen-variant-surveillance/scripts

脚本	解答的问题
resolve_lineage.py	这个名称是否仍然存在？它会扩展成什么？它的祖先谱系是什么？
lineage_prevalence.py	这个谱系在每周序列中占多少比例？它是否在增长？
mutation_profile.py	它携带哪些突变？与另一个谱系有何不同？
reporting_lag.py	数据需要回溯多久才值得信赖？

这四个脚本都接受 --format table|tsv|json，并将溯源信息（实例、数据版本、解析后的字段名称、筛选条件）打印到 stderr，因此使用 > out.tsv 可保持数据干净，同时保留可见的溯源信息。

从数据入手，而不是依赖记忆中的列表

# no names: discover what is actually circulating in the window
python3 lineage_prevalence.py --top 5 --where country=USA --weeks 12

note：发现了时间窗口内最常见的 5 个 pangoLineage 值： XFG.1.1、XFG.23.1.3、PY.1.1.1、XFJ.3.1.2、PQ.17

对于“目前正在传播什么”这个问题，这是正确的第一条命令。一开始就列出谱系，意味着你已经知道哪些谱系重要；而这项技能正是为了消除这种假设。

使用名称前先检查

python3 resolve_lineage.py XFG.23.1.3 PQ.17 PC.2 NOTALINEAGE

query        status     unaliased                        parent    recombinant_of  descendants  sequences  detail
XFG.23.1.3   current    XFG.23.1.3                       XFG.23.1  LF.7+LP.8.1.2   6            317        S:A1174V, on C29137T branch
PQ.17        current    XDV.1.5.1.1.8.1.17               NB.1.8.1                  23           931        Alias of XDV.1.5.1.1.8.1.17
PC.2         withdrawn  B.1.1.529.2.86.1.1.16.1.7.2.1.2  LF.7.2.1                  4            25         now LF.7.9; Redesignated as LF.7.9
NOTALINEAGE  unknown    NOTALINEAGE                                                0            n/a        no such name in the live nomenclature

（detail 内容经过删节；每个实际行还会注明其来源的谱系提案。）

只要有任何名称已撤销或未知，退出码就为 1，因此可用它来把关稿件中的谱系列表。注意 PC.2：它已被上游撤销，但由于该实例的指定结果滞后，仍有 25 条序列带有此标签。这两个事实都成立，也都很重要。

流行情况与增长

python3 lineage_prevalence.py "XFG.1.1*" "XFJ*" --where country=USA --weeks 16 --growth

lineage   week        n   total  proportion  ci_low  ci_high  coverage
XFG.1.1*  2026-05-04  42  80     0.5250      0.4170  0.6308   ok
XFG.1.1*  2026-06-15  3   49     0.0612      0.0210  0.1652   ok
XFG.1.1*  2026-06-29  1   30     0.0333      0.0059  0.1667   low
XFG.1.1*  2026-07-13  0   0                                   low

由于监测周的样本量较小，比例均附有 Wilson 区间。分母尚未填满的周会标记为 low，并在拟合增长趋势时排除，除非使用 --include-incomplete。

时间窗口会扩展为完整的 ISO 周，并在扩展时注明。若窗口从周中开始，第一行将涵盖三天，最后一行涵盖四天，与其中的完整周都无法比较。

--growth 会报告对数优势随时间变化的加权最小二乘斜率。它是描述性的：其中包含测序对象、地点和报告速度的所有变化。它不是适应度或传播力估计。观测数量过少的谱系不会打印斜率——有关此保护措施存在原因，请参阅陷阱表。

突变，以及检测方法是否仍然匹配

python3 mutation_profile.py "XFJ*" --versus "XFG*" --gene S --since 2026-01-01

mutation  gene  position  verdict  prop_a  prop_b  n_a  n_b
S:L441R   S     441       gained   1.000   0.000   66   0
S:A475V   S     475       gained   1.000   0.000   68   0
S:K444R   S     444       lost     0.000   0.996   0    5031
S:Q493E   S     493       lost     0.000   0.998   0    5359

分节段基因组也可采用相同方法——使用 --instance h5n1 --gene HA 或 --gene seg4。对于引物和探针相关问题，请使用 --nucleotide，因为密码子并非相关的分析单位。

确定可以信任到多早的数据

python3 reporting_lag.py --where country=USA

lag_days  mean_complete  min_complete  max_complete  cohorts
14        0.456          0.332         0.557         6
30        0.677          0.580         0.822         6
60        0.868          0.802         0.949         6
90        0.939          0.916         1.000         6

90 天时，队列中已有 90% 的数据到达。可信任截至 2026-04-28 的采集日期；此后的数据应视为暂定数据。

在引用近期流行率之前，请先运行此项分析。不同病原体和国家的曲线差异显著：对 H5N1 进行同样的测量，结果显示 14 天时完成度为 0%，30 天时为 15%，因此，所谓“当前”的 H5N1 情况实际上有两个月处于盲区。

会导致答案悄然出错的陷阱

所有内容均已于 2026-07-27 根据实时 API 验证。这些问题正是本技能提供脚本而非操作步骤的原因；完整详情见 references/lapis-api.md。

陷阱	后果
单独的谱系名称不包含其后代	pangoLineage=XFG 返回 4 条序列；XFG* 返回 640 条
末尾的 * 需要谱系索引	在 H5N1 中，clade=2.3.4.4b 返回 62,413 条，而 clade=2.3.4.4b* 返回 0——相同语法，含义却截然相反
字段名称因实例而异	dateFrom 在 H5N1 中会返回 400；采集日期字段是 sampleCollectionDateRangeLower
只有类型为 date 的字段才接受范围	H5N1 将 sampleCollectionDate 定义为字符串，因此它根本没有 From/To 键
近期周的数据并非对流行情况的抽样	这些数据反映的是报告速度最快的人群；美国队列中，仅 29% 会在 7 天内上报
LAPIS 不会为重组株追溯谱系树	查询 XFG 的父谱系不会返回任何结果；只有 alias_key.json 记录了 XFG = LF.7 + LP.8.1.2
已撤回的名称仍会保留在数据中	上游已将 PC.2 重新指定为 LF.7.9，但序列中仍使用 PC.2
未知名称只有在经过索引时才会明确报错	已索引列遇到拼写错误会返回 400；未索引列则返回 0
突变的 proportion 以 coverage 为分母	而非所有匹配序列——覆盖度较低的位点可能仅基于极少数读段就显示 1.000
/sample/aggregated 不接受 limit/orderBy	结果没有固有顺序；请在客户端排序

报告结果

请注明实例、数据版本、筛选条件和时间窗口——若缺少这些信息，流行率数字就无法复现，因为底层数据库每天都会变化。请同时给出计数和比例，注明区间，并明确说明时间窗口是否过近，无法支持估计。“过去六周无法得出可靠估计”是合理且经常正确的回答。

参考资料

• references/lapis-api.md — 端点、筛选语法、各实例的架构差异、实例注册表，以及所有已验证陷阱的完整说明。
• references/lineage-nomenclature.md — Pango 别名和重组株、指定名称的变动、Nextstrain 分支、WHO 标签、流感分支、H5N1 分支和基因型，以及不同命名系统之间的对应关系。
• references/surveillance-caveats.md — 报告延迟、抽样和确证偏差、分母的选择、区间和增长的解读，以及此类数据无法支持的结论。

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一条染色体、几千个细胞）上运行流水线。
4. 使用以上说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些事项仍不确定。

如果发生这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并统一（liftover、ID 映射）后再继续。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自带的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 不要解读超出统计结果所支持范围的生物学意义；报告多重检验校正情况。
• 请将此处与版本相关的细节视为可能已过时：根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，执行前必须先询问。