Calculate Predictive Probabilities for the Upcoming UFC Fight Card

Automatically identifies the next scheduled UFC event from the provided datasets and calculates win probabilities and method-of-victory prop spreads (KO/TKO, Submission, Decision) for every matchup on the card.

get_upcoming_fight_probs(
  method_type = "multinomial",
  fights_data = ufc_fights,
  athletes_data = ufc_athletes,
  predictors = NULL,
  plot_chart = TRUE
)

Arguments

method_type: A character string specifying the modeling approach. Must be one of "multinomial", "bradley-terry", or "thurstone-mosteller". Default is "multinomial".
fights_data: A data frame containing historical and upcoming UFC bout records. Upcoming fights must have NA in the f1_result column.
athletes_data: A data frame containing fighter biographies and aggregate statistics.
predictors: A character vector of column names to use as independent variables. If NULL, a comprehensive default set of differential metrics is utilized.
plot_chart: Logical. If TRUE, generates a faceted ggplot2 bar chart visualizing the implied probabilities for the entire card. Default is TRUE.

Value

An S3 object of class fight_prediction_card containing:

event_title: String of the upcoming event name.
model_name_label: String detailing the statistical method used.
model: The final fitted model object (nnet::multinom or BradleyTerry2::BTm).
method_probs: A data frame containing the modeled probabilities for each fighter and method.
plot: A ggplot2 object visualizing the card's probability spread.
plot_chart: Logical indicating if the plot was generated.

Details

The function supports three modeling engines: * Multinomial Logistic Regression: Computes feature differentials (e.g., age, reach, striking defense) between paired fighters and fits a multinomial model to predict the exact method of victory. * Bradley-Terry (Logit) & Thurstone-Mosteller (Probit): Graph-theoretic approaches that treat the UFC roster as a network. For each fight, the engine builds a localized, 2-degree subgraph of historical opponents to estimate latent fighter "abilities" (\(\lambda\)). Win probabilities are derived from the difference in abilities, while method props are proportionally distributed using the fighters' historical win-method distributions.

Examples

if (FALSE) { # \dontrun{
# Run multinomial logistic regression on the upcoming card
card_predictions <- get_upcoming_fight_probs(
  method_type = "multinomial",
  fights_data = my_fights_df,
  athletes_data = my_athletes_df
)

# Print CLI summary
print(card_predictions)

# View the faceted probability chart
plot(card_predictions$plot)
} # }