# Football event definitions: TEMPLATE

> Fill in every [bracketed] field, version the file, and get it signed off before tagging starts.
> Guide: https://trainmatricx.com/blog/football-event-definitions-pass-duel-pressure-tagging
> Example thresholds below are placeholders to show the format, not recommendations. Set your own.

- Guideline version: [e.g. v1.0]   Date: [date]   Owner: [name]
- Applies to schema version: [e.g. tm-football-1.1]
- Change rule: any edit to a definition below gets a new guideline version and is noted in the change log.

---

## How to write each definition

Every event gets the same six fields:

1. **Definition:** one sentence, written so two people watching the same clip reach the same answer.
2. **Observable test:** what the tagger must see in the video. No mind-reading: avoid "intended" or "tried to" unless you say what counts as evidence of intent.
3. **Includes:** situations that count.
4. **Excludes:** situations that do not count, and which event they go to instead.
5. **Edge cases:** the calls taggers will disagree on, each with the decision.
6. **Timestamp rule:** which frame the event is stamped at.

---

## Pass
- Definition: [e.g. A touch that sends the ball along a line a team-mate could reach.]
- Observable test: [e.g. Ball leaves the player's foot or head along a line that a team-mate could reach.]
- Includes: [open-play passes; set-piece deliveries played as passes]
- Excludes: [crosses (see Cross); clearances (see Clearance); throw-ins; goalkeeper throws: tagged as their own events]
- Edge cases: [a "pass" deflected by an opponent: still a pass, outcome = intercepted or deflected]
- Timestamp rule: [frame of ball contact]

## Cross
- Definition: [e.g. A pass from a wide zone into a target zone near goal.]
- Observable test: [start inside zone A, ball path enters zone B; draw both zones on a pitch diagram]
- Includes: [ ]
- Excludes: [ ]
- Edge cases: [low driven ball across the six-yard box from the byline; cut-back]
- Timestamp rule: [frame of ball contact]

## Clearance
- Definition: [e.g. A defensive touch that sends the ball away from the defending team's danger zone with no team-mate as a target.]
- Observable test: [ ]
- Includes: [ ]
- Excludes: [a long ball under no pressure that finds a team-mate: Pass]
- Edge cases: [a hurried clearance that happens to reach a team-mate]
- Timestamp rule: [frame of ball contact]

## Carry
- Definition: [e.g. The ball carrier moves with the ball under control.]
- Observable test: [minimum distance: e.g. X metres; or minimum duration: e.g. X seconds]
- Includes: [ ]
- Excludes: [a first touch that sets up a pass in the same movement]
- Edge cases: [player standing still on the ball; carry ending in a tackle]
- Timestamp rule: [start frame and end frame]

## Duel
- Definition: [e.g. A contest between one player from each team for the same ball.]
- Observable test: [both players make a movement towards the ball or the ball carrier]
- Includes: [ground duels; aerial duels; loose-ball contests, if not a separate event]
- Types: [ground / aerial / loose ball]
- Records: [one event per player, linked; outcome won or lost for each]
- Excludes: [ ]
- Edge cases: [contest where neither player gains control; foul during the contest]
- Timestamp rule: [frame of first contact]

## Tackle
- Definition: [e.g. A ground-level challenge where the defender plays the ball away from the ball carrier.]
- Is it a type of Duel or a separate event: [decide and state]
- Observable test: [defender's foot or body makes contact with the ball at ground level while the opponent has it under control]
- Includes: [ ]
- Excludes: [contact with the player but not the ball: Foul or no event]
- Outcome rule: [won = tackler's team gains possession; lost = ...]
- Edge cases: [ball goes out of play off the tackle; tackle wins ball for a team-mate]
- Timestamp rule: [frame of contact with the ball]

## Interception
- Definition: [e.g. A player stops an opponent's pass by moving into its path.]
- Observable test: [the pass had left the passer's foot; interceptor gains or redirects the ball]
- Includes: [ ]
- Excludes: [a block of a shot (see Block); a loose-ball recovery (see Ball recovery)]
- Edge cases: [interception that goes straight to another opponent]
- Timestamp rule: [frame of contact]

## Pressure
- Definition: [e.g. A defender closes down the ball carrier, receiver or passer.]
- Observable test: [distance threshold: e.g. within X metres; and movement towards the player]
- Start and end: [when pressure starts; when it ends; minimum duration]
- Includes: [ ]
- Excludes: [a defender standing within range but not moving towards the player, if your rule requires movement]
- How on-ball events inherit it: [e.g. any pass, carry or shot made while a pressure event is active is flagged. As a boolean (StatsBomb style: under_pressure) or as a grade (tm-football schema: qualifiers.pressure = none / medium / high, each grade with its own threshold)]
- Edge cases: [two defenders pressing one player; pressure on a receiver before the ball arrives]
- Timestamp rule: [start frame and end frame]

---

## Change log
| Guideline version | Date | Event | Change | Re-tag needed for earlier matches? |
|---|---|---|---|---|
| [v1.0] | [date] | [all] | [first version] | [n/a] |
