Skip to contents

Adds an xg column to a play-by-play data frame using the fastRhockey xG models (XGBoost).

The models were trained on NHL PBP data from 2010-2024 using the same methodology as the hockeyR (Daniel Morse) xG models. Three models are used:

  • 5v5 model - Even-strength situations

  • Special teams model - Power play, short-handed, and other non-5v5 situations (adds skater count features)

  • Penalty shot model - A constant xG value for penalty shot attempts

The models are downloaded on the first call from the sportsdataverse-data nhl_xg_models release, checked against the sha256s in the release's manifest (xg_model_meta.json) and cached. Each session re-reads the small manifest; files that still match it are not downloaded again, and a cached copy from another training is replaced, so a retrain needs no fastRhockey update. Offline, the last manifest seen and its cached files are used.

Usage

helper_nhl_calculate_xg(pbp)

Arguments

pbp

A play-by-play data frame produced by nhl_game_pbp or nhl_game_feed. Must contain columns needed by helper_nhl_prepare_xg_data(): event_type, secondary_type, period_type, period, game_seconds, x, y, x_fixed, event_team_abbr, home_abbr, away_abbr, home_skaters, away_skaters, shot_distance, shot_angle, empty_net, strength_state, game_id, event_id, season.

pbp may hold more than one game: predictions are matched back by game_id and event_id. An existing xg column is replaced.

Value

The original pbp data frame, same rows in the same order, with an xg column appended (replacing any existing one):

col_nametypesdescription
xgnumericExpected-goal probability of the shot, NA for non-shot events.

If xgboost is not installed, the function raises a warning of class fastRhockey_no_xgboost and every xg is NA.

Examples

if (FALSE) { # \dontrun{
  pbp <- nhl_game_pbp(2024020001, include_shifts = TRUE)
  pbp <- helper_nhl_calculate_xg(pbp)
  # View xG for shots
  pbp[!is.na(pbp$xg), c("event_type", "shot_distance", "shot_angle", "xg")]
} # }