用途
该技能用于任何依赖病原体当前种群状态的回答场景：当前流行哪些谱系、某个谱系是否在增长、某个谱系名称当前代表什么，或某个检测靶标是否仍然匹配。核心规则是：绝不凭记忆陈述流行情况，也绝不凭记忆写出谱系名称。
原因在于三个问题同时发生：第一，名称晚于训练数据，Pango 命名列表已超过 6,200 个名称并持续增长；第二，命名法是一个实时数据结构而非固定约定，例如 XFG 是重组体，只能通过 alias_key.json 解析，PQ.17 展开为 XDV.1.5.1.1.8.1.17，这些映射来自会变化的文件，无法通过推理得出；第三，先验知识不仅过时，还可能被撤回，当前 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，因为其采集日期字段是 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 可保持数据干净且来源可见。
使用方式
从数据出发，而非记忆中的列表：
python3 lineage_prevalence.py --top 5 --where country=USA --weeks 12
这是回答“当前流行什么”的正确首条命令。预先指定谱系名称会假定你已经知道哪些重要，而这正是该技能要消除的假设。
使用名称前先检查：
python3 resolve_lineage.py XFG.23.1.3 PQ.17 PC.2 NOTALINEAGE
如果任何名称为撤回或未知，退出码为 1，可用于把关稿件中的谱系列表。注意 PC.2 在上游已撤回，但仍有 25 条序列携带该标签，因为实例的分配滞后于命名指定。两个事实都成立且都重要。
流行率与增长：
python3 lineage_prevalence.py "XFG.1.1*" "XFJ*" --where country=USA --weeks 16 --growth
比例带有 Wilson 区间，因为监测周样本量小。分母尚未填满的周会被标记为 low，并排除在增长拟合之外，除非使用 --include-incomplete。窗口会扩展到完整 ISO 周，并在这样做时说明。--growth 报告对数几率对时间的加权最小二乘斜率，它是描述性的，吸收了测序对象、地点和报告速度的所有变化，不是适应度或传播性估计。观测太少的谱系不打印斜率。
突变与检测靶标匹配：
python3 mutation_profile.py "XFJ*" --versus "XFG*" --gene S --since 2026-01-01
对分段基因组同样适用，例如 --instance h5n1 --gene HA 或 --gene seg4。使用 --nucleotide 处理引物和探针问题，此时密码子不是关键单位。
判断可信回溯范围：
python3 reporting_lag.py --where country=USA
在引用任何近期流行率之前运行此命令。曲线因病原体和地区差异显著：在 H5N1 上，同样测量在 14 天返回 0% 完整，30 天返回 15%，因此“当前”H5N1 图景实际上有两个月盲区。
适用场景
适用于研究性病原体基因组监测数据分析，包括谱系流行率与增长趋势、谱系名称解析、突变谱比较、检测靶标匹配评估以及报告滞后评估。
限制
不产生临床解读、疫情响应建议或公共卫生指导。序列计数不等于病例数。所有数字依赖实时实例，底层数据库每日变化，因此报告结果时必须说明实例、数据版本、过滤器和窗口。近期周数据不代表实际流行情况，只代表报告最快者的样本。突变比例基于覆盖度而非所有匹配序列。/sample/aggregated 拒绝 limit/orderBy，结果无固有顺序，需客户端排序。