# **cfbplotR**

[**`cfbplotR`**](https://cfbplotR.sportsdataverse.org/) is an R package
for plotting College Football (CFB) team logos, player headshots,
wordmarks, and conference logos in
[**`ggplot2`**](https://ggplot2.tidyverse.org/) graphics and
[**`gt`**](https://gt.rstudio.com/) tables. It is built on the
[**`ggpath`**](https://mrcaseb.github.io/ggpath/) package and follows
the conventions established by
[nflplotR](https://nflplotr.nflverse.com/) — porting that proven
approach to college football.

Part of the [SportsDataverse](https://sportsdataverse.org/) family of R
packages for sports analytics.

## **Installation**

You can install the development version of
[**`cfbplotR`**](https://github.com/sportsdataverse/cfbplotR) from
[GitHub](https://github.com/sportsdataverse/cfbplotR) with:

``` r

# using the pak package (recommended):
if (!requireNamespace('pak', quietly = TRUE)){
  install.packages('pak')
}
pak::pak("sportsdataverse/cfbplotR")
```

``` r

# or using the devtools package:
if (!requireNamespace('devtools', quietly = TRUE)){
  install.packages('devtools')
}
devtools::install_github(repo = "sportsdataverse/cfbplotR")
```

``` r
# 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.](https://cfbplotR.sportsdataverse.org/articles/tutorial.html)

The core function
[`geom_cfb_logos()`](https://cfbplotR.sportsdataverse.org/reference/geom_cfb_logos.md)
adds CFB team logos to a ggplot. Axis helpers
([`scale_x_cfb()`](https://cfbplotR.sportsdataverse.org/reference/scale_axes_cfb.md),
[`scale_y_cfb()`](https://cfbplotR.sportsdataverse.org/reference/scale_axes_cfb.md))
replace axis labels with team logos via
[`element_cfb_logo()`](https://cfbplotR.sportsdataverse.org/reference/element.md).
The
[`gt_fmt_cfb_logo()`](https://cfbplotR.sportsdataverse.org/reference/gt_cfb.md)
helper adds logos inside `gt` table cells.

``` r

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()
```

``` r

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)
  )
```

``` r

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](https://cfbplotR.sportsdataverse.org).

## **The SportsDataverse**

`cfbplotR` is part of the
[**SportsDataverse**](https://sportsdataverse.org/), a family of
open-source R, Python, and Node.js packages for sports data.

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

See the full ecosystem at
[sportsdataverse.org](https://sportsdataverse.org/).

## Follow [cfbplotR](https://twitter.com/cfbfastR) and the [SportsDataverse](https://twitter.com/SportsDataverse) on Twitter and star this repo

[![Twitter
Follow](https://img.shields.io/twitter/follow/JaredDLee?color=blue&label=%40JaredDLee&logo=twitter&style=for-the-badge)](https://twitter.com/JaredDLee)

[![Twitter
Follow](https://img.shields.io/twitter/follow/SportsDataverse?color=blue&label=%40SportsDataverse&logo=twitter&style=for-the-badge)](https://twitter.com/SportsDataverse)

[![GitHub
stars](https://img.shields.io/github/stars/sportsdataverse/cfbplotR.svg?color=eee&logo=github&style=for-the-badge&label=Star%20cfbplotR&maxAge=2592000)](https://github.com/sportsdataverse/cfbplotR/stargazers/)

## **Our Authors**

- [Jared Lee](https://twitter.com/JaredDLee)
  [![@JaredDLee](https://img.shields.io/twitter/follow/JaredDLee?color=blue&label=%40JaredDLee&logo=twitter&style=for-the-badge)](https://twitter.com/JaredDLee)
  [![@Kazink36](https://img.shields.io/github/followers/Kazink36?color=eee&logo=Github&style=for-the-badge)](https://github.com/Kazink36)

- [Saiem Gilani](https://twitter.com/saiemgilani)
  [![@saiemgilani](https://img.shields.io/twitter/follow/saiemgilani?color=blue&label=%40saiemgilani&logo=twitter&style=for-the-badge)](https://twitter.com/saiemgilani)
  [![@saiemgilani](https://img.shields.io/github/followers/saiemgilani?color=eee&logo=Github&style=for-the-badge)](https://github.com/saiemgilani)

- [Sebastian Carl](https://twitter.com/mrcaseb)
  [![@mrcaseb](https://img.shields.io/twitter/follow/mrcaseb?color=blue&label=%40mrcaseb&logo=twitter&style=for-the-badge)](https://twitter.com/mrcaseb)
  [![@mrcaseb](https://img.shields.io/github/followers/mrcaseb?color=eee&logo=Github&style=for-the-badge)](https://github.com/mrcaseb)

## **Citations**

To cite the [**`cfbplotR`**](https://cfbplotR.sportsdataverse.org/) R
package in publications, use:

BibTex Citation

``` bibtex
@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}
}
```

# Package index

## Logos, Wordmarks & Headshots

ggplot2 geoms and ggproto objects for rendering CFB team logos,
wordmarks, and player headshots on plots.

- [`GeomCFBheads`](https://cfbplotR.sportsdataverse.org/reference/geom_cfb_logos.md)
  [`geom_cfb_logos()`](https://cfbplotR.sportsdataverse.org/reference/geom_cfb_logos.md)
  [`GeomCFBlogo`](https://cfbplotR.sportsdataverse.org/reference/geom_cfb_logos.md)
  : ggplot2 Layer for Visualizing CFB Team Logos
- [`geom_cfb_headshots()`](https://cfbplotR.sportsdataverse.org/reference/geom_cfb_headshots.md)
  : ggplot2 Layer for Visualizing CFB Player Headshots
- [`geom_cfb_wordmarks()`](https://cfbplotR.sportsdataverse.org/reference/geom_cfb_wordmarks.md)
  : ggplot2 Layer for Visualizing CFB Team Wordmarks

## Theme Elements

Image-based ggplot2 theme elements for axis text — replace tick labels
with CFB logos, wordmarks, or headshots.

- [`element_cfb_logo()`](https://cfbplotR.sportsdataverse.org/reference/element.md)
  [`element_cfb_wordmark()`](https://cfbplotR.sportsdataverse.org/reference/element.md)
  [`element_cfb_headshot()`](https://cfbplotR.sportsdataverse.org/reference/element.md)
  [`element_grob(`*`<element_cfb_logo>`*`)`](https://cfbplotR.sportsdataverse.org/reference/element.md)
  [`element_grob(`*`<element_cfb_wordmark>`*`)`](https://cfbplotR.sportsdataverse.org/reference/element.md)
  [`element_grob(`*`<element_cfb_headshot>`*`)`](https://cfbplotR.sportsdataverse.org/reference/element.md)
  : Theme Elements for Image Grobs

## Scales & Axes

CFB color/fill scales and logo/headshot axis annotation scales.

- [`scale_color_cfb()`](https://cfbplotR.sportsdataverse.org/reference/scale_color_cfb.md)
  [`scale_colour_cfb()`](https://cfbplotR.sportsdataverse.org/reference/scale_color_cfb.md)
  [`scale_fill_cfb()`](https://cfbplotR.sportsdataverse.org/reference/scale_color_cfb.md)
  : Scale for college football team colors
- [`scale_x_cfb()`](https://cfbplotR.sportsdataverse.org/reference/scale_axes_cfb.md)
  [`scale_y_cfb()`](https://cfbplotR.sportsdataverse.org/reference/scale_axes_cfb.md)
  [`scale_x_cfb_headshots()`](https://cfbplotR.sportsdataverse.org/reference/scale_axes_cfb.md)
  [`scale_y_cfb_headshots()`](https://cfbplotR.sportsdataverse.org/reference/scale_axes_cfb.md)
  : Axis Scales for CFB Team Logos
- [`theme_x_cfb()`](https://cfbplotR.sportsdataverse.org/reference/theme_cfb.md)
  [`theme_y_cfb()`](https://cfbplotR.sportsdataverse.org/reference/theme_cfb.md)
  : Theme for CFB Team Logos

## gt Table Helpers

Embed CFB team logos, wordmarks, and player headshots inside gt table
cells or column labels.

- [`gt_fmt_cfb_logo()`](https://cfbplotR.sportsdataverse.org/reference/gt_cfb.md)
  [`gt_fmt_cfb_wordmark()`](https://cfbplotR.sportsdataverse.org/reference/gt_cfb.md)
  [`gt_fmt_cfb_headshot()`](https://cfbplotR.sportsdataverse.org/reference/gt_cfb.md)
  :

  Add logos into rows of a `gt` table

- [`gt_cfb_cols_label()`](https://cfbplotR.sportsdataverse.org/reference/gt_cfb_cols_label.md)
  : Render CFB logos in gt column labels

- [`gt_merge_stack_team_color()`](https://cfbplotR.sportsdataverse.org/reference/gt_stack_team.md)
  :

  Merge and stack text from two columns in `gt` and color one with
  school colors

## Team Utilities

Validate, clean, and factor-order CFB team names and abbreviations; look
up athlete IDs; control the image cache.

- [`valid_team_names()`](https://cfbplotR.sportsdataverse.org/reference/valid_team_names.md)
  : Output Valid CFB Team Names and Abbreviations
- [`clean_school_names()`](https://cfbplotR.sportsdataverse.org/reference/clean_school_names.md)
  : Standardize NCAA School Names
- [`clean_team_abbrs()`](https://cfbplotR.sportsdataverse.org/reference/clean_team_abbrs.md)
  : Clean CFB team abbreviations
- [`cfb_team_factor()`](https://cfbplotR.sportsdataverse.org/reference/cfb_team_factor.md)
  : Order CFB teams as a factor
- [`add_athlete_id_col()`](https://cfbplotR.sportsdataverse.org/reference/add_athlete_id_col.md)
  : Add Athlete ID's to data frame
- [`.cfbplotR_clear_cache()`](https://cfbplotR.sportsdataverse.org/reference/dot-cfbplotR_clear_cache.md)
  : Clear the cfbplotR (ggpath) image cache

## Premade Plots

High-level functions that build complete CFB-branded plots.

- [`cfb_team_tiers()`](https://cfbplotR.sportsdataverse.org/reference/cfb_team_tiers.md)
  : Create CFB Team Tiers

## Plot Titles & Preview

Add images to ggplot2 titles and preview plots at exact output
dimensions.

- [`ggtitle_image()`](https://cfbplotR.sportsdataverse.org/reference/ggtitle_image.md)
  [`theme_title_image()`](https://cfbplotR.sportsdataverse.org/reference/ggtitle_image.md)
  : Functions for adding an image to the title of a ggplot
- [`ggpreview()`](https://cfbplotR.sportsdataverse.org/reference/ggpreview.md)
  : Preview ggplot in Specified Dimensions

## Package Data

Built-in reference datasets shipped with cfbplotR.

- [`logo_ref`](https://cfbplotR.sportsdataverse.org/reference/data.md)
  [`team_name_mapping`](https://cfbplotR.sportsdataverse.org/reference/data.md)
  :

  **Data in the package for reference**

## Re-exported from ggpath

Generic image geoms and theme elements provided by the ggpath backend.

- [`reexports`](https://cfbplotR.sportsdataverse.org/reference/reexports.md)
  [`geom_from_path`](https://cfbplotR.sportsdataverse.org/reference/reexports.md)
  [`GeomFromPath`](https://cfbplotR.sportsdataverse.org/reference/reexports.md)
  [`element_path`](https://cfbplotR.sportsdataverse.org/reference/reexports.md)
  [`element_raster`](https://cfbplotR.sportsdataverse.org/reference/reexports.md)
  [`geom_mean_lines`](https://cfbplotR.sportsdataverse.org/reference/reexports.md)
  [`geom_median_lines`](https://cfbplotR.sportsdataverse.org/reference/reexports.md)
  [`GeomRefLines`](https://cfbplotR.sportsdataverse.org/reference/reexports.md)
  : Objects exported from other packages

# Articles

### All vignettes

- [Using
  cfbplotR](https://cfbplotR.sportsdataverse.org/articles/tutorial.md):