nflseedR

https://nflseedr.com
Admin
nflseedR is an R package that enables NFL modelers to simulate complete seasons using Monte Carlo...
Tokens:47,004
Snippets:326
Trust Score:7.4
Update:10 months ago
Show doc for...
Tokens:
Raw
### Example NFL Simulation with Progress and Parallelism (R)

Source: https://nflseedr.com/reference/simulate_nfl

An example demonstrating how to run NFL simulations using nflseedR, with progress updates enabled and parallel processing configured. This example simulates the 2020 NFL season multiple times.

```R
# \donttest{
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
)


```

--------------------------------

### Install nflseedR from Development Repository

Source: https://nflseedr.com/index

This code snippet provides an alternative method to install the development version of nflseedR by specifying a custom repository. This method is useful if you want to install directly from the development build without using GitHub.

```r
install.packages("nflseedR", repos = c("https://nflverse.r-universe.dev", getOption("repos")))
```

--------------------------------

### Example Usage of nflseedR Simulations

Source: https://nflseedr.com/reference/nfl_simulations

Provides a complete example of using the nfl_simulations function from the nflseedR package. This snippet shows how to set up simulations and includes comments on activating progress updates and parallel processing. The output demonstrates the messages displayed during simulation execution.

```R
# \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
)
#> ℹ Computation in multiple chunks can be accelerated with parallel processing.
#> ℹ You should consider calling a `future::plan()`. Please see the function
#>   documentation for further information.
#> ℹ Will go on sequentially...
#> This message is displayed once every 8 hours.
#> ℹ 12:40:48 | Start simulation of 4 seasons in 2 chunks with a chunk size of 2.
#> ℹ 12:40:49 | CHUNK #1: Start simulation of regular season weeks "1", "2", "3",
#> …, "17", and "18"
#> ℹ 12:40:49 | Initiate Standings & Tiebreaking Data
#> ℹ 12:40:49 | Compute Division Ranks
#> ℹ 12:40:49 | Compute Conference Ranks
#> ℹ 12:40:49 | CHUNK #1: Start simulation of post season weeks "WC" and "SB"
#> ℹ 12:40:49 | Compute Draft Order
#> ℹ 12:40:49 | CHUNK #2: Start simulation of regular season weeks "1", "2", "3",
#> …, "17", and "18"
#> ℹ 12:40:49 | Initiate Standings & Tiebreaking Data
#> ℹ 12:40:49 | Compute Division Ranks
#> ℹ 12:40:50 | Compute Conference Ranks
#> ℹ 12:40:50 | CHUNK #2: Start simulation of post season weeks "WC" and "SB"
#> ℹ 12:40:50 | Compute Draft Order
#> ℹ 12:40:50 | Combine simulation data
#> ℹ 12:40:50 | Aggregate across simulations
#> ℹ 12:40:50 | DONE!
#

```

--------------------------------

### Install nflseedR Development Version from GitHub

Source: https://nflseedr.com/index

This code snippet demonstrates how to install the development version of the nflseedR package directly from its GitHub repository. This is useful for accessing the latest features or bug fixes before they are released on CRAN. It first checks if the 'pak' package is installed and installs it if necessary.

```r
if (!requireNamespace("pak")) install.packages("pak")
pak::pak("nflverse/nflseedR")
```

--------------------------------

### Inspect Example Teams Data Structure (R)

Source: https://nflseedr.com/reference/sims_teams_example

This snippet demonstrates how to inspect the structure of the `sims_teams_example` data frame, which is used in NFL simulations within the nflseedR package. It shows the data frame's dimensions, variable types, and a preview of the first few observations.

```R
str(sims_teams_example)
#> Classes ‘data.table’ and 'data.frame':	64 obs. of  5 variables:
#>  $ sim     : int  1 1 1 1 1 1 1 1 1 1 ...
#>  $ team    : chr  "ARI" "ATL" "BAL" "BUF" ...
#>  $ conf    : chr  "NFC" "NFC" "AFC" "AFC" ...
#>  $ division: chr  "NFC West" "NFC South" "AFC North" "AFC East" ...
#>  $ sdiv    : chr  "NFCW" "NFCS" "AFCN" "AFCE" ...
```

--------------------------------

### Install nflseedR from CRAN

Source: https://nflseedr.com/index

This code snippet shows the standard method for installing the nflseedR package from the Comprehensive R Archive Network (CRAN). This is the recommended method for most users as it provides stable releases.

```r
install.packages("nflseedR")
```

--------------------------------

### R: Running NFL Simulations with Custom Logic

Source: https://nflseedr.com/articles/articles/nflsim2

Executes NFL simulations using the `nflseedR` package with a custom game result computation function (`biased_games_model`). This example demonstrates passing specific 'best' and 'worst' teams to influence the simulation outcomes. It includes parameters for simulation count, chunk size, and verbosity.

```r
sims3 <- nflseedR::nfl_simulations(
  games = games, 
  compute_results = biased_games_model, 
  simulations = 500, 
  chunks = 1, 
  best = "CHI", 
  worst = "GB",
  verbosity = "NONE"
)
#> ℹ 12:51:35 | Start simulation of 500 seasons in 1 chunk with a chunk size of 500.
#> ℹ 12:51:41 | DONE!
sims3$overall |> 
  dplyr::arrange(-wins) |> 
  gt::gt_preview(top_n = 5, bottom_n = 5)
```

--------------------------------

### Prettify and Order NFL Standings by Draft Rank (R)

Source: https://nflseedr.com/articles/articles/nflseedR

This example demonstrates how to use the nflseedR::nfl_standings_prettify function to display all NFL standings ordered by draft rank, rather than by division. The `grp_by = "nfl"` argument groups all teams together, and `order_by = "draft_rank"` specifies the sorting criteria.

```r
nflseedR::nfl_standings_prettify(s, grp_by = "nfl", order_by = "draft_rank")
```

--------------------------------

### Display Structure of Example Games Data in R

Source: https://nflseedr.com/reference/sims_games_example

This R code snippet demonstrates how to display the structure of the 'sims_games_example' data frame, which contains NFL schedule information. It shows the data frame's dimensions and the data types of its variables. This is useful for understanding the format of the data before simulation.

```r
str(sims_games_example)
#> Classes ‘data.table’ and 'data.frame':	284 obs. of  9 variables:
#>  $ season   : int  2022 2022 2022 2022 2022 2022 2022 2022 2022 2022 ...
#>  $ game_type: chr  "REG" "REG" "REG" "REG" ...
#>  $ week     : int  1 1 1 1 1 1 1 1 1 1 ...
#>  $ away_team: chr  "BUF" "NO" "CLE" "SF" ...
#>  $ home_team: chr  "LA" "ATL" "CAR" "CHI" ...
#>  $ away_rest: int  7 7 7 7 7 7 7 7 7 7 ...
#>  $ home_rest: int  7 7 7 7 7 7 7 7 7 7 ...
#>  $ location : chr  "Home" "Home" "Home" "Home" ...
#>  $ result   : int  NA -1 -2 NA -3 -3 0 NA -15 6 ...
```

--------------------------------

### Simulate NFL Season with nflseedR

Source: https://nflseedr.com/articles/nflsim

Simulates an NFL season using the simulate_nfl function. This example sets a specific random seed for reproducibility, enables overwriting existing season data, and specifies the number of simulations. The output provides detailed results for each simulated season.

```r
set.seed(4)
sims <- simulate_nfl(
  nfl_season = 2020,
  fresh_season = TRUE,
  simulations = 100
)
#> ℹ 12:44:29 | Loading games data
#> ℹ 12:44:30 | Beginning simulation of 100 seasons in 1 round
#> ℹ 12:44:46 | Combining simulation data
#> ℹ 12:44:46 | Aggregating across simulations
#> ℹ 12:44:46 | DONE!
```

--------------------------------

### Verify NFL Seedr Simulation Results

Source: https://nflseedr.com/reference/simulations_verify_fct

This example demonstrates how to verify the results of NFL seeding simulations using the `simulations_verify_fct` function from the nflseedR package. It takes the computed results as input and checks for any discrepancies or issues, providing a warning if a shallow copy of the data.table was made, and indicating success if no problems are found.

```r
simulations_verify_fct(nflseedR_compute_results)
#> Warning: A shallow copy of this data.table was taken so that := can add or remove 1 columns by reference. At an earlier point, this data.table was copied by R (or was created manually using structure() or similar). Avoid names<- and attr<- which in R currently (and oddly) may copy the whole data.table. Use set* syntax instead to avoid copying: ?set, ?setnames and ?setattr. It's also not unusual for data.table-agnostic packages to produce tables affected by this issue. If this message doesn't help, please report your use case to the data.table issue tracker so the root cause can be fixed or this message improved.
#> ✔ No problems found!
```

--------------------------------

### Configure Default Parallel Processing (R)

Source: https://nflseedr.com/reference/simulate_nfl

Sets a default parallel processing plan for R futures by editing the R user profile. This ensures functions using futures will resolve in parallel by default. It requires restarting the R session for changes to take effect. The example sets 'multisession' as the default plan.

```R
usethis::edit_r_environ()
R_FUTURE_PLAN="multisession"

```

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

```

--------------------------------

### Convert Market Spreads to Elo Ratings (R)

Source: https://nflseedr.com/articles/articles/nflsim2

Converts market implied team spreads into Elo ratings. It starts with a base Elo of 1500 and adds 25 points for each point a team is favored by. The resulting named vector of Elo ratings is then printed.

```R
team_ratings$elo <- 1500 + 25 * team_ratings$spread
team_ratings <- setNames(team_ratings$elo, team_ratings$team)
print(team_ratings)
```

--------------------------------

### Simulate NFL with Custom Model in R

Source: https://nflseedr.com/articles/articles/nflsim

Executes an NFL simulation using the 'simulate_nfl' function from the nflseedR package. This example demonstrates passing the custom 'biased_games_model' to the 'process_games' argument and specifying 'best' and 'worst' teams ('CHI' and 'GB') to influence the simulation outcomes. It also sets 'fresh_season = TRUE' and 'simulations = 100'.

```R
sims3 <- simulate_nfl(
  nfl_season = 2020,
  process_games = biased_games_model, 
  fresh_season = TRUE, 
  simulations = 100,
  best = "CHI", 
  worst = "GB"
)
#> ℹ 12:45:00 | Loading games data
#> ℹ 12:45:00 | Beginning simulation of 100 seasons in 1 round
#> ℹ 12:45:13 | Combining simulation data
#> ℹ 12:45:13 | Aggregating across simulations
#> ℹ 12:45:13 | DONE!
```

--------------------------------

### Filter and Display NFL Regular Season Games with nflseedR

Source: https://nflseedr.com/articles/articles/nflsim2

This R code snippet filters the example NFL game data to include only regular season games and displays them using a data table. It utilizes the dplyr package for filtering and nflseedR for example data.

```r
all_games <- nflseedR::sims_games_example |> dplyr::filter(game_type == "REG")
DT::datatable(all_games)
```

--------------------------------

### Verify Custom NFL Result Simulation Function in R

Source: https://nflseedr.com/reference/simulations_verify_fct

The `simulations_verify_fct` function in nflseedR is used to verify custom functions designed for computing NFL game results during season simulations. It checks the output structure and ensures game results are computed as expected. The function takes a custom `compute_results` function, optional arguments, and example `games` and `teams` data. It returns TRUE invisibly if no issues are found, otherwise, it throws an error with a descriptive message.

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

--------------------------------

### Enable Progress Updates (R)

Source: https://nflseedr.com/reference/simulate_nfl

Demonstrates how to activate progress updates for nflfastR functions using the 'progressr' package. Progress updates can be enabled globally for the session or specifically for a function call by piping it into `with_progress()`.

```R
progressr::handlers(global = TRUE)

```

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

```

--------------------------------

### Run Simulation with Custom `compute_results` (R)

Source: https://nflseedr.com/articles/articles/nflsim2

This R code demonstrates how to run nflseedR simulations using a custom `compute_results` function (`stupid_games_model`). It configures the simulation with a specified number of `simulations` and `chunks`, and sets `verbosity` to "NONE" to minimize output. The output of the simulation is stored in `sims2` and then a preview of the overall results is displayed using `gt::gt_preview`.

```r
sims2 <- nflseedR::nfl_simulations(
  games = games,
  compute_results = stupid_games_model,
  simulations = 500,
  chunks = 1,
  verbosity = "NONE"
)
#> ℹ You have provided your own function to `compute_results`, cool!
#> ℹ To maximize performance, `nfl_simulations()` does not control the output of
#>   your function during the simulation. Please use `simulations_verify_fct()` in
#>   advance to ensure that you do not get any unexpected results or errors.
#> ℹ 12:51:28 | Start simulation of 500 seasons in 1 chunk with a chunk size of 500.
#> 
#> ℹ 12:51:34 | DONE!
#> 
#> This message is displayed once every 8 hours.

sims2$overall |> 
  dplyr::arrange(team) |> 
  gt::gt_preview(top_n = 5, bottom_n = 5)
```

--------------------------------

### Enable Progress Updates with progressr

Source: https://nflseedr.com/reference/nfl_simulations

Demonstrates how to enable and utilize progress updates for functions in nflseedR using the 'progressr' package. Progress updates can be activated globally for the session or applied to specific function calls using a pipe. This is useful for monitoring long-running computations.

```R
progressr::handlers(global = TRUE)
nflseedR::nfl_simulations(
  games = nflseedR::sims_games_example,
  simulations = 4,
  chunks = 2
) |> 
  progressr::with_progress()
```

--------------------------------

### Simulate NFL Season with nflseedR

Source: https://nflseedr.com/reference/summary.nflseedR_simulation

This code snippet demonstrates how to simulate NFL seasons using the nflseedR package. It sets a specific random seed for reproducibility and then calls the `simulate_nfl` function to run a specified number of simulations for a given season. The function handles loading game data, running the simulations, and aggregating the results. Dependencies include the nflseedR package itself.

```R
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
)

```

--------------------------------

### Set Seed and Run NFL Simulations with L'Ecuyer-CMRG

Source: https://nflseedr.com/articles/articles/nflsim2

Sets a specific random seed using the 'L'Ecuyer-CMRG' method and then runs NFL simulations using the nfl_simulations function. This function takes game data, team Elo ratings, and simulation parameters as input. It outputs simulation progress messages.

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

sims <- nflseedR::nfl_simulations(
  games = games,
  elo = team_ratings,
  simulations = 50000,
  chunks = 20,
  verbosity = "NONE"
)
```

--------------------------------

### Initialize and Simulate NFL Season in R

Source: https://nflseedr.com/articles/nflsim

This R code initializes random Elo values for NFL teams and then runs a partial simulation of an NFL season using the `simulate_nfl` function. The simulation is configured to run up to a specified week (`test_week`) and return the results from the `elo_model` function at that point. Dependencies include the nflseedR and tibble packages.

```r
initial_elo <- tibble::tibble(
  team = unique(nflseedR::divisions$team),
  elo = rnorm(length(unique(nflseedR::divisions$team)), 1500, 150)
)

test <- simulate_nfl(
  nfl_season = 2020,
  process_games = elo_model, # Assuming elo_model is defined elsewhere
  elo = initial_elo,
  fresh_season = TRUE,
  test_week = 3
)

# The following lines are for displaying results and are not part of the core simulation logic:
# print(test$teams |>
#   dplyr::filter(team == "CHI") |
#   utils::head() |
#   knitr::kable())

# print(test$games |
#   filter(sim == 1) |
#   filter(away_team == "CHI" | home_team == "CHI")
# )
```

--------------------------------

### Create Summary Table from nflseedR Simulation

Source: https://nflseedr.com/reference/summary.nflseedR_simulation

This R code snippet shows how to generate a summary table from an nflseedR simulation object. It takes a simulation object (created by `simulate_nfl`) and passes it to the `summary` function, which uses the `gt` package to format the output as an HTML table. The primary input is the simulation object, and the output is a formatted data frame suitable for display.

```R
# Create Summary Tables
tbl <- summary(sim)

```

--------------------------------

### R: Custom Game Logic with Generic Arguments in nflseedr

Source: https://nflseedr.com/articles/nflsim2

This R function demonstrates how to create custom game logic for NFL simulations using generic arguments. It accepts additional arguments like 'best' and 'worst' teams via the '...' syntax, allowing for flexible input. The function modifies game results based on these custom arguments and returns updated team and game data.

```R
library(rlang)
biased_games_model <- function(teams, games, week_num, ...) {
  
  # collect all arguments in dots
  args <- list(...)
  
  # if "best" or "worst" are in dots, assign them to best of worst
  # if not, then args$best and args$worst will be NULL and we replace 
  # them with empty strings
  best <- args$best %||% "" 
  worst <- args$worst %||% ""

  # make the best team always win and the worst team always lose
  # otherwise, make the earlier alphabetical team win 90% of the time
  games <- games |>
    dplyr::mutate(
      result = dplyr::case_when(
        !is.na(result) | week != week_num ~ result,
        away_team == best | home_team == worst ~ -3,
        away_team == worst | home_team == best ~ 3,
        away_team < home_team ~
          sample(c(-3, 3), dplyr::n(), prob = c(0.9, 0.1), replace = TRUE),
        away_team > home_team ~
          sample(c(-3, 3), dplyr::n(), prob = c(0.1, 0.9), replace = TRUE),
        TRUE ~ 0
      )
    )
  
  # return values
  list(teams = teams, games = games)
}
```

--------------------------------

### Simulate NFL Seasons with nflseedR

Source: https://nflseedr.com/articles/nflsim2

This snippet simulates NFL seasons using the nflseedR package. It takes a list of games as input and specifies the number of simulations and chunks for parallel processing. The function outputs simulation results, including regular season and playoff outcomes, and draft order. It is recommended to run a high number of simulations (e.g., 10k or more) for robust analysis.

```r
sims <- nflseedR::nfl_simulations(
  games = all_games,
  simulations = 4,
  chunks = 2
)
```

--------------------------------

### Run NFL Simulations with Custom Elo Ratings in R

Source: https://nflseedr.com/articles/nflsim2

Executes NFL season simulations using the `nfl_simulations` function from the `nflseedR` package. It allows passing custom Elo ratings via the `...` argument, which are then used as initial team ratings. The simulation parameters include the number of games, initial team ratings, number of simulations, chunking for parallel processing, and verbosity level.

```R
sims <- nflseedR::nfl_simulations(
  games = games,
  elo = team_ratings,
  simulations = 50000,
  chunks = 20,
  verbosity = "NONE"
)
```

--------------------------------

### NFL Simulation Parameters

Source: https://nflseedr.com/articles/nflsim2

Details the parameters used for running NFL season simulations, including season year, playoff configurations, and simulation settings.

```APIDOC
## NFL Simulation Parameters (`sim_params`)

### Description
This section outlines the parameters used to configure NFL season simulations. These parameters are passed to the `nfl_simulations()` function to control various aspects of the simulation process.

### Parameters
- **`nfl_season`** (integer) - The year of the NFL season to simulate.
- **`playoff_seeds`** (list) - Configuration for playoff seeding.
- **`simulations`** (integer) - The total number of simulations to run.
- **`chunks`** (integer) - Number of chunks to divide simulations into (for parallel processing).
- **`byes_per_conf`** (integer) - Number of bye weeks allocated per conference.
- **`tiebreaker_depth`** (integer) - Depth for tiebreaker resolution.
- **`sim_include`** (string) - Specifies what to include in the simulation (e.g., 'REG', 'POST').
- **`verbosity`** (integer) - Controls the level of output during simulation (e.g., 0 for silent, higher for more details).
- **`sims_per_round`** (integer) - Number of simulations to run per playoff round.
- **`nflseedR_version`** (string) - The version of the `nflseedR` package used.
- **`finished_at`** (timestamp) - The timestamp when the simulation finished.

### Request Example
```json
{
  "nfl_season": 2024,
  "simulations": 50000,
  "sim_include": "REG",
  "verbosity": 0
}
```

### Response Example
```json
{
  "simulation_status": "completed",
  "elapsed_time_seconds": 85
}
```
```

--------------------------------

### Inspect Simulation Data with dplyr::glimpse

Source: https://nflseedr.com/reference/simulate_nfl

This snippet uses the `dplyr::glimpse` function to provide a concise summary of the simulation output object 'sim'. It displays the structure and first few observations of each data frame within the object, aiding in understanding the simulation's results.

```r
dplyr::glimpse(sim)
```

--------------------------------

### R: Running nflseedr Simulation with Custom Game Model

Source: https://nflseedr.com/articles/nflsim2

This R code snippet shows how to execute an NFL simulation using the nflseedr package with a custom game logic function. It passes the 'biased_games_model' to the 'compute_results' argument and specifies custom team data ('best' and 'worst') directly in the function call. The results are then displayed in a formatted table.

```R
sims3 <- nflseedR::nfl_simulations(
  games = games,
  compute_results = biased_games_model, 
  simulations = 500,
  chunks = 1,
  best = "CHI", 
  worst = "GB",
  verbosity = "NONE"
)

sims3$overall |>
  dplyr::arrange(-wins) |>
  gt::gt_preview(top_n = 5, bottom_n = 5)
```

--------------------------------

### Verify Custom `compute_results` Function (R)

Source: https://nflseedr.com/articles/articles/nflsim2

This R code uses `nflseedR::simulations_verify_fct()` to validate a custom `compute_results` function, such as `stupid_games_model`. This verification step is essential to ensure the custom function adheres to the expected input/output structure and behavior required by nflseedR's simulation engine, preventing potential errors and performance issues during large-scale simulations.

```r
nflseedR::simulations_verify_fct(stupid_games_model)
#> ✔ No problems found!
```

--------------------------------

### NFL Season Simulation

Source: https://nflseedr.com/reference/nfl_simulations

Simulates NFL seasons based on provided game data and simulation parameters.

```APIDOC
## POST /websites/nflseedr

### Description
Simulates NFL seasons, calculates standings, playoff seeds, and draft order based on provided game data and simulation parameters.

### Method
POST

### Endpoint
/websites/nflseedr

### Parameters
#### Request Body
- **games** (data.frame) - A data frame containing real or simulated game scores. Must include variables like `sim`, `season`, `game_type`, `week`, `away_team`, `home_team`, and `result`.
- **sim or season** (numeric or character) - A season or simulation ID. If both are included, `sim` takes precedence.
- **game_type** (character) - Type of game: 'REG', 'WC', 'DIV', 'CON', 'SB'.
- **week** (numeric) - The week of the NFL season.
- **away_team** (character) - Abbreviation of the away team.
- **home_team** (character) - Abbreviation of the home team.
- **result** (numeric) - Home score minus away score.
- **compute_results** (function) - Function to compute game results. Defaults to `nflseedR_compute_results`.
- **playoff_seeds** (numeric, optional) - Number of conference ranks to compute. Defaults to 16.
- **simulations** (numeric) - The number of times the season shall be simulated.
- **chunks** (numeric) - The number of chunks to split simulations into for parallel processing.
- **byes_per_conf** (numeric) - The number of teams with a playoff bye week per conference.
- **tiebreaker_depth** (character) - Tiebreaker method: 'SOS', 'PRE-SOV', 'POINTS', or 'RANDOM'. Defaults to 'SOS'.
- **sim_include** (character) - What to include in simulation: 'REG', 'POST', or 'DRAFT'. Defaults to 'DRAFT'.
- **verbosity** (character) - Verbosity level: 'MIN', 'MAX', or 'NONE'. Defaults to 'MIN'.

### Request Example
```json
{
  "games": "<dataframe>",
  "season": "2023",
  "game_type": "REG",
  "week": 10,
  "away_team": "KC",
  "home_team": "LV",
  "result": 10,
  "simulations": 1000,
  "tiebreaker_depth": "SOS",
  "sim_include": "DRAFT",
  "verbosity": "MIN"
}
```

### Response
#### Success Response (200)
- **simulation_results** (list of data frames) - Contains simulated game results, final standings, summary statistics, and simulation parameters.

#### Response Example
```json
{
  "simulation_results": {
    "simulated_games": "<dataframe>",
    "final_standings": "<dataframe>",
    "summary_stats": "<dataframe>",
    "simulation_parameters": "<list>"
  }
}
```
```

--------------------------------

### View Data Dictionary for Standings (R)

Source: https://nflseedr.com/reference/dictionary_standings

Displays the data dictionary for the 'standings' simulation output table. This object is of class 'data.frame' and contains information about the simulation results. It is useful for understanding the structure and content of the simulation output.

```r
dictionary_standings
```

--------------------------------

### Display NFL Seedr Simulation Structure (R)

Source: https://nflseedr.com/reference/nfl_simulations

This R code snippet displays the hierarchical structure of the simulation results. It is useful for understanding the organization of the data, including team standings, game details, and simulation parameters. No external libraries are required beyond the nflseedr package itself.

```r
str(sim, max.level = 3)
```

--------------------------------

### Create Pretty HTML Standings Table with nflseedR

Source: https://nflseedr.com/articles/articles/nflseedR

Generates a visually appealing HTML table of NFL standings using the `gt` package. This function takes the output from `nfl_standings()` and allows customization of grouping and sorting.

```r
nflseedR::nfl_standings_prettify(standings)
```

--------------------------------

### Simulate NFL Season Results with nflseedR

Source: https://nflseedr.com/articles/articles/nflsim2

This R code snippet simulates NFL season results using the nflseedR package. It takes a list of games (e.g., regular season games) and simulates a specified number of seasons over a given number of chunks. The output includes progress messages from the simulation process.

```r
sims <- nflseedR::nfl_simulations(
  games = all_games,
  simulations = 4,
  chunks = 2
)
#> ℹ 12:46:56 | Start simulation of 4 seasons in 2 chunks with a chunk size of 2.
#> ℹ 12:46:58 | CHUNK #1: Start simulation of regular season weeks "1", "2", "3",
#> …, "17", and "18"
#> ℹ 12:46:58 | Initiate Standings & Tiebreaking Data
#> ℹ 12:46:58 | Compute Division Ranks
#> ℹ 12:46:58 | Compute Conference Ranks
#> ℹ 12:46:58 | CHUNK #1: Start simulation of post season weeks "WC", "DIV",
#> "CON", and "SB"
#> ℹ 12:46:58 | Compute Draft Order
#> ℹ 12:46:58 | CHUNK #2: Start simulation of regular season weeks "1", "2", "3",
#> …, "17", and "18"
#> ℹ 12:46:58 | Initiate Standings & Tiebreaking Data
#> ℹ 12:46:58 | Compute Division Ranks
#> ℹ 12:46:58 | Compute Conference Ranks
#> ℹ 12:46:58 | CHUNK #2: Start simulation of post season weeks "WC", "DIV",
#> "CON", and "SB"
#> ℹ 12:46:58 | Compute Draft Order
#> ℹ 12:46:58 | Combine simulation data
#> ℹ 12:46:58 | Aggregate across simulations
#> ℹ 12:46:58 | DONE!
```

--------------------------------

### Simulate NFL Season and Elo Model in R

Source: https://nflseedr.com/articles/articles/nflsim

This R code demonstrates how to simulate an NFL season using the simulate_nfl function from the nflseedR package. It initializes random Elo values for each team and allows for stopping the simulation at a specific week to return the Elo model's results.

```r
initial_elo <- tibble::tibble(
  team = unique(nflseedR::divisions$team),
  elo = rnorm(length(unique(nflseedR::divisions$team)), 1500, 150)
)
test <- simulate_nfl(
  nfl_season = 2020,
  process_games = elo_model,
  elo = initial_elo,
  fresh_season = TRUE,
  test_week = 3
)
```

--------------------------------

### Load nflseedR and dplyr for NFL Season Simulation

Source: https://nflseedr.com/articles/articles/nflsim

Loads the nflseedR package for NFL season simulation and the dplyr package for data manipulation. It also sets global options for digit precision. These are foundational steps for running any simulation using the package.

```R
library(nflseedR)
library(dplyr, warn.conflicts = FALSE)
options(digits = 3)
```

--------------------------------

### Run NFL Simulation with Custom Game Model in R

Source: https://nflseedr.com/articles/articles/nflsim

This R code snippet demonstrates how to run the nflseedr simulation using a custom game model function. It calls the 'simulate_nfl' function, passing the 'stupid_games_model' to the 'process_games' argument. Other parameters like 'nfl_season', 'fresh_season', and 'simulations' are also set. The output displays the head and tail of the aggregated simulation results, sorted by team.

```r
sims2 <- simulate_nfl(
  nfl_season = 2020,
  process_games = stupid_games_model,
  fresh_season = TRUE,
  simulations = 100
)

sims2$overall |> dplyr::arrange(team) |> utils::head() |> knitr::kable()

sims2$overall |> dplyr::arrange(team) |> utils::tail() |> knitr::kable()
```

--------------------------------

### Simulate NFL Season with nflseedR

Source: https://nflseedr.com/reference/nfl_simulations

This R function simulates NFL games and potential playoff outcomes. It takes a games object, a results computation function, and simulation parameters as input. The function is designed for performance, supporting parallel computation via future::plan and progress updates via progressr::handlers. It can calculate playoff participants and simulate the post-season.

```r
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")
)
```

--------------------------------

### R: Custom Game Logic with Generic Arguments

Source: https://nflseedr.com/articles/articles/nflsim2

Defines a custom game model function in R that accepts generic arguments for 'best' and 'worst' teams. This function modifies game results based on these specified teams, allowing for biased simulations. It uses `rlang` for argument handling and `dplyr` for data manipulation.

```r
library(rlang)
biased_games_model <- function(teams, games, week_num, ...) {
  
  # collect all arguments in dots
  args <- list(...)
  
  # if "best" or "worst" are in dots, assign them to best of worst
  # if not, then args$best and args$worst will be NULL and we replace 
  # them with empty strings
  best <- args$best %||% "" 
  worst <- args$worst %||% ""

  # make the best team always win and the worst team always lose
  # otherwise, make the earlier alphabetical team win 90% of the time
  games <- games |>
    dplyr::mutate(
      result = dplyr::case_when(
        !is.na(result) | week != week_num ~ result,
        away_team == best | home_team == worst ~ -3,
        away_team == worst | home_team == best ~ 3,
        away_team < home_team ~ 
          sample(c(-3, 3), dplyr::n(), prob = c(0.9, 0.1), replace = TRUE),
        away_team > home_team ~ 
          sample(c(-3, 3), dplyr::n(), prob = c(0.1, 0.9), replace = TRUE),
        TRUE ~ 0
      )
    )
  
  # return values
  list(teams = teams, games = games)
}
```

--------------------------------

### Load and Inspect NFL Game Data using nflreadr

Source: https://nflseedr.com/reference/load_sharpe_games

This R code snippet demonstrates how to load NFL game data using the `load_sharpe_games()` function from the `nflreadr` package and then inspect its structure using `dplyr::glimpse()`. It includes error handling to prevent CRAN test issues.

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

--------------------------------

### Load and Prepare 2024 NFL Season Games (R)

Source: https://nflseedr.com/articles/articles/nflsim2

Loads the 2024 NFL season schedule and filters for regular season games. It then removes existing results and scores, setting them to NA, to prepare for simulation. This ensures that only missing results will be simulated.

```R
games <- nflreadr::load_schedules(2024) |> 
  dplyr::filter(game_type == "REG") |> 
  dplyr::mutate(
    result = NA_integer_,
    away_score = NA_integer_,
    home_score = NA_integer_
  )
```

--------------------------------

### Load NFL Games Data using nflseedR

Source: https://nflseedr.com/reference/load_sharpe_games

This function downloads and loads Lee Sharpe's NFL games dataset into memory. It acts as a convenient helper, abstracting away the need to manage the direct URL. It accepts arguments passed to the `nflreadr::load_schedules` function, such as specifying which 'seasons' to load.

```r
load_sharpe_games(...)

# Example: Load games for specific seasons
# load_sharpe_games(seasons = c(2020, 2021))
```

--------------------------------

### Analyze Overall Simulation Results for a Team

Source: https://nflseedr.com/articles/articles/nflsim

Filters the 'overall' results from the simulation data ('sims$overall') to display key statistics for a specific team (e.g., 'CHI'). It then formats the output using 'knitr::kable()' for a readable table, showing average wins, playoff appearance probability, and draft order.

```R
sims$overall |> dplyr::filter(team == "CHI") |> knitr::kable()
```

--------------------------------

### Simulate NFL Season

Source: https://nflseedr.com/reference/simulate_nfl

The primary function `simulate_nfl` allows users to simulate a given NFL season multiple times. It estimates and simulates game results, computes season outcomes including playoffs and draft order, and supports parallel processing and progress updates.

```APIDOC
## POST /simulate_nfl

### Description
Simulates a given NFL season multiple times using custom functions to estimate and simulate game results. Computes the outcome of the season, including playoffs and draft order. Supports parallel processing and progress updates.

### Method
POST

### Endpoint
/simulate_nfl

### Parameters
#### Query Parameters
- **nfl_season** (numeric) - The season to simulate.
- **process_games** (function) - A function to estimate and simulate the results of games. Uses team, schedule, and week number as arguments.
- **...** (any) - Additional parameters passed on to the `process_games` function.
- **playoff_seeds** (numeric) - Number of playoff teams per conference (default: 7 for season >= 2020, 6 otherwise).
- **if_ended_today** (boolean) - If TRUE, ignore remaining regular season games and cut to playoffs based on current regular season data.
- **fresh_season** (boolean) - Whether to simulate the season from scratch (TRUE) or take game results so far as a given and only simulate the rest (FALSE).
- **fresh_playoffs** (boolean) - Whether to simulate playoff game results from scratch (TRUE) or take results so far as a given and only simulate the rest (FALSE).
- **tiebreaker_depth** (numeric) - Controls the depth of tiebreakers applied (1, 2, or 3). Default is 3.
  - `1`: Break all ties with a coinflip.
  - `2`: Apply head-to-head and division win percentage tiebreakers. Random if still tied.
  - `3`: Apply all tiebreakers through strength of schedule. Random if still tied.
- **test_week** (numeric) - Aborts simulation after this week and returns results.
- **simulations** (numeric) - The number of times the given NFL season shall be simulated. Default is 1000.
- **sims_per_round** (numeric) - The number of simulations per round for parallel processing. Default calculates based on available cores.
- **.debug** (boolean) - Controls whether additional messages are printed to the console about tie-breaking algorithms.
- **print_summary** (boolean) - If TRUE, prints summary statistics to the console.
- **sim_include** (character array) - Specifies which parts of the simulation to include: "REG" (regular season), "POST" (postseason), "DRAFT" (draft order). Default is c("DRAFT", "REG", "POST").

### Request Example
```json
{
  "nfl_season": 2023,
  "simulations": 500,
  "playoff_seeds": 7,
  "sim_include": ["REG", "POST"]
}
```

### Response
#### Success Response (200)
- **results** (list of data frames) - Contains simulated game results, final standings, playoff outcomes, and draft order.
- **summary_stats** (data frame) - Summary statistics across all simulated seasons.
- **parameters** (list) - The parameters used for the simulation.

#### Response Example
```json
{
  "results": {
    "games": [
      { "week": 1, "home_team": "TeamA", "away_team": "TeamB", "home_score": 24, "away_score": 17, ... },
      ...
    ],
    "standings": [
      { "season": 1, "division": "AFC East", "team": "TeamA", "wins": 12, "losses": 5, ... },
      ...
    ],
    "playoffs": [
      { "season": 1, "round": "Wild Card", "winner": "TeamA", "loser": "TeamC", ... },
      ...
    ],
    "draft": [
      { "season": 1, "pick": 1, "team": "TeamX", ... },
      ...
    ]
  },
  "summary_stats": {
    "avg_wins": { "TeamA": 11.5, ... },
    "playoff_appearances": { "TeamA": 0.95, ... },
    "championship_wins": { "TeamA": 0.2, ... },
    ...
  },
  "parameters": {
    "nfl_season": 2023,
    "simulations": 500,
    ...
  }
}
```
```

--------------------------------

### Ensure Reproducible RNG with L'Ecuyer-CMRG Seed

Source: https://nflseedr.com/reference/nfl_simulations

Explains how to achieve reproducible random number generation (RNG) when using nflseedR, particularly when parallel processing with the 'furrr' package. It emphasizes the need to set the seed with the 'L'Ecuyer-CMRG' type for consistent results across parallel computations. The code demonstrates how to set and verify the RNG kind and seed.

```R
set.seed(5, "L'Ecuyer-CMRG")
RNGkind()
.Random.seed
```

--------------------------------

### Load NFL Schedules and Calculate Standings (R)

Source: https://nflseedr.com/reference/nfl_standings

This R code snippet loads NFL game schedules for specified seasons and then calculates team standings using the nflseedR package. It handles potential CRAN test issues by wrapping the loading function in a try-catch block. The output includes season, team, conference, division, games played, wins, true wins, losses, ties, points for (pf), and other relevant metrics.

```r
try({
  games <- nflreadr::load_schedules(2021:2022)
})
standings <- nflseedR::nfl_standings(games)
print(standings, digits = 3)
```

--------------------------------

### NFL Seedr Simulation Completion Time and Class

Source: https://nflseedr.com/reference/simulate_nfl

Displays the POSIXct formatted completion time of the NFL Seedr simulation and its class attribute, which indicates the type of object. This is useful for understanding when the simulation concluded and verifying its object type.

```r
#>   ..$ finished_at     : POSIXct[1:1], format: "2025-11-16 12:41:01"
#>  - attr(*, "class")= chr "nflseedR_simulation"
# }
```

--------------------------------

### Summarize NFL Simulation Results in R

Source: https://nflseedr.com/articles/articles/nflsim

Generates a summary of an NFL simulation object in R using the 'summary()' function. This function, when applied to an nflseedR simulation object (like 'sims3'), produces a formatted table (gt table) detailing various performance metrics across different divisions and teams, such as average wins, playoff appearances, division wins, conference wins, and Super Bowl wins.

```R
summary(sims3)
```

--------------------------------

### Configure Default Parallel Processing in R

Source: https://nflseedr.com/reference/nfl_simulations

Sets a default parallel processing plan for R sessions by modifying the user's R environment file. This ensures that futures are resolved using the specified method, such as 'multisession', by default. Restarting the R session is required for the changes to take effect. This impacts how functions that utilize the 'future' package will execute.

```R
usethis::edit_r_environ()
R_FUTURE_PLAN="multisession"
inherits(future::plan(), "sequential")
```

--------------------------------

### View Individual Season Performance Data

Source: https://nflseedr.com/articles/articles/nflsim

Extracts and displays the performance data for a specific team ('CHI') across individual simulations. It selects relevant columns such as simulation number, team, wins, playoff seed, and draft order, then shows the first six rows using 'utils::head()' and 'knitr::kable()'.

```R
sims$teams |
  dplyr::filter(team == "CHI") |
  dplyr::select(sim, team, wins, seed, draft_order) |
  utils::head(6) |
  knitr::kable()
```

--------------------------------

### Load NFL Game Data

Source: https://nflseedr.com/articles/articles/nflseedR

Loads NFL game data for specified seasons using the `nflreadr` package. This data is a prerequisite for calculating standings.

```r
games <- nflreadr::load_schedules(2023:2024)
```
Tokens:
Raw