Football Match Report

Metrics included (per team)

• Passing network — nodes at median positions with shirt numbers, circle = starter / square = sub, line thickness ∝ pass volume, verticality %, defensive/forward line heights + shaded zone.
• Shot map — football markers for goals, hatched saves, orange posts, big-chance scaling, plus a Goals/xG/xGOT/Shots/On Target/BigChance/ BigC.Miss/xG-Shot/Avg.Dist comparison bar.
• Defensive block — KDE heatmap, action-height line, compactness %.
• Goalkeeper saves — goal-mouth view of shots faced per keeper.
• Progressive passes & carries — comet lines / dashed arrows with left-center-right zone split.
• xT momentum — average xT per minute (home above / away below zero) with goal and red-card markers.
• Match stats — possession, field tilt, passes, long balls, corners, GK kick length, tackles, interceptions, clearances, aerials, PPDA.
• Zone charts — final-third entries (by pass/carry), box entries, Zone 14 & half-space passes, crosses (acc./unacc.), pass-end-zone heatmaps, high turnovers (led to goal/shot), chance-creating zones (key passes = violet, assists = green), congestion map.
• Top Players dashboard (figure 3) — top ball progressor pass maps (all/progressive/key/assist passes + progressive carries), passes received by the center-forward, top defender action maps, GK pass maps (open play vs goal kicks/free kicks), Top10 stacked bars: ball progressors, shot-sequence involvement, defenders, xT threat creators.
• Individual player dashboard — pass map (accuracy, progressive, chances created, assists, final third, penalty box, crosses, longballs, xT), carries & take-ons (progressive, led to shot/goal, box entries, dispossessed, success rate), shot map with xG/xGOT (FotMob) and inside/outside box split, passes received (final third, box, progressive, cutbacks, ball retention, most passes from), defensive actions (tackles won, dribbles past, recoveries, blocks, aerials, possession wins per third), touches heatmap with distance covered and area covered.

See references/metrics.md for definitions and interpretation notes.

Pitfalls

• Both sources are needed for the full report. WhoScored supplies the event stream; FotMob supplies shots/xG/momentum/colors. A FotMob-only scrape renders a reduced report.
• WhoScored blocks plain requests (403). Use the Playwright path; if playwright install chromium was skipped, the script exits with install instructions. --no-browser only works when matchdict.json already exists in the data dir.
• Coordinate spaces. WhoScored events are 0-100 and scaled to a UEFA 105x68 pitch (x*1.05, y*0.68) — the blueprint convention. Both teams attack toward x=105 in the raw data; the away team's axes are inverted for display and home shots are flipped in the shot map.
• FotMob match id resolution needs the match date. If the date endpoint returns nothing, pass --fotmob-id explicitly (from the FotMob URL #<id>).
• Empty shot map = missing FotMob id. Event panels still render; only shot/xG/momentum/GK panels degrade.
• Player names in passing networks come from WhoScored's playerIdNameDictionary; without matchdict.json only counts are shown.
• Player-level panels need real names to match. FotMob shot xG/xGOT match on playerName (fallback: shortName); if a player's name differs between sources, xG shows 0. Without shots.csv the individual shot map falls back to WhoScored events (positions but no xG).
• Only players who touched the ball appear in player_stats.csv and the per-player dashboards — bench/roster players with zero events are skipped by design.
• Players with <3 touches get a 0 Total_Area_Covered (convex hull guard) instead of crashing the heatmap.
• Be polite: scrape one match at a time; don't loop over hundreds of URLs.

Verification

• scrape_match.py prints per-step status lines and a final ✅ Done in Xs. Bundle ready in ....
• render_report.py prints ✅ <path> for both PNGs.
• Open match_report_1.png: every panel populated, black background, team colors consistent (home left, away right), shirt numbers legible inside nodes, xT momentum in the center row.
• Open match_report_2.png: all 12 zone panels populated with data.
• uv run pytest passes (offline, uses synthetic match data).