# Football events, 2017/18: data, methods and four charts

Two Messi charts cover the men's domestic top divisions in England, Spain,
Germany, Italy and France; two Ronaldo charts cover La Liga. All are historical
2017/18 season counts using Wyscout's event definitions, not current form or
career totals.

Data: Wyscout / Pappalardo & Massucco (2019), Figshare,
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
[Original Events, fixed version 1](https://doi.org/10.6084/m9.figshare.7770599.v1) ·
[Data paper](https://doi.org/10.1038/s41597-019-0247-7).
Filtering, aggregation, ranking, coordinate conversion, analysis and
visualization: Meplar. No source endorsement is implied. See
`SOURCE_LICENSE_METHODS.md` for definitions, calculations, linked attribution
and limitations, and `SOURCE_TERMS.txt` for the reuse notice.

## Complete plotted tables

| File under `plotted_data/` | Rows | Meaning |
| --- | ---: | --- |
| `01_plotted_top10_take_ons.csv` | 10 | Exact top ten by strict take-ons won; attempts and win percentages retained. |
| `01_all_2568_players_take_ons.csv` | 2,568 | Complete distinct-player cohort, including zero-attempt players. |
| `02_all_97_clubs_plus_messi.csv` | 98 | All 97 non-Barcelona clubs, including zeros, plus Messi as a separate player reference. |
| `03_all_shot_location_groups.csv` | 152 | Exact location/outcome/box groups representing all 170 Ronaldo attempts and 26 goals. |
| `04_all_166_nonpenalty_attempt_dots.csv` | 166 | Schematic non-penalty grids: 83 dots per scheduled matchweek half, not shot chronology. |

Take-on attempts require legacy subtype 11 and tag 503 or 504; wins require
tag 703. Accurate tag 1801 is a different measure. Messi's 209 attempts comprise
159 wins, nine neutral outcomes and 41 losses. `take_ons_not_won` is attempts
minus wins and includes neutrals; it must not be relabelled losses.
`win_percentage` is wins/attempts × 100, stored to six decimals, with a blank
for zero attempts. The top ten are ranked over all 2,568 players with no
minimum-minute or attempt threshold; 2,163 players have at least one attempt.

`leagues` contains semicolon-separated league-country labels, not nationality.
`appearances_with_events` counts distinct matches with recorded player events,
not minutes or official appearance data. Counts reflect opportunity and playing
time; the chart ranks total wins, not win rate or per-90 performance.

Club `plot_y_stack_position` values are arbitrary layout coordinates: zero-based
within each goal total, with Messi's separate reference at y=37. Vertical
position is not another performance metric. The 97-club denominator excludes
Barcelona because Messi scored all six of its qualifying free-kick goals.

For shot groups, `marker_attempt_count` is the group weight and `event_ids` is
a semicolon-separated exact partition of the 170 source attempt IDs. Display
coordinates are `y_pct × 0.68` across the pitch and `105 − x_pct × 1.05` from
the attacking goal line, in metres on a standard 105 × 68 m pitch. Rounded source
locations and the reference-pitch assumption can affect boundary classifications.

Dot `dot_index` is one-based 1–83 within each half, in schematic goal-first
counting order. `plot_column` and `plot_row` are zero-based, using
`((index−1) % 10, (index−1) // 10)`. They are not event identifiers or chronology.
Scheduled matchweeks 1–19 and 20–38 retain rescheduled games' assigned matchweek;
they are not chronological halves or equal-appearance samples.

## Complete selected audits

- `reproducibility/input_takeons_v3/messi_take_on_event_audit.csv`: all 209
  Messi take-on IDs with tags and won/neutral/lost outcomes. These rows do not
  contain subtype; the subtype predicate is retained in the recount script
  and attributed upstream validation, not newly recounted from raw events here.
- `reproducibility/input/messi/all_direct_freekick_goals_2017_18.csv`: all 122
  qualifying goal events, with subtype 33 and direct/goal tags 1101/101.
- `reproducibility/input/ronaldo/data/ronaldo_shot_map.csv`: all 170 season
  attempts, including four penalties and all 26 goals.
- `reproducibility/input/ronaldo/data/ronaldo_by_match.csv`: all 27 match rows.
- `reproducibility/input/ronaldo/data/ronaldo_half_season.csv`: both scheduled
  halves, with all-shot and non-penalty attempts, goals and conversion rates.

Original metadata, tag/event mappings, complete derivative inputs, older source
notes and compact handoffs remain under `reproducibility/`. Earlier optional
research tables are provenance, not additional plotted charts in this set.
`files.json` is the inventory of files actually included here.

## Reproduction and raw-data boundary

This compact bundle includes complete derivative tables and selected event
audits, not the approximately 1 GB expanded original raw-event archive or its
complete league-event, player or match JSONs. The supplied upstream handoffs
report raw-event recalculation; validation during bundle assembly independently
reconciles the supplied tables and selected audits. It is not a new raw-event
audit. For example, the 122-goal audit cannot recount every unsuccessful free
kick, and the take-on audit cannot itself verify a subtype field it does not carry.

To render from the supplied CSVs, use Python 3.12 with the retained pinned
dependencies. From the extracted download:

```sh
python3 -m venv reproducibility/.venv
reproducibility/.venv/bin/python -m pip install -r reproducibility/requirements.lock.txt
reproducibility/.venv/bin/python reproducibility/build_charts_v4.py
```

Installing dependencies may require internet access. Rendering uses the
supplied tables offline and writes to `reproducibility/deliverables_v4/`, leaving
the included root chart exports unchanged. The supplied packaging/QA script
additionally uses Poppler and librsvg for vector raster checks. Recounting
complete raw events requires separately obtaining the cited source files and
following the scripts' documented input paths.

## Export files and inventory

Under `charts/`, these stems each have PNG, editable-text SVG, outlined SVG
(`_outlined.svg`) and embedded-font PDF:

- `01_messi_take_ons_v4`
- `02_messi_free_kicks_clubs_v4`
- `03_ronaldo_outside_box_v4`
- `04_ronaldo_matchweek_halves_v4`

The PNGs are 1800 × 2700. Editable SVG text uses DejaVu Sans; the supplied
fonts and separate licence are under `fonts/`. Outlined SVGs preserve font
geometry without installing a font.

`files.json` records relative paths, byte sizes, SHA256 hashes and media types.
It excludes itself and the outer ZIP to avoid recursive hashes; the ZIP includes
the inventory and all listed payloads. Quantitative CSVs, fonts, metadata and
scripts are copied unchanged. Main methods were adapted to remove internal
workflow details; original supplied methods remain under
`reproducibility/source_handoff/` for exact provenance.

Do not mix providers' shot denominators. No xG, chance-quality, minutes,
opposition, strength or alternative-action adjustment is applied. These figures
do not establish intent, enduring skill or what would have happened had a
player passed instead.