Title: Functions to Access Premier Hockey Federation and National Hockey League Play by Play Data
Version: 0.4.0
Description: A utility to scrape and load play-by-play data and statistics from the Premier Hockey Federation (PHF) https://www.premierhockeyfederation.com/, formerly known as the National Women's Hockey League (NWHL). Additionally, allows access to the National Hockey League's stats API https://www.nhl.com/.
License: MIT + file LICENSE
URL: https://fastRhockey.sportsdataverse.org/, https://github.com/sportsdataverse/fastRhockey
BugReports: https://github.com/sportsdataverse/fastRhockey/issues
Depends: R (≥ 4.0.0)
Imports: cli (≥ 3.0.0), data.table, dplyr, glue, httr, janitor, jsonlite, lubridate, magrittr, progressr (≥ 0.6.0), purrr (≥ 0.3.0), Rcpp, RcppParallel, rlang, rvest (≥ 1.0.0), stringr (≥ 1.3.0), tibble (≥ 3.0), tidyr (≥ 1.0.0)
Suggests: crayon (≥ 1.3.4), curl, DBI, furrr, future, ggplot2, ggrepel, qs (≥ 0.25.1), rmarkdown, RSQLite, stringi, stats, testthat, usethis (≥ 1.6.0), xml2 (≥ 1.3)
Encoding: UTF-8
RoxygenNote: 7.2.1
Config/testthat/edition: 3
LazyData: true
NeedsCompilation: no
Packaged: 2022-10-25 20:38:20 UTC; saiem
Author: Ben Howell [aut], Saiem Gilani [cre, aut], Alyssa Longmuir [ctb]
Maintainer: Saiem Gilani <saiem.gilani@gmail.com>
Repository: CRAN
Date/Publication: 2022-10-25 20:55:15 UTC

fastRhockey: Functions to Access Premier Hockey Federation and National Hockey League Play by Play Data

Description

logo

A utility to scrape and load play-by-play data and statistics from the Premier Hockey Federation (PHF) https://www.premierhockeyfederation.com/, formerly known as the National Women's Hockey League (NWHL). Additionally, allows access to the National Hockey League's stats API https://www.nhl.com/.

Author(s)

Maintainer: Saiem Gilani saiem.gilani@gmail.com

Authors:

Other contributors:

See Also

Useful links:

Load .csv / .csv.gz file from a remote connection

Description

This is a thin wrapper on data.table::fread

Usage

csv_from_url(...)

Arguments

...

passed to data.table::fread

Value

a dataframe as created by data.table::fread()

Data in the package for reference

Description

A dataset containing the full team names, abbreviations, colors & logos for all 32 NHL teams.

A dataset containing the full team names, abbreviations, colors & logos for all PHF teams.

Usage

nhl_team_logos

phf_team_logos

Format

A data frame with 32 rows and 11 variables:

full_team_name

full team name

team_abbr

NHL.com team abbreviation

team_nick

lowercase, no spaces team nickname

division

current NHL division

conference

current NHL conference

team_logo_espn

primary team logo from ESPN.com

team_color1

current primary team color

team_color2

current secondary team color

team_logo_alternate

alternate or throwback logo

team_color_alt1

alternate logo primary color

team_color_alt2

alternate logo secondary color

A data frame with 6 rows and 7 variables:

full_team_name

Full team name

team_abbr

PremierHockeyFederation.com team abbreviation

team_nick

Team Nickname

team_location

PHF team location

team_color1

Current primary team color. Full disclosure, I just color picked from the logos

team_color2

Current secondary team color. Full disclosure, I just color picked from the logos

team_logo

Primary team logo from fastRhockey data repository

Get ESPN NHL team names and IDs

Description

Get ESPN NHL team names and IDs

Usage

espn_nhl_teams()

Value

A teams data frame with the following columns:

col_name types
espn_team_id integer
abbreviation character
display_name character
short_name character
mascot character
nickname character
team character
color character
alternate_color character
logo character
logo_dark character
logos_href_3 character
logos_href_4 character

Author(s)

Saiem Gilani

Examples


  try(espn_nhl_teams())

Load fastRhockey NHL play-by-play

Description

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_nhl_pbp(
  seasons = most_recent_nhl_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given NHL seasons. (Min: 2011)

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_nhl_db()).

dbConnection

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

tablename

The name of the play by play data table within the database

Value

A dataframe

Examples


  try(load_nhl_pbp(2021))

Load fastRhockey NHL player box scores

Description

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_nhl_player_box(
  seasons = most_recent_nhl_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given NHL seasons. (Min: 2011)

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_nhl_db()).

dbConnection

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

tablename

The name of the player box data table within the database

Value

Returns a tibble

Examples


  try(load_nhl_player_box(2021))

Load fastRhockey NHL schedules

Description

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_nhl_schedule(
  seasons = most_recent_nhl_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given NHL seasons. (Min: 2011)

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_nhl_db()).

dbConnection

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

tablename

The name of the schedule data table within the database

Value

Returns a tibble

Examples


  try(load_nhl_schedule(2021))

Load fastRhockey NHL team box scores

Description

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_nhl_team_box(
  seasons = most_recent_nhl_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given NHL seasons. (Min: 2011)

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_nhl_db()).

dbConnection

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

tablename

The name of the team box data table within the database

Value

Returns a tibble

Examples


  try(load_nhl_team_box(2021))

Load fastRhockey PHF play-by-play

Description

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_phf_pbp(
  seasons = most_recent_phf_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given PHF seasons. (Min: 2011)

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_phf_db()).

dbConnection

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

tablename

The name of the play by play data table within the database

Value

A dataframe

Examples


  try(load_phf_pbp(2021))

Load fastRhockey PHF player box scores

Description

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_phf_player_box(
  seasons = most_recent_phf_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given PHF seasons. (Min: 2011)

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_phf_db()).

dbConnection

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

tablename

The name of the player box data table within the database

Value

Returns a tibble

Examples


  try(load_phf_player_box(2021))

Load fastRhockey PHF schedules

Description

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_phf_schedule(
  seasons = most_recent_phf_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given PHF seasons. (Min: 2011)

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_phf_db()).

dbConnection

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

tablename

The name of the schedule data table within the database

Value

Returns a tibble

Examples


  try(load_phf_schedule(2021))

Load fastRhockey PHF team box scores

Description

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_phf_team_box(
  seasons = most_recent_phf_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given PHF seasons. (Min: 2011)

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_phf_db()).

dbConnection

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

tablename

The name of the team box data table within the database

Value

Returns a tibble

Examples


  try(load_phf_team_box(2021))

Most Recent NHL Season

Description

Most Recent NHL Season

Usage

most_recent_nhl_season()

Value

Value for most recent NHL season

Most Recent NHL Season for NHL API

Description

Most Recent NHL Season for NHL API

Usage

most_recent_nhl_season_api_param()

Value

Value for most recent NHL season in the format of the NHL API

Most Recent PHF Season

Description

Most Recent PHF Season

Usage

most_recent_phf_season()

Value

Value for most recent NHL season

NHL Conferences

Description

Returns a table of current NHL conferences

Usage

nhl_conferences()

Value

Returns a data frame

Examples


  try(nhl_conferences())

NHL Conference Info

Description

Returns information on a conference by conference ID

Usage

nhl_conferences_info(conference_id)

Arguments

conference_id

Conference ID

Value

Returns a data frame

Examples


  try(nhl_conferences_info(conference_id = 7))

NHL Divisions

Description

Returns information on divisions

Usage

nhl_divisions()

Value

Returns a data frame

Examples


   try(nhl_divisions())

NHL Divisions Info

Description

Returns information on a division by division ID

Usage

nhl_divisions_info(division_id)

Arguments

division_id

Division ID

Value

Returns a data frame

Examples


  try(nhl_divisions_info(division_id=17))

NHL Draft

Description

Returns information on draft

Usage

nhl_draft()

Value

Returns a data frame: * year - * round - * pick_overall - * pick_in_round - * team_id - * team_name - * team_link - * prospect_id - * prospect_full_name - * prospect_link -

Examples


   try(nhl_draft())

NHL Draft Prospects

Description

Returns information on draft prospects

Usage

nhl_draft_prospects()

Value

Returns a tibble with the following columns:

col_name types
prospect_id integer
full_name character
link character
first_name character
last_name character
birth_date character
birth_city character
birth_country character
height character
weight integer
shoots_catches character
nhl_player_id integer
draft_status character
birth_state_province character
primary_position_code character
primary_position_name character
primary_position_type character
primary_position_abbreviation character
prospect_category_id integer
prospect_category_short_name character
prospect_category_name character
amateur_team_name character
amateur_team_link character
amateur_league_name character
amateur_league_link character
ranks_midterm integer
ranks_final_rank integer
ranks_draft_year integer

Examples


   try(nhl_draft_prospects())

NHL Draft Prospects Info

Description

Returns information on draft prospect for a given prospect id

Usage

nhl_draft_prospects_info(prospect_id)

Arguments

prospect_id

Prospect unique ID

Value

Returns a data frame: * prospect_id - * full_name - * link - * first_name - * last_name - * birth_date - * birth_city - * birth_country - * nationality - * height - * weight - * shoots_catches - * nhl_player_id - * primary_position_code - * primary_position_name - * primary_position_type - * primary_position_abbreviation - * prospect_category_id - * prospect_category_short_name - * prospect_category_name - * amateur_team_link - * amateur_league_link -

Examples


   try(nhl_draft_prospects_info(prospect_id=65242))

NHL Draft by Year

Description

Returns information on draft for a given year

Usage

nhl_draft_year(year)

Arguments

year

Draft year (XXXX)

Value

Returns a data frame: * year - * round - * pick_overall - * pick_in_round - * team_id - * team_name - * team_link - * prospect_id - * prospect_full_name - * prospect_link -

Examples


   try(nhl_draft_year(year=2020))

NHL Game Boxscore

Description

Returns information on game boxscore for a given game id

Usage

nhl_game_boxscore(game_id)

Arguments

game_id

Game unique ID

Value

Returns a named list of data frames: team_box, player_box, skaters, goalies, on_ice, on_ice_plus, penalty_box, scratches, team_coaches

Examples


   try(nhl_game_boxscore(game_id=2021020182))

NHL Game Content

Description

Returns game content for a given game ID

Usage

nhl_game_content(game_id)

Arguments

game_id

Game unique ID

Value

Returns a tibble

Examples


   try(nhl_game_content(game_id=2021020182))

NHL Game Feed

Description

Returns information on game feed for a given game id

Usage

nhl_game_feed(game_id)

Arguments

game_id

Game unique ID

Value

Returns a named list of data frames: all_plays, scoring_plays, penalty_plays, plays_by_period, current_play, linescore, decisions, team_box, player_box, skaters, goalies, on_ice, on_ice_plus, penalty_box, scratches, team_coaches

Examples


   try(nhl_game_feed(game_id=2018020561))

NHL Game Shifts

Description

Returns information on game shifts for a given game id

Usage

nhl_game_shifts(game_id)

Arguments

game_id

Game unique ID

Value

Returns a tibble

Examples


  try(nhl_game_shifts(game_id=2021020182))

NHL Player Info

Description

Returns player information for a given player ID

Usage

nhl_player_info(player_id)

Arguments

player_id

Player unique ID

Value

Returns a tibble

Examples


  try(nhl_player_info(player_id=8476899))

NHL Player Stats

Description

Returns player stats for a given player ID

Usage

nhl_player_stats(player_id)

Arguments

player_id

Player unique ID

Value

Returns a tibble

Examples


  try(nhl_player_stats(player_id=8476899))

NHL Schedule

Description

Returns NHL Schedule data

Usage

nhl_schedule(season = NULL, day = as.Date(Sys.Date(), "%Y-%m-%d"))

Arguments

season

NHL Season

day

Date

Value

Returns a tibble

Examples


  try(nhl_schedule(season = 2023))

NHL Teams

Description

Returns NHL Teams information

Usage

nhl_teams()

Value

Returns a tibble

Examples


  try(nhl_teams())

NHL Teams Info

Description

Returns NHL Teams information for a given team ID

Usage

nhl_teams_info(team_id)

Arguments

team_id

A unique team ID

Value

Returns a tibble

Examples


  try(nhl_teams_info(team_id = 14))

NHL Teams Roster

Description

Returns NHL Teams roster information for a given team ID

Usage

nhl_teams_roster(team_id, season = most_recent_nhl_season_api_param())

Arguments

team_id

A unique team ID

season

season in format XXXXYYYY

Value

Returns a tibble

Examples


  try(nhl_teams_roster(team_id = 14, season = 20202021))

NHL Teams Stats

Description

Returns NHL Teams stats information for a given team ID

Usage

nhl_teams_stats(team_id, season = most_recent_nhl_season_api_param())

Arguments

team_id

A unique team ID

season

season in format XXXXYYYY

Value

Returns a tibble

Examples


  try(nhl_teams_stats(team_id = 14))

PHF Game All

Description

phf_game_all: pull in the raw data for a game_id from the PHF/NWHL API

Usage

phf_game_all(game_id)

Arguments

game_id

The unique ID code for the game that you are interested in viewing the data for

Value

A named list of data frames: plays, team_box, skaters, goalies, game_details, scoring_summary, shootout_summary, penalty_summary, officials, team_staff, timeouts

Examples


  try(phf_game_all(game_id = 268127))

PHF Game Details

Description

phf_game_details: pull in the raw data for a game_id from the PHF/NWHL API

Usage

phf_game_details(game_id)

Arguments

game_id

The unique ID code for the game that you are interested in viewing the data for

Value

A data frame with game team details

Examples


  try(phf_game_details(game_id = 268078))

PHF Game Raw

Description

phf_game_raw: pull in the raw data for a game_id from the PHF/NWHL API

Usage

phf_game_raw(game_id)

Arguments

game_id

The unique ID code for the game that you are interested in viewing the data for

Value

A list of data frames

Examples


  try(phf_game_raw(game_id = 268078))

PHF Game Summary

Description

phf_game_summary: pull in the raw data for a game_id from the PHF/NWHL API

Usage

phf_game_summary(game_id)

Arguments

game_id

The unique ID code for the game that you are interested in viewing the data for

Value

A named list of data frames: scoring_summary,shootout_summary, penalty_summary, officials, team_staff, timeouts

Examples


  try(phf_game_summary(game_id = 268078))

PHF Player Leaderboards

Description

PHF Player Leaderboards

Usage

phf_leaders(player_type, season = 2021, season_type = "Regular Season")

Arguments

player_type

Player type: skaters, goalies

season

Season (YYYY) to pull the team stats from, the concluding year in XXXX-YY format

season_type

Season type: Regular Season or Playoffs

Value

A data frame of stat leaders

Examples


 try(phf_leaders(player_type = "skaters", season = 2022, season_type="Regular Season"))
 try(phf_leaders(player_type = "goalies", season = 2022, season_type="Regular Season"))

PHF League Information

Description

PHF League Information per year

Usage

phf_league_info(season = 2022)

Arguments

season

Season (YYYY) to pull the league info and IDs for. Season is the concluding year in XXXX-YY format

Value

A named list of data frames: seasons, divisions, teams, league, officials, brackets

Examples


  try(phf_league_info(season = 2021))

phf_pbp

Description

phf_pbp: pull in the raw data for a game_id from the PHF/NWHL API

Usage

phf_pbp(game_id)

Arguments

game_id

The unique ID code for the game that you are interested in viewing the data for

Value

A data frame of play by play information

Examples


  try(phf_pbp(game_id = 268127))

PHF Player Boxscore

Description

phf_player_box: loads the player boxscore

Usage

phf_player_box(game_id)

Arguments

game_id

The unique ID code for the game that you are interested in viewing the data for

Value

A named list of data frames: skaters, goalies

Examples


  try(phf_player_box(game_id = 420339))

PHF Player Stats

Description

phf_player_stats: loads the player stats

Usage

phf_player_stats(player_id)

Arguments

player_id

The unique ID code for the player that you are interested in viewing the data for

Value

A named list of data frames: career, game_log

Examples


  try(phf_player_stats(player_id = 431611))

PHF Schedule

Description

PHF Schedule lookup

Usage

phf_schedule(season)

Arguments

season

Season (YYYY) to pull the schedule from, the concluding year in XXXX-YY format

Value

A data frame with schedule data

Examples


  try(phf_schedule(season=2022))

PHF Standings

Description

phf_standings: pull in the standings data for a game_id from the PHF/NWHL API

Usage

phf_standings(season = most_recent_phf_season())

Arguments

season

Season (YYYY) to pull the standings from, the concluding year in XXXX-YY format

Value

A data frame of standings data

Examples


  try(phf_standings(season = most_recent_phf_season()))

PHF Team Boxscore

Description

phf_team_box: loads the team boxscore and shot/score data for a game into one data frame through just one function

Usage

phf_team_box(game_id)

Arguments

game_id

The unique ID code for the game that you are interested in viewing the data for

Value

A dataframe of team-level box score information

Examples


  try(phf_team_box(game_id = 420339))

PHF Team Roster

Description

PHF Team Roster lookup

Usage

phf_team_roster(team, season = most_recent_phf_season())

Arguments

team

Team name with nickname (e.g. Boston Pride, Buffalo Beauts)

season

Season (YYYY) to pull the team stats from, the concluding year in XXXX-YY format

Value

A named list of data frames: roster, team_staff

Examples


   try(phf_team_roster(team = "Boston Pride", season = 2022))

PHF Team Stats

Description

PHF Team Stats lookup

Usage

phf_team_stats(team, season = most_recent_phf_season())

Arguments

team

Team name with nickname (e.g. Boston Pride, Buffalo Beauts)

season

Season (YYYY) to pull the team stats from, the concluding year in XXXX-YY format

Value

A named list of data frames: skaters, goalies

Examples


  try(phf_team_stats(team = "Boston Pride", season = 2022))

Progressively

Description

This function helps add progress-reporting to any function - given function f() and progressr p(), it will return a new function that calls f() and then (on-exiting) will call p() after every iteration.

Usage

progressively(f, p = NULL)

Arguments

f

a function to add progressr functionality to.

p

a progressr function as created by progressr::progressor()

Details

This is inspired by purrr's safely, quietly, and possibly function decorators.

Value

a function that does the same as f but it calls p() after iteration.

Load .rds file from a remote connection

Description

Load .rds file from a remote connection

Usage

rds_from_url(url)

Arguments

url

a character url

Value

a dataframe as created by readRDS()

Update or create a fastRhockey NHL play-by-play database

Description

update_nhl_db() updates or creates a database with fastRhockey play by play data of all completed and available games since 2011.

Usage

update_nhl_db(
  dbdir = ".",
  dbname = "fastRhockey_db",
  tblname = "fastRhockey_nhl_pbp",
  force_rebuild = FALSE,
  db_connection = NULL
)

Arguments

dbdir

Directory in which the database is or shall be located

dbname

File name of an existing or desired SQLite database within dbdir

tblname

The name of the play by play data table within the database

force_rebuild

Hybrid parameter (logical or numeric) to rebuild parts of or the complete play by play data table within the database (please see details for further information)

db_connection

A DBIConnection object, as returned by DBI::dbConnect() (please see details for further information)

Details

This function creates and updates a data table with the name tblname within a SQLite database (other drivers via db_connection) located in dbdir and named dbname. The data table combines all play by play data for every available game back to the 2010 season and adds the most recent completed games as soon as they are available for fastRhockey.

The argument force_rebuild is of hybrid type. It can rebuild the play by play data table either for the whole fastRhockey era (with force_rebuild = TRUE) or just for specified seasons (e.g. force_rebuild = c(2019, 2020)). Please note the following behavior:

The parameter db_connection is intended for advanced users who want to use other DBI drivers, such as MariaDB, Postgres or odbc. Please note that the arguments dbdir and dbname are dropped in case a db_connection is provided but the argument tblname will still be used to write the data table into the database.

Value

Logical TRUE/FALSE

Update or create a fastRhockey PHF play-by-play database

Description

update_phf_db() updates or creates a database with fastRhockey play by play data of all completed and available games since 2011.

Usage

update_phf_db(
  dbdir = ".",
  dbname = "fastRhockey_db",
  tblname = "fastRhockey_phf_pbp",
  force_rebuild = FALSE,
  db_connection = NULL
)

Arguments

dbdir

Directory in which the database is or shall be located

dbname

File name of an existing or desired SQLite database within dbdir

tblname

The name of the play by play data table within the database

force_rebuild

Hybrid parameter (logical or numeric) to rebuild parts of or the complete play by play data table within the database (please see details for further information)

db_connection

A DBIConnection object, as returned by DBI::dbConnect() (please see details for further information)

Details

This function creates and updates a data table with the name tblname within a SQLite database (other drivers via db_connection) located in dbdir and named dbname. The data table combines all play by play data for every available game back to the 2016 season and adds the most recent completed games as soon as they are available for fastRhockey.

The argument force_rebuild is of hybrid type. It can rebuild the play by play data table either for the whole fastRhockey era (with force_rebuild = TRUE) or just for specified seasons (e.g. force_rebuild = c(2019, 2020)). Please note the following behavior:

The parameter db_connection is intended for advanced users who want to use other DBI drivers, such as MariaDB, Postgres or odbc. Please note that the arguments dbdir and dbname are dropped in case a db_connection is provided but the argument tblname will still be used to write the data table into the database.

Value

Logical TRUE/FALSE