ROOT CLI スキル

root-cli は CERN ROOT ファイル向けのトークン効率的な CLI です。冗長な MCP JSON 交換を簡潔で組み合わせ可能なシェルコマンドに置き換えます。中間結果（ヒストグラム、フィッティング結果）は /tmp/root_mcp/ 以下に JSON として キャッシュされ、後続のコマンドで消費されます。

セットアップ

# データパスを一度設定する（または -d でコマンド毎に指定）
export ROOT_MCP_DATA_PATH=/path/to/data

# インストール確認
root-cli info

すべてのコマンドは --json を受け付け、他のツールにパイプできるマシン可読出力を提供します。

---

コマンドリファレンス

ファイル操作

コマンド	目的
root-cli ls [pattern] [--limit N]	データディレクトリ内の ROOT ファイルを一覧表示
root-cli inspect <file.root>	TTree、RNTuple、ヒストグラム、ディレクトリを表示
root-cli inspect <file.root>	TTree、ヒストグラム、ディレクトリを表示
root-cli branches <file.root> <tree> [-p pattern] [-s]	ブランチと型を一覧表示；-s で統計情報を追加
root-cli validate <file.root>	ファイルの整合性をチェック

データアクセス

コマンド	目的
root-cli stats <file.root> <tree> <branches...> [-s cut]	平均/標準偏差/最小値/最大値/中央値
root-cli read <file.root> <tree> <branches...> [-s cut] [-l N] [--flatten] [-d name=expr]	生データを読み込み
root-cli sample <file.root> <tree> [--size N] [--method first|random]	高速サンプリング
root-cli export <file.root> <tree> <branches...> -o out [-s cut] [--format csv|json|parquet]	データをエクスポート

カット構文: C++ 式 — "pt > 20 && abs(eta) < 2.4"、"n_jets >= 2" 派生変数: -d met_x="met*cos(met_phi)" — インラインで新しいブランチを定義

ヒストグラム解析

# 1D ヒストグラム（結果は /tmp/root_mcp/<branch>_hist.json にキャッシュ）
root-cli histogram <file.root> <tree> <branch> \
  [--bins 100] [--range MIN MAX] [-s cut] \
  [--fit gaussian|exponential|polynomial|crystal_ball] [--fit-range MIN MAX]

# 2D ヒストグラム
root-cli histogram2d <file.root> <tree> <x_branch> <y_branch> \
  [--xbins 50] [--ybins 50] [--xrange MIN MAX] [--yrange MIN MAX]

# キャッシュされたヒストグラム JSON をフィッティング
root-cli fit /tmp/root_mcp/<hist>.json <model> \
  [--fit-range MIN MAX] [-i param=value]

# ヒストグラム演算（シグナル/バックグラウンド比、効率など）
root-cli hist-arithmetic <add|subtract|multiply|divide|asymmetry> hist1.json hist2.json

統計解析とキネマティクス

# ピアソン相関またはスピアマン相関行列
root-cli correlation <file.root> <tree> <branches...> [--method pearson|spearman]

# 4ベクトル（pt、eta、phi、[質量]）からの不変質量
root-cli invariant-mass <file.root> <tree> \
  --pt mu1_pt mu2_pt \
  --eta mu1_eta mu2_eta \
  --phi mu1_phi mu2_phi \
  [--mass mu1_m mu2_m] [-s cut] [-l N]

可視化

# キャッシュされたヒストグラム JSON から 1D プロット
root-cli plot1d /tmp/root_mcp/<hist>.json -o out.png \
  [-t "Title"] [-x "X label"] [-y "Y label"] [--log-y] \
  [--style default|publication|presentation]

# 2D プロット
root-cli plot2d /tmp/root_mcp/<hist2d>.json -o out.png \
  [-t "Title"] [--colormap viridis|inferno|...] [--log-z]

---

標準的なワークフロー

探索的解析

root-cli ls                                          # ファイルを発見
root-cli inspect data.root                           # トップレベル構造
root-cli branches data.root events --pattern "mu*"   # ブランチ一覧
root-cli stats data.root events met muon_pt jet1_pt  # 簡易チェック
root-cli sample data.root events --size 10           # データを確認

ヒストグラム→フィッティング→プロット（例：J/ψ ピーク）

root-cli histogram data.root events dimuon_mass \
  --bins 100 --range 2.8 3.4 --fit gaussian --fit-range 3.0 3.2

root-cli plot1d /tmp/root_mcp/dimuon_mass_hist.json \
  -o jpsi.png --title "J/ψ → μμ" --xlabel "m(μμ) [GeV]" --style publication

選択→エクスポートパイプライン

root-cli export data.root events met muon_pt muon_eta \
  --selection "met > 50 && muon_pt > 20" \
  -o selected.parquet --format parquet

シグナル/バックグラウンド効率

root-cli histogram2d data.root events muon_pt muon_eta -o
root-cli hist-arithmetic divide /tmp/root_mcp/sig.json /tmp/root_mcp/bkg.json

運動学的再構成

root-cli invariant-mass data.root events \
  --pt mu1_pt mu2_pt --eta mu1_eta mu2_eta --phi mu1_phi mu2_phi \
  --selection "mu1_pt > 20 && mu2_pt > 10" --limit 50000

---

主な動作と注意点

• 中間 JSON は /tmp/root_mcp/ に保存される — histogram と fit コマンドは自動的にそこに書き込みます；plot1d/plot2d/fit はパスでそれらのファイルを消費します。
• ジャグ配列（例：イベントごとのミューオンコレクション）：read で --flatten を使用するか、root-cli は統計情報/ヒストグラムで暗黙的に処理します。
• モードフォールバック：root-cli は常に利用可能です；MCP サーバーが実行中である必要はありません。
• トークン効率：カスタムロジックが避けられない場合を除き、生の PyROOT/uproot Python スクリプトではなく root-cli を優先してください。
• 利用可能なフィットモデル：gaussian、exponential、polynomial、crystal_ball — 非対称なテール（例：B メソン質量ピーク）には crystal_ball を使用してください。
• --json 出力：jq にパイプするか、プログラムで消費できます；スクリプト内でコマンドをチェーンする場合に便利です。

---

判定ガイド

タスク	推奨コマンド
新しいファイルを初めて確認	inspect → branches
簡易数値チェック	stats
質量ピーク/シグナル抽出	histogram --fit gaussian または crystal_ball
相関研究	correlation
粒子再構成	invariant-mass
下流の ML/pandas	export --format parquet
発表用プロット	plot1d --style publication
データ vs MC 比較	hist-arithmetic divide または asymmetry