pathogen-variant-surveillance

病原体変異株サーベイランス

使用するタイミング

病原体集団が現在どのような状況かに答えが左右される場合、つまり、どの系統が流行しているか、ある系統が増加しているか、系統名が現在何を意味するか、またはアッセイの標的にまだ適合しているかを確認する場合です。

ルール

何が流行しているかを断言してはならず、系統名を記憶に頼って書いてはなりません。

同時に3つの問題が起きています。そのうち通常の知識カットオフの問題に当たるのは最初の1つだけです。

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 を読み込み、インスタンスが実際に宣言しているフィールドから、採取日、提出日、系統の各カラムを選択します。SARS-CoV-2 では dateFrom= が正しい一方、H5N1 ではハード 400 エラーになります。H5N1 の採取日は sampleCollectionDateRangeLower です。

スクリプト

cd skills/pathogen-variant-surveillance/scripts

スクリプト	回答する質問
resolve_lineage.py	この名前はまだ存在するか、何に展開されるか、どの系統に由来するか？
lineage_prevalence.py	この系統は配列のうちどの程度を占めるか、週ごとの割合はどう変化しているか、増加しているか？
mutation_profile.py	どのような変異を持ち、別の系統とどう異なるか？
reporting_lag.py	データを信頼できるものにするには、どれくらい過去まで遡る必要があるか？

4つのスクリプトはすべて --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: ウィンドウ内で最も一般的な pangoLineage 値を5つ検出しました： 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

監視週のサンプル数は少ないため、割合にはウィルソン区間を付けています。分母がまだ揃っていない週には low のフラグを付け、--include-incomplete を指定しない限り、増加傾向のフィッティングから除外します。

期間は ISO 週の全期間に広げられ、広げた場合はその旨が表示されます。週の途中から始まる期間では、最初の行が 3 日分、最後の行が 4 日分を対象とする一方、その間の行は丸 1 週間分となり、比較できなくなるためです。

--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 の状況は実質的に 2 か月間は把握できません。

気付かないうちに誤った回答を生む落とし穴

すべて 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 件が返される。同じ構文でも意味は正反対
フィールド名はインスタンスごとに異なる	H5N1 では dateFrom は 400 エラーとなり、採取日は sampleCollectionDateRangeLower で指定する
範囲指定を受け付けるのは date 型のフィールドのみ	H5N1 では sampleCollectionDate は文字列型のため、From／To キーは存在しない
直近の週は、実際に流行したものの標本ではない	最も速く報告する人々の標本にすぎない。米国のコホートでは、7 日以内に到着するのはわずか 29%
LAPIS は組換え体を祖先へ解決する	XFG の親系統を問い合わせても何も返されない。XFG = LF.7 + LP.8.1.2 を記録しているのは alias_key.json のみ
廃止された名称もデータに残る	上流では PC.2 が LF.7.9 に再指定された一方、シーケンスには引き続き PC.2 が付いている
未知の名称で明示的にエラーになるのは、インデックス化された場合のみ	インデックス化された列では誤記を 400 エラーで拒否するが、インデックス化されていない列では 0 を返す
変異の proportion は coverage を分母とする	一致する全シーケンスが分母ではない。カバレッジの低い部位では、ごく少数のリードでも 1.000 と表示されることがある
/sample/aggregated は limit／orderBy を拒否する	結果に固有の並び順はないため、クライアント側でソートする

結果の報告

インスタンス、データのバージョン、フィルター、期間を明記してください。基盤となるデータベースは毎日更新されるため、これらがなければ流行割合の数値を再現できません。件数も割合と併せて示し、区間を明記し、推定を裏付けるには期間が新しすぎる場合はその旨をはっきり伝えてください。「過去 6 週間について信頼できる推定値はありません」は、妥当であり、多くの場合正しい回答です。

参考資料

• references/lapis-api.md — エンドポイント、フィルター構文、インスタンスごとのスキーマの違い、インスタンスレジストリ、検証済みの落とし穴すべての詳細。
• references/lineage-nomenclature.md — Pango エイリアスと組換え体、名称指定の変遷、Nextstrain クレード、WHO ラベル、インフルエンザのクレード、H5N1 のクレードと遺伝子型、および各命名体系の対応関係。
• references/surveillance-caveats.md — 報告の遅れ、サンプリングと確認のバイアス、分母の選び方、区間と増加傾向の解釈、およびこのデータでは裏付けられない結論。

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、および入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを確定します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 最初に、小さなサブセット（1サンプル、1染色体、数千個の細胞）でパイプラインを実行します。
4. 上記の手順と参照情報を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの同一性、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の点を明示します。

次の状況が発生した場合	対応
入力間でゲノムビルドまたは識別子が一致しない	続行する前に停止し、調整します（liftover、ID マッピング）。
インストール済みバージョンに、これらの手順に記載された関数、フラグ、またはエンドポイントがない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。API を決してでっち上げないでください。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えます。
• 統計的な裏付けを超えて生物学的意義を解釈しないでください。多重検定補正について報告します。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する操作、共有 GPU やクラウドクォータを消費する操作、個人データまたは患者データに触れる操作、あるいは取り消せない操作を行う前に、確認してください。