The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Title: Functions to Calculate Optimal Fourth Down Decisions in the National Football League
Version: 1.0.4
Description: A set of functions to estimate outcomes of fourth down plays in the National Football League and obtain fourth down plays from https://www.nfl.com/ and https://www.espn.com/.
License: MIT + file LICENSE
URL: https://www.nfl4th.com/, https://github.com/nflverse/nfl4th/, https://github.com/nflverse/nfl4th
BugReports: https://github.com/nflverse/nfl4th/issues
Depends: R (≥ 3.6)
Imports: backports (≥ 1.1.6), curl, dplyr, glue, httr, janitor, jsonlite, magrittr, mgcv, nflfastR (≥ 4.0.0), nflreadr, purrr, rlang, stringr, tibble, tidyr, tidyselect, xgboost
Suggests: data.table, future, gt, nflplotR, rmarkdown, tictoc, testthat (≥ 2.0.0), withr
Encoding: UTF-8
RoxygenNote: 7.2.3
Config/testthat/edition: 2
NeedsCompilation: no
Packaged: 2023-08-18 14:05:05 UTC; carl
Author: Ben Baldwin [aut, cre, cph], Sebastian Carl [ctb]
Maintainer: Ben Baldwin <bbaldwin206@gmail.com>
Repository: CRAN
Date/Publication: 2023-08-21 09:32:33 UTC

nfl4th: Functions to Calculate Optimal Fourth Down Decisions in the National Football League

Description

logo

A set of functions to estimate outcomes of fourth down plays in the National Football League and obtain fourth down plays from https://www.nfl.com/ and https://www.espn.com/.

Author(s)

Maintainer: Ben Baldwin bbaldwin206@gmail.com [copyright holder]

Other contributors:

See Also

Useful links:

Get 2pt decision probabilities

Description

Get various probabilities associated with each option on PATs (go for it, kick PAT).

Usage

add_2pt_probs(df)

Arguments

df

A data frame of decisions to be computed for.

Value

Original data frame Data frame plus the following columns added:

first_down_prob, wp_fail, wp_succeed, go_wp, fg_make_prob, miss_fg_wp, make_fg_wp, fg_wp, punt_wp

wp_0

Win probability when scoring 0 points on PAT.

wp_1

Win probability when scoring 1 point on PAT.

wp_2

Win probability when scoring 2 points on PAT.

conv_1pt

Probability of making PAT kick.

conv_2pt

Probability of converting 2-pt attempt.

wp_go1

Win probability associated with going for 1.

wp_go2

Win probability associated with going for 2.

Examples


play <-
  tibble::tibble(
    # things to help find the right game (use "reg" or "post")
    home_team = "GB",
    away_team = "TB",
    posteam = "GB",
    type = "post",
    season = 2020,

    # information about the situation
    qtr = 4,
    quarter_seconds_remaining = 123,
    score_differential = -2,

    home_opening_kickoff = 0,
    posteam_timeouts_remaining = 3,
    defteam_timeouts_remaining = 3
  )

probs <- nfl4th::add_2pt_probs(play)

dplyr::glimpse(probs)

Get 4th down decision probabilities

Description

Get various probabilities associated with each option on 4th downs (go for it, kick field goal, punt).

Usage

add_4th_probs(df)

Arguments

df

A data frame of decisions to be computed for.

Value

Original data frame Data frame plus the following columns added:

go_boost

Gain (or loss) in win prob associated with choosing to go for it (percentage points).

first_down_prob

Probability of earning a first down if going for it on 4th down.

wp_fail

Win probability in the event of a failed 4th down attempt.

wp_succeed

Win probability in the event of a successful 4th down attempt.

go_wp

Average win probability when going for it on 4th down.

fg_make_prob

Probability of making field goal.

miss_fg_wp

Win probability in the event of a missed field goal.

make_fg_wp

Win probability in the event of a made field goal.

fg_wp

Average win probability when attempting field goal.

punt_wp

Average win probability when punting.

Examples


play <-
  tibble::tibble(
    # things to help find the right game (use "reg" or "post")
    home_team = "GB",
    away_team = "TB",
    posteam = "GB",
    type = "post",
    season = 2020,

    # information about the situation
    qtr = 4,
    quarter_seconds_remaining = 129,
    ydstogo = 8,
    yardline_100 = 8,
    score_differential = -8,

    home_opening_kickoff = 0,
    posteam_timeouts_remaining = 3,
    defteam_timeouts_remaining = 3
  )

probs <- nfl4th::add_4th_probs(play)

dplyr::glimpse(probs)

Get 4th down plays from a game

Description

Get 4th down plays from a game.

Usage

get_4th_plays(gid)

Arguments

gid

A game to get 4th down decisions of.

Details

Obtains a data frame that can be used with add_4th_probs(). The following columns must be present:

Value

Original data frame Data frame plus the following columns added:

desc

Play description from ESPN.

type_text

Play type text from ESPN.

index

Index number of play from a given game. Useful for tracking plays (e.g. for 4th down bot).

The rest

All the columns needed for ⁠add_4th_probs().⁠

Examples


plays <- nfl4th::get_4th_plays('2020_20_TB_GB')

dplyr::glimpse(plays)

Load calculated 4th down probabilities from nflfastR data

Description

Load calculated 4th down probabilities from nflfastR data.

Usage

load_4th_pbp(seasons, fast = FALSE)

Arguments

seasons

Seasons to load. Must be 2014 and later.

fast

Defaults to FALSE. If TRUE, loads pre-computed decisions from repository

Value

nflfastR data on 4th downs with the add_4th_probs() columns added and also the following:

go

100 if a team went for it on 4th down, 0 otherwise. It's 100 and 0 as a convenience for obtaining percent of times going for it.

Examples


try({# Wrap in try to avoid CRAN test problems
probs <- load_4th_pbp(2019:2020)
dplyr::glimpse(probs)
})

Get 2pt decision probabilities

Description

Get a table with the probabilities associated with a 2-pt decision.

Usage

make_2pt_table_data(probs)

Arguments

probs

A data frame consisting of one play that has had add_2pt_probs() already run on it.

Value

A table showing the probabilities associated with each possible choice.

Examples


play <-
  tibble::tibble(
    # things to help find the right game (use "reg" or "post")
    home_team = "GB",
    away_team = "TB",
    posteam = "GB",
    type = "post",
    season = 2020,

    # information about the situation
    qtr = 4,
    quarter_seconds_remaining = 123,
    score_differential = -2,

    home_opening_kickoff = 0,
    posteam_timeouts_remaining = 3,
    defteam_timeouts_remaining = 3
  )

probs <- nfl4th::add_2pt_probs(play)
nfl4th::make_2pt_table_data(probs)

Get 4th down decision probabilities

Description

Get a table with the probabilities on 4th down.

Usage

make_table_data(probs)

Arguments

probs

A data frame consisting of one play that has had add_4th_probs() already run on it.

Value

A table showing the probabilities associated with each possible choice.

Examples


play <-
  tibble::tibble(
    # things to help find the right game (use "reg" or "post")
    home_team = "GB",
    away_team = "TB",
    posteam = "GB",
    type = "post",
    season = 2020,

    # information about the situation
    qtr = 4,
    quarter_seconds_remaining = 129,
    ydstogo = 8,
    yardline_100 = 8,
    score_differential = -8,

    home_opening_kickoff = 0,
    posteam_timeouts_remaining = 3,
    defteam_timeouts_remaining = 3
  )

probs <- nfl4th::add_4th_probs(play)
nfl4th::make_table_data(probs)

Reset nfl4th Package Cache

Description

Reset nfl4th Package Cache

Usage

nfl4th_clear_cache(type = c("games", "fd_model", "wp_model", "all"))

Arguments

type

One of "games" (the default), "fd_model", or "all". "games" will remove an internally used games file. "fd_model" will remove the nfl4th 4th down model (only necessary in the unlikely case of a model update). "wp_model" will remove the nfl4th win probability model (only necessary in the unlikely case of a model update). "all" will remove all of the above.

Value

Returns TRUE invisibly if cache has been cleared.

Examples

nfl4th_clear_cache()

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.