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.

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

Our Authors

• Jared Lee
  

• Saiem Gilani
  

• Sebastian Carl
  

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}
}