Merge pull request #84 from nflverse/advstats-season

add summary_level argument to pfr_advstats

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: nflreadr
 Title: Download 'nflverse' Data
-Version: 1.1.2.06
+Version: 1.1.2.07
 Authors@R: c(
     person("Tan", "Ho", , "[email protected]", role = c("aut", "cre", "cph"),
            comment = c(ORCID = "0000-0001-8388-5155")),

NEWS.md

@@ -1,25 +1,10 @@
 # nflreadr (development version)
 
-## Changes
-
-- Pkgdown site updated to feature dictionaries and also to upgrade to Bootstrap 5 (v1.1.2.00)
-- Added [data dictionary for ESPN QBR](https://nflreadr.nflverse.com/articles/dictionary_espn_qbr.html) (v1.1.2.01)
-- Added [data dictionary for Injuries](https://nflreadr.nflverse.com/articles/dictionary_injuries.html) (v1.1.2.02)
-- Added [data dictionary for Trades](https://nflreadr.nflverse.com/articles/dictionary_trades.html) (v1.1.2.02)
-- Added [data dictionary for Depth Charts](https://nflreadr.nflverse.com/articles/dictionary_depth_charts.html) (v1.1.2.02)
-- Added [data dictionary for Combine](https://nflreadr.nflverse.com/articles/dictionary_combine.html) (v1.1.2.02)
-- Exported `most_recent_season()` function since it can be useful elsewhere (v1.1.2.03)
-- Updated documentation with more/better linking (v1.1.2.04)
-- Added [ffopportunity](https://ffopportunity.ffverse.com) and [nflverse](https://nflverse.nflverse.com) packages to sitrep (v1.1.2.04)
-- Added `load_ff_opportunity()` function to download expected fantasy points data. (v1.1.2.05)
-- Added notes about where to file issues to each data function. (v1.1.2.05)
-- Added "all" parameter for `load_ff_rankings()` to return all available data (weekly archives since 2019). (v1.1.2.05)
-- `options(nflreadr.verbose)` replaces `options(nflreadr.cache_warning)` as the best way to silence nflreadr messages. (v1.1.2.06)
-
 ## New data and functions
 
 - `load_ff_opportunity()` downloads expected fantasy points data from the [ffopportunity package](https://ffopportunity.ffverse.com)
 - `load_ff_rankings()` gains an `"all"` parameter to return all available rankings data (weekly archives since 2019)
+- `load_pfr_advstats()` gains a `"summary_level"` parameter to return season-level data, which has some fields that are not available at the week-level. 
 
 ## Backend
 
@@ -30,7 +15,7 @@
 - Sitrep functions have ffopportunity and nflverse packages.
 - Pkgdown site upgraded to Bootstrap 5.
 
-Thank you to [@armstjc](https://github.com/armstjc), [@Grayhawk34](https://github.com/Grayhawk34), [@john-b-edwards](https://github.com/john-b-edwards), [@pranavrajaram](https://github.com/pranavrajaram), [@rogers1000](https://github.com/rogers1000), and [@tanho63](https://github.com/tanho63) for their contributions and feedback on this release!
+Thank you to [@armstjc](https://github.com/armstjc), [@Grayhawk34](https://github.com/Grayhawk34), [@john-b-edwards](https://github.com/john-b-edwards), [@mrcaseb](https://github.com/mrcaseb), [@pranavrajaram](https://github.com/pranavrajaram), [@rogers1000](https://github.com/rogers1000), and [@tanho63](https://github.com/tanho63) for their contributions and feedback on this release!
 
 ---
 

R/load_nflverse.R

@@ -385,8 +385,9 @@ load_espn_qbr <- function(league = c("nfl", "college"),
 #' @export
 load_pfr_passing <- function(seasons = TRUE){
 
-  load_pfr_advstats(seasons = seasons, stat_type = "pass")
+  cli::cli_warn("`load_pfr_passing()` has been deprecated, please use `load_pfr_advstats(stat_type = 'pass', summary_level = 'season')`")
 
+  load_pfr_advstats(seasons = seasons, stat_type = "pass", summary_level = "season")
 }
 
 #' Load Advanced Stats from PFR
@@ -396,28 +397,35 @@ load_pfr_passing <- function(seasons = TRUE){
 #'
 #' @param seasons a numeric vector specifying what seasons to return, if `TRUE` returns all available data
 #' @param stat_type one of "pass", "rush", "rec", "def"
+#' @param summary_level one of "week" (default) or "season" - some data is only available at the season level
 #'
 #' @examples
 #' \donttest{
 #'   load_pfr_advstats()
 #' }
 #'
-#' @return A tibble of week-level player statistics provided by Pro Football Reference to supplement data in nflverse
+#' @return A tibble of player statistics provided by Pro Football Reference that supplements data in nflverse
 #'
 #' @seealso <https://nflreadr.nflverse.com/articles/dictionary_pfr_passing.html> for the web data dictionary
 #' @seealso <https://www.pro-football-reference.com/years/2021/passing_advanced.htm>
 #' @seealso Issues with this data should be filed here: <https://github.com/nflverse/pfr_scrapR>
 #'
 #' @export
-load_pfr_advstats <- function(seasons = most_recent_season(), stat_type = c("pass","rush","rec","def")){
+load_pfr_advstats <- function(seasons = most_recent_season(), stat_type = c("pass","rush","rec","def"), summary_level = c("week","season")){
 
   if(isTRUE(seasons)) seasons <- 2018:most_recent_season()
   stat_type <- rlang::arg_match0(stat_type, c("pass","rush","rec","def"))
-
+  summary_level <- rlang::arg_match0(summary_level, c("week","season"))
   stopifnot(is.numeric(seasons),
             seasons >= 2018,
             seasons <= most_recent_season())
 
+  switch(summary_level,
+         "week" = .pfr_advstats_week(seasons, stat_type),
+         "season" = .pfr_advstats_season(seasons, stat_type))
+}
+
+.pfr_advstats_week <- function(seasons,stat_type){
   urls <- paste0("https://github.com/nflverse/pfr_scrapR/",
                  "raw/master/data/adv_stats/weekly/",
                  stat_type,
@@ -433,6 +441,21 @@ load_pfr_advstats <- function(seasons = most_recent_season(), stat_type = c("pas
   out
 }
 
+.pfr_advstats_season <- function(seasons, stat_type){
+
+  data_url <- switch(stat_type,
+                "pass" = "https://github.com/nflverse/pfr_scrapR/raw/master/data/adv_stats/adv_passing_season.rds",
+                "rush" = "https://github.com/nflverse/pfr_scrapR/raw/master/data/adv_stats/adv_rushing_season.rds",
+                "rec" = "https://github.com/nflverse/pfr_scrapR/raw/master/data/adv_stats/adv_receiving_season.rds",
+                "def" = "https://github.com/nflverse/pfr_scrapR/raw/master/data/adv_stats/adv_defense_season.rds",
+                )
+
+  out <- rds_from_url(data_url)
+  out <- out[out$season %in% seasons]
+  class(out) <- c("tbl_df","tbl","data.table","data.frame")
+  out
+}
+
 #' Load Snap Counts from PFR
 #'
 #' @description Loads game level snap counts stats provided by Pro Football Reference

tests/testthat/test-nflverse.R

@@ -220,16 +220,14 @@ test_that("load_pfr_passing", {
   skip_on_cran()
   skip_if_offline("github.com")
 
-  expect_error(load_pfr_passing("2020"))
-
-  passing <- load_pfr_passing()
+  expect_warning(passing <- load_pfr_passing())
 
   expect_s3_class(passing, "tbl_df")
 
   expect_gt(nrow(passing), 200)
 })
 
-test_that("load_pfr_passing", {
+test_that("load_pfr_advstats", {
 
   skip_on_cran()
   skip_if_offline("github.com")
@@ -238,6 +236,7 @@ test_that("load_pfr_passing", {
 
   pass <- load_pfr_advstats(seasons = 2020, stat_type = "pass")
   rush <- load_pfr_advstats(seasons = TRUE, stat_type = "rush")
+  def <- load_pfr_advstats(seasons = TRUE, stat_type = "def", summary_level = "season")
 
   expect_s3_class(pass, "tbl_df")
   expect_s3_class(rush, "tbl_df")