Merge pull request #7 from saiemgilani/doc-orgs

Doc orgs, it is just docs really, some renaming

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: cfbfastR
 Title: Functions to Access College Football Play by Play Data
-Version: 1.1.0
+Version: 1.2.0
 Authors@R: 
     c(person(given = "Saiem",
              family = "Gilani",

NAMESPACE

@@ -25,9 +25,11 @@ export(cfbd_metrics_wp_pregame)
 export(cfbd_pbp_data)
 export(cfbd_play_stats_player)
 export(cfbd_play_stats_types)
+export(cfbd_play_types)
 export(cfbd_player_info)
 export(cfbd_player_returning)
 export(cfbd_player_usage)
+export(cfbd_plays)
 export(cfbd_rankings)
 export(cfbd_ratings_sp)
 export(cfbd_ratings_sp_conference)

NEWS.md

@@ -1,5 +1,24 @@
 # cfbfastR 
 
+### **v1.2.0**
+#### **Add significant documentation to the package**
+
+* Added mini-vignettes pertaining to CFB Data functionality:   
+  - [```cfbd_betting```](https://saiemgilani.github.io/cfbfastR/articles/cfbd_betting.html),
+  - [```cfbd_games```](https://saiemgilani.github.io/cfbfastR/articles/cfbd_games.html),
+  - [```cfbd_plays```](https://saiemgilani.github.io/cfbfastR/articles/cfbd_plays.html),    
+  - [```cfbd_recruiting```](https://saiemgilani.github.io/cfbfastR/articles/cfbd_recruiting.html),    
+  - [```cfbd_stats```](https://saiemgilani.github.io/cfbfastR/articles/cfbd_stats.html), 
+  - [```cfbd_teams```](https://saiemgilani.github.io/cfbfastR/articles/cfbd_teams.html)
+
+* [Introductory vignette stub](https://saiemgilani.github.io/cfbfastR/articles/intro.html) added
+
+#### **ESPN/CFBD metrics function variable return standardization**
+
+* Change `id` variable to `team_id` in [```espn_ratings_fpi()```](https://saiemgilani.github.io/cfbfastR/reference/espn_ratings.html)
+* Changed `espn_game_id` variable to `game_id` in [```espn_metrics_wp()```](https://saiemgilani.github.io/cfbfastR/reference/espn_metrics.html), corrected the `away_win_percentage` calculation and added `tie_percentage` to the returns.
+* Change `id` variable to `athlete_id` in [```cfbd_metrics_ppa_players_season()```](https://saiemgilani.github.io/cfbfastR/reference/cfbd_metrics.html)
+
 ### **v1.1.0**
 #### **Add loading from Data Repository functionality**
 

R/helper_database_functions.R → R/cfb_pbp.R

@@ -1,5 +1,89 @@
-#' Update or Create a cfbfastR Play-by-Play Database
-#' `update_cfb_db` updates or creates a database with `cfbfastR`
+#' Load cfbfastR play-by-play
+#' @name load_cfb_pbp
+NULL
+#' @title Load cleaned pbp from the data repo
+#' @rdname load_cfb_pbp
+#' @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
+#' @param seasons A vector of 4-digit years associated with given College Football seasons.
+#' @param ... Additional arguments passed to an underlying function that writes
+#' the season data into a database (used by \code{\link[=update_cfb_db]{update_cfb_db()}}).
+#' @param qs Wheter to use the function [qs::qdeserialize()] for more efficient loading.
+#' @export
+load_cfb_pbp <- function(seasons, ..., qs = FALSE) {
+  dots <- rlang::dots_list(...)
+
+  if (all(c("dbConnection", "tablename") %in% names(dots))) in_db <- TRUE else in_db <- FALSE
+
+  if (isTRUE(qs) && !is_installed("qs")) {
+    usethis::ui_stop("Package {usethis::ui_value('qs')} required for argument {usethis::ui_value('qs = TRUE')}. Please install it.")
+  }
+
+  most_recent <- most_recent_season()
+
+  if (!all(seasons %in% 2014:most_recent)) {
+    usethis::ui_stop("Please pass valid seasons between 2014 and {most_recent}")
+  }
+
+  if (length(seasons) > 1 && is_sequential() && isFALSE(in_db)) {
+    usethis::ui_info(c(
+      "It is recommended to use parallel processing when trying to load multiple seasons.",
+      "Please consider running {usethis::ui_code('future::plan(\"multisession\")')}!",
+      "Will go on sequentially..."
+    ))
+  }
+
+
+  p <- progressr::progressor(along = seasons)
+
+  if (isFALSE(in_db)) {
+    out <- furrr::future_map_dfr(seasons, cfb_single_season, p = p, qs = qs)
+  }
+
+  if (isTRUE(in_db)) {
+    purrr::walk(seasons, cfb_single_season, p, ..., qs = qs)
+    out <- NULL
+  }
+
+  return(out)
+}
+
+cfb_single_season <- function(season, p, dbConnection = NULL, tablename = NULL, qs = FALSE) {
+  if (isTRUE(qs)) {
+
+    .url <- glue::glue("https://github.com/saiemgilani/cfbfastR-data/blob/master/data/rds/pbp_players_pos_{season}.qs")
+    pbp <- qs_from_url(.url)
+
+  }
+  if (isFALSE(qs)) {
+    .url <- glue::glue("https://raw.githubusercontent.com/saiemgilani/cfbfastR-data/master/data/rds/pbp_players_pos_{season}.rds")
+    con <- url(.url)
+    pbp <- readRDS(con)
+    close(con)
+  }
+  if (!is.null(dbConnection) && !is.null(tablename)) {
+    DBI::dbWriteTable(dbConnection, tablename, pbp, append = TRUE)
+    out <- NULL
+  } else {
+    out <- pbp
+  }
+  p(sprintf("season=%g", season))
+  return(out)
+}
+
+# load games file
+load_games <- function(){
+  .url <- "https://raw.githubusercontent.com/saiemgilani/cfbfastR-data/master/data/games_in_data_repo.csv"
+  con <- url(.url)
+  dat <- utils::read.csv(con)
+  # close(con)
+  return (dat)
+}
+
+#' @name update_cfb_db
+#' @aliases update_cfb_db cfb_db cfb database cfb_pbp_db
+#' @title Update or Create a cfbfastR Play-by-Play Database
+#' @description `update_cfb_db()` updates or creates a database with `cfbfastR`
 #' play by play data of all completed games since 2014.
 #'
 #' @details This function creates and updates a data table with the name `tblname`
@@ -38,10 +122,10 @@
 #' [DBI::dbConnect()] (please see details for further information)
 #' @export
 update_cfb_db <- function(dbdir = ".",
-                      dbname = "cfb_pbp_db",
-                      tblname = "cfbfastR_pbp",
-                      force_rebuild = FALSE,
-                      db_connection = NULL) {
+                          dbname = "cfb_pbp_db",
+                          tblname = "cfbfastR_pbp",
+                          force_rebuild = FALSE,
+                          db_connection = NULL) {
 
   # rule_header("Update cfbfastR Play-by-Play Database")
 

R/cfbd_betting_lines.R → R/cfbd_betting.R

@@ -1,13 +1,16 @@
-#' CFBD Betting Endpoint
-#'
 #' @name cfbd_betting
-NULL
-#' Get Betting information from games
-#'
-#' @rdname cfbd_betting
+#' @aliases betting cfbd_betting cfbd_betting_lines
+#' @title CFBD Betting Lines Endpoint
+#' @description Get betting lines information from games
+#' @examples
+#' \donttest{
+#'    cfbd_betting_lines(year = 2018, week = 12, team = "Florida State")
 #'
+#'    # 7 OTs LSU at TAMU
+#'    cfbd_betting_lines(year = 2018, week = 13, team = "Texas A&M", conference = "SEC")
+#' }
 #' @param game_id (\emph{Integer} optional): Game ID filter for querying a single game
-#' Can be found using the \code{\link[cfbfastR:cfbd_game_info]{cfbfastR::cfbd_game_info()}} function
+#' Can be found using the [cfbd_game_info()] function
 #' @param year (\emph{Integer} required): Year, 4 digit format(\emph{YYYY})
 #' @param week (\emph{Integer} optional): Week - values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier)
 #' @param season_type (\emph{String} default regular): Select Season Type: regular or postseason
@@ -16,26 +19,25 @@ NULL
 #' @param away_team (\emph{String} optional): Away D-I Team
 #' @param conference (\emph{String} optional): Conference abbreviation - Select a valid FBS conference\cr
 #' Conference abbreviations P5: ACC, B12, B1G, SEC, PAC\cr
-#' Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC\cr
+#' Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC
 #' @param line_provider (\emph{String} optional): Select Line Provider - Caesars, consensus, numberfire, or teamrankings
 #' @param verbose Logical parameter (TRUE/FALSE, default: FALSE) to return warnings and messages from function
-#'
 #' @return Betting information for games with the following columns:
 #' \describe{
-#'   \item{\code{game_id}}{integer. Unique game identifier - `game_id`.}
-#'   \item{\code{season}}{integer. Season parameter.}
-#'   \item{\code{season_type}}{character. Season Type (regular, postseason, both).}
-#'   \item{\code{week}}{integer. Week, values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier).}
-#'   \item{\code{home_team}}{character. Home D-I Team.}
-#'   \item{\code{home_conference}}{character. Home D-I Conference.}
-#'   \item{\code{home_score}}{integer. Home Score.}
-#'   \item{\code{away_team}}{character. Away D-I Team.}
-#'   \item{\code{away_conference}}{character. Away D-I Conference.}
-#'   \item{\code{away_score}}{integer. Away Score.}
-#'   \item{\code{provider}}{character. Line provider.}
-#'   \item{\code{spread}}{character. Spread for the game.}
-#'   \item{\code{formatted_spread}}{character. Formatted spread for the game.}
-#'   \item{\code{over_under}}{character. Over/Under for the game.}
+#'   \item{`game_id`:integer.}{Unique game identifier - `game_id`.}
+#'   \item{`season`:integer.}{Season parameter.}
+#'   \item{`season_type`:character.)}{Season Type (regular, postseason, both}
+#'   \item{`week`:integer.}{Week, values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier).}
+#'   \item{`home_team`:character.}{Home D-I Team.}
+#'   \item{`home_conference`:character.}{Home D-I Conference.}
+#'   \item{`home_score`:integer.}{Home Score.}
+#'   \item{`away_team`:character.}{Away D-I Team.}
+#'   \item{`away_conference`:character.}{Away D-I Conference.}
+#'   \item{`away_score`:integer.}{Away Score.}
+#'   \item{`provider`:character.}{Line provider.}
+#'   \item{`spread`:character.}{Spread for the game.}
+#'   \item{`formatted_spread`:character.}{Formatted spread for the game.}
+#'   \item{`over_under`:character.}{Over/Under for the game.}
 #' }
 #' @source \url{https://api.collegefootballdata.com/lines}
 #' @keywords Betting Lines
@@ -49,13 +51,6 @@ NULL
 #' @importFrom dplyr filter as_tibble rename
 #' @importFrom tidyr unnest
 #' @export
-#' @examples
-#' \donttest{
-#'    cfbd_betting_lines(year = 2018, week = 12, team = "Florida State")
-#'
-#'    # 7 OTs LSU at TAMU
-#'    cfbd_betting_lines(year = 2018, week = 13, team = "Texas A&M", conference = "SEC")
-#' }
 #'
 cfbd_betting_lines <- function(game_id = NULL,
                                year = NULL,

R/cfbd_coaches.R

@@ -1,33 +1,38 @@
-#' Coach Information Search
-#'
+#' 
+#' @name cfbd_coaches
+#' @aliases coaches cfbd_coaches
+#' @title CFBD Coaches Endpoint
+#' @description Coach Information Search
 #' A coach search function which provides coaching records and school history for a given coach
-#'
+#' ```r
+#' cfbd_coaches(first = "Nick", last = "Saban", team = "alabama")  
+#' ````
 #' @param first (\emph{String} optional): First name for the coach you are trying to look up
 #' @param last (\emph{String} optional): Last name for the coach you are trying to look up
 #' @param team (\emph{String} optional): Team - Select a valid team, D1 football
 #' @param year (\emph{Integer} optional): Year, 4 digit format (\emph{YYYY}).
 #' @param min_year (\emph{Integer} optional): Minimum Year filter (inclusive), 4 digit format (\emph{YYYY}).
 #' @param max_year (\emph{Integer} optional): Maximum Year filter (inclusive), 4 digit format (\emph{YYYY})
 #' @param verbose Logical parameter (TRUE/FALSE, default: FALSE) to return warnings and messages from function
-#' @return \code{\link[cfbfastR:cfbd_coaches]{cfbfastR::cfbd_coaches()}} - A data frame with coach information with the following columns:
+#' @return [cfbd_coaches()] - A data frame with coach information with the following columns:
 #' \describe{
-#'   \item{\code{first_name}}{character. First name of coach.}
-#'   \item{\code{last_name}}{character. Last name of coach.}
-#'   \item{\code{school}}{character. School of coach.}
-#'   \item{\code{year}}{integer. Season of record.}
-#'   \item{\code{games}}{integer. Games as coach.}
-#'   \item{\code{wins}}{integer. Wins for the season.}
-#'   \item{\code{losses}}{integer. Losses for the season.}
-#'   \item{\code{ties}}{integer. Ties for the season.}
-#'   \item{\code{preseason_rank}}{integer. Preseason rank for the school of coach.}
-#'   \item{\code{postseason_rank}}{integer. Postseason rank for the school of coach.}
-#'   \item{\code{srs}}{character. Simple Rating System adjustment for team.}
-#'   \item{\code{sp_overall}}{character. Bill Connelly's SP+ overall for team.}
-#'   \item{\code{sp_offense}}{character. Bill Connelly's SP+ offense for team.}
-#'   \item{\code{sp_defense}}{character. Bill Connelly's SP+ defense for team.}
+#'   \item{`first_name`:character.}{First name of coach.}
+#'   \item{`last_name`:character.}{Last name of coach.}
+#'   \item{`school`:character.}{School of coach.}
+#'   \item{`year`:integer.}{Season of record.}
+#'   \item{`games`:integer.}{Games as coach.}
+#'   \item{`wins`:integer.}{Wins for the season.}
+#'   \item{`losses`:integer.}{ Losses for the season.}
+#'   \item{`ties`:integer.}{Ties for the season.}
+#'   \item{`preseason_rank`:integer.}{Preseason rank for the school of coach.}
+#'   \item{`postseason_rank`:integer.}{Postseason rank for the school of coach.}
+#'   \item{`srs`:character.}{Simple Rating System adjustment for team.}
+#'   \item{`sp_overall`:character.}{Bill Connelly's SP+ overall for team.}
+#'   \item{`sp_offense`:character.}{Bill Connelly's SP+ offense for team.}
+#'   \item{`sp_defense`:character.}{Bill Connelly's SP+ defense for team.}
 #' }
 #' @source \url{https://api.collegefootballdata.com/coaches}
-#' @keywords Recruiting
+#' @keywords Coaches
 #' @importFrom jsonlite fromJSON
 #' @importFrom httr GET
 #' @importFrom utils URLencode

R/cfbd_conferences.R

@@ -1,12 +1,23 @@
-#' CFB Conference Information
-#'
-#' Pulls all college football conferences and returns as data frame the following fields:
-#' @return \code{\link[cfbfastR:cfbd_conferences]{cfbfastR::cfbd_conferences()}} - A data frame with 11 rows and 4 variables:
+#' @name cfbd_conferences
+#' @aliases conferences cfbd_conferences
+#' @title CFBD Conferences Endpoint 
+#' @description CFB Conference Information
+#' Pulls all college football conferences and returns as data frame
+#' 
+#' You can call this function simply with 
+#' ```r   
+#' cfbd_conferences()
+#' ```
+#' @examples
+#' \donttest{
+#'    cfbd_conferences()
+#' }
+#' @return [cfbd_conferences()] - A data frame with 11 rows and 4 variables:
 #' \describe{
-#'   \item{conference_id}{Referencing conference id}
-#'   \item{name}{Conference name}
-#'   \item{long_name}{Long name for Conference}
-#'   \item{abbreviation}{Conference abbreviation}
+#'   \item{`conference_id`:}{Referencing conference id.}
+#'   \item{`name`:}{Conference name.}
+#'   \item{`long_name`:}{Long name for Conference.}
+#'   \item{`abbreviation`:}{Conference abbreviation.}
 #'   ...
 #' }
 #' @source \url{https://api.collegefootballdata.com/conferences}
@@ -16,10 +27,6 @@
 #' @import dplyr
 #' @import tidyr
 #' @export
-#' @examples
-#' \donttest{
-#'    cfbd_conferences()
-#' }
 cfbd_conferences <- function() {
   full_url <- "https://api.collegefootballdata.com/conferences"