Skip to contents

cfbplotR

cfbplotR is an R package for plotting College Football (CFB) team logos, player headshots, wordmarks, and conference logos in ggplot2 graphics and gt tables. It is built on the ggpath package and follows the conventions established by nflplotR — porting that proven approach to college football.

Part of the SportsDataverse family of R packages for sports analytics.

Installation

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

# using the pak package (recommended):
if (!requireNamespace('pak', quietly = TRUE)){
  install.packages('pak')
}
pak::pak("sportsdataverse/cfbplotR")
# or using the devtools package:
if (!requireNamespace('devtools', quietly = TRUE)){
  install.packages('devtools')
}
devtools::install_github(repo = "sportsdataverse/cfbplotR")
# or clone and install locally
git clone https://github.com/sportsdataverse/cfbplotR
cd cfbplotR
Rscript -e "pak::local_install()"  # or: Rscript -e "devtools::install()"

Usage

You can follow the package tutorial for several detailed examples.

The core function geom_cfb_logos() adds CFB team logos to a ggplot. Axis helpers (scale_x_cfb(), scale_y_cfb()) replace axis labels with team logos via element_cfb_logo(). The gt_fmt_cfb_logo() helper adds logos inside gt table cells.

library(cfbplotR)
library(ggplot2)

# grab the first 32 valid team abbreviations
team <- valid_team_names()[1:32]
df <- data.frame(
  a     = rep(1:8, 4),
  b     = sort(rep(1:4, 8), decreasing = TRUE),
  teams = team
)

ggplot(df, aes(x = a, y = b)) +
  geom_cfb_logos(aes(team = teams), width = 0.075) +
  geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) +
  theme_void()
library(cfbplotR)
library(ggplot2)

# logos on the x-axis via scale_x_cfb() + element_cfb_logo()
df2 <- data.frame(
  team  = c("Alabama", "Georgia", "Ohio State", "Michigan"),
  score = c(42, 38, 35, 30)
)

ggplot(df2, aes(x = team, y = score)) +
  geom_col(aes(fill = team), show.legend = FALSE) +
  scale_x_cfb(labels = "logo") +
  theme_minimal() +
  theme(
    axis.text.x = element_cfb_logo(size = 1)
  )
library(cfbplotR)
library(gt)

# logos inside a gt table
data.frame(
  team  = c("Alabama", "Georgia", "Ohio State"),
  wins  = c(13, 12, 11)
) |>
  gt() |>
  gt_fmt_cfb_logo(columns = "team")

Documentation

For more information on the package and function reference, please see the cfbplotR documentation website.

There is also a printable cfbplotR cheat sheet (PDF), one of a set covering every SportsDataverse package.

The SportsDataverse

cfbplotR is part of the SportsDataverse, a family of open-source R, Python, and Node.js packages for sports data.

Package Sport / Scope
cfbfastR College football
hoopR Men’s basketball (NBA & NCAA)
wehoop Women’s basketball (WNBA & NCAA)
fastRhockey Hockey (NHL & PWHL)
baseballr Baseball (MLB, MiLB, NCAA)
oddsapiR Sports betting odds (The Odds API)
sportsdataverse-R Umbrella R metapackage
sportsdataverse-py · sportsdataverse.js Python & Node.js

See the full ecosystem at sportsdataverse.org.

Follow cfbplotR and the SportsDataverse on Twitter and star this repo

Twitter Follow

Twitter Follow

GitHub stars

Our Authors

Cheat sheet

A printable one-page reference covering cfbplotR, cfb4th and cfbseedR — the function families, the loaders, and what each one returns.

📄 Download the cfbplotR 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 cfbplotR R package in publications, use:

BibTex Citation

@misc{lee_carl_gilani_cfbplotR,
  author = {Lee, Jared and Gilani, Saiem and Carl, Sebastian},
  title = {cfbplotR: The SportsDataverse's R Package for College Football Plotting.},
  url = {https://cfbplotR.sportsdataverse.org},
  year = {2021}
}