wa-setpieces 0.4.0__tar.gz

wa_setpieces-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waltzing Analytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wa_setpieces-0.4.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: wa-setpieces
+Version: 0.4.0
+Summary: Set-piece metrics and mplsoccer pitch visualizations (penalties, kick-offs, free kicks, corners, throw-ins, goal kicks) from Opta F24 event data, including second phases, xT, zones and retention
+Author: Waltzing Analytics
+License: MIT
+Project-URL: Homepage, https://github.com/marclamberts/waltzinganalytics
+Project-URL: Documentation, https://waltzinganalytics.readthedocs.io
+Keywords: football,soccer,opta,set-pieces,sports-analytics
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: numpy>=1.23
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.6; extra == "viz"
+Requires-Dist: mplsoccer>=1.2; extra == "viz"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.15; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: matplotlib>=3.6; extra == "docs"
+Requires-Dist: mplsoccer>=1.2; extra == "docs"
+Dynamic: license-file
+
+# wa-setpieces
+
+Set-piece metrics for football (soccer) matches from **Opta / Stats Perform F24**
+event-feed JSON exports: penalties, kick-offs, free kicks, corners,
+throw-ins and goal kicks.
+
+Given a raw F24 match file, this package tags every set-piece restart,
+aggregates attempts/success rates by team and player, tracks pass end
+locations for delivery maps, and links each set piece to the shot or goal
+it produced (via Opta's assist-chain qualifier). It also covers, for
+corners and free kicks specifically: second-phase detection, Expected
+Threat (xT), pitch zones/thirds/channels, and possession retention —
+with pitch plots built on [mplsoccer](https://mplsoccer.readthedocs.io).
+
+<p align="center">
+  <img src="docs/source/_static/hero_corners.png" alt="Corner delivery map drawn with mplsoccer" width="640">
+</p>
+
+**Full documentation, with a runnable plot gallery: https://waltzinganalytics.readthedocs.io**
+
+## Install
+
+```bash
+pip install wa-setpieces
+```
+
+Not yet published to PyPI? Install from source instead:
+
+```bash
+git clone https://github.com/marclamberts/waltzinganalytics.git
+cd waltzinganalytics
+pip install -e .
+```
+
+## Quickstart
+
+```python
+from wa_setpieces import load_events, set_piece_summary
+
+match = load_events("match.json")
+summary = set_piece_summary(match.events)
+print(summary)
+```
+
+```
+              contestantId set_piece_type  attempts  successful  success_rate  shots  goals
+cxb4hqite921i...      corner         2           1         0.500      1      0
+cxb4hqite921i...   free_kick        12           9         0.750      0      0
+cxb4hqite921i...   goal_kick         8           5         0.625      0      0
+cxb4hqite921i...    kick_off         1           1         1.000      0      0
+cxb4hqite921i...    throw_in        20          16         0.800      1      0
+...
+```
+
+## Second phases, xT, zones and retention
+
+```python
+from wa_setpieces import (
+    second_phases, second_phase_summary,   # corner/free-kick second-phase shots
+    retention_detail, retention_rate,      # possession retained N seconds later
+    add_thirds, add_channels, add_zone_grid,  # pitch location tagging
+    XTModel, set_piece_delivery_xt, set_piece_xt_summary,  # Expected Threat
+)
+
+second_phases(match.events, "corner")           # per-corner: cleared / first-phase shot / second-phase shot
+second_phase_summary(match.events, "free_kick") # per-team roll-up
+
+retention_rate(match.events, "corner")          # per-team: % of corners where the ball is retained ~8s later
+
+tagged = add_thirds(match.events)               # defensive_third / middle_third / attacking_third
+tagged = add_channels(tagged, n=5)              # wide / half-space / central
+
+model = XTModel.fit(match.events)               # fit an xT grid (fit on many matches for real use!)
+set_piece_xt_summary(match.events, "corner", model)  # total/average xT added per team
+```
+
+All four are **derived heuristics**, not raw Opta fields — see
+`docs/source/advanced.rst` (or the hosted docs) for the exact assumptions
+and tunable thresholds behind each one.
+
+## Plots
+
+```bash
+pip install -e ".[viz]"   # matplotlib + mplsoccer
+```
+
+```python
+from wa_setpieces.viz import (
+    plot_delivery_map,      # arrow map of deliveries, colored by outcome
+    plot_zone_heatmap,      # where events happen, gridded onto the pitch
+    plot_xt_grid,           # a fitted XTModel's grid, as a heatmap
+    plot_second_phase,      # one corner/free-kick's phase sequence, numbered
+    plot_team_comparison,   # grouped bars: both teams, every set-piece type
+    plot_xt_added_bars,     # diverging bar chart of xT added per delivery
+    plot_corner_sonar,      # polar plot of delivery angle + distance
+    plot_match_timeline,    # every set piece on one shared match-minute axis
+    plot_dashboard,         # one-figure report card combining several of the above
+)
+
+plot_delivery_map(delivery_locations(match.events, "corner"), title="Corner deliveries")
+plot_dashboard(match.events, team_id, set_piece_type="corner")  # the "hero" figure
+```
+
+Every plotting function returns `(fig, ax)` (`plot_dashboard` returns just
+`fig`, being multi-panel) for further customization. Colors are assigned by
+the job they do — a validated categorical palette for team identity, a
+status pair for success/fail, single-hue sequential ramps for magnitude,
+and a diverging pair for signed quantities like xT added — not picked for
+looks; see `wa_setpieces/theme.py`. See the
+[gallery](https://waltzinganalytics.readthedocs.io/en/latest/gallery/index.html)
+for all nine plots with full source code.
+
+## Command line
+
+```bash
+wa-setpieces match.json
+wa-setpieces match.json --csv summary.csv
+wa-setpieces match.json --xt   # also fit + print xT for this match (illustrative on one match)
+```
+
+## What counts as a set piece
+
+| Type        | Detected on                              | Opta qualifierId |
+|-------------|-------------------------------------------|-------------------|
+| Penalty     | shot event (miss/post/saved/goal)          | 9                 |
+| Kick-off    | pass event                                 | 279               |
+| Free kick   | pass event (corners excluded)              | 5                 |
+| Corner      | pass event                                 | 6                 |
+| Throw-in    | pass event                                 | 107                |
+| Goal kick   | pass event                                 | 124               |
+
+These qualifier IDs are the standard Opta/Stats Perform F24 vocabulary and
+were cross-checked against a real match export (see `tests/data/sample_match.json`
+and `tests/test_filters.py`): tagged events line up with their expected pitch
+location (corner arc, touchline, centre spot, six-yard line).
+
+## Package layout
+
+- `wa_setpieces.loader` — parse F24 JSON into a tidy `pandas.DataFrame`; `load_events_multi` stacks a whole season.
+- `wa_setpieces.constants` — Opta typeId / qualifierId reference.
+- `wa_setpieces.filters` — extract/tag each set-piece type.
+- `wa_setpieces.metrics` — team/player counts, success rates, delivery locations.
+- `wa_setpieces.chains` — link set pieces to the shots/goals they produced.
+- `wa_setpieces.zones` — pitch thirds, channels and a configurable zone grid.
+- `wa_setpieces.phases` — second-phase detection for corners/free kicks.
+- `wa_setpieces.retention` — possession retention after any restart.
+- `wa_setpieces.xt` — grid-based Expected Threat (xT), fit from data.
+- `wa_setpieces.viz` — mplsoccer/matplotlib plots: delivery maps, heatmaps, sonar, timeline, dashboard (optional `viz` extra).
+- `wa_setpieces.theme` — the validated color palette every plot draws from.
+- `wa_setpieces.cli` — `wa-setpieces` command-line tool.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Releasing
+
+Publishing to PyPI is automated via GitHub Actions trusted publishing
+(`.github/workflows/publish.yml`) — no API token stored anywhere. **One-time
+setup** (only a PyPI project owner can do this, since it requires logging
+into PyPI):
+
+1. On PyPI: <https://pypi.org/manage/account/publishing/> → add a pending
+   trusted publisher with project name `wa-setpieces`, owner
+   `marclamberts`, repository `waltzinganalytics`, workflow `publish.yml`,
+   environment `pypi`.
+2. From then on, publishing a GitHub Release (or pushing a `v*` tag) builds
+   the sdist/wheel and uploads them automatically.
+
+## Docs
+
+Docs are built with Sphinx (`pydata-sphinx-theme` + `sphinx-gallery`, the
+same stack mplsoccer's docs use) and hosted on Read the Docs
+(`.readthedocs.yaml` at the repo root). The gallery under `examples_gallery/`
+is executed at build time, so its plots and DataFrame outputs are always
+current. To build locally:
+
+```bash
+pip install -e ".[docs]"
+sphinx-build -b html docs/source docs/_build/html
+```
+
+## License
+
+MIT

wa_setpieces-0.4.0/README.md

@@ -0,0 +1,188 @@
+# wa-setpieces
+
+Set-piece metrics for football (soccer) matches from **Opta / Stats Perform F24**
+event-feed JSON exports: penalties, kick-offs, free kicks, corners,
+throw-ins and goal kicks.
+
+Given a raw F24 match file, this package tags every set-piece restart,
+aggregates attempts/success rates by team and player, tracks pass end
+locations for delivery maps, and links each set piece to the shot or goal
+it produced (via Opta's assist-chain qualifier). It also covers, for
+corners and free kicks specifically: second-phase detection, Expected
+Threat (xT), pitch zones/thirds/channels, and possession retention —
+with pitch plots built on [mplsoccer](https://mplsoccer.readthedocs.io).
+
+<p align="center">
+  <img src="docs/source/_static/hero_corners.png" alt="Corner delivery map drawn with mplsoccer" width="640">
+</p>
+
+**Full documentation, with a runnable plot gallery: https://waltzinganalytics.readthedocs.io**
+
+## Install
+
+```bash
+pip install wa-setpieces
+```
+
+Not yet published to PyPI? Install from source instead:
+
+```bash
+git clone https://github.com/marclamberts/waltzinganalytics.git
+cd waltzinganalytics
+pip install -e .
+```
+
+## Quickstart
+
+```python
+from wa_setpieces import load_events, set_piece_summary
+
+match = load_events("match.json")
+summary = set_piece_summary(match.events)
+print(summary)
+```
+
+```
+              contestantId set_piece_type  attempts  successful  success_rate  shots  goals
+cxb4hqite921i...      corner         2           1         0.500      1      0
+cxb4hqite921i...   free_kick        12           9         0.750      0      0
+cxb4hqite921i...   goal_kick         8           5         0.625      0      0
+cxb4hqite921i...    kick_off         1           1         1.000      0      0
+cxb4hqite921i...    throw_in        20          16         0.800      1      0
+...
+```
+
+## Second phases, xT, zones and retention
+
+```python
+from wa_setpieces import (
+    second_phases, second_phase_summary,   # corner/free-kick second-phase shots
+    retention_detail, retention_rate,      # possession retained N seconds later
+    add_thirds, add_channels, add_zone_grid,  # pitch location tagging
+    XTModel, set_piece_delivery_xt, set_piece_xt_summary,  # Expected Threat
+)
+
+second_phases(match.events, "corner")           # per-corner: cleared / first-phase shot / second-phase shot
+second_phase_summary(match.events, "free_kick") # per-team roll-up
+
+retention_rate(match.events, "corner")          # per-team: % of corners where the ball is retained ~8s later
+
+tagged = add_thirds(match.events)               # defensive_third / middle_third / attacking_third
+tagged = add_channels(tagged, n=5)              # wide / half-space / central
+
+model = XTModel.fit(match.events)               # fit an xT grid (fit on many matches for real use!)
+set_piece_xt_summary(match.events, "corner", model)  # total/average xT added per team
+```
+
+All four are **derived heuristics**, not raw Opta fields — see
+`docs/source/advanced.rst` (or the hosted docs) for the exact assumptions
+and tunable thresholds behind each one.
+
+## Plots
+
+```bash
+pip install -e ".[viz]"   # matplotlib + mplsoccer
+```
+
+```python
+from wa_setpieces.viz import (
+    plot_delivery_map,      # arrow map of deliveries, colored by outcome
+    plot_zone_heatmap,      # where events happen, gridded onto the pitch
+    plot_xt_grid,           # a fitted XTModel's grid, as a heatmap
+    plot_second_phase,      # one corner/free-kick's phase sequence, numbered
+    plot_team_comparison,   # grouped bars: both teams, every set-piece type
+    plot_xt_added_bars,     # diverging bar chart of xT added per delivery
+    plot_corner_sonar,      # polar plot of delivery angle + distance
+    plot_match_timeline,    # every set piece on one shared match-minute axis
+    plot_dashboard,         # one-figure report card combining several of the above
+)
+
+plot_delivery_map(delivery_locations(match.events, "corner"), title="Corner deliveries")
+plot_dashboard(match.events, team_id, set_piece_type="corner")  # the "hero" figure
+```
+
+Every plotting function returns `(fig, ax)` (`plot_dashboard` returns just
+`fig`, being multi-panel) for further customization. Colors are assigned by
+the job they do — a validated categorical palette for team identity, a
+status pair for success/fail, single-hue sequential ramps for magnitude,
+and a diverging pair for signed quantities like xT added — not picked for
+looks; see `wa_setpieces/theme.py`. See the
+[gallery](https://waltzinganalytics.readthedocs.io/en/latest/gallery/index.html)
+for all nine plots with full source code.
+
+## Command line
+
+```bash
+wa-setpieces match.json
+wa-setpieces match.json --csv summary.csv
+wa-setpieces match.json --xt   # also fit + print xT for this match (illustrative on one match)
+```
+
+## What counts as a set piece
+
+| Type        | Detected on                              | Opta qualifierId |
+|-------------|-------------------------------------------|-------------------|
+| Penalty     | shot event (miss/post/saved/goal)          | 9                 |
+| Kick-off    | pass event                                 | 279               |
+| Free kick   | pass event (corners excluded)              | 5                 |
+| Corner      | pass event                                 | 6                 |
+| Throw-in    | pass event                                 | 107                |
+| Goal kick   | pass event                                 | 124               |
+
+These qualifier IDs are the standard Opta/Stats Perform F24 vocabulary and
+were cross-checked against a real match export (see `tests/data/sample_match.json`
+and `tests/test_filters.py`): tagged events line up with their expected pitch
+location (corner arc, touchline, centre spot, six-yard line).
+
+## Package layout
+
+- `wa_setpieces.loader` — parse F24 JSON into a tidy `pandas.DataFrame`; `load_events_multi` stacks a whole season.
+- `wa_setpieces.constants` — Opta typeId / qualifierId reference.
+- `wa_setpieces.filters` — extract/tag each set-piece type.
+- `wa_setpieces.metrics` — team/player counts, success rates, delivery locations.
+- `wa_setpieces.chains` — link set pieces to the shots/goals they produced.
+- `wa_setpieces.zones` — pitch thirds, channels and a configurable zone grid.
+- `wa_setpieces.phases` — second-phase detection for corners/free kicks.
+- `wa_setpieces.retention` — possession retention after any restart.
+- `wa_setpieces.xt` — grid-based Expected Threat (xT), fit from data.
+- `wa_setpieces.viz` — mplsoccer/matplotlib plots: delivery maps, heatmaps, sonar, timeline, dashboard (optional `viz` extra).
+- `wa_setpieces.theme` — the validated color palette every plot draws from.
+- `wa_setpieces.cli` — `wa-setpieces` command-line tool.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Releasing
+
+Publishing to PyPI is automated via GitHub Actions trusted publishing
+(`.github/workflows/publish.yml`) — no API token stored anywhere. **One-time
+setup** (only a PyPI project owner can do this, since it requires logging
+into PyPI):
+
+1. On PyPI: <https://pypi.org/manage/account/publishing/> → add a pending
+   trusted publisher with project name `wa-setpieces`, owner
+   `marclamberts`, repository `waltzinganalytics`, workflow `publish.yml`,
+   environment `pypi`.
+2. From then on, publishing a GitHub Release (or pushing a `v*` tag) builds
+   the sdist/wheel and uploads them automatically.
+
+## Docs
+
+Docs are built with Sphinx (`pydata-sphinx-theme` + `sphinx-gallery`, the
+same stack mplsoccer's docs use) and hosted on Read the Docs
+(`.readthedocs.yaml` at the repo root). The gallery under `examples_gallery/`
+is executed at build time, so its plots and DataFrame outputs are always
+current. To build locally:
+
+```bash
+pip install -e ".[docs]"
+sphinx-build -b html docs/source docs/_build/html
+```
+
+## License
+
+MIT

wa_setpieces-0.4.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wa-setpieces"
+version = "0.4.0"
+description = "Set-piece metrics and mplsoccer pitch visualizations (penalties, kick-offs, free kicks, corners, throw-ins, goal kicks) from Opta F24 event data, including second phases, xT, zones and retention"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Waltzing Analytics" }]
+keywords = ["football", "soccer", "opta", "set-pieces", "sports-analytics"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Intended Audience :: Science/Research",
+]
+dependencies = [
+    "pandas>=1.5",
+    "numpy>=1.23",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+viz = [
+    "matplotlib>=3.6",
+    "mplsoccer>=1.2",
+]
+docs = [
+    "sphinx>=7.0",
+    "pydata-sphinx-theme>=0.15",
+    "sphinx-gallery>=0.15",
+    "myst-parser",
+    "matplotlib>=3.6",
+    "mplsoccer>=1.2",
+]
+
+[project.scripts]
+wa-setpieces = "wa_setpieces.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/marclamberts/waltzinganalytics"
+Documentation = "https://waltzinganalytics.readthedocs.io"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wa_setpieces-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wa_setpieces-0.4.0/src/wa_setpieces/__init__.py

@@ -0,0 +1,76 @@
+"""wa-setpieces: set-piece metrics (penalties, kick-offs, free kicks,
+corners, throw-ins, goal kicks) from Opta / Stats Perform F24 event data.
+"""
+
+from .chains import link_set_piece_shots, set_piece_goal_summary
+from .filters import (
+    extract_all,
+    extract_corners,
+    extract_free_kicks,
+    extract_goal_kicks,
+    extract_kick_offs,
+    extract_penalties,
+    extract_throw_ins,
+    tag_set_pieces,
+)
+from .loader import Match, load_events, load_events_multi
+from .metrics import (
+    delivery_locations,
+    player_set_piece_counts,
+    set_piece_summary,
+    team_set_piece_counts,
+)
+from .phases import (
+    PhaseResult,
+    classify_phase,
+    second_phase_summary,
+    second_phases,
+)
+from .retention import retention_detail, retention_rate
+from .xt import XTModel, set_piece_delivery_xt, set_piece_xt_summary
+from .zones import (
+    add_channels,
+    add_thirds,
+    add_zone_grid,
+    to_reference_frame,
+    zone_counts,
+    zone_id,
+)
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "Match",
+    "load_events",
+    "load_events_multi",
+    "extract_all",
+    "extract_corners",
+    "extract_free_kicks",
+    "extract_goal_kicks",
+    "extract_kick_offs",
+    "extract_penalties",
+    "extract_throw_ins",
+    "tag_set_pieces",
+    "link_set_piece_shots",
+    "set_piece_goal_summary",
+    "team_set_piece_counts",
+    "player_set_piece_counts",
+    "delivery_locations",
+    "set_piece_summary",
+    "PhaseResult",
+    "classify_phase",
+    "second_phases",
+    "second_phase_summary",
+    "retention_detail",
+    "retention_rate",
+    "XTModel",
+    "set_piece_delivery_xt",
+    "set_piece_xt_summary",
+    "add_thirds",
+    "add_channels",
+    "add_zone_grid",
+    "to_reference_frame",
+    "zone_id",
+    "zone_counts",
+    "__version__",
+]

wa_setpieces-0.4.0/src/wa_setpieces/chains.py

@@ -0,0 +1,99 @@
+"""Link set pieces to the shots and goals they produce.
+
+Opta connects a shot to the pass that created it via qualifier 55
+("related event id"), which stores the ``eventId`` of the assisting pass.
+A shot can also *be* a set piece directly (e.g. a direct free kick or a
+penalty), in which case there is no separate assisting pass to look up.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from . import constants as c
+from .filters import tag_set_pieces
+
+
+def link_set_piece_shots(events: pd.DataFrame) -> pd.DataFrame:
+    """Return one row per shot (incl. goals) with its set-piece origin, if any.
+
+    Columns:
+        eventId, typeId, outcome, is_goal, contestantId, playerId, playerName,
+        x, y, timeMin, timeSec, set_piece_type, set_piece_event_id.
+
+    ``set_piece_type`` is ``None`` for shots that did not originate from a
+    tagged set piece (open play, or a phase the assist qualifier does not
+    reach back to).
+    """
+    tagged = tag_set_pieces(events)
+    shots = tagged.loc[tagged["typeId"].isin(c.SHOT_TYPE_IDS)].copy()
+
+    by_event_id = tagged.set_index("eventId", drop=False)
+
+    set_piece_type: list[str | None] = []
+    set_piece_event_id: list[int | None] = []
+    for _, shot in shots.iterrows():
+        # Case 1: the shot itself is the set piece (direct free kick, penalty).
+        if shot["set_piece_type"] is not None:
+            set_piece_type.append(shot["set_piece_type"])
+            set_piece_event_id.append(shot["eventId"])
+            continue
+
+        # Case 2: walk back to the assisting pass via qualifier 55.
+        related_raw = shot.get(f"q_{c.QUALIFIER_RELATED_EVENT_ID}")
+        origin_type = None
+        origin_event_id = None
+        if related_raw is not None:
+            try:
+                related_id = int(float(related_raw))
+            except (TypeError, ValueError):
+                related_id = None
+            if related_id is not None and related_id in by_event_id.index:
+                origin = by_event_id.loc[related_id]
+                if isinstance(origin, pd.DataFrame):  # duplicate eventId guard
+                    origin = origin.iloc[0]
+                if origin["set_piece_type"] is not None:
+                    origin_type = origin["set_piece_type"]
+                    origin_event_id = int(related_id)
+        set_piece_type.append(origin_type)
+        set_piece_event_id.append(origin_event_id)
+
+    shots["is_goal"] = shots["typeId"] == c.TYPE_GOAL
+    shots["set_piece_type"] = set_piece_type
+    shots["set_piece_event_id"] = set_piece_event_id
+
+    cols = [
+        "eventId",
+        "typeId",
+        "outcome",
+        "is_goal",
+        "contestantId",
+        "playerId",
+        "playerName",
+        "x",
+        "y",
+        "timeMin",
+        "timeSec",
+        "set_piece_type",
+        "set_piece_event_id",
+    ]
+    return shots[cols].reset_index(drop=True)
+
+
+def set_piece_goal_summary(events: pd.DataFrame) -> pd.DataFrame:
+    """Goals scored per set-piece type per team.
+
+    Returns a DataFrame indexed by ``(contestantId, set_piece_type)`` with a
+    ``goals`` count, restricted to set pieces that produced at least one goal.
+    """
+    linked = link_set_piece_shots(events)
+    goals = linked.loc[linked["is_goal"] & linked["set_piece_type"].notna()]
+    if goals.empty:
+        return pd.DataFrame(columns=["contestantId", "set_piece_type", "goals"])
+    summary = (
+        goals.groupby(["contestantId", "set_piece_type"])
+        .size()
+        .rename("goals")
+        .reset_index()
+    )
+    return summary