cfbfastR

• load_cfb_ratings(), load_cfb_ratings_weekly(), load_cfb_fpi_weekly(), load_cfb_team_summaries_weekly(), load_cfb_team_talent(), load_cfb_recruits(), load_cfb_recruiting_proj(), load_cfb_returning_production() — season/weekly ratings, talent, and recruiting datasets.
• load_cfb_schedule_crosswalk(), load_cfb_teams_crosswalk(), load_cfb_rosters_crosswalk() — CFBD/ESPN id crosswalks.
• load_ncaa_mfb_*() — 10 loaders for the stats.ncaa.org men's football family (covers FCS and lower divisions): pbp, pbp_cfbfastr (the cfbfastR-schema-shaped variant), drives, linescore, officials, player_stats, rosters, schedule, team_stats, teams.
• New internal parquet_from_url() helper backs the parquet-only datasets (requires the suggested arrow package).

**Which play-by-play loader do I want?** Nothing is deprecated — the classic

functions are unchanged; the new families add sources:

• load_cfb_pbp() (unchanged) — the classic cfbfastR EPA/WPA play-by-play, FBS 2014+.
• load_espn_cfb_pbp() (new) — the ESPN-derived play-by-play (469 columns, EPA/WPA + participant ids), 2004+.
• load_ncaa_mfb_pbp() (new) — stats.ncaa.org play-by-play incl. FCS and lower divisions, 2013+; load_ncaa_mfb_pbp_cfbfastr() is the same data reshaped onto cfbfastR pbp column conventions for cross-source binds.

This release adds a 65-function ESPN college-football API layer, expanding cfbfastR's ESPN surface from 8 wrappers to 73. The new wrappers expose ESPN's core-v2 endpoints in ESPN's own ID space — complementary to the CollegeFootballData (cfbd_*) wrappers, and the natural join partners for espn_cfb_pbp() / espn_cfb_scoreboard(). Every wrapper was verified live against the 2023, 2024, and 2025 seasons.

**Naming alignment with the sportsdataverse convention (this dev cycle, never on CRAN):** espn_cfb_player_statistics() is renamed to espn_cfb_player_career_stats() (the core-v2 /athletes/{id}/statistics career view, matching hoopR/wehoop/sportsdataverse-py). New espn_cfb_player_stats_v3() wraps the comprehensive web-common-v3 /athletes/{id}/stats payload (all categories, long format) — the _v3 companion to espn_cfb_player_stats() (core-v2 season statistics).

New Fox Sports API wrappers (fox_cfb_*)

A read-only Fox Sports "Bifrost" college-football layer (api.foxsports.com/bifrost/v1/cfb/*), complementary to the espn_cfb_* and cfbd_* families. Eight wrappers flatten Fox's layout-oriented JSON (sections → tables → rows → cells) into tidy cfbfastR-tagged tibbles. Reverse-engineering notes and an OpenAPI 3.1 spec live in the sdv-internal-refs repo. Verified live against the 2025 season.

• fox_cfb_pbp() — game play-by-play (quarters → drives → plays), one row per play.
• fox_cfb_boxscore() — per-team player stat tables, tidy long (one row per player-stat).
• fox_cfb_odds() — matchup six-pack (spread / to-win / total) per team.
• fox_cfb_team_roster() — roster by position group, one row per player.
• fox_cfb_team_stats() — team stat leaders by category.
• fox_cfb_team_gamelog() — per-game team stats, tidy long (game × category × stat), each game keyed to its Fox event id.
• fox_cfb_standings() — a team's conference standings table.
• fox_cfb_league_leaders() — statistical leaderboards by category (stats-con).

New ESPN wrappers — football-specific metrics

• espn_cfb_powerindex() — ESPN's College Football Power Index (FPI): every predictive metric and efficiency component, in long format.
• espn_cfb_qbr() — Total Quarterback Rating (QBR) and the full set of clutch-weighted EPA components, one row per qualified passer.
• espn_cfb_futures() — the season betting-futures board (national championship, conference, and award markets) with each sportsbook's American odds.
• espn_cfb_recruits() — ESPN's recruiting board for a class, one row per recruit with grade, position/state/region rank, committed school, and hometown.

New ESPN wrappers — players

• espn_cfb_players(), espn_cfb_player(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_statistics(), espn_cfb_player_splits(), espn_cfb_player_overview(), and espn_cfb_player_seasons() — player index, biographical detail, per-game logs, season statistics, and split breakdowns. The season-level wrappers resolve athlete_id to human-readable name/position columns via an athlete_detail argument.

New ESPN wrappers — teams

• espn_cfb_teams(), espn_cfb_team(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_team_record(), and espn_cfb_team_leaders() — team index, team-in-season detail, roster, schedule, records, and statistical leaders.
• espn_cfb_team_ats(), espn_cfb_team_powerindex(), espn_cfb_team_events(), espn_cfb_team_ranks(), espn_cfb_team_awards(), and espn_cfb_team_coaches() — team against-the-spread records, single-team power index, season event log, poll-rank history, player awards, and coaching staff.

New ESPN wrappers — game detail

• espn_cfb_game_teams(), espn_cfb_game_team_linescores(), espn_cfb_game_team_leaders(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), and espn_cfb_game_team_records() — per-game team breakdowns.
• espn_cfb_game_odds(), espn_cfb_game_broadcasts(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_powerindex(), and espn_cfb_game_pbp() — per-game odds, broadcasts, pre-game predictor, live win-probability, matchup power index, and play-by-play.
• espn_cfb_game_drives(), espn_cfb_game_drive_plays(), espn_cfb_game_play(), espn_cfb_game_leaders(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_player_statistics(), and espn_cfb_game_player_box() — drive log, drive-scoped plays, single-play detail, game statistical leaders, situation, status, and per-player game box lines.
• The play-level wrappers (espn_cfb_game_pbp(), espn_cfb_game_drive_plays(), espn_cfb_game_play()) extract every field ESPN returns for a play and expose its nested child collections through opt-in parameters: participants ("none"/"wide"/"long") and participants_list surface per-play athlete involvement (passer, rusher, tackler, …), and team_participants / team_participants_list surface the offense/defense team participants — "wide" modes pivot to one row per play, the *_list flags keep the raw detail as a list-column.
• espn_cfb_game_team_records(detail = TRUE) unpacks each record's full statistic breakdown; espn_cfb_game_odds(line_history = TRUE) returns the open/close/current line-movement history. Roster and player-stats wrappers join ESPN position-catalog detail when position_detail = TRUE.
• espn_cfb_game_drives() gains a plays argument — "list" nests each drive's plays (full play-by-play schema, with the participant pass-through options) as a list-column, "expand" returns the flat one-row-per-play table with drive_* context columns. The new espn_cfb_unnest_plays() performs the same drives-to-play-by-play transform on an already-fetched nested frame.
• The game wrappers join human-readable team detail when team_detail = TRUE (default): every team-id column (team_id, home_team_id, start_team_id, leader_team_id, …) gains sibling *_name, *_abbreviation, *_location, *_display_name, *_color, *_logo_href, … columns from the ESPN team catalog. espn_cfb_game_teams(format = "wide") collapses the two competitor rows into a single per-game row with home_* / away_* columns for direct joining onto one-row-per-game tables.
• espn_cfb_pbp_v2() — a core-v2-sourced successor to espn_cfb_pbp(): assembles play-by-play in one structured request (vs. the legacy site-v2 summary parse) and, with epa_wpa = TRUE, runs cfbfastR's full EPA/WPA model pipeline — producing EPA/WPA columns identical to the legacy modeled feed.

New ESPN wrappers — catalogs and season metadata

• espn_cfb_seasons(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_groups(), and espn_cfb_standings() — season structure, conferences, and standings.
• espn_cfb_coaches(), espn_cfb_coach(), espn_cfb_venues(), espn_cfb_positions(), espn_cfb_awards(), espn_cfb_rankings(), and espn_cfb_week_rankings() — league catalogs and poll rankings.
• espn_cfb_coach_record(), espn_cfb_franchises(), espn_cfb_franchise(), espn_cfb_venue(), espn_cfb_position(), and espn_cfb_award() — coach season win/loss records, the league franchise catalog, and single-record venue / position / award detail.

New Yahoo Sports wrappers

• Added Yahoo Sports college football wrappers: yahoo_cfb_player_season_stats(), yahoo_cfb_team_season_stats(), yahoo_cfb_player_season_stats_legacy(), yahoo_cfb_team_season_stats_legacy(), yahoo_cfb_scoreboard(), and yahoo_cfb_boxscore() (scaffold), wrapping Yahoo's shangrila stats graph and editorial feed.

New CollegeFootballData wrappers

• cfbd_betting_ats() — season against-the-spread (ATS) summary records by team, wrapping the CollegeFootballData /teams/ats endpoint.
• cfbd_stats_game_havoc() — per-game havoc statistics (total / front-seven / defensive-back havoc events and rates, offense and defense), wrapping the CollegeFootballData /stats/game/havoc endpoint.
• cfbd_pbp_data_v2() is a new public function: a modular successor to cfbd_pbp_data() that runs the same EPA/WPA pipeline through a single shared engine (.run_epa_wpa()) and a canonical play-type taxonomy (.pbp_play_types()). The legacy cfbd_pbp_data() is unchanged.
• espn_cfb_pbp_v2() now sources play-by-play and meta through the shared engine, requests participants = "wide" and team_participants = "wide" from espn_cfb_game_drives(), and adds the meta columns home_team_name, home_team_color, home_team_alternate_color, home_team_rank (and away_*) via the new .espn_pbp_game_meta() bridge. Output is a strict superset of legacy espn_cfb_pbp() on the meta columns.

Play-by-play engine — v2 is now the default

• **cfbd_pbp_data() and espn_cfb_pbp() now run the v2 engine by default.** Both gain penalty enforcement resolution, ESPN-resolved player names, the *_player_id columns and the output tier selector without a code change. The previous behaviour is one argument away — engine = "legacy" per call, or options(cfbfastR.pbp_engine = "legacy") for a session — and a once-per-session message says so. engine = "auto" continues to mean "whatever this release considers current". tests/testthat/test-pbp_equivalence.R asserts v2 reproduces the legacy frames column-for-column, with an explicit allow-list of intentional deltas.
• Play-by-play now overwrites the regex-extracted *_player_name values with ESPN's own participants[] names (2014 onward), so a capture that trailed narration ("Rod Smith 3 Yd"), abbreviated, or carried a team code becomes the real name. Ported from sportsdataverse's CFBPlayProcess.__join_participants and verified against a 60-game offline oracle (5 games from each of 2004, 2006, 2008, 2010, 2013, 2014, 2017, 2019, 2020, 2021, 2023, 2025, including the postseason): 1,236 of 9,545 × 11 name cells change, with zero divergence from the Python. The stage runs **before** id resolution, so the roster matcher gets a clean key rather than narration.
• espn_cfb_pbp_v2() gains resolve_names (default TRUE). When epa_wpa = TRUE it spends one memoised request per game on ESPN's play-by-play sidecar, which supplies (a) full athlete names — "Jalen Mitchell" rather than the core-v2 roster's "J. Mitchell" — and (b) the per-player box score as a second identity source. The box score is the *only* identity source on the large share of games where ESPN 404s the roster resource; adding it cuts *_player_id divergence from sdv-py from 52/163,656 to 26/166,482 — fewer mismatches over more plays. Set resolve_names = FALSE for a bulk sweep that would rather have the short names than the requests.
• Play-by-play now resolves **which team** each event belongs to, adding 30 columns cfbfastR could not previously produce: the special-teams flip (kicking_team, return_team, punt_return_team, kick_return_team, fg_team, punt_team), the event-credit columns (sack_team, interception_team, pass_breakup_team, forced_fumble_team, fumble_recovery_team), the fumble/recovery chain (fumble_or_muff, fumbling_team, recovery_team, recovery_team_2), the per-side turnover model (is_turnover, turnover_team, int_turnover, pos_fumble_lost, def_fumble_lost, is_pos_team_turnover, is_def_pos_team_turnover, is_st_turnover, is_blocked_punt_turnover, is_blocked_fg_turnover), penalty attribution (penalized_team, penalty_team_id, penalty_yards_signed) and the id-keyed pos_team_id / def_pos_team_id. Ported from sportsdataverse's CFBPlayProcess.__add_attribution_cols and verified against the 60-game offline oracle at zero divergence over 267,260 cells. The turnover flags are framed **per side** because one play can lose the ball twice — the offense fumbles, the defense recovers and fumbles back — and a single boolean cannot say that both teams turned it over. Blocked punts and blocked field goals deliberately stay *out* of is_turnover: ESPN's official box counts only giveaways, so folding them in would break the reconciliation against it. They get their own flags instead. On the ESPN path, ESPN's own per-play turnover flag is preserved as **espn_is_turnover** rather than being silently overwritten. The two legitimately differ — ESPN's also fires on blocked kicks.
• Play-by-play gains air_yards, air_yardsToEndzone and yards_after_catch, splitting a completed pass into the yards thrown and the yards run after the catch. ESPN states the catch point as "caught at OU35"; the stated yard line belongs to whichever team owns that side of the field, so the abbreviation is sided against the possessing and defending teams with the same prefix-tolerant matcher the recovery and penalty teams use. yards_after_catch is computed for completions only. Ported from sportsdataverse's CFBPlayProcess.__add_air_yards_cols. **One deliberate divergence from the Python:** sdv-py's pattern has no article, so it resolves "caught at OU35" and silently drops "thrown to the ARK30". Both forms occur in ESPN's text — and cfbfastR's core-v2 feed uses the article form almost exclusively, where a verbatim port would have matched nothing at all. This implementation accepts both. The parity test is partitioned accordingly: exact agreement on the 137 oracle rows sdv-py resolves, plus an explicit assertion that the 7 article-form rows it drops are recovered here.
• Play-by-play gains pass_depth, pass_direction, rush_direction and qb_hurry, read from the play text ("short"/"deep", "left"/"middle"/"right", and ESPN's "QB hurried by" annotation). Null where ESPN omits the phrase — sacks, screens, and older seasons that never annotated depth or direction.
• espn_cfb_pbp_v2() now refuses to run the EPA/WPA models on an obviously malformed feed — no plays, or implausibly few or many for a game that has finished — and returns the unmodeled frame with a warning instead. A truncated game models perfectly cleanly and produces EPA, drive results and a box score that all