{
  "metric": "FullContact",
  "handle": "full_contact",
  "version": "v0-spec",
  "status": "specification — 0 match measured",
  "sport": "rugby union (XV)",
  "inspired_by": "fabcraft.eu/datascience/verticalite",
  "unit_of_observation": "action",
  "unit_of_aggregation": "player x competition x season",
  "denominator_unit": "minutes on field",
  "normalisation": "per 80 minutes",
  "conditions": [
    {
      "id": "C1",
      "name": "CONTACT",
      "verticalite_analogue": "CONTROLE (ball within 2.5 m of carrier >=70% of the action)",
      "rule": "The player is the ball carrier of the phase and takes the ball from a won contact (ruck, maul, lineout, tackle) or receives it at one.",
      "requires": ["carrier_identity", "contact_event", "possession_chain"]
    },
    {
      "id": "C2",
      "name": "PORTEE",
      "verticalite_analogue": "COURSE (carrier body advances >=5 m toward goal)",
      "rule": "The carrier advances >= 10 m toward the opposition goal line, or crosses the opposition gain line, measured on the pitch coordinate frame.",
      "requires": ["carrier_trajectory", "pitch_coordinates", "goal_direction"]
    },
    {
      "id": "C3",
      "name": "RUPTURE",
      "verticalite_analogue": "ELIMINATION (goal-side defender engaged, beaten, never returns)",
      "rule": "A defender engaged the carrier within 6 m, is beaten by the carrier's body, and does not return within 1.5 m of the ball nor re-enter the phase within 3 s.",
      "requires": ["tackle_attempt", "defender_tracking_or_tag", "beaten_flag", "return_window"]
    },
    {
      "id": "C4",
      "name": "QUALIFICATION",
      "verticalite_analogue": "TIR (the same phase produces a shot)",
      "rule": "The same possession or sequence (<= 3 phases and <= 90 s after the rupture) ends in a try scored by the attacking team.",
      "requires": ["possession_chain", "try_event", "sequence_window"]
    }
  ],
  "formulas": {
    "C": "C(p,t) = 1 if exists d in defenders : contact(p,t) ∧ d_engaged(d,t) ∧ d_beaten(d,t) ∧ gain(p,t) >= 10m ∧ not d_returned(d, t -> t+3s)",
    "Cq": "Cq(p,t) = C(p,t) AND try(sequence(t), after t)",
    "rate": "rate(p) = sum(Cq) / minutes_on_field * 80",
    "stabilised": "stabilised(p) = (sum(Cq) + lambda * k) / (minutes_on_field + k) * 80,  k = 240",
    "variant_broad": "Cq_broad(p,t) = C(p,t) AND (try(sequence) OR entry_into_22(sequence) OR penalty(sequence))",
    "variant_expected": "Cq_x(p,t) = C(p,t) AND xPoints(sequence(t)) >= 1.0"
  },
  "variants": {
    "v1_strict": "rupture -> try. Rare; use Poisson intervals.",
    "v1_broad": "rupture -> try OR entry into 22 OR penalty. Doubles the volume; primary ranking.",
    "v2_expected": "rupture -> expected points >= threshold. Continuous label, reuses the platform's own xT engine."
  },
  "validation_protocol": {
    "primary": "Spearman rho between stabilised rate and next-3-match try involvement per 80 (out of sample, match-level split)",
    "secondary": "Incremental value: delta AUC / log-loss over a baseline of minutes + position + team xP",
    "discriminant": "rho with raw volumes (passes, tackles, rucks) must stay LOW — otherwise the metric is a volume metric",
    "convergent": "rho with the platform CLASSEMENT JOUEURS index and with xP contribution per player",
    "reliability": "split-half by match (odd/even rounds) and ICC",
    "inter_rater": "two independent taggers on the 'tackle missed' flag, Cohen kappa; tracking-derived definition as a second annotator",
    "sensitivity": "sweep gain 5/10/15 m, window 1/2/3 phases, beaten-defender return window 2/3/4 s, report top-25 overlap"
  },
  "grain": {
    "observation": "one row per qualifying action",
    "fact_event": "one row per tagged event: match_id, event_id, period, clock_ms, team_id, player_id, event_type, outcome, x_m, y_m, zone",
    "fact_phase": "one row per attacking phase: match_id, phase_id, possession_team_id, n_phases, start_event_id, end_event_id, outcome",
    "fact_player_match": "one row per player per match: player_id, match_id, team_id, position, minutes_on_field, starter, sin_bin_minutes",
    "dim_player": "player_id (surrogate), name, birthdate, club history, preferred position",
    "dim_match": "match_id, competition_id, round, home, away, score",
    "fact_xpoints": "one row per event: event_id, x_t, x_points, x_penalty_tries, x_penalty_points (from the platform's expected-points engine)",
    "tracking_optional": "one row per frame per player: match_id, frame_id, player_id, x, y, vx, vy (10-25 Hz)"
  },
  "data_sources": [
    {
      "id": "S1",
      "name": "AiaSports internal event tables",
      "type": "commercial, internal",
      "grain": "event / phase / player-match",
      "status": "to be requested — the platform already displays every atom needed (gains by magnitude, rucks, tackles, tries, minutes, zones, alignments)",
      "cost": "none (existing product data)"
    },
    {
      "id": "S2",
      "name": "WhartonSABI/rugby-ep (MIT) — expected points for rugby union",
      "type": "open, phase-level",
      "grain": "phase (2018-19 Premiership Rugby)",
      "status": "public, verified",
      "cost": "none",
      "url": "https://github.com/WhartonSABI/rugby-ep"
    },
    {
      "id": "S3",
      "name": "Kalisteo / CEA rugby sevens tracking dataset",
      "type": "open, tracking + video clips",
      "grain": "frame x player, 3 x 40 s extracts (World Rugby 2021 Dubai)",
      "status": "public but small; the closest rugby analogue to SkillCorner Open Data",
      "cost": "none",
      "url": "https://kalisteo.cea.fr/"
    },
    {
      "id": "S4",
      "name": "Foundations of Expected Points in Rugby Union (MMU)",
      "type": "academic, phase-level notational analysis",
      "grain": "phase — 132 Premiership matches, 35,199 phases",
      "status": "methodological reference for the outcome model",
      "cost": "none",
      "url": "https://e-space.mmu.ac.uk/640981"
    },
    {
      "id": "S5",
      "name": "CodeProcessor/rugby-events-dataset",
      "type": "open, event annotations with start/end time",
      "grain": "event",
      "status": "public; candidate for an external replication check",
      "cost": "none",
      "url": "https://github.com/CodeProcessor/rugby-events-dataset"
    },
    {
      "id": "S6",
      "name": "Full-body tracking in rugby (commercial)",
      "type": "tracking",
      "grain": "frame x player",
      "status": "availability to be confirmed — required only to make the RUPTURE condition tracking-derived instead of tag-derived",
      "cost": "to be quoted"
    }
  ],
  "known_traps": [
    "Outcome leakage: tries and points are the label, never a feature.",
    "Denominator must be minutes ON FIELD, not matches played; a sin-binned or substituted player changes it mid-match.",
    "Non-independence: several qualifying actions can belong to one possession — cluster on phase_id, bootstrap by phase.",
    "Player identity: the platform mixes Top 14, Champions Cup, internationals and U20 — surrogate player_id plus a jersey/club/birthdate disambiguation map.",
    "Clock: two 40-minute halves, stoppage time, continuous vs cumulative T — normalise before any rate.",
    "Zones: the platform grid is not the standard pitch frame — re-express as x in [0,100] own try line to opponent try line, y in [-35,35].",
    "Double tagging: a ruck and a 'ruck won' flag often coexist — dedupe on (match_id, event_type, phase_id, clock bucket).",
    "Position confounding: the rate must be standardised within position groups before ranking.",
    "Opportunity confounding: per-80 rates need an opponent-strength baseline (the platform's xP) or they measure the fixture, not the player."
  ]
}
