wa-setpieces

Note

This package is a work in progress – updates will keep coming heavily in the near future. Feedback, bug reports, or trouble getting something to work? Reach out at marc@waltzinganalytics.com.

Set-piece analytics for football, in pandas. Point it at an Opta, StatsBomb or IMPECT match export – one file, or a whole folder of them for a season – and get every corner, free kick, throw-in, penalty, goal kick and kick-off tagged, measured and rated – as tidy DataFrames, plus pitch plots built on mplsoccer.

from wa_setpieces import load_matches, set_piece_summary
from wa_setpieces.viz.plots import plot_delivery_map
from wa_setpieces import delivery_locations

events = load_matches("match.json", provider="opta", type="match")
set_piece_summary(events)

corners = delivery_locations(events, "corner")
plot_delivery_map(corners, title="Corner deliveries")
Corner delivery map drawn with mplsoccer

That one call already answers “how many, how successful, who took them” – set_piece_summary() returns attempts, success rate, shots and goals for every set-piece type, per team, in one table. Everything past that – second phases, retention, an xT value model, benchmarked 0-100 ratings, routine taxonomies, defensive scouting, season form, HTML reports, CSV/Excel export – is one function call away. The Quickstart walks through your first match end to end; past that, pick a reference page below.

load_matches() above is the one loading entry point for all three providers, both scopes – every call has the exact same two knobs, provider and type, nothing else about the call changes shape between them:

load_matches("match.json", provider="opta", type="match")               # one Opta match
load_matches("season/", provider="statsbomb", type="season")            # a folder of StatsBomb matches
load_matches("impect_export.csv", provider="impect", type="match")      # one IMPECT export, often many matches already

Every function past this point takes the result unchanged – there is no separate code path per provider anywhere else in the package.

  • Quickstart – load a match, get a summary table and a plot on screen in five minutes.

  • Gallery – every plot this package makes, with the source that made it.

  • By set piece – corner, free kick, throw-in, penalty, goal kick, kick-off: pick yours, see what’s available.

  • By value model – xT, added value, shot value, ratings: pick one, see what it measures and how to compute it.

  • By metric – counts, delivery locations, shot/goal linking, zones: pick one, see how to pull it.

  • By phase and outcome – second phases, retention, outcomes, aerial duels: pick one, see what it detects.

  • By routine – routine taxonomy, data-driven clusters, long throws, penalty placement: pick one, see how to compute it.

  • By report and export – HTML reports, CSV/Excel export, the command line: pick one, see how to produce it.

Why this package

Event-feed set-piece analysis means re-deriving the same handful of hard things on every project: which qualifier actually means “in-swinger” and not something else entirely, whether a defensive clearance travelled far enough to count as “cleared,” how to fit an xT model without a season’s worth of matches lying around. wa_setpieces does that derivation once, with its reasoning written down next to the code – see each reference page’s callouts for what’s a verified fact about the feed versus a tunable heuristic.

Install

pip install wa-setpieces          # core package
pip install "wa-setpieces[viz]"   # + matplotlib/mplsoccer for the plotting helpers

See Installation for the full set of optional extras.