Skip to contents

Functions to efficiently simulate and evaluate college football seasons: standings with a documented tiebreaker cascade, conference champions, College Football Playoff (CFP) seeding, and week-by-week season simulation with a pluggable results generator.

cfbseedR is adapted from nflseedR (MIT) by Lee Sharpe and Sebastian Carl of the nflverse, and is part of the SportsDataverse.

Data freshness and pipeline status for every SportsDataverse dataset: sportsdataverse.org/status.

Installation

You can install the CRAN version of cfbseedR with:

install.packages("cfbseedR")

You can install the latest build from R-universe with:

install.packages("cfbseedR", repos = c("https://sportsdataverse.r-universe.dev", getOption("repos")))

You can install the development version of cfbseedR from GitHub with:

if (!requireNamespace("pak", quietly = TRUE)) install.packages("pak")
pak::pak("sportsdataverse/cfbseedR")
# or, with remotes:
# if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
# remotes::install_github("sportsdataverse/cfbseedR")

Quick start

library(cfbseedR)

# Bundled toy season (9 teams, 2 conferences + 1 independent)
games <- cfb_games_example
teams <- cfb_teams_example

# Standings with conference ranks and champions
standings <- cfb_standings(games, teams, tiebreaker_depth = "POINTS")

# Simulate a season 100 times (blank results are simulated)
games$result[games$week >= 3] <- NA
set.seed(42)
sim <- cfb_simulations(games, teams, simulations = 100, playoff_seeds = 4)
sim$overall

# Pretty gt summary, grouped by conference.
# Needs the optional presentation packages: install.packages(c("gt", "scales"))
summary(sim)

# Spread the simulations across cores
# future::plan("multisession")
# sim <- cfb_simulations(games, teams, simulations = 10000, chunks = 8)

# Real data via cfbfastR (install it separately; the engine never needs it)
# sched <- cfbfastR::load_cfb_schedules(2024)
# games <- cfb_games_from_schedule(sched)

See the Getting started article for a full walkthrough and Simulating seasons for custom compute_results functions, the tiebreaker ladder, and CFP-12 seeding rules.

Function naming convention

Following the SportsDataverse convention, the engine’s user-facing exports are prefixed with cfb_: cfb_standings(), cfb_playoff_seeds(), cfb_simulations(), and cfb_games_from_schedule(). Two helpers mirror their nflseedR namesakes instead: cfbseedR_compute_results() (the default results generator, after nflseedR_compute_results()) and simulations_verify_fct() (the custom-generator contract checker).

CFB semantics

  • Conferences first, divisions on demand. Standings group by conference; independents ("FBS Independents" or NA conference) appear in overall standings but get no conference rank. Supplying a conf_division column on teams opts a conference into division-format ranking (division champions take conf_rank 1-2 — the 2026 Sun Belt, or any historical divisional season).
  • Conference championship games (game_type == "CONF_CHAMP") count toward the overall record and decide the conference champion, but do not count toward the conference record/rank.
  • Official per-conference tiebreakers, season-scoped. The SEC, Big Ten, Big 12, ACC (including its all-new 2026 policy with the alternate-game-count candidate-pool rule), MAC, American, Conference USA, Mountain West, and Sun Belt procedures are registered as dated epochs; unregistered conferences (e.g. the re-formed Pac-12, which has not published a procedure) use a documented generic cascade.
  • CFP 12-team straight seeding via cfb_playoff_seeds(), with a season-keyed autobid policy: "2026" (default) puts the ACC / Big 12 / Big Ten / SEC champions in regardless of ranking, plus the highest-ranked Group-of-6 team (champion or not) and Notre Dame when ranked inside the field; "2025" keeps the five-best-champions rule. The field is seeded strictly by committee rank (rankings).

Documented simplifications vs. real CFB / nflseedR

  • External metric composites (SportSource, Connelly SP+, ESPN SOR, KPI, APR, CFP rankings) enter the official tiebreakers only through tiebreaker_data — the package computes none of them; absent inputs skip their rungs deterministically and are recorded in tiebreak_notes. All cascade quantities the package does compute are regular-season-conference-scoped, so conference ranks depend only on conference play.
  • sov/sos in the standings output are conference-scoped (opponents’ conference records over regular-season conference games; sov over conference victories, sos over conference opponents); independents get 0.
  • When rankings = NULL, cfb_playoff_seeds() falls back to ordering teams by win pct, SOV, SOS, and point differential instead of a committee ranking.
  • Committee rankings are static across simulations.
  • Conference championship matchups are simulated as scheduled — the engine does not re-derive participants from simulated standings.
  • Playoff games are generated only when the input games has no game_type == "POST" rows; the first round is hosted by the higher seed, later rounds are neutral-site.
  • No draft order and no simulate_nfl()-style legacy v1 API — the former is not a CFB concept, the latter would be new-package cruft.

Attribution

The architecture (standings init → conference ranks → seeds; week-loop simulation with pluggable compute_results; ELO-based default results generator) is a direct adaptation of nflseedR (MIT), Copyright (c) Lee Sharpe and Sebastian Carl. Huge thanks to them and the broader nflverse team for the original design.

Companion packages

The SportsDataverse

cfbseedR is part of the SportsDataverse, a set of open-source packages for sports data.

Package Sport / Scope
cfbfastR College football
hoopR Men’s basketball (NBA and NCAA)
wehoop Women’s basketball (WNBA and NCAA)
fastRhockey Hockey (NHL and PWHL)
baseballr Baseball (MLB, MiLB, NCAA)
softballR College softball
oddsapiR Sports betting odds
recruitR College football recruiting
usfootballR US soccer
cfbseedR · cfb4th CFB playoff simulation · fourth-down decisions
cfbplotR · sdvplotR · sportyR Logos, colors, tables · playing surfaces
sportsdataverse-R Umbrella R metapackage
sportsdataverse-py · sportsdataverse.js Python and Node.js

See the full ecosystem at sportsdataverse.org.

Follow the SportsDataverse on X and star this repo

X Follow

GitHub stars

Star history of sportsdataverse/cfbseedR

Our Authors

Cheat sheet

A printable one-page reference for cfbseedR, shared with cfbplotR and cfb4th.

📄 Download the cfbplotR / cfb4th / cfbseedR cheat sheet (PDF)

Free to download, print and hand out; light and dark, US Letter landscape. Every SportsDataverse package has one — browse them all at sportsdataverse.org/cheatsheets.

Citations

To cite the cfbseedR R package in publications, use:

BibTeX Citation

@misc{gilani_cfbseedR,
  author = {Saiem Gilani and Sebastian Carl and Lee Sharpe},
  title = {cfbseedR: The SportsDataverse's R Package to Simulate and Evaluate College Football Seasons.},
  url = {https://cfbseedR.sportsdataverse.org/},
  year = {2026}
}

If you use the season-simulation methodology, please also cite nflseedR by Sebastian Carl and Lee Sharpe.

License

cfbseedR is released under the MIT License.