How nhlscraper Scores Expected Goals

What xG Means Here

Expected goals, or xG, is the estimated probability that a shot becomes a goal. In nhlscraper, calculate_expected_goals() adds one column, xG, to a current-schema play-by-play table. Non-shot rows receive NA; shot-attempt rows receive probabilities from versioned XGBoost boosters that are cached locally on first use.

The package does not train models during package use. It ships the frozen runtime preprocessing contract and downloads the matching trained boosters from the companion NHLxG model store when they are first needed. That contract is just as important as the boosters: numeric medians, categorical levels, dummy-column maps, and final feature order all have to match training exactly.

Basic Use

pbp <- nhlscraper::gc_play_by_play(2023030417)
pbp <- nhlscraper::add_shift_times(
  play_by_play = pbp,
  shift_chart  = nhlscraper::shift_chart(2023030417)
)
pbp <- nhlscraper::add_deltas(pbp)
pbp <- nhlscraper::calculate_expected_goals(pbp)

calculate_expected_goals() can derive several missing context columns itself, but the richest input is a play-by-play that already has shift timing and event-to-event deltas. The function keeps the legacy model argument for compatibility, but that argument is ignored.

Six Shot Environments

The model system is not one giant all-purpose classifier. Each target-season vintage contains six mutually exclusive models:

The order matters. A shootout attempt is handled before empty-net or manpower rules. Empty-net shots are pulled out before normal strength partitions. Standard 5v5 is separated from other even-strength play because its sample is large and its scoring environment is cleaner.

Runtime Routing

Each shot is routed by game season and game state:

Runtime routing from play-by-play row to xG value.

Historical games use the target-season vintage when one exists. Seasons before the supported range use the earliest available vintage. Seasons beyond the model range use the latest deployment vintage. That behavior keeps scoring possible for old and future rows while preserving rolling-model logic where exact vintages exist.

Feature Families

The feature set is intentionally broader than “distance plus angle.” The model frame includes information about where the shot came from, what happened just before it, who took it, who was in net, and what state the game was in.

Not every partition uses every feature in the same way, and not every row has every upstream field. The preprocessing bundle is responsible for converting the available public schema into the exact numeric matrix the booster expects.

Training Windows

Each completed target-season vintage is trained only on earlier seasons. For a target season, the training window is the three immediately previous seasons. That keeps the evaluation leak-free: the model never trains on the season it is being evaluated against.

Deployment Vintage Size

The latest deployment vintage is trained on a large three-season sample, but the six partitions differ dramatically in size and base goal rate.

This is why the partitions exist. Empty-net attempts and penalty shots are not rare versions of ordinary five-on-five shots; they are different scoring problems with different base rates.

Completed-Season Evaluation

Completed-season evaluation currently covers target seasons from 2013-14 through 2025-26.

Observed goal rate and xG rate by completed target season.

Across completed seasons, ROC AUC ranges from 0.7685 to 0.7945, and the calibration ratio ranges from 0.9626 to 1.0332. Those values are not a promise that every game-level sum will be exact. They are a check that, across large seasonal samples, the model stays close to observed scoring rates while preserving useful ranking power.

Caveats

Use xG as an estimate of chance quality, not as a perfect replay of intent. The model sees public event and tracking-derived context. It does not see every screen, pre-shot pass, goalie sightline, defensive stick, shooter injury, or tactical instruction. The best use is comparative:

• Which team created more dangerous attempts?
• Which period changed the game?
• Which players produced the best looks?
• Did a club win by shot volume, shot quality, or finishing?

Key Takeaway

calculate_expected_goals() is intentionally simple at the user level and more careful under the hood. Give it a current-schema play-by-play, and it routes each shot through a rolling season vintage, a game-state partition, a frozen preprocessing recipe, and a cached XGBoost booster. The returned xG column is therefore easy to use, but it is not a black box stapled onto raw NHL data.