# How the Play-By-Play Pipeline Works

## Why This Article Exists

The play-by-play functions are the package’s most opinionated tools. They do not simply flatten an NHL endpoint and hand the result back. They reconcile multiple public sources, repair a few known event-order problems, derive a large public schema, and add event-level on-ice player IDs from the official HTML report.

That makes `gc_play_by_play()` and `wsc_play_by_play()` extremely useful, but it also means the output deserves a mental model. This article is that model. It is strictly informational: the goal is to explain what the pipeline trusts, what it derives, what it refuses to infer, and where `shift_chart()` fits.

## Two Feeds, One Public Schema

`gc_play_by_play()` and `wsc_play_by_play()` start from different event feeds, but both return a cleaned event table. The source split looks like this:

Public sources used by the play-by-play and shift-chart pipeline.
source | used_by | role
--- | --- | ---
GameCenter API | gc_play_by_play(), game metadata for WSC | Authoritative event stream for GameCenter rows and common metadata.
World Showcase API | wsc_play_by_play() | Alternate event stream with UTC timestamps and fewer clip fields.
HTML play-by-play report | gc_play_by_play(), wsc_play_by_play() | Primary source for event-level on-ice goalie and skater IDs.
Stats shift-chart API | shift_chart() | Preferred source for player shift start/end clocks.
HTML shift reports | shift_chart() fallback | Fallback source for shift start/end clocks when stats API rows are missing.

The important separation is identity versus timing. HTML play-by-play reports are used to recover who was on the ice for an event. Shift charts are used later to calculate how long those players had been on the ice.

    pbp <- nhlscraper::gc_play_by_play(2023030417)
    shifts <- nhlscraper::shift_chart(2023030417)
    pbp <- nhlscraper::add_shift_times(pbp, shifts)

## Pipeline Map

The high-level flow is deliberately conservative. The API event feed remains the backbone. The HTML report is matched back onto that backbone. Derived features are added only after the event order and public naming are stable.

Conceptual order of the play-by-play cleanup pipeline.

## What Gets Repaired

The package is not trying to rewrite the game. It fixes only issues that are plainly incompatible with the event clock or with the package’s public schema.

Conservative repairs made before public output is finalized.
issue | action
--- | ---
Source-specific column names | Rename to stable public names such as periodNumber and eventTypeDescKey.
Goal row without shootingPlayerId | Use scoringPlayerId as shootingPlayerId when the scorer is known.
Blocked-shot zone perspective | Normalize blocked shots to the shooting-team perspective.
Impossible period-boundary order | Drop or repair only the small set of rows that violate clock boundaries.
Missing public output columns | Allocate typed NA columns so GC and WSC outputs keep stable schemas.

The design goal is auditability. When something can be derived directly, the package derives it. When something would require a hockey assumption that cannot be verified from the public sources, the package leaves the public state alone.

## `situationCode` Means State, Not Identity

The raw `situationCode` is parsed into manpower state columns:

- `homeIsEmptyNet`
- `awayIsEmptyNet`
- `homeSkaterCount`
- `awaySkaterCount`
- `isEmptyNetFor`
- `isEmptyNetAgainst`
- `skaterCountFor`
- `skaterCountAgainst`
- `manDifferential`
- `strengthState`

Those columns describe the intended rules state of the event. They are not recalculated from the HTML on-ice player list. That distinction is important because the official HTML report can list extra skaters around line changes, delayed penalties, bench situations, or reporting quirks.

## HTML Matching

The HTML report is not joined to the API feed only by clock. A single game can have multiple events in the same second, and a clock-only join would create bad matches. The package builds matching signatures from:

Signals used when matching HTML rows back to API events.
feature | why_it_matters
--- | ---
Period | Prevents same-clock matches across periods.
Elapsed seconds | Keeps the match near the official event time.
Event type | Separates faceoffs, shots, hits, penalties, goals, and stoppages.
Event-owning team | Prevents same-time events by opposite teams from swapping.
Primary actor | Anchors the event to the shooter, scorer, hitter, winner, or penalized player.
Secondary and tertiary actors | Disambiguates goals, blocks, faceoffs, hits, and penalties.
Local event order | Avoids backwards matches in duplicate clusters.

Once a match is accepted, the HTML on-ice IDs are written into scalar columns: `homeGoaliePlayerId`, `awayGoaliePlayerId`, `homeSkater1PlayerId`, `awaySkater1PlayerId`, `skater1PlayerIdFor`, `skater1PlayerIdAgainst`, and so on. Five skater slots are guaranteed; additional `skater6`, `skater7`, and later slots appear only when a game requires them.

## One-On-One Rows Are Special

Penalty shots and shootouts are not ordinary strength states. Rows such as `0101` and `1010` are constrained to the shooter and defending goalie. Even if the HTML report shows extra players, the public on-ice identity columns are kept to the one-on-one context because that is the play being recorded.

## Delayed-Penalty Backfill

Some delayed-penalty marker rows do not appear as ordinary event rows in the HTML report. When that happens, the package can backfill on-ice IDs from the nearest prior compatible event in the same period. The backfill is allowed only when the state signature is unchanged, the time gap is tiny, and the prior row already has a populated on-ice set. This is intentionally narrow.

## GC and WSC Differences

The public schemas are aligned, but not identical. GameCenter rows include GameCenter clip fields such as `highlightClip`, `discreteClip`, and `pptReplayUrl`. WSC rows include `utc` immediately after game elapsed seconds and omit the GC-only clip fields. That source-specific difference is intentional because the source feeds do not expose exactly the same metadata.

## Practical Checklist

Use this sequence when building event-level analysis:

    # Load cleaned event stream.
    pbp <- nhlscraper::gc_play_by_play(2023030417)

    # Add shift timing when fatigue or shift length matters.
    shifts <- nhlscraper::shift_chart(2023030417)
    pbp <- nhlscraper::add_shift_times(pbp, shifts)

    # Add movement context when previous-event geometry matters.
    pbp <- nhlscraper::add_deltas(pbp)

    # Score shots when chance quality matters.
    pbp <- nhlscraper::calculate_expected_goals(pbp)

Use `gc_play_by_play_raw()` or `wsc_play_by_play_raw()` only when you want to inspect the upstream feed itself. Use `gc_play_by_play()` or `wsc_play_by_play()` when you want the package’s public analysis schema.

## Key Takeaway

The pipeline keeps three ideas separate:

- API events define what happened and in what order.
- `situationCode` defines the intended manpower state.
- HTML reports define who was listed on the ice.

That separation is what makes the output practical for research while still being honest about where each piece of information came from.