nflseedR: Functions to Efficiently Simulate and Evaluate NFL Seasons

Description

A set of functions to simulate National Football League seasons including the sophisticated tie-breaking procedures.

Author(s)

Maintainer: Sebastian Carl mrcaseb@gmail.com [copyright holder]

Authors:

• Lee Sharpe

See Also

Useful links:

• https://nflseedr.com

• https://github.com/nflverse/nflseedR

• Report bugs at https://github.com/nflverse/nflseedR/issues

Compute NFL Playoff Seedings using Game Results and Divisional Rankings

Description

Compute NFL Playoff Seedings using Game Results and Divisional Rankings

Usage

compute_conference_seeds(
  teams,
  h2h = NULL,
  tiebreaker_depth = 3,
  .debug = FALSE,
  playoff_seeds = 7
)

Arguments

Value

A data frame of division standings including playoff seeds and the week in which the season ended for the respective team (exit).

A list of two data frames:

standings

Division standings including playoff seeds.

h2h

A data frame that is used for head-to-head tiebreakers across the tie-breaking functions.

See Also

The examples on the package website

Examples

# Change some options for better output
old <- options(list(digits = 3, tibble.print_min = 64))
library(dplyr, warn.conflicts = FALSE)

try({#to avoid CRAN test problems
s <- nflseedR::load_sharpe_games() |>
  dplyr::filter(season %in% 2019:2020) |>
  dplyr::select(sim = season, game_type, week, away_team, home_team, result) |>
  nflseedR::compute_division_ranks()
  nflseedR::compute_conference_seeds(s, h2h = s$h2h) |>
  purrr::pluck("standings")
})

# Restore old options
options(old)

Compute NFL Division Rankings using Game Results

Description

Compute NFL Division Rankings using Game Results

Usage

compute_division_ranks(
  games,
  teams = NULL,
  tiebreaker_depth = 3,
  .debug = FALSE,
  h2h = NULL
)

Arguments

Value

A list of two data frames:

standings

Division standings.

h2h

A data frame that is used for head-to-head tiebreakers across the tie-breaking functions.

See Also

The examples on the package website

Examples

# Change some options for better output
old <- options(list(digits = 3, tibble.print_min = 64))
library(dplyr, warn.conflicts = FALSE)

try({#to avoid CRAN test problems
nflseedR::load_sharpe_games() |>
  dplyr::filter(season %in% 2019:2020) |>
  dplyr::select(sim = season, game_type, week, away_team, home_team, result) |>
  nflseedR::compute_division_ranks() |>
  purrr::pluck("standings")
})

# Restore old options
options(old)

Compute NFL Draft Order using Game Results and Divisional Rankings

Description

Compute NFL Draft Order using Game Results and Divisional Rankings

Usage

compute_draft_order(
  teams,
  games,
  h2h = NULL,
  tiebreaker_depth = 3,
  .debug = FALSE
)

Arguments

Value

A data frame of standings including the final draft pick number and the variable exit which indicates the week number of the teams final game (Super Bowl Winner is one week higher).

See Also

The examples on the package website

Examples

# Change some options for better output
old <- options(list(digits = 3, tibble.print_min = 64))
library(dplyr, warn.conflicts = FALSE)

try({#to avoid CRAN test problems
games <-
  nflseedR::load_sharpe_games() |>
  dplyr::filter(season %in% 2018:2019) |>
  dplyr::select(sim = season, game_type, week, away_team, home_team, result)

s <- games |> nflseedR::compute_division_ranks()
s <- nflseedR::compute_conference_seeds(s, h2h = s$h2h, playoff_seeds = 6)
nflseedR::compute_draft_order(s, games = games, h2h = s$h2h)
})

# Restore old options
options(old)

Data Dictionary: Simulations | Game Summary

Description

A dataframe containing the data dictionary of the simulation output table "game_summary"

Usage

dictionary_game_summary

Format

An object of class data.frame with 11 rows and 2 columns.

See Also

https://nflseedr.com/articles/articles/nflsim2.html#simulation-output

Data Dictionary: Simulations | Games

Description

A dataframe containing the data dictionary of the simulation output table "games"

Usage

dictionary_games

Format

An object of class data.frame with 9 rows and 2 columns.

See Also

https://nflseedr.com/articles/articles/nflsim2.html#simulation-output

Data Dictionary: Simulations | Overall

Description

A dataframe containing the data dictionary of the simulation output table "overall"

Usage

dictionary_overall

Format

An object of class data.frame with 11 rows and 2 columns.

See Also

https://nflseedr.com/articles/articles/nflsim2.html#simulation-output

Data Dictionary: Simulations | Standings

Description

A dataframe containing the data dictionary of the simulation output table "standings"

Usage

dictionary_standings

Format

An object of class data.frame with 21 rows and 2 columns.

See Also

https://nflseedr.com/articles/articles/nflsim2.html#simulation-output

Data Dictionary: Simulations | Team Wins

Description

A dataframe containing the data dictionary of the simulation output table "team_wins"

Usage

dictionary_team_wins

Format

An object of class data.frame with 4 rows and 2 columns.

See Also

https://nflseedr.com/articles/articles/nflsim2.html#simulation-output

NFL team names and the conferences and divisions they belong to

Description

NFL team names and the conferences and divisions they belong to

Usage

divisions

Format

A data frame with 36 rows and 4 variables containing NFL team level information, including franchises in multiple cities:

team

Team abbreviation

conf

Conference abbreviation

division

Division name

sdiv

Division abbreviation

This data frame is created using the teams_colors_logos data frame of the nflfastR package. Please see data-raw/divisions.R for the code to create this data.

Examples

str(divisions)

Format Numerical Values to Special Percentage Strings

Description

This function formats numeric vectors with values between 0 and 1 into percentage strings with special specifications. Those specifications are:

• 0 and 1 are converted to "0%" and "100%" respectively (takes machine precision into account)

• all other values < 0.01 are converted to "<1%"

• all other values between 0.01 and 0.995 are rounded to percentages without decimals

• values between 0.995 and 0.999 are rounded to percentages with 1 decimal

• values between 0.999 and 1 are converted to ">99.9%" unless closer to 1 than machine precision.

Usage

fmt_pct_special(x)

Arguments

Value

A character vector

Examples

x <- c(0, 0.004, 0.009, 0.011, 0.9, 0.98, 0.994,
       .995, .9989, .999, .9991, .99999999)
fmt <- fmt_pct_special(x)
data.frame(x = x, fmt = fmt)

Load Lee Sharpe's Games File

Description

Lee Sharpe maintains an important data set that contains broadly used information on games in the National Football League. This function is a convenient helper to download the file into memory without having to remember the correct url.

Usage

load_sharpe_games(...)

Arguments

Value

A data frame containing the following variables for all NFL games since 1999:

game_id

The ID of the game as assigned by the nflverse. Note that this value matches the game_id field in nflfastR if you wish to join the data.

season

The year of the NFL season. This represents the whole season, so regular season games that happen in January as well as playoff games will occur in the year after this number.

game_type

What type of game? One of the following values:

REG

a regular season game

WC

a wildcard playoff game

DIV

a divisional round playoff game

CON

a conference championship

SB

a Super Bowl

week

The week of the NFL season the game occurs in. Please note that the game_type will differ for weeks >= 18 because of the season expansion in 2021. Please use game_type to filter for regular season or postseason.

gameday

The date on which the game occurred.

weekday

The day of the week on which the game occurred.

gametime

The kickoff time of the game. This is represented in 24-hour time and the Eastern time zone, regardless of what time zone the game was being played in.

away_team

The away team.

away_score

The number of points the away team scored. Is NA for games which haven't yet been played.

home_team

The home team. Note that this contains the designated home team for games which no team is playing at home such as Super Bowls or NFL International games.

home_score

The number of points the home team scored. Is NA for games which haven't yet been played.

location

Either Home if the home team is playing in their home stadium, or Neutral if the game is being played at a neutral location. This still shows as Home for games between the Giants and Jets even though they share the same home stadium.

result

Equals home_score - away_score. The number of points the home team scored minus the number of points the away team scored. Is NA for games which haven't yet been played. Convenient for evaluating against the spread bets.

total

The sum of each team's score in the game. Equals home_score + away_score. Is NA for games which haven't yet been played. Convenient for evaluating over/under total bets.

overtime

Whether the game went into overtime (= 1) or not (= 0).

old_game_id

The id of the game issued by the NFL Game Statistics & Information System.

away_rest

The number of days since that away team's previous game (7 is used for the team's first game of the season).

home_rest

The number of days since that home team's previous game (7 is used for the team's first game of the season).

away_moneyline

Odd of the away_team winning the game.

home_moneyline

Odd of the home_team winning the game.

spread_line

The spread line for the game. A positive number means the home team was favored by that many points, a negative number means the away team was favored by that many points. This lines up with the result column.

away_spread_odds

Odd of the away_team covering the spread_line.

home_spread_odds

Odd of the home_team covering the spread_line.

total_line

The total line for the game.

under_odds

Odd of the total being under the total_line.

over_odds

Odd of the total being over the total_line.

div_game

Whether the game was a divisional game (= 1) or not (= 0).

roof

What was the status of the stadium's roof? Will be one of the following values:

closed

Stadium has a retractable roof which was closed

dome

An indoor stadium

open

Stadium has a retractable roof which was open

outdoors

An outdoor stadium

surface

What type of ground the game was played on.

temp

The temperature at the stadium (for roof types outdoors and open only).

wind

The speed of the wind in miles/hour (for roof types outdoors and open only).

away_qb_id

GSIS ID of the "starting quarterback" of the away team identified as the first quarterback (per roster data) listed as passer (in nflfastR play by play data) in 2+ plays that game. In the final regular season game it is the QB with the most plays as the passer.

home_qb_id

GSIS ID of the "starting quarterback" of the home team identified as the first quarterback (per roster data) listed as passer (in nflfastR play by play data) in 2+ plays that game. In the final regular season game it is the QB with the most plays as the passer.

away_qb_name

Full name of the "starting quarterback" of the away team identified as the first quarterback (per roster data) listed as passer (in nflfastR play by play data) in 2+ plays that game. In the final regular season game it is the QB with the most plays as the passer.

home_qb_name

Full name of the "starting quarterback" of the home team identified as the first quarterback (per roster data) listed as passer (in nflfastR play by play data) in 2+ plays that game. In the final regular season game it is the QB with the most plays as the passer.

away_coach

Name of the head coach of the away team.

home_coach

Name of the head coach of the home team.

referee

Name of the game's referee (head official).

stadium_id

Pro Football Reference ID of the stadium.

stadium

Name of the stadium.

See Also

The internally called function nflreadr::load_schedules()

Examples

try({#to avoid CRAN test problems
games <- load_sharpe_games()
dplyr::glimpse(games)
})

Simulate an NFL Season

Description

Simulate NFL games based on a user provided games/schedule object that holds matchups with and without results. Missing results are computed using the argument compute_results and possible further arguments to compute_results in ... (please see simulations_verify_fct for further information.).

It is possible to let the function calculate playoff participants and simulate the post-season. The code is also developed for maximum performance and allows parallel computation by splitting the number of simulations into chunks and calling the appropriate future::plan. Progress updates can be activated by calling progressr::handlers before the start of the simulations. Please see the below given section "Details" for further information.

Usage

nfl_simulations(
  games,
  compute_results = nflseedR_compute_results,
  ...,
  playoff_seeds = 7L,
  simulations = 10000L,
  chunks = 8L,
  byes_per_conf = 1L,
  tiebreaker_depth = c("SOS", "PRE-SOV", "RANDOM"),
  sim_include = c("DRAFT", "REG", "POST"),
  verbosity = c("MIN", "MAX", "NONE")
)

Arguments

Details

More Speed Using Parallel Processing

We recommend choosing a default parallel processing method and saving it as an environment variable in the R user profile to make sure all futures will be resolved with the chosen method by default. This can be done by following the below given steps.

First, run the below line and the user profile should be opened automatically. If you haven't saved any environment variables yet, this will be an empty file.

usethis::edit_r_environ()

In the opened file add the next line, then save the file and restart your R session. Please note that this example sets "multisession" as default. For most users this should be the appropriate plan but please make sure it truly is.

R_FUTURE_PLAN="multisession"

After the session is freshly restarted please check if the above method worked by running the next line. If the output is FALSE you successfully set up a default non-sequential future::plan(). If the output is TRUE all functions will behave like they were called with purrr::map() and NOT in multisession.

inherits(future::plan(), "sequential")

For more information on possible plans please see the future package Readme.

Get Progress Updates while Functions are Running

nflseedR is able to show progress updates using progressr::progressor() if they are turned on before the function is called. There are at least two basic ways to do this by either activating progress updates globally (for the current session) with

progressr::handlers(global = TRUE)

or by piping the function call into progressr::with_progress():

nflseedR::nfl_simulations(
  games = nflseedR::sims_games_example,
  simulations = 4,
  chunks = 2
) |>
  progressr::with_progress()

For more information how to work with progress handlers please see progressr::progressr.

Reproducible Random Number Generation (RNG)

It is to be expected that some form of random number generation is required in the function in argument compute_results. For better performance, nflseedR uses the furrr package to parallelize chunks. furrr functions are guaranteed to generate the exact same sequence of random numbers given the same initial seed if, and only if, the initial seed is of the type "L'Ecuyer-CMRG". So if you want a consistent seed to be used across all chunks, you must ensure that the correct type is specified in set.seed, e.g. with the following code

set.seed(5, "L'Ecuyer-CMRG")

It is sufficient to set the seed before nfl_simulations is called. To check that the type has been set correctly, you can use the following code.

RNGkind()
"L'Ecuyer-CMRG" "Inversion"     "Rejection"

# Should be a integer vector of length 7
.Random.seed
10407  1157214768 -1674567567 -1532971138 -1249749529  1302496508  -253670963

For more information, please see the section "Reproducible random number generation (RNG)" in furrr::furrr_options.

Value

An nflseedR_simulation object containing a list of 6 data frames with the results of all simulated games, the final standings in each simulated season, summary statistics across all simulated seasons, and the simulation parameters. For a full list, please see the package website.

See Also

The examples on the package website

The method summary.nflseedR_simulation() that creates a pretty html summary table.

Examples

library(nflseedR)

# Activate progress updates
# progressr::handlers(global = TRUE)

# Parallel processing can be activated via the following line
# future::plan("multisession")

sim <- nflseedR::nfl_simulations(
  games = nflseedR::sims_games_example,
  simulations = 4,
  chunks = 2
)

# Overview output
str(sim, max.level = 3)

Compute NFL Standings

Description

Compute NFL Standings

Usage

nfl_standings(
  games,
  ...,
  ranks = c("CONF", "DIV", "DRAFT", "NONE"),
  tiebreaker_depth = c("SOS", "PRE-SOV", "POINTS", "RANDOM"),
  playoff_seeds = NULL,
  verbosity = c("MIN", "MAX", "NONE")
)

Arguments

Details

nflseedR does not support all levels of tie-breakers at the moment. The deepest tie-breaker currently is "best net points in all games". After that, the decision is made at random. However, the need for the last level ("best net touchdowns in all games") is extremely unlikely in practice. Deeper levels than strength of schedule have never actually been needed to resolve season-end standings since the NFL expanded to 32 teams.

Value

A data.table of NFL standings including the ranks selected in the argument ranks

See Also

For more information on the implemented tiebreakers, see https://nflseedr.com/articles/tiebreaker.html

Examples

try({#to avoid CRAN test problems
  games <- nflreadr::load_schedules(2021:2022)
})
standings <- nflseedR::nfl_standings(games)
print(standings, digits = 3)

Compute Pretty NFL Standings Table

Description

Uses the R package gt to create a pretty html table of NFL standings.

Usage

nfl_standings_prettify(
  standings,
  ...,
  grp_by = c("div", "conf", "nfl"),
  order_by = c("div_rank", "conf_rank", "draft_rank"),
  reverse = FALSE
)

Arguments

Value

An object of class gt_tbl.

Output of below examples

Examples

# Calculate standings
s <- nflreadr::load_schedules(2024) |>
  nflseedR::nfl_standings(ranks = "DRAFT")

# Create table
tbl1 <- nfl_standings_prettify(s, grp_by = "conf", order_by = "conf_rank")
tbl2 <- nfl_standings_prettify(s, grp_by = "nfl", order_by = "draft_rank")

# The output of tbl1 and tbl2 is given in the above images.

Compute NFL Game Results in Season Simulations

Description

This is the default nflseedR function to compute game results in season simulations.

Usage

nflseedR_compute_results(teams, games, week_num, ...)

Arguments

Details

This function implements a variant of 538's elo model initially coded by Lee Sharpe (in nflseedR 1.0) and for performance rewritten by Sebastian Carl (in nflseedR 2.0).

Value

A list of updated teams and games tables.

Examples

g <- nflseedR::sims_games_example
# The functions expects the variable "sim" instead of "season"
g$sim <- g$season
t <- nflseedR::sims_teams_example

out <- nflseedR_compute_results(
  teams = t,
  games = g,
  week_num = 5L
)

str(out, max.level = 2)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

nflreadr

load_schedules

Example Games Data used in NFL Simulations

Description

Example Games Data used in NFL Simulations

Usage

sims_games_example

Format

A data frame with 284 rows and 9 variables containing NFL schedule information.

Details

Please see data-raw/sim_examples.R for the code to create this data.

Examples

str(sims_games_example)

Example Teams Data used in NFL Simulations

Description

Example Teams Data used in NFL Simulations

Usage

sims_teams_example

Format

A data frame with 64 rows and 5 variables containing team name and division information.

Details

Please see data-raw/sim_examples.R for the code to create this data.

Examples

str(sims_teams_example)

Simulate an NFL Season

Description

This function simulates a given NFL season multiple times using custom functions to estimate and simulate game results and computes the outcome of the given season including playoffs and draft order. It is possible to run the function in parallel processes by calling the appropriate plan. Progress updates can be activated by calling handlers before the start of the simulations. Please see the below given section "Details" for further information.

Usage

simulate_nfl(
  nfl_season = NULL,
  process_games = NULL,
  ...,
  playoff_seeds = ifelse(nfl_season >= 2020, 7, 6),
  if_ended_today = FALSE,
  fresh_season = FALSE,
  fresh_playoffs = FALSE,
  tiebreaker_depth = 3,
  test_week = NULL,
  simulations = 1000,
  sims_per_round = max(ceiling(simulations/future::availableCores() * 2), 100),
  .debug = FALSE,
  print_summary = FALSE,
  sim_include = c("DRAFT", "REG", "POST")
)

Arguments

Details

More Speed Using Parallel Processing

We recommend choosing a default parallel processing method and saving it as an environment variable in the R user profile to make sure all futures will be resolved with the chosen method by default. This can be done by following the below given steps.

First, run the following line and the user profile should be opened automatically. If you haven't saved any environment variables yet, this will be an empty file.

usethis::edit_r_environ()

In the opened file add the next line, then save the file and restart your R session. Please note that this example sets "multisession" as default. For most users this should be the appropriate plan but please make sure it truly is.

R_FUTURE_PLAN="multisession"

After the session is freshly restarted please check if the above method worked by running the next line. If the output is FALSE you successfully set up a default non-sequential future::plan(). If the output is TRUE all functions will behave like they were called with purrr::map() and NOT in multisession.

inherits(future::plan(), "sequential")

For more information on possible plans please see the future package Readme.

Get Progress Updates while Functions are Running

Most nflfastR functions are able to show progress updates using progressr::progressor() if they are turned on before the function is called. There are at least two basic ways to do this by either activating progress updates globally (for the current session) with

progressr::handlers(global = TRUE)

or by piping the function call into progressr::with_progress():

simulate_nfl(2020, fresh_season = TRUE) |>
  progressr::with_progress()

For more information how to work with progress handlers please see progressr::progressr.

Value

An nflseedR_simulation object containing a list of 6 data frames data frames with the results of all simulated games, the final standings in each simulated season (incl. playoffs and draft order), summary statistics across all simulated seasons, and the simulation parameters. For a full list, please see the package website.

See Also

The examples on the package website

The method summary.nflseedR_simulation() that creates a pretty html summary table.

Examples

library(nflseedR)

# Activate progress updates
# progressr::handlers(global = TRUE)

# Parallel processing can be activated via the following line
# future::plan("multisession")

try({#to avoid CRAN test problems
# Simulate the season 4 times in 2 rounds
sim <- nflseedR::simulate_nfl(
  nfl_season = 2020,
  fresh_season = TRUE,
  simulations = 4,
  sims_per_round = 2
)

# Overview output
dplyr::glimpse(sim)
})

Verify Custom NFL Result Simulation Function

Description

nflseedR supports custom functions to compute results in season simulations through the argument compute_results in the season simulation function nfl_simulations. To ensure that custom functions work as nflseedR expects them to, it is recommended to verify their behavior. This function first checks the structure of the output and then whether game results are changed as expected. Whenever a problem is found, the function will error with a hint to the problem (this means that you might be required to iterate over all problems until the function stops erroring). See below detail section for more information on expected behavior.

Usage

simulations_verify_fct(
  compute_results,
  ...,
  games = nflseedR::sims_games_example,
  teams = nflseedR::sims_teams_example
)

Arguments

Details

The following sections detail the requirements for the compute_results function. If anything is unclear, please see the source code of nflseedR's default function nflseedR_compute_results.

Required Function Arguments of compute_results

The function passed to compute_results is required to support the arguments "teams", "games", and "week_num". The two leading ones are already described above. The latter is a factor with a length of 1, which identifies the current week. Regular season weeks are labeled "1", "2", etc. Playoff weeks are labeled "WC", "DIV", "CON", and "SB".

Required Output Structure of compute_results

The function passed to compute_results is required to return a list of the two objects "teams" and "games" as passed to it in the arguments of the same name. The function must not remove rows or columns. So the last line of compute_results usually looks like

list("teams" = teams, "games" = games)

Required Behavior of compute_results when Computing Game Results

nflseedR calls compute_results for every week where a result is missing in games. The variable result is defined as the point differential between the home team and the away team. If the home team loses, the value is therefore < 0, if it wins > 0 and if it ties == 0. To support elo-based simulations, this is done in a loop so that elo ratings can be updated based on the results and "transported" from week to week. You can "transport" ratings or other information by joining them to the "teams" table. This behavior requires that compute_results only changes the results of the current week - called week_num. And only if there is not already a result. So compute_results must only compute a result when

week == week_num & is.na(result)

For the playoffs, there is also the special case that matches cannot end in a tie (result == 0). In most cases, ties are not simulated anyway because they occur so rarely. But in the event that they are simulated, they must not be in the playoffs.

Value

Returns TRUE invisibly if no problems are found.

Examples

simulations_verify_fct(nflseedR_compute_results)

Compute Pretty Simulations Summary Table

Description

Uses the R package gt to create a pretty html table of the nflseedR simulation summary data frame.

Usage

## S3 method for class 'nflseedR_simulation'
summary(object, ...)

Arguments

Output of below example

Examples

library(nflseedR)
# set seed for recreation,
# internal parallelization requires a L'Ecuyer-CMRG random number generator
set.seed(19980310, kind = "L'Ecuyer-CMRG")

# Simulate the season 20 times in 1 round
sim <- nflseedR::simulate_nfl(
  nfl_season = 2021,
  fresh_season = TRUE,
  simulations = 20
)

# Create Summary Tables
tbl <- summary(sim)

# The output of tbl is given in the above image.