確定した実験目的を解析フォルダ配下 reports/<analysis_id>.objective.md に記録する（gap駆動探索の前提）。

GATEWAY 手順1で、データから推測した目的をユーザー確認したあとに呼ぶ。biological_context （対象系: 生物種/細胞/処理）も確認のうえ渡す。sub_questions は Q1..Qn の本文。 assay_kind は lipid / metabolite / unknown。確定した種別を渡すと、以後のツール出力の 解釈規則（脂質名文法か候補集合か）がサーバ側で切り替わる。

objective の確定目的/文脈/状態を更新し、創発的な小問を追記する。

assay_kind（lipid / metabolite / unknown）を渡すと解釈規則も切り替わる。

探索結果を objective の探索ログに記録する（既探索 Qi の再探索を防ぐ）。

subquestion はラベル（例 "Q2"）。paper_search を実行したら必ず記録すること。

objective の各小問 Qi を COVERED / WEAK / GAP に分類する（探索候補=GAP）。

決定論ベースライン（文字bigram＋脂質クラス語彙）。COVERED は該当ノートを expand して 真偽を必ず検証すること。GAP かつ未探索の Qi だけが自動探索の対象（探索済みは注記される）。

Europe PMC を検索し、撤回除外・重複除外した候補を返す（ユーザー確認済みクエリ前提）。

返した各候補は LLM が当該 Qi への関連度で採点し、関連するものだけ ingest_stage で _inbox へ隔離すること。生ファイル名・サンプル名をクエリに含めないこと。

関連と判断した候補を knowledge/_inbox に speculative 隔離する（出典必須）。

found_for は "<analysis_id>/" 形式。source は引用可能な書誌（出典なしは拒否）。

_inbox の保留中ノートを analysis_id×Qi でグルーピングして返す。

_inbox の保留ノートを knowledge/ へ昇格する（信頼知識化の唯一の経路）。

claim_strength は established / suggested / speculative のいずれか。links を渡すと 関連ノートへの [[link]] を本文末尾に追記する。

_inbox の保留ノートを破棄する。

解析・解釈レポートを reports/<analysis_id>.md に上書き保存する（成果物＋記録）。

body は frontmatter を含まない Markdown 本文。推奨セクション見出し: ## 目的 / ## 実施した解析 / ## 主要な所見 / ## 解釈 / ## 注意点・コンフリクト / ## 結論。所見が増えたら本文を作り直して再度呼ぶ （ファイルは毎回上書き）。引用した knowledge/playbook の slug を knowledge_refs に渡す。 LIPIDMIX_REPORTS_DIRの明示先を優先し、書込不可なら解析フォルダ配下reports/。 未指定時は解析フォルダ配下reports/だけを使う（リポジトリ側へは退避しない）。

analysis_id はファイル名 slug の元になるため ASCII で一意に。別IDが同一slugに潰れて既存 レポートを上書きしそうな場合は保存を中止して通知する（objectiveレコードと同じIDを推奨）。

過去レポートを読み戻す（候補ディレクトリ横断で最新更新のものを返す）。セッション継続用。

解析フォルダ配下と退避先の両方に同名レポートが残る場合（書き込み可否が途中で変化した等）、 古い方を返さないよう mtime が最新のファイルを採用する。

既存レポートの1行索引（analysis_id / date / status）を返す。

候補ディレクトリ横断で同一 analysis_id が重複する場合は mtime が最新の1件を採用する。

明示的なユーザー要求時だけ、直近の図を reports/figures/<analysis_id>_.png に保存する。

kind: "pca"（arf_parser / arf_pca_preprocessed / arf_pca_species / dataset_pca のスコア。 arf_pca_species の結果は source="species"）/ "volcano" （arf_differential / dataset_differential。間引き前の全点）/ "eic"（eic_plot_chromatograms / eic_plot_compounds）/ "group_intensity"（arf_plot_group_intensity。dpi 300 の PNG と同名 .svg）/ "species"（arf_plot_species。dpi 300 の PNG と同名 .svg）/ "pca_loadings"（plot_pca_loadings。dpi 300 の PNG と同名 .svg）。 source / result_id: kind が pca / volcano のときだけ使う。"auto"（既定）はどちらも優先せず、 有効な結果が 2 つ以上あると AMBIGUOUS_RESULT_SOURCE で止まる（"arf" / "mztab"、kind="pca" のときだけ "species"（arf_pca_species）でも指定できる）。 通常の対話描画では呼ばない（各描画ツールが画像を返す）。返り値の相対パスは write_report の 本文に ![...](figures/<analysis_id>_<kind>.png) として埋め込める。

1つの .pai2（単一測定ファイル）を解析し、ピーク在庫の要約を返します。

返すのは注釈状況・m/z・RT・強度・S/N の分布と、強度上位ピーク（生化学的に意味のある ランキング）です。PAI2 は単一サンプルなので、サンプル間比較（オミクス PCA）はこの単位 では行えません（複数サンプルの多変量比較は ARF/ARF2 を使う）。個々のピークは pai2_inspect_peak / verify_peak_annotation で深掘りできます。MS/MS は 同名 .dcl（dcl_index がリスト順に対応）を参照します。

特定のピークについて、強度・S/N・MS/MS相当の情報を返す。

返り値には signal_to_noise フィールドが含まれます。peak_id か peak_name の いずれかを指定する。

指定した1ピークのアノテーションが生化学的に妥当かを検証するドシエを返す。

分析化学的な同定確度（精密質量誤差ppm・アダクト/イオンモード整合）を決定的に 判定し、生物学的妥当性は関連 knowledge slug を添えて LLM の判断に委ねる。 先に pai2_parser でデータを読み込むこと。peak_id か peak_name の いずれかを指定する。

1つの .dcl（MSDecResult）を解析し、MS/MS 在庫の要約と先頭数件を返す。

.dcl は測定ファイル1つにつき1個で、dcl_index が同名 .pai2 のピーク順に 対応する。返すのは取得率・ピーク本数分布・precursor m/z / RT 範囲の要約と、 先頭 preview 件の主要フラグメント。個々のピークの同定確度に効かせるには pai2_parser（同名 .dcl を自動で付与する）→ verify_peak_annotation を使う。

• top_n_peaks: 各スペクトルを強度上位 N 本に間引く（既定 10。全件は 0 を指定）。

• preview: 要約に添える MSDecResult の件数。

precursor m/z（任意で RT）に一致する MS/MS を .dcl から引く。

アノテーションの裏取り（期待フラグメントが実際に出ているか）に使う。RT を渡すと 同一 m/z の別溶出ピークを分離できる。該当なしは status="not_found"。

参照ライブラリを読み込み、照合用の SQLite store を構築（または既存キャッシュを 再利用）する。

解決順: file_path の明示 → ion_mode（"positive" / "negative"）に対応する 設定（環境変数 MSDIAL_MSP_POS / MSDIAL_MSP_NEG → lipidmix.local.toml の [library] msp_positive / msp_negative）→ データディレクトリの *_Loaded.msp2.dbs → 設定済みの極性（両方あれば ion_mode を求める）→ データディレクトリの *.msp。候補が 1 つに決まらなければ code 付きの エラー（MSP_AMBIGUOUS など）を返し、黙って選ばない。一度に保持する ライブラリは 1 つだけ——測定の極性に合わせて ion_mode を指定する。

初回の構築は大きな .msp（1 GB 級）で数分かかる。MCP のタイムアウトに当たる なら、手元で python -m metabolomix.library.store --ion-mode <極性> を 1 度 走らせておけば、以後はキャッシュを開くだけで済む。

library_match_feature の前提。別ライブラリへ切り替えると直近の照合結果 （library_plot_mirror が読む座標）は破棄する——古い照合を新ライブラリの 結果と取り違えないため。

rebuild=True はキャッシュを無視して構築し直す（元ファイルが壊れている 疑いがあるときなど）。通常は不要——store は元ファイルの sha256 をキーに キャッシュされるため、内容が変わらない限り再構築しない。

測定 MS/MS（.dcl）を参照ライブラリ（library_load 済みの store）と照合し、 上位候補を返す。

照合の対象は precursor_mz か spot_id のどちらか一方で指定する。 spot_id（MasterAlignmentID。eic_search 等で引ける）を渡すと、precursor m/z・ RT・極性を同じバッチの .arf2（arf2_path、省略時は現在のデータフォルダ）から取り、 測定スペクトルはアラインメント .dcl（dcl_file、省略時は .arf2 と同じバッチ）の そのスポットの代表 MS/MS を使う。precursor が ARF2 と ±0.01 で合わなければ 照合せず status="dcl_precursor_mismatch"、ID が無ければ spot_not_found。 rt / ion_mode を明示すれば ARF2 の値より優先する。

ion_mode は "positive" / "negative"（大小は問わない——store.candidates() が COLLATE NOCASE で比較するため、PAI2 由来の IonMode.Positive.name のような "Positive" 表記もそのまま渡してよい）。

mz_tol / ms2_tol / rt_tol は明示指定が無ければ store の search_params （.dbs 由来なら実値）を使い、それも無ければ既定値 （_DEFAULT_MZ_TOL / _DEFAULT_MS2_TOL / _DEFAULT_RT_TOL、現在の値は 0.01 / 0.025 / 0.2）を使う。これらは参照ライブラリの候補検索（store.candidates() の precursor m/z 窓・RT 窓）にだけ効く。 .dcl から測定 MS/MS を引く窓は _measured_spectrum 内部の固定既定（dcl/reader.py と同じ mz_tol=0.01/ rt_tol=0.2）を常に使い、ここの引数や store の search_params の影響を受けない （最終レビュー Important 7: .dbs の RtTolerance 既定 100.0 のような ライブラリ用の値を .dcl 側の RT 窓に流用すると、同じ precursor m/z の 別ピークの測定スペクトルを黙って拾ってしまうため、2 つの窓を分離した）。 足切り（relative_amp_cutoff / absolute_amp_cutoff）と質量範囲 （mass_range_begin / mass_range_end）も同じ search_params から採って 採点（match_spectrum）に渡す——検証 CLI（scripts/verify_spectral_match.py） と同じ集合（最終レビュー Important 2）。

.dcl に MS/MS が無い（未取得）場合は status="not_found" を返す—— 「候補と合わなかった」のではなく「照合する測定スペクトルがそもそも無い」ことを 区別するため、dcl_find_msms と同じ文言の方針に揃える。

候補は total_score の降順で返す（rank 列・ranked_by フィールドが 同じ基準を指す）。MS-DIAL の総合スコア（上流 GetTotalScore）で、 rt + precursor_mz + (weighted+simple+reverse)/3 + matched_peaks_percentage の正規化しない和——1 を超える。組み立て方は戻り値の scoring が明示する （RT 項が入ったかは .dbs の IsUseTimeForAnnotationScoring 次第で、 数値だけを見ても分からないため）。同点は候補順を温存する（安定ソート）。

上流の順位付けと完全に同じではない。 MsScanMatchResultContainer.ResultOrder は (IsManuallyModified, IsReferenceMatched, IsAnnotationSuggested, Priority, TotalScore) の辞書順で、TotalScore は最後のタイブレークにすぎない。 支配項の IsReferenceMatched は脂質クラス固有の判定 （Lipidomics/、上流 66,932 行）に依存するため移植していない。実データでは この判定が無いと全候補が True になってゲートとして働かないので、 total_score 単独比較が現実的な最良の近似という位置づけ。 帰結として、上位に化学的にありえない候補が残ることがある （docs/output_format/library.md §14.9）。

top_n は上位何件を返すかの上限（既定 5）。負値を渡すと全件を返す （明示的な仕様ではなく Python のスライス挙動に由来する副作用的な動作 ——件数を絞りたくないだけなら大きな正の値を渡すこと）。

候補一覧は TSV（列名 1 回）で返す。スペクトル座標と alignment は戻り値に 含めない（LLM の文脈を食うため）。座標は session.library.last_match に 持ち、library_plot_mirror がそこから読む。

直近の library_match_feature 結果から対向プロット（mirror plot）を描く。

上段が測定、下段が参照（rank 位の候補）。output="image"（既定）は サーバ側で描画した PNG を返し、output="payload" は座標を丸めた lipidmix.mirror.v2 JSON を返す（Use-LLLM 等、自前で描くクライアント向け。 v2 で採点外ピーク unscored_mz の層を追加）。

測定側の一致色分けには許容幅（ms2_tol）が要る——library_match_feature が使った値（store の search_params か既定値）を自動で引き継ぐ。

.dbs の強度足切りで採点に入らなかった測定ピークは灰色で薄く描く （last_match["unscored_mz"] を引き継ぐ）。採点は normalize_measured が 足切りした後のスペクトルに対して行うのに、図は足切り前の生ピークを描くため、 区別が無いと「描かれているのに採点されていない」ピークが黙って混ざる。 消さずに描くのは、消すと「MS/MS が取れていない」と読めてしまうため。 この層はラベル枠を取らず、凡例と caption の件数は該当ピークがあるときだけ 出る（足切りが 0 の run では図も caption も従来と変わらない）。

scale は縦軸の写し方で "relative"（既定）/ "sqrt" / "log10"。 precursor がベースピークのスペクトル（脂質の [M-H]- など）は relative だと診断イオンが相対数 % に潰れて読めない——そのときに "sqrt" を使う。 上流 MS-DIAL も同じ問題を軸の切り替えで解いている （ObservableMsSpectrum.CreateAxisPropertySelectors2 の Relative / Absolute / Log10 / Sqrt）。Absolute は用意しない——対向プロットは単位の違う 2 つの スペクトルを上下に並べるので、生の強度で並べても比較にならない。

label_policy は m/z ラベルの衝突回避の方式。どちらも強度降順に走査して 既に置いたラベルと重なるものを飛ばす（上流 Annotator.OnRender と同じ 貪欲法）が、重なりの見方が違う:

• "auto"（既定）— 水平と垂直の両方が近いときだけ飛ばす。箱は ラベル自身の文字列を実測する。対向プロットは同じ側でもピークの高さが 大きく違うので、2 次元で見るほうが読めるラベルを多く残せる。

• "msdial" — 上流に忠実。水平距離だけを見て、箱は代表文字列 "1000.00000" 1 つで全ラベル共通にする。上流の MS2 ビューは Overlap="Horizontal, Direct" だが、この合成は OR で、全ラベルが同じ箱を 使うため Direct は Horizontal の部分集合になり実質 Horizontal 単独に 縮退している。縦にどれだけ離れていても m/z が近ければ飛ばすので、 "auto" よりラベルは少なくなる。

どちらも上下は別枠で数える（上流は上下で別々の Annotator を持つため、 側をまたぐ衝突は起きない）。

List MS-DIAL tags discovered for the currently loaded ARF dataset.

絞り込み・群分けに使える因子トークンの一覧を返す（Class ID とサンプル名の両方）。

class_ids / group_levels / group_factors / group_a / group_b に何を書けるかを 発見するための入口。.mddata が無くてもサンプル名の語彙は返る。 sample_token_vocabulary.tokens[<token>] は出現サンプル数・role 内訳・ サンプル名内の出現位置を持つ。位置は因子の並びを推測する手掛かりだが、値が 2トークンに割れる場合（G_uralensis）にずれるため指定には使わない。

ロード済み ARF のサンプルを sample/qc/blank に分類し、TSV 表で返す（前処理の適用前確認）。

列は sample / role / group / batch / run_order / excluded。group は group_levels 未指定時の既定＝完全 Class ID。batch は MS-DIAL に専用項目が 無いためファイル名中の8桁日付からの推定で、その出所（batch_source）は 全行共通なのでヘッダ行にまとめてある。

PCA 外れサンプルや特定ピークを名前/ID で手動除外・再包含する（可逆・非破壊）。

先に arf_parser で ARF を読み込んでおくこと。除外は session に保持され、以降の arf_parser の再実行 / arf_preprocess（→ arf_pca_preprocessed / arf_differential）へ反映される。 filtered_features 自体は変更しないため、mode="remove"/"clear" で元に戻せる。

引数:

• exclude_samples: 除外するサンプル。完全なサンプル名に加え、_ 区切りの因子 トークン指定（"ILG_6h" = ILG かつ 6h の全サンプル）を受ける。トークンは Class ID とサンプル名の両方から解決される。解決結果は payload の resolved_samples に必ず出る。一致ゼロの指定は unmatched_samples 行きで、 除外指定の取りこぼしだけで解析を止めない。

• exclude_spots: 除外するスポットの MasterAlignmentID（int）のリスト。

• mode: add（既定・追加）/ remove（再包含）/ clear（全消去）/ list（現状表示のみ）。

ロード済み ARF 行列に前処理レシピを適用し、session を更新して報告を返す。

以降の PCA/差次的解析は session_state.session.feature_matrix（前処理後）を消費する。

arf_preprocess で用意した前処理後行列で PCA を実行する（前処理後経路の PCA 入口）。

正規化・QC フィルタ・欠損補完を経た行列に対する PCA。生スポットへ直接フィルタして やり直す PCA は arf_parser。手順は arf_preprocess → 本ツール。色分け(group_levels)や log 変換だけを変えて再実行しても、前処理はやり直さない。 群分けは group_levels（1因子）または group_factors（因子軸の直積、例 [["control","ILG"],["0h","6h"]] → "control|0h"）で指定する。値トークンは Class ID とサンプル名の両方から解決されるため、Class ID に無い時点などでも色分けできる。

.arf（サンプル別強度）を読み込み、フィルタを適用して PCA を実行する。

生スポット行列に対する PCA の唯一の入口。フィルタ条件を変えて PCA をやり直したい ときは、引数を変えて本ツールを再呼び出しする（ファイルはセッションキャッシュされ 再パースは走らない）。手動除外（arf_exclude）も PCA 前に反映される。 正規化・QC・欠損補完を経た「前処理後」行列での PCA は arf_preprocess → arf_pca_preprocessed。

正負の Loading 上位とスコアプロット用 JSON を含む Markdown 要約を返す。

引数:

• file_path: 解析する .arf ファイルのパス (省略時は自動検索)

• props: PCAに使用するプロパティのリスト (デフォルト: ["height"])

• components: 計算する主成分の数

• top_features: 各主成分から抽出する正・負の寄与トップ件数 (デフォルト: 10)

• log_transform: [任意] PCA前に log10 変換を適用する（強度の歪みを抑え条件分離が向上しやすい。既定 False）

• min_detection_rate: [任意] 特徴量の実検出率(非ギャップフィル)による足切り 0.0-1.0（既定 0.0=無効）

• min_intensity: [任意] スポット平均強度(HeightAverage)の最小閾値（既定 0.0=無効）

• annotation_keyword: [任意] 同一バッチARF2の名前を優先した部分一致検索。 ARF2が無い/未注釈ならARF名を使う。PCはLPCにも部分一致するため、クラス限定はontologiesを使う。

• spot_ids: [任意] MasterAlignmentIDの完全一致リスト（0以上、空リスト不可）。

• ontologies: [任意] 脂質クラスの完全一致リスト（大文字小文字を区別しない）。 spot_ids、キーワード、他のフィルタとはAND。元のピーク値は変更しない。 これは生スポットの選択であり、選択変更後はarf_preprocessを再実行する。 部分集合でTIC正規化すると分母が変わる。全体の正規化/FDRを維持する用途では 全体で解析・エクスポートしてから対象を参照し、部分集合で再計算しない。

• tag_labels: [任意] MS-DIALタグ名またはタグIDのリスト

• tag_mode: any/all/none/not_all のいずれか

• tag_scope: sample_peak（サンプル別Peak ID）または alignment_spot（MasterAlignmentID）

• tag_directory: [任意] *_tags.xml の探索先。既定はARFと同じディレクトリ

• missing_sample_policy: タグファイル未対応サンプルの扱い。error/exclude/untagged（既定 error）

• class_ids: [任意] 因子トークンによるサンプル絞り込み。各要素は _ 区切りの部分指定 で、指定した全トークンを含むサンプルに一致する（要素内AND・順不同）。要素間はOR。 トークンは Class ID とサンプル名の両方から解決されるため、Class ID に入って いない因子（時点・複製・測定日）でも絞れる。例: ["6h"], ["ILG_6h","control_6h"]。

• class_missing_sample_policy: Class IDメタデータ未対応サンプルの扱い。error/exclude（既定 error）

• group_levels: [任意] PCA点の色分け因子の値トークン（例: ["gf","spf"]）。 未指定なら各サンプルの完全Class IDで色分け。指定するとその因子だけで統合し、 該当しないサンプルは "other" 群になる。

• group_factors: [任意] 因子軸のリスト。各軸は値トークンのリストで、直積ラベルを 作る（例 [["control","ILG"],["0h","6h"]] → "control|0h"）。group_levels より優先。 処置×時点のような多群を手書き列挙せずに色分けできる。

• include_roles: [任意] class_ids のフィルタに含める role（既定 ["sample"]）。 統合トークン空間ではサンプル名経由で QC/blank を掴み得るため既定で落とす。 QC も含めたいときだけ ["sample","qc"] のように明示する。

前処理後行列で2群差次的解析（Welch t 検定 + log2FC）を行う。

group_a / group_b の両方を指定する。多群 ANOVA は「因子（加齢/菌叢等）→水準」の 対応が MS-DIAL メタに無く安全に導けないため現状は非対応（誤って全 Class ID を 水準にした結果を返さないよう封鎖している）。3群以上を比べたいときは、下記の 因子トークン・プール指定で関心のある2群を切り出して呼ぶこと。

先に arf_preprocess を実行して session_state.session.arf.feature_matrix を用意すること （未実行ならエラーを返す。生行列への暗黙フォールバックはしない）。

• group_a / group_b: 完全な Class ID（24M_GF_F）に加え、因子トークンによる プール群指定を受け付ける。group_a="24M", group_b="9w" のように書くと、その トークンを含む全 Class ID がプールされる（24M_GF_F + 24M_SPF_M + …）。 複数トークンの AND 指定も可（"24M_GF"）。両群が同じ Class ID を掴むとエラー。

• log_transform: [既定 True] log2(x+1) 空間で検定する。MS 強度は対数正規に近く、 生強度での t 検定/ANOVA は正規性仮定を外れやすいため既定で有効。2群では log2FC も log2 空間の群平均差（＝幾何平均比）になる。生スケールで検定したい場合のみ False。

差次的結果を InChIKey 付きの 1 ファイルへ書き出す（spec §6.1）。

先に arf_preprocess → arf_differential を実行しておくこと。同一 アラインメントの兄弟 .arf2 から同定情報を MasterAlignmentID で結合する。 濃縮解析の背景を保つため、有意な行だけでなく InChIKey が付いた全行を出す。

apply_curation（既定 true）: curation_submit で wrong を付けたスポットを 同定なしとして扱い、出力から外す。フラグがあればメタ行 # curation = ... で 適用状況を宣言する。フラグが無ければ出力は変わらない。成功 payload の curation は {state, wrong_excluded, suspect, orphaned}（orphaned は以前の版の .arf2 に付いたまま当たらないフラグの件数。1 件以上なら warnings にも出る）。 assign（curation_submit の候補付け）は同定を置き換え（name_source / inchikey_source = curation）、redundant は除外する。どちらかがあれば curation に assigned と redundant_excluded が足される。 フラグ記録（curation/flags.jsonl）に読めない行があれば書き出さずにエラーを返す （wrong を黙って落とさないため）。

Show the latest two-group volcano — as a PNG image by default.

Run arf_differential (two-group) first. Read-only; writes no file.

output="image" (the default) renders the plot server-side and returns it as an image block plus a one-line caption, so the figure appears directly in the chat. output="payload" instead returns the client-neutral lipidmix.volcano.v1 JSON for a client that draws its own interactive chart (Use-LLLM's Plotly view); the deployment default can be flipped with the LIPIDMIX_PLOT_OUTPUT environment variable.

Prefer the image: the coordinate payload costs tens of thousands of tokens and an LLM cannot read a point cloud usefully — the numbers you should reason about (counts, top hits, caveats) are in arf_differential's own result. In payload mode, up/down points are always kept in full and only ns points are thinned to fit max_points; every count is reported in selection. The image always draws every feature.

Call save_figure(kind="volcano") only when the user wants the PNG written to disk.

選んだクラス・分子種ごとに、試料群の試料別強度を並べる（1 項目 1 パネル。既定は PNG 画像）。

• items: 1 項目 1 パネル（1〜30 件）。.arf2 の Ontology に完全一致すればクラス（全分子種の合計）、 しなければ分子種名（| で分けた候補名に完全一致。low score: 等の接頭辞は無視）。 "PE+EtherPE" のように + で合算。当たらない項目は N.D. のパネルになる。

• groups: 1 群以上。arf_differential と同じトークン規則（"KO_9w" は両方を含む試料）。 QC・ブランクは群の指定に qc / blank を書いたときだけ入る。

• 1 点 = 1 試料の PeakHeight 合計（gap-fill 含む）。縦軸は log10 で全パネル共通、群は log10 の平均 ± SD。 検定はしない（arf_differential を使う）。

• クラスの合計からは標識内部標準（(d7) 等）と、standard_samples の試料にだけある分子種を除く。 apply_curation（既定 True）で人の判断（wrong / redundant 除外、assign 付け替え）、 exclude_auto_likely_wrong で最新レビューの likely_wrong も除く。除いたものは payload の excluded。

• low_reliability_samples: 白抜きで描き、平均 ± SD から外す。

• detection_limit: 検出下限の破線。省略時は param ファイルの Minimum peak height。

• arf_exclude で除いた試料は描かず、除いたスポットはクラスにも名前指定にも入れない（excluded の manual）。

• output: "image"（既定）/ "payload"（lipidmix.group_intensity.v1）。PNG ファイルが要るときは save_figure(kind="group_intensity")。

• 入力の誤り（群が当たらない・detection_limit が 0 以下・ncols が 1 未満など）は {"status": "error", "message": ...} で返す。失敗した呼び出しの後は前回の図を破棄する。

全特徴量と出典別候補をmassbank-context用v2バンドルへ出力する。既存v1は変更しない。

選んだクラスを分子種（アラインメントスポット）に展開し、1 分子種 1 パネルで群ごとの試料別の値を並べる。

• items: クラス名（.arf2 の Ontology に完全一致）は配下のスポットに展開、それ以外は分子種名。 同じ名前でも付加イオンが違えば別パネル（見出しに付加イオンと ID）。1 回 40 パネルまで。

• groups: arf_plot_group_intensity と同じトークン規則（QC・ブランクは qc / blank を書いたときだけ）。

• value: "share"（既定。試料ごとに 高さ ÷ 分母の合計 × 100。棒 = 群平均、ひげ = SD）/ "height" （PeakHeight を log10 で。横線 = log10 の平均、ひげ = SD、0 は軸の下端）。検定はしない。

• share_basis: 割合の分母にする項目（省略時は items）。例: PG のページでも分母は ["PG", "DGDG", "MGDG", "CL"]。分母にも同じ除外を適用する。当たらない部品があると分母が変わるので 描かずにエラー。items に当たらない部品は caveats に書く。value="height" では share_basis は無視される。

• 除外は arf_plot_group_intensity と同じ（内部標準・standard_samples だけにある分子種・ apply_curation の判断・exclude_auto_likely_wrong・arf_exclude したスポット）。require_msms=True で MS/MS の裏付けがない分子種も除く。除いたものは payload の excluded。

• low_reliability_samples: 白抜きで描き、平均と SD から外す。菱形は gap-filled の値。

• output: "image"（既定）/ "payload"（lipidmix.species_intensity.v1）。PNG ファイルは save_figure(kind="species")。

• 入力の誤りは {"status": "error", "message": ...}。失敗した呼び出しの後は前回の図を破棄する。

選んだ分子種（arf_plot_species と同じ項目指定・除外）で PCA を回し、スコア図を返す。

• 対象の試料は groups に入る試料（2 群に入る試料は最初の群の色で 1 回だけ）。

• low_reliability_samples は主成分の計算に使わず、投影だけする（図では白抜き）。

• normalize: "none"（既定）/ "total"（試料ごとに選んだ分子種の合計で割り、全試料の合計の中央値を掛ける。 試料量の差を除いて組成を比べるとき）。log_transform（既定 True）で log10(x + 1)。 その後、計算に使う試料の平均と母標準偏差で autoscale。分散 0 の分子種は外す。

• orient_by: 群名。その群の平均スコアが正になるよう主成分の符号をそろえる（符号は本来任意）。

• ローディング（固有ベクトルの成分と相関 r）はセッションに残し、plot_pca_loadings(source="species") が描く。スコア図のファイルは save_figure(kind="pca", source="species")。

• output: "image"（既定）/ "payload"（点列・寄与率・PC1 の r の上位と下位）。

• 計算に使う試料が 3 未満などの入力の誤りは {"status": "error", "message": ...}。

因子トークンでサンプルを検索し、FileID と実ファイルパスを返す。

MS-DIAL の Class ID には実験デザインの全因子が入らない（時点・複製・測定日は サンプル名にしか無いことがある）。本ツールは Class ID とサンプル名を統合した トークン空間で検索し、pai2 / dcl / EIC が直接使える形で結果を返す。

• specs: _ 区切りの因子トークン指定のリスト（要素内 AND・順不同、要素間 OR）。 例 ["ILG_6h"], ["ILG_6h","control_6h"]。省略すると全サンプルと token_vocabulary（何で絞れるかの語彙一覧）を返す。

• directory: 探索先。省略時は既定のデータディレクトリ。ロード済み ARF があれば そのサンプル名を優先して使う。

• extensions: 実パスを引く拡張子（既定 [".pai2", ".dcl"]）。複数バッチが 混在していても最新バッチを自動選択する。

• include_roles: 結果に含める role。省略時は全 role を返す（role フィールドで 判断できるため検索側では絞らない）。["sample"] で QC/blank を落とせる。

返り値の各サンプルは name / file_id / class_id / role / tokens / files{拡張子: 実パス}。file_id は eic_plot_chromatograms(file_ids=[...])、 files[".pai2"] は pai2_parser(file_path=...) にそのまま渡せる。

.arf2 ファイル（MS-DIALの全体カタログ）を解析し、データセットの全体像（メタデータ）を要約して返します。 このファイルにはサンプル個別の強度データは含まれていないため、PCA等の多変量解析は実行できません。 データ全体の品質や、アノテーション状況の概観を把握するために使用します。

指定/自動解決の ARF2 スポット注釈を GOSLIN 正規化・RefMet/LIPID MAPS ID・ MSI レベルで一括標準化し、TSV 表で返す（オフライン）。

返すのはファイル先頭から max_rows 件だけで、強度順でも MSI 順でもない。 総スポット数と残り件数はヘッダ行に出るので、カタログ全体を見たと思わないこと。 絞り込みには arf_parser(annotation_keyword=...) や arf2_parser の概観を使う。

ARF2 には MS/MS 取得フラグ・精密質量誤差が無いため、MSI は保守的にクラス上限で 評価する（has_msms=False, バンドは UNKNOWN）。より確度の高い MSI 評価は個別ピークの verify_peak_annotation（精密質量・アダクト整合を含むドシエ）を参照。

.EIC.aef ファイルに対応する解析用関数 ファイルを解析し、テキスト要約を返します。

Return client-neutral plot data for selected EIC chromatograms.

This read-only tool returns structured lipidmix.eic.v1 JSON only. It does not render an image and does not write files: Use-LLLM may render the series with Plotly, while Claude Desktop or another MCP client may use its own UI. Call save_figure(kind="eic") only after the user explicitly requests PNG output.

spot_id is exact and should normally come from the existing m/z or RT search tools. file_ids selects at most 12 sample traces; when omitted all traces are returned only if the spot contains 12 samples or fewer.

Overlay several identified compounds' EIC traces for ONE sample — as a PNG image by default.

Read-only; writes no file.

output="image" (the default) renders the overlay server-side and returns it as an image block plus a one-line caption, so the figure appears directly in the chat. output="payload" instead returns the client-neutral lipidmix.eic.multi.v1 JSON for a client that draws its own interactive chart (Use-LLLM's Plotly view); the deployment default can be flipped with the LIPIDMIX_PLOT_OUTPUT environment variable. Prefer the image — one overlay's coordinate payload costs tens of thousands of tokens and an LLM cannot read a trace usefully.

One call plots one sample: file_id is required. To compare samples, call this tool once per sample and show the figures side by side. top_n caps how many compounds are overlaid (default 8: more than that is unreadable in one figure and multiplies the payload).

Compounds are selected from the ARF2 annotation: names matches ARF2 Name as a case-insensitive substring and ontologies matches ARF2 Ontology exactly (case-insensitive); the two results are unioned. At least one of them is required.

spot_id = AlignmentID is verified against the EIC spot RT and m/z, so a compound whose identity cannot be confirmed is not drawn. EIC files written by MS-DIAL before 2023-11-20 carry no spot m/z (-1); those spots borrow the ARF2 MassCenter after an RT check, and a caveat says so. Everything that was excluded — mismatch, missing trace, or falling outside top_n — is listed with its reason in selection.dropped; read it before concluding that a compound is absent from the sample.

EIC スポットを spot ID・m/z 範囲・RT 範囲で検索し、TSV で返す。

指定した条件はすべて AND で掛かる（何も指定しなければ全件）。境界値は含む。 spot_ids は MasterAlignmentID（ARF / ARF2 / .dcl と共通）の完全一致で、 範囲外の ID は注記に列挙する。sort="max_intensity" は各試料のクロマトグラム 最大強度の、そのまた最大値で降順に並べる（強度上位ランキング）。既定は spot_id 昇順。

各行は spot_id rt mz max_intensity num_samples name ontology adduct n_msms。 name / ontology / adduct は同じバッチの .arf2、n_msms は アラインメント .dcl の代表試料 MS/MS のピーク数。- は未取得または precursor 不一致で、0 本ではない。未注釈で n_msms がある行は library_match_feature(spot_id=...) → library_plot_mirror で照合・確認できる。

データフォルダにある解析対象ファイルを拡張子別に一覧します。

• directory: 探索するフォルダ。省略時は既定のデータディレクトリ (環境変数 LIPIDMIX_DATA_DIR または /data)。

• extension: 指定するとその拡張子だけに絞る（例 '.pai2', '.arf2', '.EIC.aef'）。

• all_files: 既定では解析できる拡張子 (.arf / .arf2 / .pai2 / .dcl / .EIC.aef / .mddata / .mdproject) だけを返す。 測定生データ（MS-DIAL が読む .abf / .ibf / .cdf / .mzml / .wiff / .raw / .d / .wiff2 / .qgd / .lcd / .lrp / .imzml）まで見たいときだけ True にする。 Agilent・Bruker の .d と Waters の .raw はフォルダが 1 検体なので、 末尾に / を付けて示す。

返すのは絶対パスで、pai2_parser(file_path=...) 等へそのまま渡せる。 フォルダ全体をまず解析するなら load_dataset(directory) が入口。

データフォルダを指定して、最初の標準解析（arf2 概観 → arf 詳細）を一括実行します。

MS-DIAL出力フォルダを解析する際の 入口 です。フォルダのパスを渡すと:

1. .arf2（データセット全体のカタログ＝概観）を要約し、

2. サンプル別強度を持つ .arf で PCA を実行します。フォルダに DriftSpots.arf と PeakProperties.arf が併存する場合は、解析に使う PeakProperties.arf を自動選択 します。 以降の arf_list_classes / arf_parser 等はこのセッション状態をそのまま利用できます。

複数日付（複数回のMS-DIAL処理＝複数バッチ）のファイルが混在していても解析は 止まりません。ファイル名の AlignmentResult_<timestamp> を見て 最新バッチを 自動選択 し、選択結果を出力に明示します（旧バッチはスキップ）。

• directory: MS-DIAL出力フォルダのパス。省略時は既定のデータディレクトリ (環境変数 LIPIDMIX_DATA_DIR または /data) を使用します。 明示した場合は以降のツールの既定探索先もこのフォルダに更新されます。

mzTab-M 2.0 ファイルを読み込んで正準状態（DatasetState）を作る。

呼び出し方:

• mztab_path: .mzTab ファイルへの絶対パスを直接指定する場合。

• job_path: analysis-job.json へのパスを指定する場合。ジョブの宣言 （polarity・measure）で正準エントリを一意に選ぶ。console_run 完了後は こちらを推奨。

• pipeline_path: pipeline_run が返した pipeline-run.json（またはその親 ディレクトリ）を指定する場合。その run の mzTab に加えて、解決済みの 試料対応表・feature binding・解析行列も同じ run からまとめて載せる。 行列だけを別に載せる入口は置いていない——別 run の行列を混ぜると群の 対応が黙ってずれるため。載せた行列は dataset_statistic へ matrix_id で渡す。run の差次的結果も、データと群の指紋が今の データセットと一致するものだけを戻す（result_id は run の TSV と同じ。 直近の結果にはしないので result_id で名指しして使う）。戻せなかった ものは理由つきで要約に並ぶ。

3つとも省略するとエラー、2つ以上指定するとエラー。

allow_incomplete: 完了していない実行（partial / failed / running）の出力を 読み込みます（既定 False）。中断時点の生成物なので、既定では拒否します （INCOMPLETE_ANALYSIS_JOB）。True で読んだデータセットは探索専用になり、 2 群比較（dataset_differential）と差次的エクスポートは拒否されます—— 欠けた検体を「その群には無い」と読み違えたまま結論が出てしまうためです。

成功すると session.dataset に DatasetState が格納され、 dataset_status で内容を確認できる。 既存の session.arf / .arf2 / .pai2 / .eic は変更しない。

現在の DatasetState の概要を返す。

samples に name/role の TSV が入る。dataset_differential の group_a / group_b はここに出る名前をそのまま使う。

dataset_load を先に実行しておくこと。 未実行の場合は missing_state エンベロープを返す。

MS-DIAL Console の実行計画を作成し、analysis-job.json を生成します。

Parameters

dataset_root: 生データフォルダのパス。MS-DIAL が読む 12 形式 （.abf / .ibf / .cdf / .mzml / .wiff / .raw / .d / .wiff2 / .qgd / .lcd / .lrp / .imzml）が入っているフォルダを指します。 Agilent・Bruker の .d と Waters の .raw はフォルダが 1 検体です。 リポジトリ外のパスを指定してください。 method_file: MS-DIAL Console のパラメータファイル（ASCII テキスト。key: value 形式）。 省略できます — 省略時は dataset_root 直下・兄弟フォルダ・過去 run （runs/*/analysis-job.json）まで探し、Ion mode が polarity と 一致する最新のものを使います。一致が無く別極性の候補があれば METHOD_FILE_CHOICE_REQUIRED で止まります（候補の列挙だけなら console_method_candidates）。 .mdproject / .mddata は使えません（ZIP なので Console は中身を 読めず、全パラメータが既定値のまま実行されます）。 lbm_file: 脂質ライブラリ（.lbm2）のパス。省略時は「メソッドファイルの宣言 → ビルド生成物（MsdialWorkbench をソースからビルドしている場合） → [msdial] lbm（lipidmix.local.toml）か環境変数 MSDIAL_LBM → Console の実行体（[msdial] exe / MSDIAL_EXE）と同じフォルダ」の順に、MS-DIAL GUI と 同じ規則で自動解決します。GUI 由来のパラメータは Lbm file path: が 必ず空なので、この自動解決が無いと警告なしで同定 0 件になります。 自動補完（宣言より後ろの 3 つ）は lipidomics だけです。引数と宣言は metabolomics でも使います（Console は omics を問わず LBM で脂質を同定する）。 解決した LBM と、相対で宣言されたライブラリ類のパス（Msp file path Text DB file path 等）は、メソッドファイル基準の絶対パスにして run_dir/effective-method.txt へ書きます（Console は相対パスを 自分の作業フォルダ基準で読み、見つからなければ黙って飛ばすため）。 polarity: "positive" または "negative"。 measure: "peak_height"（既定）または "peak_area_above_zero"。 現行 MS-DIAL Console は peak_height のみ正確に出力します。 "peak_area_above_zero" を指定すると UNSUPPORTED_AREA_CONSOLE で停止します。 omics: "lipidomics"（既定）または "metabolomics"。 save_project: True（既定）なら MS-DIAL Console に -p を渡し、GUI で開ける .mdproject を出力フォルダに生成させます。 timeout_s: MS-DIAL Console のタイムアウト秒数（既定 21600 ＝ 6 時間）。 実測では 4 サンプルで約 3 分。60 サンプル規模では 1 時間を超え得ます。 keep_extension: アライメントする計測形式（例 "wiff" / "wiff2"）。dataset_root に形式が 混在しているとき（SCIEX は 1 測定につき .wiff と .wiff2 ができる）に 使います。省略して混在していれば、選べる形式を choices に入れた MIXED_RAW_FORMATS を返すので、そこから選んで呼び直してください。 指定すると、その形式の計測ファイルと随伴ファイルだけを集めたフォルダを <元フォルダ>_<拡張子> にハードリンクで作り（既にあれば欠けている分だけ 補う）、そちらで計画します。元フォルダは変更しません。 library_mode: "auto"（既定）か "msp_only"。"msp_only" は LBM を使わず、研究室の参照ライブラリ （.msp）だけで同定する: 実効メソッドの Lbm file path を空にし、Msp file path に msp_file か極性の設定（環境変数 MSDIAL_MSP_POS / MSDIAL_MSP_NEG → lipidmix.local.toml の [library] msp_positive / msp_negative）を書き、メソッドが宣言する Text DB と MSP / Text の注釈器設定表を空にする（消したキーは removed_declarations）。 メソッドの Msp file path の宣言は使わない。MSP が決まらなければ MSP_NOT_CONFIGURED / MSP_NOT_FOUND で止まり、ジョブを作らない。lbm_file とは同時に指定できない。 戻り値の msp はファイル名と出どころだけで、ライブラリの置き場所は返さない。 msp_file: library_mode="msp_only" で使う MSP の明示パス（設定より優先）。"auto" では指定できない。

成功すると session.current_job_path にジョブパスが設定され、 console_run でそのまま実行できます。

MS-DIAL Console を実行します。

job_path: analysis-job.json へのパス。省略時は session.current_job_path を使用します。 事前に console_plan を実行しておく必要があります。

detach: True にすると監視ワーカーを親から切り離して起動し、待たずに戻ります。 実データ 60 サンプルは約 44 分かかるため、既定の同期実行では 1 ツール 呼び出しがその間ずっと戻らず、呼び出し元が中断されると生成物ごと失います。 長い実行ではこちらを使ってください。

返る `pid` は**監視ワーカーのもの**で、MS-DIAL Console のものではありません
（Console の pid は run_dir の execution-result.json に載ります）。ワーカーが
終了まで見張り、生成物の収集とジョブの確定まで行うので、`console_status` を
呼ばなくても結果は確定します。

どちらの経路でも run_dir に終了証跡（execution-result.json）が残ります。 終了コードが 0 でも、主 mzTab-M が一意に選べ、定量行列に有限値があり、予定した 入力が全て assay に対応していなければ completed にはなりません（partial / failed）。

実行完了後、session.current_job_path は同じジョブを指し続けます。 結果は console_status または dataset_load で確認してください。

計測フォーマットが 1 種類だけの入力フォルダを作ります（MIXED_RAW_FORMATS の解消）。

MS-DIAL は .wiff と .wiff2 を別フォーマットとして数えるため、SCIEX の 生データフォルダはそのままでは対話プロンプトが出て実行できません。 このツールは指定した拡張子の計測ファイルとその随伴ファイル （.wiff.scan / .timeseries.data 等）だけを集めたフォルダを作ります。

Agilent・Bruker の .d と Waters の .raw のようにフォルダそのものが 1 検体の形式も扱えます。その場合はフォルダ構造を実体として作り直し、 中のファイルだけをリンクします（フォルダ自体はリンクにしません）。

実体はコピーせずハードリンクを張ります（同一ボリュームで無い場合のみコピー）。 元フォルダは一切変更しません。 MS-DIAL の生成物はこの新しいフォルダ側に 出るので、生データ本体を汚さずに済みます。

dataset_root: 生データフォルダ。 keep_extension: 残す計測拡張子（既定 "wiff"）。MS-DIAL が読む 12 形式 （abf / ibf / cdf / mzml / wiff / raw / d / wiff2 / qgd / lcd / lrp / imzml）から選びます。MIXED_RAW_FORMATS の formats が実際の内訳です。 out_dir: 出力先。省略時は <元フォルダ>_<拡張子> を兄弟として作ります。

ジョブの現在のステータスを返します。

保存済みの状態を読むだけで、完了処理はしません。実行の監視・生成物の 収集・ジョブの確定は切り離しワーカー（console_run が起こす）が最後まで行うので、 このツールを呼ばなくても結果は確定します。

job_path: analysis-job.json へのパス。省略時は session.current_job_path を使用します。 include_artifacts: 生成物の全文一覧（TSV）を含めます。既定 False。 生成物は 1 サンプルにつき 5 件出るため 60 サンプルで 300 行を超え、 全文を返すと後ろの warnings / error が埋没します。既定では件数 (artifact_count) と役割別内訳 (artifacts_by_role) だけを返します。 個々のパスが必要なとき（欠落の特定など）だけ True にしてください。

既存のパラメータから、別極性用のメソッドファイルを作ります（最後の手段）。

まず console_plan の method_file 省略を試してください。 MS-DIAL GUI は解析の たびに <project>_param_<終了時刻>.txt を自動保存するので、その極性で一度でも GUI 実行があれば、作る必要はありません。

このツールが要るのは「その極性で一度も処理していない」場合だけです （別極性は処理済み、というのが典型）。やることは 2 行の差し替えです: Ion mode と Searched adduct ions をその極性の標準セットにする。 検出・アライメント条件は元のまま引き継ぎます（勝手に変えると別の解析になる）。 加えて、GUI 由来では必ず空の Lbm file path を解決して埋めます。

out_path: 書き出し先。 polarity: "positive" / "negative"（作りたい側）。 based_on: 元にするパラメータファイル。省略時は dataset_root から探します （極性は問いません — 別極性から作るのがこのツールの用途なので）。 dataset_root: based_on 省略時の探索先。dataset_root 直下・兄弟フォルダ・ 過去 run まで探します。候補が複数あれば based_on で選ぶよう METHOD_FILE_CHOICE_REQUIRED で止まります（土台の選択は解析条件そのもの なので、最新を黙って採りません）。 library_mode: "auto"（既定）か "msp_only"。"msp_only" は console_plan と同じく Lbm file path を空にし、Msp file path に作りたい極性の研究室 MSP を書き、 Text DB と注釈器設定表の宣言を空にする（解決順・止まる条件も console_plan と同じ）。 msp_file: library_mode="msp_only" で使う MSP の明示パス。

使えるメソッドファイルの候補を列挙します（console_plan が失敗する前に呼べます）。

MS-DIAL GUI は解析のたびに <project>_param_<終了時刻>.txt をプロジェクト フォルダへ自動保存します。その極性で一度も GUI 実行が無いフォルダには存在 しないため、兄弟フォルダ（POS の隣の NEG 等）と過去 run まで探します。

dataset_root: 生データフォルダ。 polarity: "positive" / "negative"。省略すると極性で区別せず全件返します。 指定すると各候補に usable が付き、一致しないものは needs_polarity_conversion（console_method_template を経由させる）。 omics: 既定 "lipidomics"。None で絞り込みません。 search_dirs: 追加で探すフォルダ。再帰はしません。

候補には比較用の key_params（検出・アライメント条件のうち結果を変える少数）が 付きます。候補が 10 件を超えるときは付きません（戻り値が肥大するため）。

あるジョブが生成したファイルだけを一覧・削除します（既定は一覧のみ）。

MS-DIAL Console は生データフォルダ側にも生成物を出すため、再実行のたびに 別タイムスタンプのアライメント一式が同じフォルダへ積まれます。放置すると 「複数バッチ混在フォルダ」になり、どれが今回の結果か分からなくなります。

消す対象は analysis-job.json が記録した生成物だけです。タイムスタンプの 推測では消しません（別バッチの成果物を巻き込むため）。記録が無いジョブは NO_JOB_OUTPUT で拒否します。生データ（.wiff 等）には触れません。

dry_run: True（既定）なら一覧を返すだけ。False で実際に削除します。 削除後、ジョブの status は cleaned になります（生成物を指したまま completed で残ると、dataset_load が存在しないファイルを読もうとします）。

dataset_root/runs/ 以下のジョブ一覧を新しい順に返します。

dataset_root: 生データフォルダのパス（console_plan で指定したものと同じ）。

DatasetState の定量行列に前処理レシピを適用する。

引数は arf_preprocess と同一。以降の dataset_pca / dataset_differential は ここで作った前処理済み行列を消費する。

normalize: "none"（既定）/ "tic"（行総和）/ "median"（行中央値）/ "pqn"。 blank_min_fold: 生体試料平均がブランク平均のこの倍数未満の特徴量を背景として 除去する（例 3.0）。None（既定）でブランク除去なし。 drift_correct: QC 注入順ドリフト補正。注入順は mzTab-M の assay[N]-custom[...] の injection sequence label（MS:4000089）から読む。 それを持たない mzTab-M では実施できず、caveat で報告する。 max_qc_rsd: QC 群の RSD がこの値を超える特徴量を除去する（例 0.30）。 impute: "half_min"（既定）/ "knn" / "column_mean" / "none"。 min_detection_rate: 実検出率（gap-fill を除く）による特徴量の足切り 0.0-1.0 （既定 0.0=無効）。検出状態は mzTab-M 単体には無いので、隣接する .arf から取り込めた場合にだけ使える。取り込めていない状態で 0 より大きい値を 渡すと引数エラーを返す（黙って未検出 0 件として通さない）。 取り込み状況は dataset_status の detection を見る。

成功すると session.dataset.pp_matrix に前処理済み行列が設定される。

前処理済み DatasetState に PCA を実行する。

dataset_preprocess を先に実行しておくこと。 n_components: 主成分数（既定 5。サンプル数・特徴量数の小さい方で上限が決まる）。 log_transform: 標準化の前に log10 変換を適用する（既定 False）。

ローディング全量は戻り値に載せず session.dataset.last_pca に保持する。

前処理済み DatasetState で 2 群の差次的解析（Welch t 検定 + BH-FDR）を実行する。

group_a / group_b: サンプル名のリスト。使える名前と役割は dataset_status の samples（name/role の TSV）で確認する。前処理済み行列に無い 名前、QC/ブランクは除外し、caveat で名指しする。 q_threshold: BH-FDR 補正後の有意水準（既定 0.05）。 log2fc_threshold: この絶対値以上の log2FC を有意として数える（既定 1.0）。 log_transform: log2(x + 1) 空間で検定する（既定 True。MS 強度は対数正規に近い）。

log2FC は正なら group_b が高い（上昇）。 group_a が基準（対照）。 全特徴量の結果と volcano 点列は戻り値に載せず session.dataset.last_differential に保持する。エクスポートは dataset_export_differential を使う。

指定した差次的結果を InChIKey 付きの 1 ファイルへ書き出す。

先に dataset_preprocess → dataset_differential を実行しておくこと。 出力は arf_export_differential と同一の契約（15 列 + contract_version メタ行）なので、下流のパスウェイ解析にそのまま渡せる。

apply_curation（既定 true）: curation_submit で wrong を付けたスポットを 同定なしとして扱い、出力から外す。フラグがあればメタ行 # curation = ... で 適用状況を宣言する。フラグが無ければ出力は変わらない。成功 payload の curation は {state, wrong_excluded, suspect, orphaned}（arf_export_differential と 同じ形）。assign（curation_submit の候補付け）は同定を置き換え（name_source / inchikey_source = curation）、redundant は除外する。どちらかがあれば curation に assigned と redundant_excluded が足される。 フラグ記録に読めない行があれば書き出さずに CURATION_FLAGS_INVALID。

result_id: 書き出す結果を名指しする（省略時は直近の差次的結果）。 前処理をやり直した後の古い結果は書き出しません（STALE_ANALYSIS_RESULT）。 古い数字に現在の前処理条件のラベルが付いた TSV は、どちらも正しく見えて ずれが分からなくなります。

InChIKey は DatasetState.feature_metadata から取る（mzTab-M の database_identifier / InChI / SMILES 由来。.arf2 との結合は不要）。 濃縮解析の背景を保つため、有意な行だけでなく InChIKey が付いた全行を出す。 ontology と msi_level は mzTab-M に対応物が無いため空欄で、その旨をメタ行に 書く（空欄を「該当なし」と読み違えさせない）。メタ行には result_id と preprocess_id も入るので、あとから「どの計算の出力か」を辿れる。

実験情報シート(sample-manifest.v1)を読み込み、検証してから DatasetState へ 一括適用する（spec §7.3）。

上流のConsole実行をやり直さずに、群・バッチ・注入順・qc_pool などの誤記入を このツール単体で訂正できる。列の意味・拒否条件は sample-manifest.v1 の仕様 （docs/superpowers/specs/2026-09-05-raw-folder-pipeline-integrity-and-metadata-design.md §7.2）を参照。

検証は全件そろってから一括反映する（一部だけ適用される状態は作らない）。 シートに不備があれば session.dataset を一切変更せずエラーを返すので、 そのまま再送してよい。

前処理入力（role/batch/injection_order/qc_pool/include/sample_id/source_file）が 変われば前処理済み行列ごと・PCA・差次的解析まで無効化する。group だけの変更なら 差次的解析だけを無効化し、PCA は生かしたまま返す（changed_fields で確認できる）。

dataset_differential を直接呼ぶ経路（比較する2群のサンプル名を都度自分で 組み立てる）とは別に、比較を明示するのは pipeline 側の役割になる——群名だけで 対照/処置の向きを決めない・QC/blank/unknown/include=false を混ぜない・完全交絡を 止める、という前提検証は resolve_comparison/run_comparison（内部関数）が持つ。

v2 の統計（welch / anova_tukey / pca）を、名指しした解析行列に実行する。

specification: analysis_recipe.statistics の1要素と同じ形 （statistic_id / kind / transform / feature_scope と、kind別の reference_group+test_group、groups+alpha、scaling+n_components）。 matrix_result_id: analysis-matrix.v1 の ID。pipeline の preprocess / qc_processed が作った行列を名指しする。直近の前処理を暗黙に使わない ——recipe 違いの行列が2本ある前提の設計で、どちらの数字かを結果に残す。

v1 の dataset_differential とは別物: 効果量は統計変換前の算術平均比の log2 （effect_size_definition）、log2 変換に pseudocount を足さない、BH の母集団は 検定できた feature だけ。v1 の既定値・数値契約は変更していない。

全量（feature ごとの結果）は戻り値に載せず session に保持する。

v2 の解析行列（analysis-matrix.v1）を、セッションの DatasetState から1本作る。

recipe: profile の matrix_recipes の1要素と同じ形 （base / normalize / drift_correct / filter / impute の5キー。 過不足はそのまま拒否する）。検証は profile と同じ規則を共有しているので、 pipeline 経由より緩い recipe がここから入ることはない。 recipe_id: 行列の識別に使う名前。matrix_id は recipe 内容と dataset・ metadata から決まるので、同じ dataset に同じ recipe を与えれば同じ ID になる（pipeline が作った行列と突き合わせられる）。

揃っていない前提を揃ったことにしない:

• base="internal_standard_ratio" は対象feature↔内部標準の対応付けが要る。 この単体ツールは対応付けを作らないので missing_state で止める （空の対応付けで「比」を名乗る行列を作らない）。

• 検出状態が分からない dataset に filter.min_detection_rate を指定しても feature は落ちない。history に not_evaluable が残る。

値そのものは戻り値に載せず session に保持する。dataset_statistic へは 戻り値の matrix_id を渡す。

DatasetState の特徴を探し、目的の物質に当たる特徴を規則で判定する（読み取り専用）。

2 つの使い方があり、targets の有無で切り替わる（同時指定は DATASET_BAD_REQUEST）。

窓検索（targets なし）: feature_ids（SMF_ID の完全一致）・min_mz/max_mz・ min_rt/max_rt（分）の AND。境界を含む。何も指定しなければ FEATURE_SEARCH_EMPTY_QUERY （全件を返さない）。feature_ids=[] は「どの ID でもない」条件で 0 件。並びは m/z 昇順。 戻り値 features は TSV（feature_id mz rt evidence name inchikey adduct n_sme。 evidence は sme/sml/none）。注釈の無い特徴にも統計を付ける。

目標照合（targets あり、1 回 50 件まで）: 各要素は target_id・inchikey（必須。 先頭 14 文字で照合）と、formula か（expected_mz と adduct）。任意で name ppm （既定 10）rt_min rt_tol_min（既定 0.3）adduct_tiers polarity。付加体の層を上から、 証拠の水準 sme_match → sml_match → unannotated の順に見て、qualified がちょうど 1 つの ときだけ resolved。2 つ以上なら needs_input（multiple_qualified_candidates）、無ければ needs_input（no_qualified_candidate）。強度・ppm・RT の近さでは選ばない。 unannotated は rt_min があるときだけ qualified。SME（MS/MS 同定）が別物質なら落とす。 極性はジョブの宣言 → mzTab-M の付加体の多数決の順に決め、rule.polarity_source に書く。 目標の極性は polarity、省けば明示した付加体（adduct/adduct_tiers）の符号で、 データセットと違う目標は not_applicable（陽陰が混ざる付加体は FEATURE_TARGET_INVALID）。 戻り値 targets（目標ごとの判定と段ごとの件数）・candidates（TSV。目標ごとに max_results 件まで）・rule（正規化した規則と rule_hash。result_id・表示名 name・ 目標の並び順を含まないので、同じ目標・同じ極性なら別の session でも同じ hash）。hash は表示用の丸め（理論 m/z を 4 桁に）より前の値から作るので、返された rule.targets から計算し直すことはできない ——照合は rule_hash の値どうしで行う。

result_ids: 統計を付ける 2 群比較（dataset_differential）の結果。省略時は今も有効な 2 群比較の全部（古いものは使わず notes に挙げる）。名指しした ID が無い・古いときは missing_state。差次的結果が 1 件も無ければ統計なしで返す。 max_results: 窓検索の行数・目標ごとの候補数の上限（既定 20）。打ち切りは notes に書く。

stats は TSV（feature_id result_id status log2fc p q mean_a mean_b detected_a detected_b）。 status は tested / not_in_matrix（前処理で落ちた）/ not_testable（p が無い）で、 後の 2 つは数値欄が空（「差が無かった」ではない）。detected_* は群ごとの実検出例数 （gap-fill を数えない。検出状態が無ければ空）。results に BH の母集団 （bh_population）と caveat。キュレーションのフラグは反映しない（あれば notes）。 欄の意味は lipidmix://docs/output-format/mztab。

指定2群結果の全特徴量と候補をv2根拠バンドルへ出力する。名前だけの候補も保持する。

保存済みの PCA（arf_parser / arf_pca_preprocessed / arf_pca_species / dataset_pca）のローディングを横棒で描く。

• source: "auto"（既定）/ "arf" / "species" / "mztab"。auto はどれも優先せず、候補が 2 つ以上あると AMBIGUOUS_RESULT_SOURCE で止まる。result_id で特定の結果を名指しできる。

• pcs: 描く主成分（既定 [1, 2]、1〜3 個）。

• top_n: 主成分ごとに正の上位 N と負の上位 N（既定 15）。None は全件（60 特徴量まで）で、 全パネルの行を最初の主成分の順にそろえる。

• value: "r"（既定。各特徴量と主成分スコアの相関、−1〜1）/ "coefficient"（固有ベクトルの成分）。 r は autoscale した PCA でだけ出せ、出せないときは coefficient で描いて説明文に書く。

• 棒の色はクラス（ARF・分子種 PCA は .arf2 の Ontology）。

• output: "image"（既定）/ "payload"（lipidmix.pca_loadings.v1）。ファイルは save_figure(kind="pca_loadings")。

入力検査・不足情報・固定要求の保存のみを行う。Consoleは起動しない。

Parameters

dataset_root: 生データフォルダのパス。MS-DIAL が読む 12 形式 （.abf / .ibf / .cdf / .mzml / .wiff / .raw / .d / .wiff2 / .qgd / .lcd / .lrp / .imzml）が入っているフォルダを指します。 Agilent・Bruker の .d と Waters の .raw はフォルダが 1 検体です。 request: pipeline-request.v1 のトップレベル項目（省略可、spec §10.1）。 target / polarity / method_file / lbm_file / library_mode / msp_file / sample_manifest / preprocess / comparisons 等。相対パスは dataset_root 基準。library_mode="msp_only" は LBM を使わず研究室の参照 ライブラリ（.msp）だけで同定する（msp_file か極性の設定 [library] msp_positive / msp_negative。メソッドの Text DB・注釈器設定表の宣言は空にする）。 lbm_file との同時指定、auto での msp_file は PIPELINE_REQUEST_INVALID。 request_id: 冪等性キー。同一内容の再送は同じ結果を返し、別内容は IDEMPOTENCY_CONFLICT。

dataset_root 直下に analysis-request.json（同じトップレベル項目を持つ JSON）と sample-manifest.tsv があれば既定名として読む。要求値の優先順位は request で明示した値 > analysis-request.json > 既定値（spec §7.1)で、 preprocess だけは子キー単位で重なる。どの値がどこから来たかは保存された 要求の value_sources（explicit / request_file / default）で確認できる。 置いてあるファイルが壊れている・未知キーを持つ場合は黙って無視せず PIPELINE_REQUEST_INVALID にする。

receiptの resolved に、解決済みの実行条件——method（source_path / sha256）・lbm・polarity（value とその source）・library_mode・ msp（ファイル名・sha256・出どころ。置き場所は載せない）——が入る。何も 起動しないうちにこれらを確認するのがこのツールの用途。

起動せずに needs_input を保存することがある（不正なsample_manifest等、 spec §9.2「既知の不正入力はConsole起動前に拒否する」）。条件だけ確認したい 利用者はこちらを使い、実際に進めたいときは pipeline_run を使う。

計画と起動を一括実行する。生データから MS-DIAL Console を回す補助経路の入口。

先にフォルダに MS-DIAL を動かした形跡（.arf 等の出力）があるかを確かめ、 あれば load_dataset で下流へ進む（主経路）。形跡が無いときだけ、ユーザーに Console を回してよいか許可を取り、同意を得てからこのツールを呼ぶ。起動前に 解決結果（method file・LBM・極性）を見たいときは pipeline_plan。引数は pipeline_plan と同じ。

短時間で pipeline_path を返す——起動受理は、workerのidentity保存と 起動handshakeを確認した後に返すが、応答待ちには短い上限があり、上限に 達しても起動失敗と決め付けず再起動もしない（launch.handshake が "not_confirmed" になるだけで、pipeline_status で追跡できる）。

launch キーは実際にworkerを起動した（launched=true）ときだけ含まれる。 不正なsample_manifest等を検出した場合や、find_or_create_run が既存run （活動中／completed／失敗・取消・部分完了済み）を再利用した場合は launched=false のみを返し、launch キー自体を持たない（起動していない 以上、handshake結果も存在しない）。既存runを本当に進めたい場合は pipeline_resume を使う。

状態・不足情報・成果物参照を読む。最終化や起動は一切しない（読取専用）。

Parameters

pipeline_path: pipeline_run / pipeline_plan が返した pipeline_path（pipeline-run.json そのもの、またはその親ディレクトリのどちらでもよい）。 include_details: True なら永続レコード全体（record）も返す（既定False。通常は status / stage_statuses / needs_input / warnings で足りる）。

status="running" のときだけ、記録済みworkerの生存確認 observed_health を追加で行う。workerが消えていれば observed_health="worker_missing" と recovery_hint（pipeline_resume を促す）を返すが、statusフィールド自体は 書き換えない——監視・成果物確定をポーリング呼出しに依存させない（spec）。

入力訂正・下流revision作成・停止工程からの再開。

Parameters

pipeline_path: 対象runの pipeline_path（pipeline_status と同じく、pipeline-run.json そのもの、またはその親ディレクトリ＝pipeline_rootのどちらでもよい）。 updates: 変更したい項目のみ（target / sample_manifest / preprocess / comparisons に限定。spec §10.1「resumeで変更可能なのは...に限定する」）。 request_id: 冪等性キー。同一内容の再送は新しいrevisionを作らず直前の結果を返す。 rerun_upstream: True を明示しない限り、Console実行はやり直さない（自動再試行はしない）。 監視を失ったまま稼働中のConsoleがある場合は EXECUTION_UNRESOLVED で 待つ（終了を確認できないものを勝手に完了扱いしない）。

取消要求を保存する。二重取消は冪等。

rawデータを削除しない。 ここで保存するのは協調的な取消フラグだけで、 上流Consoleの停止は監視経路が、下流の停止はstage境界が行う。受理 （このツール呼び出しが成功したこと）と、実際にworkerが停止を確認した こと（cancelled への確定）は別状態——確定は pipeline_status で確認する。

このMCPサーバ自身を origin/main へ更新する（git 早送り＋必要なら依存の再導入）。

更新通知（load_dataset の冒頭行、dataset_status / console_status の update_available）が出たときに呼ぶ。プロセスは触らないので、適用後は 利用者が Claude Desktop を再起動する必要がある——戻り値の message を そのまま利用者へ伝えること。

手元の未コミット変更がある・main 以外にいる・早送りできない・オフラインの いずれでも何もせずに status="refused" と reason を返す（例外は投げない）。

注釈付きスポットを一覧で確かめるレビューを作る（EIC・対向プロット・Δppm・ΔRT・ RT–m/z 傾向と機械判別）。先に library_load（アラインメントに使われた *_Loaded.msp2.dbs を推奨）。

対象: 既定は注釈付き全部。ontology=["PG"] でクラス、name_contains で名前の部分一致。 戻り値は suspect 以上(とフラグ済み)のスポットだけの TSV（判定の重い順に先頭 max_rows 行、既定 100。総数は n_table_rows_total、載せた数は n_table_rows_shown。全件は HTML ビューアにある）、判定の件数、クラス別の傾向要約（点数・R²・外れ数）、HTML ビューアのパス。file_ids は .arf の行にある試料 ID だけ（無い ID はエラー）。 EIC 系列やスペクトルは返さない——ユーザーには html_path をブラウザで開いてもらい、ビューアの Submit で送ってもらう（記録と _tags.xml の反映はビューアが直接行う。submit.via == "viewer"）。送信用テキストを貼るよう 頼まない。送った結果は curation_flags で確かめられる。Copy のテキストが貼られたとき （受け口の時間切れ・submit.via == "copy"）は従来どおり curation_submit(submission_text=...) に渡す。

判定: likely_wrong（強い不一致: polarity_mismatch / precursor_unmatched / dmz_out / class_rule_rejected（MS-DIAL の脂質クラス規則による棄却で、脂質規則が走ったデータに限る）/ adduct_isomer_of:（m/z が同時溶出する証拠の強い別物質スポットの別アダクトで説明できる。 相手はレビューの対象に絞らずアラインメント全体から探す））、 suspect（ppm_out / low_score / drt_out / eic_poor / adduct_isomer_minor_of:、 または弱い兆候の重なり）、ok。 RT–m/z 傾向（trend_outlier）は補強にしか使わない。UNKNOWN は不一致に数えない。 thresholds で既定のしきい値（ppm_pass=5, ppm_borderline=10, drt_pass=0.5 分 など）を上書きできる。

キュレーションで「間違い」になったスポットと未注釈スポットに、注釈の候補を並べる （候補付けレビュー）。先に library_load と curation_review。

対象: wrong="flagged_or_likely"（既定）= wrong フラグ ＋ 元レビューの likely_wrong、 "flagged" = wrong フラグだけ。unannotated=True で未注釈スポットも。判断済み （assign / redundant）のスポットは include_decided=True のときだけ含める。 元レビューは review_id（省略時はこのアラインメントの最新のレビュー）。 候補: ① MS-DIAL の下位候補、② 閾値を緩めた再検索（スコアの足切りなし）、 ④ 注釈付きの別スポットの同位体・アダクト・インソース断片としての説明。 スペクトル類似度で並べ、極性矛盾・|Δm/z| ≥ 10 mDa は削り、非典型アダクト・RT–m/z 傾向の外れ・ 一致ピーク 0 は順位を下げる。MS-DIAL の脂質規則は評価していない（鎖組成は保証しない）ので、 既定では和組成で記録する。 戻り値は 1 スポット 1 行の TSV（強い説明のあるものが先、先頭 max_rows 行）・件数・html_path。 ユーザーには html_path をブラウザで開いてもらい、選んだ内容をビューアの 送信 で送ってもらう （記録と _tags.xml の反映はビューアが直接行う。submit.via == "viewer"）。送信用テキストを 貼るよう頼まない。Copy のテキストが貼られたとき（受け口の時間切れ・submit.via == "copy"）は curation_submit(submission_text=...) に渡す。 ユーザーの同意なしに curation_submit を呼ばない。

キュレーションのフラグを記録する（追記。フラグの無いスポットは「間違っていない」で何も書かない）。

ユーザーがビューアの「送信用テキストをコピー」で貼った文をそのまま submission_text に渡す （CURATION_SUBMIT で始まる行だけを読む。書き写さないこと）。直接渡すなら review_id と flags=[{"spot_id": 12, "flag": "wrong" | "suspect" | "confirmed" | "clear", "note": "..."}] （confirmed = 注釈が正しいと確かめた。wrong / suspect と排他）。 候補付け（cs-…）の送信は flags=[{spot_id, flag: assign|redundant|clear, candidate: "L1"|"R1", level: sum|species, note}]。候補の中身（名前・InChIKey）は保存済みの候補付けから展開するので、 送信側で名前を書かない。assign / redundant は _tags.xml を変えない。 source は誰の判断か: ユーザー自身の判断は "user"、LLM の提案にユーザーがチャットで同意した ものは "llm"。ユーザーの同意なしに呼ばない。 不正な要素が 1 つでもあれば何も書かずにエラーを返す（同じ spot_id を 1 回の送信で 2 回以上名指しした場合も含む——どちらを採るか決められないため）。 レビューはセッションの記録 → 送信用テキストの arf2_path → file_path（レビューを 作った .arf2）→ 既定の .arf2 の順に探すので、サーバ再起動の後でも貼った文で送れる。 記録の後、アラインメントの _tags.xml に反映する（wrong → Misannotation を付け Confirmed を外す、 confirmed → Confirmed を付け Misannotation を外す、suspect → Confirmed を外す、clear → 両方外す。 控えは curation/tags-backup/）。結果は tags_xml（added / removed は Misannotation、 confirmed は Confirmed の変化）。 反映に失敗しても記録は残る。MS-DIAL でプロジェクトを開いたままだと GUI の保存で 上書きされるので、tags_xml.note をユーザーに伝える。

現在のアラインメントで有効な判断（スポットごとの最新 1 行、clear 済みは除く）を TSV で返す。 列は spot_id・flag・name（assign の記録名）・of（redundant の相手スポット）・note・source・ts。

ビューア（MCP Apps）専用。保存済みレビューのスポットをページ単位で返す。LLM は呼ばない。

前処理済みの脂質データを MSLipidMapper のパスウェイへ投影し、2 群を比べる。

返すのは小さな表だけ（ノード表と、逆向きに動く隣接ペア）。JSON-LD・中間 mzTab-M は 解析フォルダの reports/pathway/<run_id>/ に残る。図は pathway_plot。

• source: auto | arf | dataset。arf は arf_preprocess 後、dataset は dataset_preprocess 後。 auto は「前処理済み ARF があれば arf、無ければ dataset_load 済みなら dataset、 どちらも無ければ arf（→ arf_preprocess を求める missing_state）」の順で選ぶ。

• group_a / group_b: arf は Class ID か因子トークン（arf_differential と同じ）、 dataset はサンプル名のリスト（group_a_label / group_b_label が群名になる）。

• pathways: remodeling / ceramide / global（既定は 3 つ全部）。

• acyl_chains: 例 ["18:0","20:4"]。指定すると鎖サブセットのスコープも比べる。

• aggregation: sum | mean | median（サブクラス内の分子種の集計）。 検定は log2(x+1) の Welch、BH はパスウェイ×スコープ種別ごと。log2fc は正なら group_b が高い。 脂質アッセイ（record_objective の assay_kind=lipid）でだけ使える。 MSLipidMapper は [mslipidmapper] mslipidmapper_api_url の研究室サーバを先に使い、使えなければローカルの R （[mslipidmapper] rscript）で動かす。どちらで動いたかは戻り値の backend。

pathway_project の run をパスウェイ図（PDF）に描き、チャットに PNG で表示する。

• run_id: 省略時は直近の run。

• pathways: その run に含まれるものから選ぶ（既定は全部）。1 枚約 2,400 画像トークン。

• plot_type: dot | box | violin（ノード内のグラフ）。横軸の群は group_a, group_b, その他の群の順 （上流は config の plot.x_order を軸順と配色の両方に使う）。 [mslipidmapper] mslipidmapper_api_url の研究室サーバを先に使い（サーバは 3 パスウェイ全部を描く）、 使えなければローカルの R で描く。ローカルではヘッドレス Chromium（[mslipidmapper] browser）と unpkg.com への接続が要る。