btd_foot: Bayesian Bradley-Terry-Davidson Model

In LeoEgidi/footBayes: Fitting Bayesian and MLE Football Models

Bayesian Bradley-Terry-Davidson Model

Description

Fits a Bayesian Bradley-Terry-Davidson model using Stan. Supports both static and dynamic ranking models, allowing for the estimation of team strengths over time.

Usage

btd_foot(
  data,
  dynamic_rank = FALSE,
  home_effect = FALSE,
  prior_par = list(logStrength = normal(0, 3), logTie = normal(0, 0.3), home = normal(0,
    5)),
  rank_measure = "median",
  method = "MCMC",
  ...
)

Arguments

data	A data frame containing the observations with columns: periods: Time point of each observation (integer >= 1). home_team: Home team's name (character string). away_team: Away team's name (character string). match_outcome: Outcome (1 if home team beats away team, 2 for tie, and 3 if away team beats home team). The data frame must not contain missing values.
dynamic_rank	A logical value indicating whether a dynamic ranking model is used (default is FALSE).
home_effect	A logical value indicating the inclusion of a home effect in the model. (default is FALSE).
prior_par	A list specifying the prior distributions for the parameters of interest, using the normal function: logStrength: Prior for the team log-strengths. Default is normal(0, 3). logTie: Prior for the tie parameter. Default is normal(0, 0.3). home: Prior for the home effect (home). Applicable only if home_effect = TRUE. Default is normal(0, 5). Only normal priors are allowed for this model.
rank_measure	A character string specifying the method used to summarize the posterior distributions of the team strengths. Options are: "median": Uses the median of the posterior samples (default). "mean": Uses the mean of the posterior samples. "map": Uses the Maximum A Posteriori estimate, calculated as the mode of the posterior distribution.
method	A character string specifying the method used to obtain the Bayesian estimates. Options are: "MCMC": Markov chain Monte Carlo algorithm (default). "VI": Automatic differentiation variational inference algorithms. "pathfinder": Pathfinder variational inference algorithm. "laplace": Laplace algorithm.
...	Additional arguments passed to cmdstanr (e.g., iter_sampling, chains, parallel_chains).

Value

An object of class "btdFoot", which is a list containing:

• fit: The fitted CmdStanFit object returned by cmdstanr.

• rank: A data frame with the rankings, including columns:

  • periods: The time period.

  • team: The team name.

  • rank_points: The estimated strength of the team based on the chosen rank_measure.

• data: The input data.

• stan_data: The data list passed to Stan.

• stan_code: The Stan code of the underline model.

• stan_args: The optional cmdstanr parameters passed to (...).

• rank_measure: The summary statistic used to compute the rankings.

• alg_method: The inference algorithm used to obtain the Bayesian estimates.

Author(s)

Roberto Macrì Demartino [e-mail].

Examples

## Not run: 
if (instantiate::stan_cmdstan_exists()) {
  library(dplyr)

  data("italy")

  italy_2020_2021 <- italy %>%
    dplyr::select(Season, home, visitor, hgoal, vgoal) %>%
    dplyr::filter(Season == "2020" | Season == "2021") %>%
    dplyr::mutate(match_outcome = dplyr::case_when(
      hgoal > vgoal ~ 1, # Home team wins
      hgoal == vgoal ~ 2, # Draw
      hgoal < vgoal ~ 3 # Away team wins
    )) %>%
    dplyr::mutate(periods = dplyr::case_when(
      dplyr::row_number() <= 190 ~ 1,
      dplyr::row_number() <= 380 ~ 2,
      dplyr::row_number() <= 570 ~ 3,
      TRUE ~ 4
    )) %>% # Assign periods based on match number
    dplyr::select(periods,
      home_team = home,
      away_team = visitor, match_outcome
    )

  # Dynamic Ranking Example with Median Rank Measure
  fit_result_dyn <- btd_foot(
    data = italy_2020_2021,
    dynamic_rank = TRUE,
    home_effect = TRUE,
    prior_par = list(
      logStrength = normal(0, 10),
      logTie = normal(0, 5),
      home = normal(0, 5)
    ),
    rank_measure = "median",
    iter_sampling = 1000,
    parallel_chains = 2,
    chains = 2
  )

  print(fit_result_dyn)

  print(fit_result_dyn, pars = c("logStrength", "home"), teams = c("AC Milan", "AS Roma"))

  # Static Ranking Example with MAP Rank Measure
  fit_result_stat <- btd_foot(
    data = italy_2020_2021,
    dynamic_rank = FALSE,
    prior_par = list(
      logStrength = normal(0, 10),
      logTie = normal(0, 5),
      home = normal(0, 5)
    ),
    rank_measure = "map",
    iter_sampling = 1000,
    parallel_chains = 2,
    chains = 2
  )

  print(fit_result_stat)
}

## End(Not run)

LeoEgidi/footBayes documentation built on June 2, 2025, 11:32 a.m.