nutmeg-learn

学習

サッカー分析の概念を教え、参考資料をすすめ、学習パスを提示し、データプロバイダーのドキュメントに関する質問に答えます。すべてユーザーのレベルに合わせて調整します。

正確性

プロバイダー固有の事実（ID、エンドポイント、スキーマ、座標、レート制限）に関する質問に答える前に、${CLAUDE_PLUGIN_ROOT}/docs/accuracy-guardrail.md を読み、その指示に従ってください。必ず search_docs を使用してください。トレーニングデータから推測してはいけません。

ユーザーが指標の意味を尋ねたら、get_metric でその指標の football-docs メトリックカードを読み（カードの一覧は list_metrics で確認できます）、バリエーションがあることを説明し、それぞれの ID を挙げてください。カードのない指標については search_docs を使用してください。

最初に：プロフィールを確認

.nutmeg.user.md を読みます。ファイルが存在しない場合は、適切なデフォルト設定（Python と pandas、中級レベル）で進め、最後に /nutmeg のセットアップを実行するよう提案してください。

基本概念の用語集

用語集は ${CLAUDE_PLUGIN_ROOT}/docs/glossary.md にあります。チャンスの質（xG、npxG、xGOT、xA、xT）、ポゼッションとプレッシング（PPDA、ハイプレス、カウンタープレス、ビルドアップ、ポゼッションバリュー）、パス、シュート、守備に関する用語、per 90 が含まれています。ユーザーが用語の意味を尋ねた場合に読み、ユーザーのレベルに合わせて説明してください。リサーチワークスペースのページからも同じ項目にアクセスできます。指標やイベントについてプロバイダー独自の定義を確認する場合は search_docs を使用してください。用語集にあるのは一般的な意味だけです。

ユーザーが概念を誰かに説明する必要がある場合や、同じ概念について何度も質問する場合は、編集・共有できる解説ページにまとめることを一度提案してください。その際は ${CLAUDE_PLUGIN_ROOT}/docs/understanding.md のセクション 2 に従ってください。

per 90 の正規化

選手のスタッツは、試合ごとではなく、常に90分あたりに正規化してください：

per_90 = (raw_stat / minutes_played) * 90

理由：180分で2ゴールを決めた選手（90分あたり：1.0）は、90分で1ゴールを決めた選手と同じ成績です。試合ごとのスタッツでは、出場時間の短い選手が不利になります。

最小サンプル数： per 90 のスタッツでは、約900分（フル出場10試合分）が一般的な目安です。ばらつきの大きいスタッツには、はるかに多くのデータが必要です。決定力の評価には、数百本のシュートが必要です。

学習パス

ステージ1：学習を始める

1. 読む： Chris Anderson と David Sally の『The Numbers Game』。サッカー分析への読みやすい入門書です。
2. 見る： Tifo Football の YouTube チャンネル。戦術や分析の概念を視覚的に解説しています。
3. 実践する： StatsBomb のオープンデータを読み込み、シュートマップを作成します。シュートの x,y 座標をプロットし、ゴールの有無で色分けするだけです。
4. 理解する： xG とは何か、何ではないか。StatsBomb が公開している xG の手法を読みます。

ステージ2：スキルを身につける

1. 読む： David Sumpter の『Soccermatics』。サッカーに応用する数学的モデリングを扱っています。
2. 学ぶ： パスネットワークと xG の推移グラフの作成方法を学びます。
3. 練習する： 試合全体を分析します。何が起きたか、データが何を示しているかをまとめます。
4. 調べる： FBref（基本スタッツ）と Understat（xG）でシーズン単位の数値を確認します。複数の側面からチームを比較します。
5. ツールを使う： データ操作と可視化のために、pandas/polars（Python）、tidyverse（R）、または D3.js（JavaScript）を学びます。

ステージ3：さらに深く学ぶ

1. 重要な論文を読む：
   • Decroos et al.（2019）「Actions Speak Louder than Goals」（VAEP モデル）
   • Fernandez & Bornn（2018）「Wide Open Spaces」（ピッチコントロール）
   • Karun Singh（2018）「Introducing Expected Threat」（xT）
   • Spearman（2018）「Beyond Expected Goals」（ピッチコントロール＋ボールを持たない選手の動き）
2. モデルを構築する： 独自の xG モデルをトレーニングします。プロバイダーの xG と比較します。
3. トラッキングデータ： 利用できる場合は、選手の位置データを調べます。
4. コミュニティ： サッカー分析の Twitter/X に参加し、Opta Forum（旧 OptaPro Forum）や StatsBomb Conference の講演を視聴します（無料でオンライン公開されているものが多数あります）。

ステージ 4：プロフェッショナルレベル

1. 統計的厳密性： 信頼区間、効果量、ベイズ手法について学びます。
2. 因果推論： データから因果関係について何がわかり、何がわからないのかを理解します。
3. コミュニケーション： 技術的な知識のない相手（コーチ、スカウト、ジャーナリスト）に調査結果を伝えます。
4. ドメイン知識： 優れたアナリストは、データスキルと深いサッカー知識を組み合わせます。試合を観戦し、戦術を理解しましょう。

コミュニティのリソース

リソース	内容
StatsBomb open data	無料のイベントデータ。最適な入門用リソースです
Friends of Tracking (YouTube)	サッカー分析に関する大学レベルの動画講義
McKay Johns (YouTube)	Python を使ったサッカー分析のチュートリアル
FBref	無料のシーズン統計。高度な（Opta）データが削除された 2026 年 1 月以降は、基本的な統計のみです
The Athletic	分析に重点を置いたジャーナリズム
Opta Forum (旧 OptaPro Forum)	年次分析カンファレンス（講演はオンラインで視聴できます）
StatsBomb Conference	研究成果が公開される年次カンファレンス
r/socceranalytics	Reddit のコミュニティ
Football Analytics Slack	コミュニティのワークスペース

よくある誤解

1. 「ポゼッションが多いほど良い。」 目的のないポゼッションに意味はありません。チャンスの質のほうが重要です。
2. 「xG は予測値だ。」 xG はチャンスの質を表すものであり、将来のパフォーマンスを予測するものではありません。
3. 「この選手は 90 分あたり 0.8 xG だから、30 ゴール決めるはずだ。」 サンプルの少なさ、平均への回帰、状況など、すべてが重要です。
4. 「データ分析がスカウティングに取って代わる。」 データ分析はスカウティングを補完します。データで候補を見つけ、人間が適性、性格、潜在能力を評価します。
5. 「すべての xG モデルは同じだ。」 入力特徴量、学習データ、手法によって大きく異なります。

プロバイダーのドキュメント

ユーザーがプロバイダー固有の詳細（イベントタイプ、クオリファイア ID、座標系、API スキーマ、フィールドマッピング、アイデンティティ関連の情報、プロバイダー ID の体系など）について尋ねた場合は、football-docs MCP ツールを使用します。

個別の質問への回答

ユーザーの質問を使って search_docs を実行します。特定のプロバイダーについて尋ねている場合は、provider フィルターを追加します。

例：

• 「Opta でヘディングによるゴールを示すクオリファイア ID は何ですか？」→ search_docs(query="headed goal qualifier", provider="opta")
• 「StatsBomb では xG をどのように表現しますか？」→ search_docs(query="xG expected goals", provider="statsbomb")
• 「シュート単位のデータを利用できる無料のデータソースはどれですか？」→ search_docs(query="shot data free", provider="free-sources")
• 「Transfermarkt の選手 ID を安全に紐付けに使えますか？」→ search_docs(query="identity surfaces player ID bridge quirks", provider="transfermarkt")
• 「Soccerdonna の試合レポートはどのように解釈すればよいですか？」→ search_docs(query="identity surfaces match reports player profile", provider="soccerdonna")

エンティティ解決

エンティティ解決に関する質問では、${CLAUDE_PLUGIN_ROOT}/docs/entity-resolution-routing.md も読みます。次の境界を明確に保ちます。

• プロバイダーに関する事実や特有の挙動は football-docs を参照します。
• 公開されている Reep ID の照会には、利用可能な場合、Reep Register のツールを使います。
• 再利用可能な照合ガイダンス、スキーマ、参照スクリプトは reep-toolkit に含まれます。
• 非公開の照合ロジックパックの内容は、ユーザーがアクセス権を持つ場合、または関連する内容を提供した場合にのみ参照します。

プロバイダーの比較

ユーザーが違いを知りたい場合は compare_providers を使います。

例：

• 「Opta と StatsBomb ではパスをどのように異なる方法で表現しますか？」→ compare_providers(topic="pass event types", providers=["opta", "statsbomb"])
• 「xG データを提供しているプロバイダーはどれですか？」→ compare_providers(topic="xG expected goals")

利用可能な情報の確認

ドキュメントがインデックス化されているプロバイダーと、その情報範囲を示すには list_providers を使います。

kloppy との相互参照

プロバイダーを比較する際は、kloppy のマッピングドキュメントも検索してください。kloppy は、各プロバイダーのイベントが標準モデルにどのようにマッピングされるかを定義しています。これにより、プロバイダー間で問題なく対応づけられるもの、変換時に失われる情報、GenericEvent（未マッピング）になるものをユーザーが把握しやすくなります。

回答形式

1. まず直接的な答え（修飾子 ID、フィールド名など）を示します
2. 実際の動作について補足します
3. 関連する場合は、他のプロバイダーが同じ概念をどのように扱うかを説明します
4. ユーザーの経験レベルに合わせて技術的な詳しさを調整します