Load hoopR NBA play-by-play

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_nba_pbp(
  seasons = most_recent_nba_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons: A vector of 4-digit years associated with given NBA seasons. (Min: 2002)
...: Additional arguments passed to an underlying function that writes the season data into a database (used by update_nba_db()).
dbConnection: A DBIConnection object, as returned by
tablename: The name of the play by play data table within the database

Value

Returns a tibble

col_name	types	description
id	numeric	Id.
sequence_number	character	Sequence number representing a shot-possession (V3 PBP).
type_id	integer	Type identifier (numeric).
type_text	character	Display text for the type field.
text	character	Text description of the play / record.
away_score	integer	Away team score at the time of the play.
home_score	integer	Home team score at the time of the play.
period_number	integer	Numeric period (1-4 for quarters; 5+ for OT).
period_display_value	character	Period display label (e.g. '1st Quarter', 'OT').
clock_display_value	character	Game clock display string (e.g. '8:32').
scoring_play	logical	TRUE if the play resulted in points scored.
score_value	integer	Point value of the play (2 / 3 / 1).
team_id	integer	Unique team identifier.
athlete_id_1	integer	Primary athlete identifier (e.g. shooter).
athlete_id_2	integer	Secondary athlete identifier (e.g. assister / fouler).
athlete_id_3	integer	Athlete id 3.
wallclock	character	Wallclock.
shooting_play	logical	TRUE if the play was a shooting attempt.
coordinate_x_raw	numeric	X coordinate as returned by the API before any adjustment.
coordinate_y_raw	numeric	Y coordinate as returned by the API before any adjustment.
season	integer	Season identifier (4-digit year or 'YYYY-YY' string).
season_type	integer	Season type (1=pre-season, 2=regular season, 3=postseason, 4=off-season for ESPN; or string label for WNBA Stats).
away_team_id	integer	Unique identifier for the away team.
away_team_name	character	Away team name.
away_team_mascot	character	Away team mascot.
away_team_abbrev	character	Away team three-letter abbreviation.
away_team_name_alt	character	Alternate away team name.
home_team_id	integer	Unique identifier for the home team.
home_team_name	character	Home team name.
home_team_mascot	character	Home team mascot.
home_team_abbrev	character	Home team three-letter abbreviation.
home_team_name_alt	character	Alternate home team name.
home_team_spread	numeric	Home team's point spread.
game_spread	numeric	Game spread (signed; positive = home favored).
home_favorite	logical	TRUE if the home team is the betting favorite.
game_spread_available	logical	TRUE if a point spread was available.
game_id	integer	Unique game identifier.
qtr	integer	Quarter (1-4) or OT period (5+).
time	character	Time / clock value.
clock_minutes	integer	Clock minutes split out for convenience.
clock_seconds	numeric	Clock seconds split out for convenience.
half	character	Half of the game (1 or 2).
game_half	character	Half of the game (1 or 2).
lead_qtr	integer	Quarter lead (the next-play's quarter).
lead_game_half	character	Half lead (the next-play's half).
start_quarter_seconds_remaining	integer	Seconds remaining in the period at the start of the play.
start_half_seconds_remaining	integer	Seconds remaining in the half at the start of the play.
start_game_seconds_remaining	integer	Seconds remaining in the game at the start of the play.
game_play_number	integer	Sequential play number within the game.
end_quarter_seconds_remaining	integer	Seconds remaining in the period at the end of the play.
end_half_seconds_remaining	integer	Seconds remaining in the half at the end of the play.
end_game_seconds_remaining	integer	Seconds remaining in the game at the end of the play.
period	integer	Period of the game (1-4 quarters; 5+ for OT).
lag_qtr	integer	Quarter lag (the previous-play's quarter).
lag_game_half	character	Half lag (the previous-play's half).
coordinate_x	numeric	X coordinate on the court (half-court layout).
coordinate_y	numeric	Y coordinate on the court (half-court layout).
game_date	Date	Game date (YYYY-MM-DD).
game_date_time	POSIXct	Game start date/time (ISO 8601).
type_abbreviation	character	Type abbreviation.

Examples

# \donttest{
load_nba_pbp(seasons = most_recent_nba_season())
#> ── ESPN NBA Play-by-Play from hoopR data repository ───────────── hoopR 3.1.0 ──
#> ℹ Data updated: 2026-05-29 19:12:53 UTC
#> # A tibble: 639,462 × 64
#>    game_play_number        id sequence_number type_id type_text text  away_score
#>               <int>     <dbl>           <int>   <int> <chr>     <chr>      <int>
#>  1                1   4.02e 9               4     615 Jumpball  Chet…          0
#>  2                2   4.02e 9               7      92 Jump Shot Juli…          0
#>  3                3   4.02e 9               9     130 Floating… Isai…          2
#>  4                4   4.02e10              11      92 Jump Shot Vict…          2
#>  5                5   4.02e10              13     128 Driving … Vict…          2
#>  6                6   4.02e10              14     156 Offensiv… Isai…          2
#>  7                7   4.02e10              19      92 Jump Shot Chet…          2
#>  8                8   4.02e10              20     155 Defensiv… Spur…          2
#>  9                9   4.02e10              15      92 Jump Shot Vict…          2
#> 10               10   4.02e10              17      16 Full Tim… Thun…          2
#> # ℹ 639,452 more rows
#> # ℹ 57 more variables: home_score <int>, period_number <int>,
#> #   period_display_value <chr>, clock_display_value <chr>, scoring_play <lgl>,
#> #   score_value <int>, team_id <int>, athlete_id_1 <int>, athlete_id_2 <int>,
#> #   athlete_id_3 <int>, wallclock <chr>, shooting_play <lgl>,
#> #   coordinate_x_raw <dbl>, coordinate_y_raw <dbl>, points_attempted <int>,
#> #   short_description <chr>, game_id <int>, season <int>, season_type <int>, …
# }

Usage

Arguments

Value

See also

Examples