/compute

name: nutmeg-compute
description: "Calculate derived football metrics and models. Use when the user wants to compute xG, xGOT, PPDA, passing networks, expected threat, possession value, pressing intensity, or any derived football statistic from raw data."
argument-hint: "[metric to compute]"
allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep", "Agent", "mcp__plugin_nutmeg_football-docs__search_docs", "mcp__football-docs__search_docs", "mcp__plugin_nutmeg_football-docs__get_metric", "mcp__football-docs__get_metric", "mcp__plugin_nutmeg_football-docs__list_metrics", "mcp__football-docs__list_metrics"]

Compute

Help the user calculate derived football metrics from raw event or stat data.

Accuracy

Read and follow `${CLAUDE_PLUGIN_ROOT}/docs/accuracy-guardrail.md` before answering any question about provider-specific facts (IDs, endpoints, schemas, coordinates, rate limits). Always use `search_docs` — never guess from training data.

First: check profile

Read `.nutmeg.user.md`. If it doesn't exist, continue with sensible defaults (Python and pandas, intermediate level) and suggest running `/nutmeg` setup at the end.

Metric reference

Before computing a metric that has a football-docs metric card (`list_metrics` shows them: xG, npxG, xA, xG assisted, PPDA, progressive passes and carries, xT, VAEP, field tilt, pass completion), read it with `get_metric("<card>")`:

• Pick one variant and name its ID (for example `ppda.statsbomb-hudl`) in the code, the output and any chart. Values

from different variants are not comparable.

• If the variant has reference code with test values on StatsBomb open data, check your implementation against them.
• In a research project, the plan choice rests on the card: `--rests-type metric --rests-ref <variant-id>`.
• For a metric without a card, use `search_docs` and say which definition you chose.

Expected Goals (xG)

**What it measures:** Probability of a shot resulting in a goal, based on shot location, type, body part, and game situation.

**If provider already has xG:** look up where it lives before writing code, with `search_docs(query="expected goals xG", provider="[provider]")`. Providers differ: some put xG on shot events, some serve it from a separate endpoint, and scraped sources can drop it. Name the doc you used.

**Building your own xG model:** 1. Gather shot data with outcomes (goal/no goal) 2. Features: distance to goal, angle, body part, shot type (open play/set piece/counter), number of defenders 3. Model: logistic regression for baseline, gradient boosting for better accuracy 4. Use as many shots as you can, from several seasons, and keep penalties out (or model them separately) 5. Validate on held-out matches or seasons with calibration plots and log-loss, and compare with a simple baseline

**Common pitfall:** xG models trained on one league may not transfer well to another. Playing styles and league quality differ.

Expected Goals on Target (xGOT)

**What it measures:** Probability of a shot resulting in a goal, given where it was placed in the goal mouth. Higher than xG for well-placed shots, 0 for off-target.

**Available from:** some providers publish it; check with `search_docs(query="xGOT post-shot xG", provider="[provider]")`.

PPDA (Passes Allowed Per Defensive Action)

**What it measures:** Pressing intensity. Lower PPDA = more aggressive pressing.

**Calculation (general shape):**

PPDA = opponent passes in the pressing zone / defensive actions in that zone

There is no single PPDA. Published variants differ in the pressing zone (for example the opponent's own half, or a larger share of the pitch) and in which defensive actions count, and the same match can give very different values across them.

• Read the card before computing: `get_metric("ppda")` lists each published variant with its zone, counted actions

and source.

• Name the variant ID you used (for example `ppda.trainor-2014`), and never compare values from different variants.

Passing Networks

**What they show:** Who passes to whom, average positions, and pass frequency.

**Calculation from event data:** 1. Filter to successful passes in a match 2. Group by passer-receiver pair, count completions 3. Calculate average position for each player (mean x, y of their events) 4. Weight edges by pass count 5. Only show players who started (exclude subs for clean networks)

**Key decisions:** minimum pass threshold for showing a connection (typically 3-4), whether to include GK.

Expected Threat (xT)

**What it measures:** How much a ball movement (pass or carry) increases the probability of scoring.

**Calculation** (Karun Singh's original model, [karun.in/blog/expected-threat.html](https://karun.in/blog/expected-threat.html)): 1. Divide the pitch into a grid (the original uses 16x12, 192 zones) 2. For each zone, estimate the probability of shooting from it (s), the probability that a shot from it scores (g), and the probability of moving the ball instead (m) 3. Estimate a transition matrix T: where moves from each zone end up. The original counts successful moves only 4. Solve iteratively: xT(zone) = s × g + m × Σ T(zone → other) × xT(other) 5. xT of an action = xT(destination) - xT(origin) 6. Use enough seasons of event data that each zone has a stable estimate; sparse zones give noisy values

**Reference implementation:** socceraction (or its maintained successor, silly-kicks) implements xT; check the current API with `search_docs(query="expected threat xT", provider="socceraction")`.

Possession Value Models

**VAEP (Valuing Actions by Estimating Probabilities; Decroos et al., 2019):**

• Trains two models: P(goal scored in next 10 actions) and P(goal conceded in next 10 actions)
• Value of an action = change in scoring probability - change in conceding probability
• Requires significant data and ML expertise

**On-Ball Value (OBV):**

• StatsBomb's proprietary model
• Similar concept to VAEP but with different methodolo