Skip to contents

Load hoopR NBA Stats metric curves

Source: R/load_nba_stats_extra.R
load_nba_stats_metric_curves.Rd

Loads the nba_stats_metric_curves release: field-goal percentage by shot distance for the league, every team and every player of a season, computed from load_nba_stats_shots(). One row per entity per distance bucket (1-ft bins from 0 to 35 ft, then 35-50 and 50-95 ft; x_lo inclusive, x_hi exclusive) with its attempts, successes (makes) and rate; an empty bucket has no row. Regular-season and playoff shots only. entity_id / team_id are stats.nba.com ids as text; down and epa_per_att are always NA (the football columns of the cross-league contract).

Usage

load_nba_stats_metric_curves(
  seasons = most_recent_nba_stats_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Source

The nba_stats_metric_curves release: https://github.com/sportsdataverse/sportsdataverse-data/releases/tag/nba_stats_metric_curves, published by https://github.com/sportsdataverse/hoopR-nba-stats-data.

Arguments

seasons

A vector of 4-digit years – the season's START year (e.g. 2024 for the 2024-25 season). Published coverage starts at 1996 (1996-97). Pass seasons = TRUE for every published season.

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

A hoopR_data tibble with one row per entity per metric per bin.

col_nametypesdescription
seasonintegerEND year of the NBA season (2025 = 2024-25), the asset's own stamp: one more than the seasons argument.
entity_typecharacterWhich aggregate the row is: "league" (every counted attempt that season), "team" or "player" on metric_curves; always "player" on rolling_windows.
entity_idcharacterstats.nba.com id of the entity as TEXT – the team_id on a team row, the person_id on a player row, NA on the league row.
entity_namecharacterLabel for the entity: the team tricode ("GSW") on a team row, the shooter's name as the pbp ships it on a player row; NA on the league row.
team_idcharacterstats.nba.com team id (e.g. 1610612737 = Atlanta Hawks).
id_sourcecharacterNamespace of entity_id / team_id on this row – "nba_stats" here; the cross-league contract carries "espn", "gsis" and "wnba_stats" elsewhere.
metriccharacterWhat the row measures: "fg_pct_by_shot_distance" on metric_curves (field-goal percentage by shot distance in feet); "fg_pct" (window_unit "fga") or "fg3_pct" (window_unit "fg3a") on rolling_windows.
downintegerNull on every row: the second axis of the football-only success_by_down_distance curve, carried for the cross-league contract.
x_lonumericBucket lower edge in feet, inclusive: 1-ft bins from 0 to 35, then 35 and 50.
x_hinumericBucket upper edge in feet, exclusive: x_lo + 1 below 35 ft, then 50 and 95.
attemptsintegerField-goal attempts in the bucket – regular-season and playoff shots only (season_type_id 2 and 4; play-in and NBA Cup final games are not counted). An empty bucket is absent, never a zero row.
successesintegerMade field goals in the bucket.
ratenumericsuccesses / attempts, one exact division (no smoothing or prior).
epa_per_attnumericNull on every row: shots carry no EPA. Populated on the football twins of this contract.

See also

The publishing pipeline, https://github.com/sportsdataverse/hoopR-nba-stats-data.

Other NBA Stats loader functions: load_nba_stats_coaches(), load_nba_stats_draft_combine, load_nba_stats_game_matchups(), load_nba_stats_hustle, load_nba_stats_injury_report(), load_nba_stats_leaguedash(), load_nba_stats_matchups(), load_nba_stats_rolling_windows(), load_nba_stats_synergy()

Examples

# \donttest{
  try(load_nba_stats_metric_curves(seasons = most_recent_nba_stats_season()))
#> ───────────────────────────────────────────────────────────────── hoopR 3.2.0 ──
#> # A tibble: 8,123 × 14
#>    season entity_type entity_id entity_name team_id id_source metric  down  x_lo
#>     <int> <chr>       <chr>     <chr>       <chr>   <chr>     <chr>  <int> <dbl>
#>  1   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     0
#>  2   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     1
#>  3   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     2
#>  4   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     3
#>  5   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     4
#>  6   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     5
#>  7   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     6
#>  8   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     7
#>  9   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     8
#> 10   2027 league      NA        NA          NA      nba_stats fg_pc…    NA     9
#> # ℹ 8,113 more rows
#> # ℹ 5 more variables: x_hi <dbl>, attempts <int>, successes <int>, rate <dbl>,
#> #   epa_per_att <dbl>
# }