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.
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")
)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.
A data frame containing real or simulated game scores. Outside of simulations, this is simply the output of nflreadr::load_schedules. The following variables are required as a minimum:
A season or simulation ID. Normally 1 - n simulated seasons.
One of 'REG', 'WC', 'DIV', 'CON', 'SB' indicating if a game was a regular season game or one of the playoff rounds.
The week of the corresponding NFL season.
Team abbreviation of the away team (please see
divisions for valid team abbreviations).
Team abbreviation of the home team (please see
divisions for valid team abbreviations).
Equals home score - away score.
If tiebreakers beyond SOS are to be used, then the actual scores of the
home (home_score) and away (away_score) teams must also be available.
Defaults to the nflseedR function nflseedR_compute_results.
A function to compute results of games. Uses team, schedule, and week number
as arguments. Please see simulations_verify_fct for further information.
Additional parameters passed on to the function compute_results.
If NULL (the default), will compute all 16 conference
ranks. This means, the function applies conference tiebreakers to all
conference ranks. For better performance, it is possible to set this to a
value < 16 to make the function skip tiebreakers of those conference ranks.
Equals the number of times the given NFL season shall be simulated
The number of chunks simulations should be split into
and potentially be processed parallel. This parameter controls the number
of simulations per chunk. There is no obvious way to determine the ideal
number of chunks in advance because there are too many dependencies on the
hardware. Too many chunks can be just as slow as too few. It is therefore
up to the user to determine the optimum number themselves.
The number of teams with a playoff bye week per conference. This number influences the number of wildcard games that are simulated.
One of "SOS", "PRE-SOV", "POINTS" or "RANDOM".
Controls which tiebreakers are to be applied. The implemented tiebreakers
are documented here https://nflseedr.com/articles/tiebreaker.html.
The values mean:
"SOS" (default): Apply all tiebreakers through Strength of Schedule. If there are
still remaining ties, break them through coin toss.
"PRE-SOV": Apply all tiebreakers before Strength of Victory. If there are
still remaining ties, break them through coin toss. Why Pre SOV? It's the
first tiebreaker that requires knowledge of how OTHER teams played.
"POINTS": Apply all tiebreakers through point differential. If there are
still remaining ties, break them through coin toss. This will go beyond SOS
and requires knowledge of points scored and points allowed. As this is not
usually part of season simulations, caution is advised in this case.
These tiebreakers should only be used if the scores are real or are
deliberately simulated.
"RANDOM": Breaks all tiebreakers with a coin toss. I don't really know,
why I allow this...
One of "REG", "POST", "DRAFT" (the default).
Simulation will behave as follows:
"REG": Simulate the regular season and compute standings, division ranks, and playoff seeds
"POST": Do "REG" + simulate the postseason
"DRAFT" (default): Do "POST" + compute draft order
One of "MIN", "MAX", or "NONE" allowing the user
to set the grade of verbosity of status reports. They mean:
"MIN" (default): Prints main steps of the process.
"MAX": Prints all steps of the complete tiebreaking process.
"NONE": No status reports at all. Do this to maximize the performance.
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.
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.
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.
The examples on the package website
The method summary.nflseedR_simulation() that creates a pretty html summary table.
# \donttest{
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)
# }
Run the code above in your browser using DataLab