ms-data-parser 仕様書

MS-DIAL は解析結果を圧縮 MessagePack と独自バイナリで書くため、GUI の外では読めず、チャットに貼るには大きすぎる。このサーバはそれらを読み、標準的な解析（前処理・PCA・差次的解析・同定の裏取り）をサーバ側で回し、LLM には結論が埋もれない大きさの要約・TSV・PNG だけを返す。生の行列は LLM の文脈に載せない。

設計原則

パッケージ構成と依存の向き

同じ LC-MS データが、ファイルごとに別の粒度で書かれている。「1 行」が何を指すかを取り違えると、検出率も同定も壊れた数字になる。

2.1 バイナリの解き方

MessagePack の Key 番号の正解表は docs/schema/*.md（MS-DIAL の C# クラスの [Key(N)] から上流 commit 45a531c 時点で抽出）。インデックス定数を変える前に必ずここを見る。推測で直さない。

2.2 mzTab-M の 2 つの同定の出所

2.3 読み間違えやすい値

2.4 脂質名の文法（assay_kind=lipid のときだけ）

一般代謝物（assay_kind=metabolite）ではこの文法は成り立たず、同定の実体は候補集合（アダクト・異性体・候補順位）になる。種別が未確定のあいだはどちらの規則も当てない。

利用者が手元に何を持っているかで入口が決まる。サーバ共通指示（MCP_INSTRUCTIONS の ENTRY POINT / GATEWAY）はこの判定を LLM に教え、最初に呼ぶツールを 1 つに絞らせる。

経路の全体地図

4 本の経路は別々のセッションスロットを使うので、並行して進めても互いの状態を壊さない。矢印は「前段が書いた状態を後段が前提として読む」を表す。実線は必須の前提、破線は任意。各箱の 2 行目は、そのツールが書く状態または出力。

3.1 独立した枝：アラインメントのキュレーション

MS-DIAL の GUI で 1 件ずつ見ていた注釈の確認（EIC・対向プロット・Δm/z・ΔRT・RT–m/z の線形性）を、一覧と機械判別で短くする枝。どの経路とも状態を共有せず、いつでも入れる。前提は 2 本で、どちらも missing_state で止まる：.arf2 が解決できること（load_dataset か arf2_parser）と、参照ライブラリが読み込み済みであること（library_load。アラインメントと同じフォルダの *_Loaded.msp2.dbs を推奨）。

1. curation_review — 一覧と機械判別

   注釈付きスポット（既定は全部、ontology でクラス、name_contains で名前）の証拠を集めて判定し（8.4 節）、ビューア HTML を書く。LLM に返すのは suspect 以上とフラグ済みの TSV・件数・クラス別の傾向要約・html_path だけで、EIC 系列とスペクトルは返さない。

2. ユーザーがビューアで確かめる

   html_path をブラウザで開く。likely_wrong は赤の破線枠で「間違い」が初期選択、メモ欄には判定根拠が入っている。クラスの選択肢の「<クラス> › 自動判別: 間違い」で絞れる。直したら「送信用テキストをコピー」してチャットに貼る。

3. curation_submit — 記録と MS-DIAL への反映

   貼られた文をそのまま渡す。flags.jsonl に追記し（正本）、アラインメントの _tags.xml の Misannotation を付け外しする（wrong → 付ける、取消 → 外す、suspect → 触らない）。

4. エクスポートと表に効く

   arf_export_differential / dataset_export_differential は既定で wrong のスポットを同定なしとして外し、メタ行 # curation = … で宣言する（10.1 節）。arf2_annotate_identities は curation_flag 列を持つ。curation_flags で有効なフラグを一覧できる。

サーバは 1 プロセスに 1 つの session = AnalysisSession() を持つ。ツールは前段が書いた状態を読み、無ければ例外ではなく missing_state 封筒で「先にどれを呼ぶか」を返す。クライアントはそれを読んでリプレイする。

4.1 前提状態の連鎖表

「このツールを呼ぶには何が要るか」。前提が無いときに返る封筒の required_tools は OR の代替候補で、クライアントは候補のうち本セッションで成功した直近の呼び出しを記録済みの引数のまま再実行する（LLM に再実行させると前処理の引数が変わりうる）。

EIC の検索系（eic_parser と eic_search_*・eic_rank_by_max_intensity）は EicState.load_data() を通るので、どれから呼んでも未ロードなら読み込まれ、missing_state にはならない。

4.2 ツールの annotations

全ツールが MCP 標準の ToolAnnotations を宣言する。readOnlyHint=true は「サーバの外（ファイル・ネットワーク）に副作用が無い」を意味し、サーバ自身の解析セッション状態の更新は副作用に数えない（依存関係は封筒で伝えるため二重に表現しない）。openWorldHint=true は paper_search だけ。同じ引数での再実行が安全かは readOnlyHint か idempotentHint で判断できる。curation_submit は destructiveHint=true：記録は追記だが、MS-DIAL の _tags.xml を書き換え、取消では Misannotation を外すため（書く前に控えを取る）。

各カードは「シグネチャ・何をするか・入力・出力・前提・状態変更・注意」を同じ順で持つ。見出しをクリックすると開く。引数名と既定値は実登録のシグネチャから取った。

解析行列は行 = 試料（assay）、列 = 特徴量で持つ。DatasetState.feature_matrix は（特徴 × assay）で保存され、解析の入口で転置される。v1（ARF ツール・dataset_* ツール・v1 pipeline）と v2（LC–MS メタボロミクス profile）は別の実装で、数値の約束事も違う。この章は v1 を扱い、v2 の行列は 7.6 節で扱う。

6.1 入力行列の組み立て

役割の判定（sample / qc / blank）

detect_sample_roles() はファイル名と Class ID を _ で区切り、大小無視でトークン照合する。既定トークンは qc と blank。blank を先に評価し、どちらにも当たらなければ sample。detect_qc_strata() は QC 名から 8 桁日付・数字・qc・neg・pos を除いた残りで層を判定し（例 20240311_QC_Cerebellum_ICR_NEG_1 → cerebellum_icr）、層が 2 つ以上なら「全 QC を 1 系列扱いするドリフト補正/RSD は近似」と警告する。

6.2 前処理レシピの実行順

preprocessing.preprocess(matrix, sample_names, roles, run_order, recipe) の実行順。既定は何も適用しない opt-in（ツール既定: normalize="none"、blank_min_fold=None、drift_correct=False、max_qc_rsd=None、impute="half_min"）。

6.3 各ステップの式

step 0 · 失敗 QC 注入の検出 detect_failed_qc(min_ratio=0.2)

失敗注入を残したまま max_qc_rsd を掛けると QC の RSD が全特徴で跳ね上がり、ほぼ全特徴が落ちる（実測: kidney aging NEG で 1345 → 51）。「閾値が厳しすぎる」ように見える現象の真因は QC 側にあることが多いので、arf_exclude で除外して前処理し直す。

step 1 · ブランク除去 blank_filter(min_fold)

blank 行か sample 行が無ければ未実施（status="skipped" と caveat）。ツール既定は off、conservative-v1 の auto では 3.0。

step 2 · 正規化 normalize(method)

どの方法も行（試料）ごとの係数で割る: x′_ij = x_ij / f_i。v1 に内部標準比は無い（v2 の base="internal_standard_ratio" だけ）。

step 3 · QC ドリフト補正 qc_drift_correct(min_qc=4, window=5)

名前は QC-RLSC に倣うが LOESS ではない。実装は QC を注入順に並べた移動中央値＋区分線形補間で、特徴ごとに全ラン 1 系列として補正する（バッチ別の扱いは無い）。

未実施になる条件: 注入順を持たない試料がある / 注入順つき QC が 4 本未満 / QC 区間に入る試料が 0（covered == 0）。注入順は ARF 経路では .mddata の analytical_order、mzTab-M 経路では MTD assay[N]-custom[...] の MS:4000089、pipeline では実験情報シート。

step 4 · QC RSD フィルタ qc_rsd_filter(max_rsd)

step 6 · 欠損補完 impute(method)

preprocess に対数変換とスケーリングの段は無い。対数は PCA（log10）と差次的解析（log2(x+1)）がそれぞれ下流で掛ける。Pareto スケーリングはコードのどこにも無い。

6.4 pipeline の自動判定 conservative-v1

dataset_service.preprocess_auto が使う方針（lipidmix/analysis/preprocess_policy.py、POLICY_VERSION="conservative-v1"）。数えるのは include=true の行だけ。前提が揃わない処理は掛けない側に倒す。

計算のあと・確定の前に check_applied_policy が走り、解決した処理が recipe_applied に無ければ PREPROCESS_STEP_NOT_APPLIED、未正規化試料があれば NORMALIZATION_DEGENERATE、特徴が 0 件なら PREPROCESS_FEATURES_EXHAUSTED で止める。v2 はこの方針を通らず explicit_policy(recipe)（profile-explicit-v2）で profile の指定をそのまま使う。

6.5 caveat の前景化

QC・ブランク・注入順が欠けて飛ばした処理は黙って消えず、report["caveats"] に文言で残る。LLM はこれを解釈結果とレポートの注意点として引用する契約になっている。

• QC も blank も無い → 常に caveat。
• 残存特徴が 0 件 → 「全特徴が除去（閾値が厳しすぎる可能性、解析不能）」。90% 超除去 → 残存割合を注記。
• QC 層が複数 → 1 系列扱いは近似。
• 正規化で未正規化のまま残した試料がある → 件数つきで注記。
• 手動除外（arf_exclude）が有効 → 0 件でも「ユーザ手動除外: サンプル N 件 / スポット M 件」を必ず開示。

PCA の正準は lipidmix/analysis/pca.py の run_pca、2 群比較は lipidmix/analysis/differential.py。ARF 経路と mzTab-M 経路は同じ純関数を共有しているので、同じ行列からは同じ数字が出る。

7.1 PCA run_pca(matrix, n_components=None, log_transform=False, scaling="autoscale")

ローディング上位（get_pca_loading_features(top_n=10, n_pcs=2)）: PC ごとに係数の大きい側上位 10 と小さい側上位 10 を、MasterAlignmentID・注釈名・m/z・RT つきで返す。注入順相関（dataset_pca）: 各 PC スコアと注入順の Pearson r（注入順つき試料 3 以上かつ SD > 0 のとき、3 桁丸め）。|r| ≥ 0.5 なら「PC がドリフトを拾っている」caveat。

7.2 2 群比較（v1）two_group_test

group_a が基準（対照）、group_b が比較対象。特徴ごとに Welch の t 検定を行う。ツール既定は q_threshold=0.05、log2fc_threshold=1.0、log_transform=True。

検定不能になる条件: どちらかの群で有限値が 2 未満、または両群とも分散 0（分母 ≤ 0）→ p=NaN。mean_a / mean_b はどちらのモードでも生値の算術平均を返す。

多重検定補正（Benjamini–Hochberg）bh_fdr

計算例（m = 10）。下から累積最小を取るので、3〜5 位の生値 0.13 / 0.1025 は 5 位の 0.084 に引き下げられる。

有意判定と volcano の分類

7.3 群の解決と交絡検査

因子トークンによるプール指定。ARF 経路の group_a / group_b は Class ID とサンプル名の両方から因子トークンを解決する（sample_factors.expand_sample_specs）。

QC・blank は群ラベルを None にしてから展開するので、Class ID が指定トークンを含んでいても（例 QC_24M と group_a="24M"）どちらのプールにも入らない。応答の resolved_samples が群の定義そのもの、n_a / n_b が除外後の実 n。mzTab-M 経路の dataset_differential はサンプル名のリストを直接受け、重複除去・未知名と QC/blank の除外・両群の重なり拒否・各群 n ≥ 2（満たさなければ bad_request。ARF 経路は caveat のみ）を行う。

差次的解析の必須 caveat

1. 交絡（群⟂バッチ） — 上図の条件で警告。
2. 正規化状態 — レシピに正規化が無ければ「未正規化データの log2FC は測定量差を含み得る」。
3. 群サイズ — n < 2 なら「各群 n ≥ 2 が必要」、2 ≤ n < 4 なら小 n（検出力の限界）。
4. 退化 — 検定できた特徴が 0 件なら「全特徴で p=NaN。『有意 0 件』を『群間差なし』と解釈しない」。20% 未満しか検定できなくても注記。

7.4 v2 統計 dataset_statistic(specification, matrix_result_id)

v2 は名指しした解析行列（analysis-matrix.v1）にだけ統計を掛け、直近の前処理を暗黙に使わない。recipe 違いの行列が 2 本並ぶ前提の設計で、どの行列の数字かを結果に残す。kind は welch / anova_tukey / pca の 3 つだけ（Kruskal–Wallis・Mann–Whitney・対応あり検定・標準化効果量は無く、反復測定は REPEATED_MEASURES_UNSUPPORTED）。

anova_tukey（multigroup.test_feature）

どれかの群で有限値が 2 未満、または全群で分散 0 なら not_testable。scipy が無ければ STATISTIC_DEPENDENCY_MISSING で止まり、別の検定へ黙って切り替えない。

7.5 v2 の内部標準比・feature binding・QC

行列の流れ（matrix_state.py）: qc_raw が無処理の __raw__ 行列で QC 評価集合をフィルタ前に固定 → preprocess が recipe ごとに make_matrix（補完しない。検出率 filter は列を消さず eligibility_mask だけに効く）→ qc_processed が固定集合で処理後 QC を評価し、落ちた feature を eligibility に反映してから finalize_matrix で補完（locked セルは補完後に NaN へ戻す）。matrix_id は値ではなく入力の identity の hashなので、同じ入力なら同じ ID になる。保存は npz（allow_pickle=False）＋メタ JSON で、読むときにメタ hash・配列ごとの SHA-256・形状を検証する。

7.6 結果の鮮度と無効化

目的は「付いている名前は本当か」を、人が数値と図の両方で判断できるようにすること。同定名の標準化・同定信頼度の推定・実スペクトルの照合はすべてオフラインで、pygoslin（同梱）と同梱 TSV と参照ライブラリだけを使う。

8.1 verify_peak_annotation の判定の流れ

ドシエの出力キー: status、identity（id・name・ontology・formula・adduct・observed_mz・rt・ion_mode・S/N）、analytical_checks（mass_error・adduct_consistency・msms）、biological_plausibility（蓄積ノートの語彙ヒットと候補 slug）、identity_normalization（goslin・reference・msi・class_token）、llm_decision（指示文と deterministic_summary、例 msms=PASS）。名前に P- / O- があればエーテル caveat を付け、プラズマローゲンの知識ノートへ繋ぐ。

8.2 名前の標準化（GOSLIN）と参照表

1. MS-DIAL の限定子を剥がす

   no MS2: w/o MS1: w/o MS2: low score: unsettled: を大小無視で除去し、A|B なら先頭を取る（stripped=True）。RIKEN N-VS1 ID-… のような真の未同定名は解析不能のまま（正しい）。

2. pygoslin で解析

   normalize_lipid_name は parse_ok・normalized・level（SPECIES / MOLECULAR_SPECIES …）・lipid_maps_category を返す。未導入でも解析不能でも例外を投げず parse_ok=False。

3. クラストークンで同梱表を引く

   reference/lipidmaps_classes.tsv（カテゴリ・メインクラス）と reference/refmet_map.tsv（RefMet 名）はキュレート済みの部分集合で、置き場所はリポジトリ直下の reference/ に固定（REFERENCE_DIR。起動ディレクトリに依存しない）。表に無いクラスは matched=False と caveat「同梱マッピング表に無いため ID 未付与」で返し、推測しない。

8.3 スペクトル照合（MS-DIAL MsScanMatching.cs の忠実移植）

目的は MS-DIAL との数値の一致で、実装の改善ではない。上流の「変な点」（未使用の中間値、両枝が同一の分岐、打ち消える ×999、隣接窓への二重計上を許すカーソル走査、Li et al. 2021 の低エントロピー重みの不在）は意図的にそのまま写してある。

参照ライブラリの store。library_load は .dbs/.lbm2/.msp を読み、元ファイルの sha256 をキーにした SQLite キャッシュ（既定 data/.library-cache）へ初回変換する。precursor m/z を持たないレコードは 1 件ずつ読み飛ばして skipped_no_precursor_mz に数え、極性欄の無いレコードは極性不明として候補に残す（ion_mode 比較は COLLATE NOCASE）。研究室の参照ライブラリは外部流出禁止で、リポジトリの外に置いて MSDIAL_MSP_POS / MSDIAL_MSP_NEG で指す。

8.4 アラインメントのキュレーション（機械判別）

curation_review はスポットごとに 5 系統の帯（PASS / BORDERLINE / FAIL / UNKNOWN）と理由コードを出し、総合判定 verdict にまとめる。画像ではなく数値に対して判定する。MS-DIAL 自身が同定時に出した判定（MsScanMatchResult のフラグ）を主にし、こちらでの再計算は食い違いの検出にだけ使う。UNKNOWN（MS/MS 未取得・参照 RT なし）は不一致に数えない。

判定を動かさない情報コードもある: msms_absent · reference_not_found · rescore_discrepancy（こちらの再照合が MS-DIAL の値と 0.1 以上ずれた）· adduct_differs_from_reference · manually_modified · class_rules_not_run（脂質クラス規則が評価されていない＝未検証であって誤りではない）· chains_unsupported（鎖レベルの名前なのに is_lipid_chains_match=False。MS-DIAL は照合に失敗しても参照名から | 付きの名前を作るので、| 名は鎖組成の証拠ではない）ほか。

ビューアとフラグの流れ

• 判定根拠のメモ。likely_wrong と suspect のカードは、メモ欄の既定値が判定根拠の文になる（例 自動: 精密質量 — Δm/z 12.4 mDa（≥10 mDa） / MS2 — 参照と一致せず（low score））。
• 「間違い」の初期選択。likely_wrong は開いた時点で「間違い」が選ばれた未送信の変更になる。記録済みのフラグがあるもの・人が取り消したもの（flag_cleared）には掛けない。「なし」に戻して送れば取消として記録され、次のレビューで掛け直さない。
• 枠。自動判別の likely_wrong は赤の破線、記録されて（または人が選び直して）「間違い」になると実線。人の「疑わしい」は橙の実線。
• 対向プロット。ピークの m/z ラベルは library_plot_mirror と同じ規則（強度降順の貪欲法、縦横とも重なるものを飛ばす、片側 25 本まで、実測と参照は独立）。縦軸は各側の最大値を 100 とした相対強度で 0 / 50 / 100 の目盛り。
• MS-DIAL への書き戻し。curation_submit はアラインメントの <stem>_tags.xml を上流 AlignmentResultContainer.Save と同じ形（<Peak Id="MasterAlignmentID"><Tag>3</Tag></Peak>、UTF-8 BOM・CRLF）で書く。実物の写しで付与 → 除去の往復がバイト一致することを確かめてある。

生データを扱う経路は 2 つある。個々のツールを手で繋ぐ Console 経路と、生データフォルダ 1 つから品質レポートまでを永続 run として自動で進める pipeline 経路。どちらも終了コード 0 だけでは成功と言わず、終了証跡・生成物の構造・試料の 1 対 1 対応まで確かめる。

9.1 Console 経路：計画 → 実行 → 確定

analysis-job.json の主な欄（analysis-job.v2、profile を持つ v2 run は .v3）: job_id（job_<日時>_<pos|neg>_<h|a>_<uuid8>）、status、dataset_root、method_file、omics、polarity、measure、run_dir、primary_mztab_files[]（path・polarity・measure・sha256・validation・root）、artifacts[]（path・role・format・sha256・root）、sample_manifest、warnings、error。run ディレクトリはリポジトリの外（生データ側の runs/）でなければならない（DATASET_ROOT_IN_REPO）。

9.2 pipeline：受付と worker

9.3 工程（stage）と成果物

v2（stage_plan.BASE_V2_STAGE_IDS）: prepare_inputs → execute_console → validate_outputs → load_dataset → resolve_metadata → load_assay_evidence → resolve_feature_bindings → qc_raw → preprocess → qc_processed → statistics:<sid> → export:<sid> → report。成果物は results/feature-table.tsv（＋ .annotations.tsv）、results/statistic-<sid>.tsv（＋ .tukey.tsv）、quality-report.md。v2 は合成入力と fake Console までしか検証されておらず、routine 目的は PROFILE_VALIDATION_INVALID で止まる（draft profile ＋ execution_purpose="validation" を使う）。

9.4 run の状態遷移

要求（pipeline-request.v1）の欄と既定値

再開で変えられるのは target / sample_manifest / preprocess / comparisons だけで、それ以外は NEW_PIPELINE_REQUIRED。値の出所は value_sources（explicit / request_file / default / explicit_update）に残る。run record の results は追記専用で、既存要素の書き換えは拒否される。

再開（prepare_resume）の判断順

1. 見張られていない Console が生きていれば止める

   EXECUTION_UNRESOLVED。

2. 上流が未完なら明示を求める

   rerun_upstream なしでは UPSTREAM_RERUN_REQUIRED。Console の自動再試行はしない。

3. 入力と有効メソッドの hash を再検証

   変わっていれば INPUT_CHANGED。

4. 更新をマージ

   内容が同じなら新しい revision を作らない（request_id 付き再送は直前の結果を返す）。

5. pending に戻す stage を決める

   rerun_upstream は全部、シート・前処理・目標の変更は比較以降と report、比較の変更はその比較の stage だけ。同じパスのシートを書き直した訂正も manifest_source の hash で検出する。

ツールが返すもの・書き出すものの見本。列名・メタ行の順序・書式・ファイル名は実装どおりで、例示値 の付いた数値と化合物名は説明用の架空の値。

10.1 差次的エクスポート（契約 v1、別リポ massbank-context との契約）

arf_export_differential と dataset_export_differential は同じ関数（export_contract.build_meta / format_row）で書く。列の追加・改名・並べ替えは CONTRACT_VERSION の引き上げと下流の同時更新なしにしてはいけない。メタ行の順序も契約の一部。

# contract_version = 1
# exported_at = 2026-09-27T05:12:44.918203+00:00
# source_arf = AlignmentResult_2026_05_15_10_13_35_PeakProperties.arf
# source_arf2 = AlignmentResult_2026_05_15_10_13_35.arf2
# group_a = control_6h	n_a = 4
# group_b = ILG_6h	n_b = 4
# log2fc_sign = positive means group_b is higher
# q_threshold = 0.05	log2fc_threshold = 1.0	log_transform = true
# preprocess = normalize=pqn blank_min_fold=3.0 drift_correct=true max_qc_rsd=0.3 impute=half_min
# n_features_total = 1345	n_with_inchikey = 412	n_unannotated = 933
# msi_note = msi_level は .arf2 由来のクラス上限の保守評価で、MS/MS 取得の有無を表さない
spot_id	name	name_source	ontology	inchikey	inchikey_source	msi_level	mz	rt	log2fc	p_value	q_value	mean_a	mean_b	significant
474	SL 33:0;O|SL 17:0;O/16:0	arf2	SL	QXKZ…-UHFFFAOYSA-N	arf2	3	580.4221	9.8812	2.418733	3.1e-05	0.0102	18342.5	98221.7	true
1248	PC 16:0_18:1	arf2	PC	WTJK…-JQQJRHCPSA-N	arf2	3	804.5760	7.0214	-1.302114	0.00041	0.0467	412330	166904	true
2031	TG 52:2	arf2	TG	CEJY…-KFDAUHNHSA-N	arf2	3	876.8015	12.4430	0.412008	0.182	0.611	1.20e+06	1.61e+06	false
3107	FA 18:2	arf2	FA	OYHQ…-HZJYTTRNSA-N	arf2	3	279.2330	3.1120	0.023117			5220.1	5301.4	false

NaN・inf・None は文字列化せず空セルにする（上の 4 行目: 両群とも分散 0 で検定不能なので p と q が空）。有意行だけでなく InChIKey が付いた全行を出すのは、下流の濃縮解析が「検出された化合物」を背景に取るため。mzTab-M 経路のメタ行には source_mztab / source_job / source_verification / result_id / preprocess_id が入り、前処理条件は現在の状態ではなくその結果自身の来歴から書く。

10.2 図

lipidmix.volcano.v1 payload（output="payload"）

{"plot_schema":"lipidmix.volcano.v1","title":"Volcano (control_6h vs ILG_6h)",
 "axes":{"x":{"label":"log2 fold change"},"y":{"label":"-log10 p"}},
 "comparison":{"group_a":"control_6h","group_b":"ILG_6h","n_a":4,"n_b":4},
 "thresholds":{"q":0.05,"log2fc":1.0},
 "points":[{"feature":"Spot_474_height","log2fc":2.4187,"neg_log10_p":4.5086,"sig":"up"}, …],
 "render_hints":{"color_by":"sig","guides":{"x":[-1.0,1.0],"y":[1.3010]}},
 "selection":{"total":1345,"plotted":846,"significant_total":46,"significant_plotted":46,
   "ns_total":1299,"ns_plotted":800,"max_points":800,"dropped_nonfinite":0}}

payload では up/down を全件残し、ns だけを等間隔で決定的に間引く。selection.plotted < total のとき図は全点ではないので、有意件数は必ず significant_total を読む。dropped_nonfinite は「有意でない」ではなく検定不能（分散 0・欠損・片群のみ検出）。

10.3 ツールの戻り値の形

# batch_source = filename_date
sample	role	group	batch	run_order	excluded
20220901_RAW_control_0h_1_NEG	sample	control	20220901	3	false
20220901_RAW_LPS_6h_2_NEG	sample	LPS	20220901	11	false
20220901_QC_01_NEG	qc	QC	20220901	1	false
20220901_Blank_01_NEG	blank	Blank	20220901	0	false
20220902_RAW_ILG_6h_1_NEG	sample	ILG	20220902	27	true

rank	name	adduct	total_score	weighted_dot_product	simple_dot_product	reverse_dot_product	matched_peaks_percentage	matched_peaks_count	entropy_similarity
1	PC 16:0_18:1	[M+H]+	2.6143	0.8921	0.9104	0.9337	0.8333	5	0.7412
2	PC 18:1_16:0	[M+H]+	2.5980	0.8874	0.9051	0.9290	0.8333	5	0.7388
3	PE 19:0_18:1	[M+H]+	1.4410	0.2105	0.3310	0.2892	0.2500	1	0.1934

scoring = {rule: MS-DIAL GetTotalScore, use_rt: false, ms1_tol: 0.01, rt_tol: null}

{"status":"success","group_a":"control_6h","group_b":"ILG_6h","n_a":4,"n_b":4,
 "resolved_samples":{"a":["…control_6h_1…", …],"b":["…ILG_6h_1…", …]},
 "summary":{"n_tested":1345,"n_significant":46,"n_up":28,"n_down":18,
   "top":[{"feature":"Spot_474_height","spot_id":474,"name":"SL 33:0;O|SL 17:0;O/16:0","name_source":"arf2","log2fc":2.4187,"q":0.0102}, …]},
 "caveats":["交絡: 各群が単一バッチ（control=20220901, ILG=20220902）。処理効果と測定バッチを分離できない",
            "小n: 各群 n<4 のため検出力に限界"],
 "volcano_note":"全特徴の点列は session に保持。図は arf_plot_volcano"}

10.4 pipeline が書くもの

pipeline_3f9c…/
├─ pipeline-run.json          # run record（pipeline-run.v1）
├─ requests/revision-0001.json # 要求の各版
├─ control/
│  ├─ worker.lock  pipeline.lock
│  ├─ cancel-request.json      # 取消フラグ
│  └─ worker-launch.log
├─ input/                      # 生データのリンク＋有効メソッド
├─ console/attempt-0001/       # attempt ごとに分ける
│  ├─ analysis-job.json
│  ├─ execution-result.json    # 終了証跡
│  ├─ worker.json  msdial.log
│  └─ msdial/*.mzTab …
├─ results/
│  ├─ pca.png
│  ├─ volcano_<cid>.png
│  └─ differential_<cid>.tsv   # 契約 v1
└─ reports/pipeline-quality-report.md

{"schema":"pipeline-run.v1",
 "identity":{"pipeline_id":"3f9c…","source_root":"D:/raw/NEG", …},
 "request":{"revision":2,"request_id":"req-0927-a",
   "content_hash":"sha256:…","effective_target":"differential"},
 "status":"completed","state_revision":41,
 "stages":{"upstream":{"status":"succeeded","attempt":1, …},
   "differential:ilg_vs_ctrl":{"status":"succeeded","result_refs":[…]}},
 "upstream":{"verification":{"status":"completed",
   "termination":"exited","exit_code":0}},
 "results":[…],   // 追記専用
 "needs_input":null,"warnings":[…],
 "worker":{"identity":{…},"started_at":"…"}}

# Pipeline quality report
status_at_report_time: completed · reason_codes: []
自動の生物学的解釈は含まない。

## Source            D:/raw/NEG · 41 raw files (.wiff)
## Method / LBM / version  param_20260915.txt (sha256 …) · Lipids.lbm2 · MS-DIAL 5.x
## Execution evidence  termination=exited exit_code=0 · execution_id … · mzTab sha256 一致
## Sample provenance   role/group: sample-manifest.tsv · batch: manifest · injection_order: manifest
## Applied / skipped steps  normalize=pqn ✓ · blank_min_fold=3.0 ✓ · drift_correct ✓ · max_qc_rsd=0.30 ✓
## PCA               PC1 31.4% · PC2 12.0% · run_order_correlation PC1 r=0.12
## Comparisons       ilg_vs_ctrl: n=8/8 · tested 698 · significant 37（up 22 / down 15）
## InChIKey coverage  with_inchikey 214 / 714 · identified_by: sme 0 · sml_only 214 · none 500
## Unverified conditions  注入順が確定していない試料 0 件 …

10.5 v2 の表（feature_export）

未同定の特徴も unidentified として 1 行残す（消すと「同定できたものだけの世界」になる）。ms1_annotation は m/z 照合だけで、v2 の required_evidence では library_match も authentic_standard_match も満たさない。

10.6 レポートと目的ノート

---
type: objective
analysis_id: licorice-neg-6h
confirmed: true
status: active
assay_kind: lipid
---
## 確定目的
ILG 処置 6h で変動する脂質クラスを特定する
## 推測の根拠 …
## 派生する小問
- Q1: スフィンゴ脂質は ILG で増えるか
- Q2: PC/PE 比の変化は膜リモデリングを示すか
## 創発的に追記された小問
## 探索ログ（search_log）
- Q1 · "isoliquiritigenin sphingolipid" · hits 7 · promoted 2

---
type: report
analysis_id: licorice-neg-6h
dataset: 2_lipidome_lcms/NEG
date: 2026-09-27
status: draft
knowledge_refs: [sphingolipid-inflammation]
---
## 結果
46 特徴が有意（q≤0.05, |log2FC|≥1）…
## 注意
- 群とバッチが交絡（20220901 / 20220902）
- 各群 n=4
## 図
![volcano](figures/licorice-neg-6h_volcano.png)

利用者がチャットで頼むことと、LLM が呼ぶツールの並び。色は経路（3 章の凡例）と同じ。

文献由来の知識（knowledge/）と再利用できる解析手順（playbook/）を MCP リソースとして配信し、解析の目的（analyses/）とレポート（reports/）をツールで読み書きする。セッションをまたいで所見が積み上がる。

GATEWAY の規則: 目的と生物学的文脈とアッセイ種別を確認してから索引を読み、未解決の小問に答えるノートだけを展開し、どのノートがどの小問に効いたかを明示する。ノート同士が食い違えば両方を source / claim_strength つきで示し、speculative を明示する。これらは硬いゲートではなく指針だが、解釈はゲートを通ることが前提。

失敗は例外ではなく、本文の JSON 封筒で返す（SDK の isError 経路は structuredContent を落とすため）。どの封筒も error.code が機械可読の識別子、message が人と LLM 向けの説明。

{"error":{"code":"missing_state",
  "state":"preprocessed_matrix",
  "required_tools":["arf_preprocess"],
  "message":"前処理後の行列がありません。先に arf_preprocess を実行してください。"}}

{"error":{"code":"METHOD_FILE_CHOICE_REQUIRED",
  "message":"positive のメソッドが無く、negative の候補があります",
  "details":{"searched":[…],"candidates":[…]},
  "required_tools":["console_method_template"]}}

pipeline で needs_input になるのは入力を直せば進める停止（PREPROCESS_PREREQUISITE_MISSING NORMALIZATION_DEGENERATE PREPROCESS_FEATURES_EXHAUSTED COMPARISON_REQUIRED CONFOUNDED_COMPARISON と、_as_needs_input が包む前提エラー）。それ以外の例外は failed（結果があれば partial）になり、traceback はログへ残る。

14.1 起動と環境変数

C:/Python314/python.exe server.py            # 既定 stdio。依存は requirements.txt（Python 3.13+）
C:/Python314/python.exe -m pytest tests -q   # リポジトリルートから
python -m lipidmix.library.store --ion-mode negative   # 大きな .msp の初回構築を事前に

14.2 戻り値を小さく保つ決まり

14.3 既知の限界

• 版依存。バイナリリーダは MS-DIAL の内部クラス配置に従う。クラスを変える MS-DIAL のリリースでは docs/schema/ の Key 番号の再確認が要る。
• 多群 ANOVA は v1 では非公開。MS-DIAL のメタデータに因子と水準の対応が無いため。v2 の anova_tukey は実験情報シートで群を明示したときだけ。
• 同定確度は報告するだけで仮定しない。MS/MS のフラグと実スペクトルを全経路で区別する。Level 1 は主張しない。スペクトル照合の順位付けは上流のタプル全体を再現していない。
• ドリフト補正は移動中央値＋線形補間（LOESS ではない）で、バッチ別の補正は無い。
• ARF 経路では欠損が 0、gap-fill 値もデータとして使うので、half_min はほぼ効かない。検出率で絞るなら min_detection_rate を使う。
• v2 の検証範囲。合成入力と fake Console まで。実 Console 接続と profile の科学的検証は未了。
• 生成物は追跡しない。data/ analyses/ reports/ はクリーンチェックアウトに無い。
• キュレーションの会話内表示は未検証。Claude Desktop のローカル stdio サーバでは MCP Apps の _meta.ui が落ちる（anthropics/claude-ai-mcp#1069）。ブラウザで html_path を開き、送信用テキストを貼る経路が主。
• MS-DIAL は _tags.xml を丸ごと書き直す。アラインメントを保存するたびにメモリ上のタグで上書きし、読むのはプロジェクトを開くときだけ。curation_submit の反映は、プロジェクトを閉じてから送り、開き直して確かめる。GUI での表示そのものはまだ確かめていない。
• MS-DIAL で絞り込まれたデータの likely_wrong。MS-DIAL は同定時に precursor の許容幅を課しているので、precursor_unmatched はまず立たない。強い理由の大半は class_rule_rejected と dmz_out。likely_wrong が少なくても「全部正しい」ではなく、suspect の理由コードを読む。
• 2026-09-27 に解消した食い違い: 同梱参照表を起動ディレクトリに依存せず読むよう修正（以前はリポジトリ外から起動すると ID 付与が黙って全滅していた）。t 値の符号を log2FC と同じ向きに統一。MCP_INSTRUCTIONS とリソース説明のトピック一覧に mztab / library を追加し、テストで固定。library_plot_mirror の説明を mirror.v2 に、ドリフト補正・行列の欠損処理の docstring とコメントを実装どおりに、output_format 文書の log2FC 定義・p 値の計算法・旧ファイル名・スロットの位置を修正。