ghost-gk-v1

Ghost-GK v1 — Conditional Density Estimation for Goalkeeper Positioning

Predicts where a league-average goalkeeper would position themselves given the current game state. Uses RFCDE (Random Forest Conditional Density Estimation) over HistGradientBoostingRegressor leaf assignments with weighted 2D kernel density estimation.

Part of the silly-kicks soccer analytics library (GKDV research program, TF-18, Layer 2).

Rest-defense / high sweeper? The default/full variants here train on a fixed x ∈ [0, 30] m goal-relative box and saturate at 30 m — they cannot place an in-possession keeper who has pushed up to 30–45 m. For that regime, see the separate extended-grid (x_max = 52.5 m) model ghost-gk-sweeper-v1 (and its velocity-less companion ghost-gk-sweeper-position-only-v1) — TF-60, ADR-083.

Model Description

Standard goalkeeper evaluation metrics (xGOT, save percentage, goals prevented) measure what happens after a shot is taken. Ghost-GK addresses the upstream question: given the current game state, where should the goalkeeper be standing?

The model learns a league-average positional density from thousands of match frames across multiple tracking data providers. For any given frame, it outputs a full 2D probability distribution over the goal-relative region, not just a point estimate. This enables downstream metrics like the GK Deterrent Value (GKDV) — comparing the actual GK position against the ghost position to quantify positioning-as-deterrent.

Key properties:

• Density estimation, not regression: Outputs a 60×64 probability grid (3,840 cells at 0.5m resolution), not a single (x, y) point. Captures multimodal positioning (e.g., split between near-post and central when the ball is wide).
• No pickle: Serialized as npz (NumPy arrays) + JSON (metadata) + SHA-256 integrity sidecar. No pickle anywhere in the load/save path.
• Vectorized inference: Tree traversal uses NumPy array operations (no sklearn at inference time). Batch prediction of 1,000 frames completes in under 1 second.
• Two variants: "default" (approx. 1.0 MB, 36k-frame subsample) ships bundled in the wheel; "full" (approx. 2.4 MB, 179-match corpus) downloads from this Hub repo on first use. Both are parameters-only artifacts — the two trained tree ensembles and their baselines, with no per-sample training data (silly-kicks 4.54.0; ADR-044).

Architecture

The model implements RFCDE (Pospisil & Lee 2018) adapted for goalkeeper positioning:

1. Feature extraction: 26 goal-relative features per frame (ball state, defensive geometry, game context). phase is trained numerically (not categorical) so the pickle-free numeric tree traversal matches sklearn exactly (4.14.0; ADR-016).
2. Leaf assignment: HistGradientBoostingRegressor (500 trees, max depth 8) trained on GK x-coordinate; leaf assignments partition the feature space
3. Co-occurrence weighting: Training frames sharing leaf assignments with the query frame receive higher weight (Dutta et al. 2024 NFL Ghosts approach)
4. 2D KDE: Weighted Gaussian KDE over (x, y) positions of weighted training frames produces the density surface (mode, mean). This step needs the per-sample training positions, so it runs only on a locally fit model — the distributed artifact is parameters-only and does not carry them (silly-kicks 4.54.0; ADR-044).
5. Served point estimate: a second HistGradientBoostingRegressor is trained on GK y-coordinate; ghost_gk_x/y serve the exact boosted mean of both ensembles, reconstructed pickle-free as baseline + Σ_trees leaf_value (no sklearn at inference). 4.14.0; ADR-016.

Features (26)

All coordinates are goal-relative: the defending goal is at x=0, pitch center at y=34.

Hyperparameters

Variants

Both variants are parameters-only artifacts (no per-sample training data is stored or redistributed). They serve identical point-estimate machinery (ghost_gk_x/y); the full variant is trained on the larger corpus. The KDE density read-out (predict_density) is available only on a locally fit model — see Usage.

Training Data

Trained on licensed tracking data from professional football matches:

The full variant is trained on 179 matches / ~1.04M frames across all three providers above (the SkillCorner cohort was expanded to include owner-tier matches — silly-kicks 4.51.0 / TF-19 PR-2); the default variant is a lighter 36k-frame subsample. Only the learned model parameters are published: the two gradient-boosted tree ensembles (split thresholds, feature indices, leaf values) and their additive baselines. No per-sample training data and no raw provider tracking data is redistributed (parameters-only artifact, silly-kicks 4.54.0 — the per-sample density arrays were removed; see ADR-044).

Training targets are restricted to a fixed goal-relative box — x ∈ [0, 30] m from the defended goal line, y ∈ [18, 50] m — a purely geometric filter with no action or possession condition. A keeper that has rushed far upfield (a sweeper action) falls outside this box and is naturally excluded, so the model represents normal in-goal positioning; the exclusion is geometric, not action-based.

Label domain: GK (x, y) position in goal-relative coordinates, filtered to the grid region [0, 30] × [18, 50].

Usage

import silly_kicks.tracking as tracking

# Default variant (bundled, works offline)
densities = tracking.compute_ghost_gk(frames, model="default")

# Full variant (downloads from HF Hub on first use)
densities = tracking.compute_ghost_gk(frames, model="full")

# Action-coupled aggregator for VAEP integration
actions = tracking.add_ghost_gk(actions, frames, model="full")

# Direct model loading — served POSITIONS (works on the distributed parameters-only artifact)
model = tracking.GhostGkModel.from_variant("full")
positions = tracking.compute_ghost_gk(frames, model=model, home_team_id=1)  # ghost_gk_x / ghost_gk_y

# The KDE density read-out (predict_density / GhostGkDensity) requires a LOCALLY FIT model:
# distributed artifacts are parameters-only and do not carry the per-sample data the density
# needs (silly-kicks 4.54.0, ADR-044). On a loaded artifact predict_density raises.
local = tracking.GhostGkModel(n_estimators=500).fit(features, labels)
density = local.predict_density(feature_vector)
print(f"Mode: ({density.mode_x:.1f}, {density.mode_y:.1f})")
print(f"Spread: {density.spread:.2f}")

Output

Each prediction returns a GhostGkDensity frozen dataclass:

The served point estimate (ghost_gk_x/y, model.predict()) is the exact boosted HGBR predict_mean (below), reconstructed pickle-free — it is not a field of GhostGkDensity.

Served point estimate (v4.14.0)

ghost_gk_x/y and model.predict() serve the exact sklearn HistGradientBoostingRegressor boosted mean — the same estimator the old card's ≈1.1 m number measured, but now reconstructed pickle-free (baseline + Σ_trees leaf_value) so it survives load() and is actually served. This closes a pre-existing integrity gap: the card reported ≈1.1 m for an estimator that save()/load() discarded, while production served the KDE mode (≈4.65 m):

The 4.14.0 number is re-measured at re-fit on the same held-out split as the mode (not copied from the old ≈1.1 m card, which was a different, phase-categorical model). An intermediate design that served the leaf-weighted conditional mean (no re-fit) was empirically rejected — it measured ≈7.0 m, worse than the mode, because the conditional density is broad + multimodal. The boosted mean is a structurally stronger estimator and is the only candidate that beats the mode. The mode remains available via predict_density(...).mode_x/mode_y. See ADR-016.

Weights re-fit + re-published (4.14.0). This is an artifact-format change (the npz now carries the gk_y tree ensemble + baselines for the reconstruction; serve_estimator = "boosted_mean"), and fit() now trains phase numerically (closing a latent KDE categorical-routing capability gap). Both the bundled default and this Hub full model are re-fit; old-format artifacts fail closed on load with a clear "re-fit required" error.

Both-axes goal-relative re-fit (silly-kicks 4.111.0 / ADR-089; training_commit=4bda048). These weights were re-fit after the ghost-GK feature extractor was corrected to apply the full 180° goal-relative point reflection (both axes). The previous convention flipped only x (105 − x), leaving the signed-y features (ball_y, ball_vy, ball_to_goal_angle, attacker_centroid_y) and the target gk_y in absolute frame coordinates — so one physical scene scored differently at the two goal ends, and away-team keepers were mislocated in y. The served ghost_gk_x/y change (chiefly for away-team keepers); the feature-contract + chirality fingerprints change, so pre-4.111.0 artifacts fail closed on load. The aggregate held-out MAE is essentially unchanged (the correction affects a subset — away-team keepers).

Parameters-only (4.54.0; ADR-044). The artifact format is now metadata.version = 1.3.0 (stores_training_data = false): the per-sample density arrays (training_gk_x/y, training_leaves) are no longer stored or distributed. The served point estimate (ghost_gk_x/y via predict_mean) is byte-identical. The emitted ghost_gk_density_spread column (renamed from ghost_gk_spread in 4.14.0) is retired from compute_ghost_gk / add_ghost_gk / ghost_gk_xfns; the KDE density read-out now requires a locally fit model.

Serialization Format

model_dir/
  rfcde_weights.npz    # NumPy arrays: gk_x + gk_y gradient-boosted tree nodes + additive baselines (parameters only; no per-sample data)
  metadata.json        # Feature names, grid spec, hyperparameters, version, corpus provenance, chirality fingerprint
  SHA256SUMS           # Integrity checksums (CRLF-normalized for cross-platform safety)

No pickle is used anywhere in the serialization or deserialization path.

Coordinate System

Input frames must be in LTR-normalized convention (home team attacks right in all periods — the standard silly-kicks tracking output after play_left_to_right normalization).

Features are extracted in goal-relative coordinates: - Origin: defending goal center (x=0, y=34) - The defending goal is inferred per (game_id, period_id, team_id) from mean GK x position

Limitations

• League-average ghost: The model predicts where an average goalkeeper would stand, not where a specific goalkeeper would stand. Stylistic differences (sweeper-keeper vs. line-keeper) are averaged out.
• No shot-stopping ability: Ghost-GK models positioning, not reactions. It does not predict save probability or diving reach.
• Tracking data quality: Predictions inherit noise from the underlying tracking system. SkillCorner broadcast-derived coordinates are noisier than optical systems (Sportec DFL).
• LTR normalization required: Input frames must be LTR-normalized. Feeding raw provider coordinates produces incorrect goal-relative features.
• Static density: Each frame produces an independent density estimate. Temporal smoothing is not built into the model (apply externally if needed).

References

@inproceedings{le2017ghosting,
  title={Data-Driven Ghosting Using Deep Imitation Learning},
  author={Le, Hoang M. and Yue, Yisong and Carr, Peter and Lucey, Patrick},
  booktitle={MIT Sloan Sports Analytics Conference},
  year={2017}
}

@article{dutta2024nflghosts,
  title={NFL Ghosts: A framework for evaluating defender positioning
         with conditional density estimation},
  author={Dutta, Rishav and Yurko, Ronald and Ventura, Samuel},
  journal={arXiv preprint arXiv:2406.17220},
  year={2024}
}

@article{pospisil2018rfcde,
  title={RFCDE: Random Forests for Conditional Density Estimation},
  author={Pospisil, Taylor and Lee, Ann B.},
  journal={arXiv preprint arXiv:1804.05753},
  year={2018}
}

@software{nielsen2026ghostgk,
  title={Ghost-GK: Conditional Density Estimation for Goalkeeper Positioning},
  author={Nielsen, Karsten Skyt},
  year={2026},
  url={https://github.com/karsten-s-nielsen/silly-kicks}
}

Model Files

More Information

• License: MIT (same as silly-kicks)
• Library: silly-kicks (v3.24.0+)
• Documentation: silly-kicks GitHub
• Research program: GKDV (GK Deterrent Value) — TF-15 through TF-19

Wheel sibling (4.134.0)

In silly-kicks 4.134.0 the wheel's bundled default was re-fit on the corrected floor velocities (TF-65 / ADR-120, training_commit=a34e992). This Hub owner-tier artifact is unchanged this cycle: the velocity-gap re-fit touched only the wheel-bundled public variant; re-fitting this full Hub model on the corrected velocities is a tracked owner-run follow-up.