The IRW competition data standard is meant to describe data derived from pairwise comparisons or competitions. Such data are widely analyzed using Elo or Bradley-Luce-Terry approaches; more information about these approaches is available here. The key distinction between these data and the conventional IRW data is that there are not id and item identifiers here but rather identifiers of the two agents that are involved in a given competition.
These tables form the competitions data family (source = "comp"). Despite the name, the family covers more than contests between teams, players or models: it also holds choices between two fixed things, such as essays judged against each other or votes between two named options, where the same named entities are compared again and again. When the things compared are instead put together at random from a set of attributes for each comparison, the data come from a conjoint experiment and belong to the conjoint family.
agent_a name/id of first competitoragent_b name/id of second competitordate Time of the data point in UNIX format.homefield Indicator of agent that had advantage based on game features (e.g., where game was played, who played first, etc).score_a Score of agent_a.score_b Score of agent_b.winner Winner of the competition (typically based on a comparison of scores). Values will be agent_a, agent_b or draw.Additional information that may be predictive of the outcome can be included as additional columns.
In some tables the two agents are listed in outcome order: agent_a is the winner by construction, so winner is agent_a in every row and the outcome is carried by the ordering rather than by the column. This is the native form of the source for dominance observations, where an interaction is recorded as a winner and a loser, and for comparative judgement, where it is recorded as the option chosen and the option passed over. As of October 2026 it is how 36 of the family’s 119 tables are built, among them every animal dominance table.
Elo and Bradley-Terry fits are unaffected, since a winner-loser dyad is what they take. Two other things do follow. Code that symmetrises or shuffles the pair before fitting will destroy the outcome, and winner is a constant column in these tables, so it cannot be used to split, filter or weight them. Most of them also carry no score_a/score_b, which leaves the ordering as the only record of who won; the Elo recipe below, keyed on score(score_a, score_b), does not apply to those tables.
Where an agent is never beaten, or never wins, its Bradley-Terry strength has no finite maximum-likelihood estimate. This is a property of the dominance structure rather than of the ordering convention, and BTm(..., br = TRUE) handles it; see the worked example below.
Before looping a model across the family, length(unique(df$winner)) == 1 identifies the tables that use this convention.
The competitions data can be accessed from both the R and Python irw packages:
# Install the package with `install.packages("irw")` (on CRAN; see the Get Started page for redivis)
library(irw)
# View available competition data
irw_list_tables(source="comp")
# Fetch competition data
df <- irw_fetch("collegefb_2021and2022", source="comp")
head(df)# Install package with `pip install irw`
import irw
# View available competition data
irw.list_tables(source="comp")
# Fetch competition data
df = irw.fetch("collegefb_2021and2022", source="comp")
head(df)Documentation related to the tables (including table names as with collegefb_2021and2022) can be found here.
The family holds 121 tables and 120.5 million contests in all. Tables range widely in size: the median table has 11,650 contests between 121 competitors, while the largest, Kaggle simulation leaderboards drawn from Meta Kaggle (18 tables), hold millions of games each and account for 72% of all contests. Each table’s own counts are in irw_metadata(source = "comp") (columns n_responses and n_actors).
Each table links to its own page, with citation, licence and fetch snippets.
Showing 121 of 121 tables. Fetch any of them with irw_fetch("<table>", source = "comp") or irw.fetch("<table>", source="comp").
Here is a first example wherein we fit an Elo model to data from the NFL.
library(elo)
library(BradleyTerry2)
# Fetch and prepare data
df <- irw::irw_fetch("fivethirtyeight_nfl_1920_2023", source = 'comp')
df <- df[df$season >= 2010 & df$season <= 2019, ] # the 2010-2019 seasons, playoffs included
df <- df[order(df$date), ]
# ===== Elo ANALYSIS =====
er <- elo.run(score(score_a, score_b) ~ agent_a + agent_b,
data = df, k = 20)
# Convert Elo results to long format
elo_results <- as.data.frame(er)
elo_long <- lapply(seq_len(nrow(elo_results)), function(i) {
data.frame(
team = c(elo_results$team.A[i], elo_results$team.B[i]),
elo = c(elo_results$elo.A[i], elo_results$elo.B[i]),
date = df$date[i]
)
})
elo_long <- do.call(rbind, elo_long)
# Convert dates to years since the start of the 2010 season
elo_long$year <- (elo_long$date - as.numeric(as.POSIXct("2010-09-01", tz = "UTC")))/(365.25*24*60*60)
elo_by_team <- split(elo_long, elo_long$team)
# ===== BRADLEY-TERRY ANALYSIS =====
# Prepare data for BT model
df_bt <- df[df$winner != 'draw', ]
df_bt$win <- as.numeric(df_bt$winner == 'agent_a')
df_bt$agent_a <- factor(df_bt$agent_a)
df_bt$agent_b <- factor(df_bt$agent_b)
# Fit BT models by season. br = TRUE uses bias-reduced estimation: a team that
# never won in a season (Cleveland in 2017) has no finite maximum-likelihood
# strength, and this keeps its estimate on the same scale as everyone else.
# Each season is a separate model with its own reference team, so the
# coefficients are centred within season to make them comparable across years.
bt_by_season <- lapply(split(df_bt, df_bt$season), function(season_df) {
mod <- BTm(win, agent_a, agent_b, data = season_df, id = "team", br = TRUE)
co <- coef(mod)
names(co) <- gsub("team", "", names(co))
co <- c(co, setNames(0, setdiff(levels(season_df$agent_a), names(co)))) # the reference team
data.frame(
season = unique(season_df$season),
est = co - mean(co),
team = names(co),
row.names = NULL
)
})
bt_results <- do.call(rbind, bt_by_season)
bt_by_team <- split(bt_results, bt_results$team)
# ===== PLOTTING =====
# Thirty-two labels at the right edge overwrite each other, so only the three
# strongest and three weakest teams at the end of the window are drawn dark and
# named; the rest are context. Labels are nudged apart where they would collide.
spread_labels <- function(y, min_gap) {
o <- order(y); y_s <- y[o]
for (k in seq_along(y_s)[-1]) y_s[k] <- max(y_s[k], y_s[k - 1] + min_gap)
y[o] <- y_s; y
}
plot_teams <- function(by_team, xcol, ycol, min_gap, n_label = 3) {
final <- sapply(by_team, function(d) d[[ycol]][nrow(d)])
picked <- names(sort(final))[c(seq_len(n_label), length(final) - seq_len(n_label) + 1)]
for (team_data in by_team[setdiff(names(by_team), picked)])
lines(team_data[[xcol]], team_data[[ycol]], col = rgb(0, 0, 0, 0.15))
for (team_data in by_team[picked])
lines(team_data[[xcol]], team_data[[ycol]], col = rgb(0, 0, 0, 0.8), lwd = 1.5)
y_lab <- spread_labels(final[picked], min_gap)
x_lab <- sapply(by_team[picked], function(d) d[[xcol]][nrow(d)])
text(x_lab, y_lab, picked, pos = 4, cex = 0.7, xpd = TRUE)
}
par(mfrow = c(2, 1), mgp = c(2.5, 0.7, 0), mar = c(4, 4, 2, 2))
# Plot 1: Elo ratings over time
plot(NULL,
xlim = c(0, 10),
ylim = c(1200, 1800),
xlab = "Years since start of 2010 season",
ylab = "Elo Rating",
main = "NFL Team Elo Ratings (2010-2019)",
xaxt = "n")
axis(1, at = 0:10)
plot_teams(elo_by_team, "year", "elo", min_gap = 40)
# Plot 2: Bradley-Terry strengths by season, centred within season
plot(NULL,
xlim = c(2010, 2020),
ylim = range(bt_results$est, na.rm = TRUE) + c(-0.3, 0.6),
xlab = "Season",
ylab = "Strength (season-centred)",
main = "NFL Team Strength by Season (Bradley-Terry Model)",
xaxt = "n")
axis(1, at = 2010:2019)
plot_teams(bt_by_team, "season", "est", min_gap = 0.4)