Package 'NFLSimulatoR'

Title: Simulating Plays and Drives in the NFL
Description: The intent here is to enable the simulation of plays/drives and evaluate game-play strategies in the National Football League (NFL). Built-in strategies include going for it on fourth down and varying the proportion of passing/rushing plays during a drive. The user should be familiar with nflscrapR data before trying to write his/her own strategies. This work is inspired by a blog post by Mike Lopez, currently the Director of Data and Analytics at the NFL, Lopez (2019) <https://statsbylopez.netlify.app/post/resampling-nfl-drives/>.
Authors: Ryan Elmore [cre, aut] , Ben Williams [aut] , Will Palmquist [aut]
Maintainer: Ryan Elmore <[email protected]>
License: MIT + file LICENSE
Version: 0.4.0
Built: 2025-02-23 03:31:44 UTC
Source: https://github.com/rtelmore/nflsimulator

Help Index


Update the down and distance of a drive

Description

The down and distance updater will run a play and update various game-based statistics accordingly.

Usage

down_distance_updater(
  what_down,
  yards_to_go,
  yards_from_own_goal,
  play_by_play_data,
  ...
)

Arguments

what_down

The current down (1st, 2nd, 3rd, or 4th down)

yards_to_go

Number of yards to go until a first down or TD

yards_from_own_goal

The number of yards from the possession team's own goal

play_by_play_data

A data file from nflscrapR prepped using the prep_pbp_data.R function

...

Additional arguments for different strategies

Value

A data.frame object

Examples

## Not run: 
down_distance_updater(what_down = 1,
                      yards_to_go = 10,
                      yards_from_own_goal = 25,
                      play_by_play_data = pbp_data,
                      strategy = "normal")

## End(Not run)

Decision for 4th downs based on expected points

Description

This function will return the expected points for several 4th down decision. The options are "go for it", "field goal", or "punt". This should be primarily used within the 'NFLSimulatoR::sample_play()' function.

Usage

expected_pts_fourth(yards_from_goal, yards_to_go, play_data)

Arguments

yards_from_goal

The number of yards until a team scores a touchdown

yards_to_go

Number of yards to go until a first down or TD

play_data

A data file from nflscrapR prepped using the prep_pbp_data.R function

Value

A data.frame of the expected points of three fourth down options

Examples

## Not run: 
expected_pts_fourth(what_down = 1,
                      yards_to_go = 10,
                      yards_from_own_goal = 25,
                      play_by_play_data = reg_pbp_2018)

## End(Not run)

Add necessary columns to nflscrapR data

Description

Add necessary columns to nflscrapR data

Usage

prep_pbp_data(data)

Arguments

data

An nflscrapR or nflfastR data set. Note that stringsAsFactors = FALSE is assumed.

Value

a data.table object

Examples

## Not run: 
dt <- prep_pbp_data(nflscrapr_pbp_data)

## End(Not run)

Sample a Series of Drives, a strategy to test verses the normal strategy

Description

Sample a Series of Drives, a strategy to test verses the normal strategy

Usage

sample_drives(
  n_sims,
  from_yard_line = 25,
  play_by_play_data,
  strategy = "normal",
  single_drive = FALSE,
  progress = TRUE,
  ...
)

Arguments

n_sims

The number of simulations

from_yard_line

The starting field position (defaults to 25)

play_by_play_data

A data file from nflscrapR prepped using the prep_pbp_data.R function

strategy

"normal", "passes_rushes", or "fourth_downs"

single_drive

TRUE indicates only a single drive, otherwise, drives sampled until a score occurs

progress

logical for inclusion of a progress bar

...

Additional arguments for different strategies

Value

A data.frame of drives

Examples

## Not run: 
sample_drives(2, 25, dt)

## End(Not run)

Sample NFL play-by-play data with a specified 4th down strategy

Description

This function will return a sample play from the nflscrapR play-by-play data for a given down, distance, yards from the team's goal, using a given strategy on fourth down. The strategies are: empirical, always going for it on fourth down, never going for it on fourth down, go for it if one is less than a certain distance from a first down/touchdown, and go for it if it maximizes one's expected points. This should be primarily used within the 'NFLSimulatoR::sample_play()' function.

Usage

sample_fourth_down_strategy(
  what_down,
  yards_to_go,
  yards_from_own_goal,
  window_yards_from_own_goal = 1,
  play_by_play_data,
  fourth_down_strategy = "empirical",
  yards_less_than = 5
)

Arguments

what_down

The current down (1st, 2nd, 3rd, or 4th down)

yards_to_go

Number of yards to go until a first down or TD

yards_from_own_goal

The number of yards from the possession team's own goal

window_yards_from_own_goal

Precision parameter for "yards_from_own_goal" (a value of 1 means the sampling will occur within plus or minus 1 of the "yards_from_own_goal" value)

play_by_play_data

A data file from nflscrapR prepped using the prep_pbp_data.R function

fourth_down_strategy

The specific fourth down strategy 'empirical', 'always_go_for_it', 'never_go_for_it','yds_less_than','exp_pts'

yards_less_than

Parameter for 'yds_less_than' strategy. If using 'yds_less_than' strategy and one is less than 'yards_less_than' yards from first down/touchdown, then go for it on fourth down

Value

A tibble containing lots of info

Examples

## Not run: 
sample_fourth_down_strategy(what_down = 3,
                      yards_to_go = 2,
                      yards_from_own_goal = 45,
                      window_yards_from_own_goal = 2,
                      play_by_play_data = reg_pbp_2018,
                      fourth_down_strategy = "empirical")

## End(Not run)

Sample NFL play-by-play data with a specified blend of rushing and passing

Description

This function will return a sample play from the nflscrapR play-by-play data for a given down, distance, yards from the team's goal, using a given pass/rush play strategy. The user may choose a value for the proportion of passing plays to be sampled. Thus one can test strategies in which the team always passes, always runs, or some distribution of the two. This strategy is only intended for downs 1 - 3, and uses an empirical strategy for fourth downs. This should be primarily used within the 'NFLSimulatoR::sample_play()' function.

Usage

sample_passes_rushes_strategy(
  what_down,
  yards_to_go,
  yards_from_own_goal,
  window_yards_from_own_goal = 1,
  play_by_play_data,
  prop_passes = 0.5
)

Arguments

what_down

The current down (1st, 2nd, 3rd, or 4th down)

yards_to_go

Number of yards to go until a first down or TD

yards_from_own_goal

The number of yards from the possession team's own goal

window_yards_from_own_goal

Precision parameter for "yards_from_own_goal" (a value of 1 means the sampling will occur within plus or minus 1 of the "yards_from_own_goal" value)

play_by_play_data

A data file from nflscrapR prepped using the prep_pbp_data.R function

prop_passes

Proportion of plays that should be pass plays, between 0 and 1, inclusive

Value

A tibble containing lots of info

Examples

## Not run: 
sample_passes_rushes_strategy(what_down = 3,
                              yards_to_go = 2,
                              yards_from_own_goal = 45,
                              window_yards_from_own_goal = 2,
                              play_by_play_data = reg_pbp_2018,
                              prop_passes = 0.5)

## End(Not run)

Sample one NFL play according to some strategy

Description

This function will return a sample play from the nflscrapR play-by-play data for a given down, distance, yards from the team's goal, using the usual NFL-coaching strategy.

Usage

sample_play(
  what_down,
  yards_to_go,
  yards_from_own_goal,
  window_yards_from_own_goal = 1,
  play_by_play_data,
  strategy = "normal",
  ...
)

Arguments

what_down

The current down (1st, 2nd, 3rd, or 4th down)

yards_to_go

Number of yards to go until a first down or TD

yards_from_own_goal

The number of yards from the possession team's own goal

window_yards_from_own_goal

Precision parameter for "yards_from_own_goal" (a value of 1 means the sampling will occur within plus or minus 1 of the "yards_from_own_goal" value)

play_by_play_data

A data file from nflscrapR prepped using the prep_pbp_data.R function

strategy

A string describing the strategy to be used, default is "normal", others include: "fourth_downs" and "passes_rushes" which implement some strategy regarding 4th downs and proportion of plays that are passing plays, respectively.

...

Additional arguments for different strategies

Value

A tibble containing lots of info

Examples

## Not run: 
sample_play_test(what_down = 3,
                 yards_to_go = 2,
                 yards_from_own_goal = 45,
                 play_by_play_data = pbp_data,
                 strategy = "normal")

## End(Not run)