nflplotR: NFL Logo Plots in 'ggplot2' and 'gt'

Description

A set of functions to visualize National Football League analysis in 'ggplot2' plots and 'gt' tables.

Usage

GeomNFLheads

GeomNFLlogo

GeomNFLwordmark

Format

An object of class GeomNFLheads (inherits from Geom, ggproto, gg) of length 5.

An object of class GeomNFLlogo (inherits from Geom, ggproto, gg) of length 5.

An object of class GeomNFLwordmark (inherits from Geom, ggproto, gg) of length 5.

Author(s)

Maintainer: Sebastian Carl mrcaseb@gmail.com

See Also

Useful links:

• https://nflplotr.nflverse.com

• https://github.com/nflverse/nflplotR

• Report bugs at https://github.com/nflverse/nflplotR/issues

Clear nflplotR Cache

Description

This function clears the memoised cache of all functions memoised by nflplotR.

Usage

.nflplotR_clear_cache()

Value

Invisibly NULL

Examples

.nflplotR_clear_cache()

Theme Elements for Image Grobs

Description

In conjunction with the ggplot2::theme system, the following element_ functions enable images in non-data components of the plot, e.g. axis text.

• element_nfl_logo(): draws NFL team logos instead of their abbreviations.

• element_nfl_wordmark(): draws NFL team wordmarks instead of their abbreviations.

• element_nfl_headshot(): draws NFL player headshots instead of their GSIS IDs.

• element_path(): draws images from valid image URLs instead of the URL.

Usage

element_nfl_logo(
  alpha = NULL,
  colour = NA,
  hjust = NULL,
  vjust = NULL,
  color = NULL,
  size = 0.5
)

element_nfl_wordmark(
  alpha = NULL,
  colour = NA,
  hjust = NULL,
  vjust = NULL,
  color = NULL,
  size = 0.5
)

element_nfl_headshot(
  alpha = NULL,
  colour = NA,
  hjust = NULL,
  vjust = NULL,
  color = NULL,
  size = 0.5
)

element_path(...)

Arguments

Details

The elements translate NFL team abbreviations or NFL player GSIS IDs into logo images or player headshots, respectively.

Value

An S3 object of class element.

See Also

geom_nfl_logos(), geom_nfl_headshots(), geom_nfl_wordmarks(), and geom_from_path() for more information on valid team abbreviations, player IDs, and other parameters.

The examples on https://nflplotr.nflverse.com/articles/nflplotR.html

Examples

library(nflplotR)
library(ggplot2)

team_abbr <- valid_team_names()
# remove conference logos from this example
team_abbr <- team_abbr[!team_abbr %in% c("AFC", "NFC", "NFL")]

df <- data.frame(
  random_value = runif(length(team_abbr), 0, 1),
  teams = team_abbr
)

# use logos for x-axis
ggplot(df, aes(x = teams, y = random_value)) +
  geom_col(aes(color = teams, fill = teams), width = 0.5) +
  scale_color_nfl(type = "secondary") +
  scale_fill_nfl(alpha = 0.4) +
  theme_minimal() +
  theme(axis.text.x = element_nfl_logo())

# use logos for y-axis
ggplot(df, aes(y = teams, x = random_value)) +
  geom_col(aes(color = teams, fill = teams), width = 0.5) +
  scale_color_nfl(type = "secondary") +
  scale_fill_nfl(alpha = 0.4) +
  theme_minimal() +
  theme(axis.text.y = element_nfl_logo())

#############################################################################
# Headshot Examples
#############################################################################
library(nflplotR)
library(ggplot2)

# Silence an nflreadr message that is irrelevant here
old <- options(nflreadr.cache_warning = FALSE)

dfh <- data.frame(
  random_value = runif(9, 0, 1),
  player_gsis = c("00-0033873",
                  "00-0026498",
                  "00-0035228",
                  "00-0031237",
                  "00-0036355",
                  "00-0019596",
                  "00-0033077",
                  "00-0012345",
                  "00-0031280")
)

# use headshots for x-axis
ggplot(dfh, aes(x = player_gsis, y = random_value)) +
  geom_col(width = 0.5) +
  theme_minimal() +
  theme(axis.text.x = element_nfl_headshot(size = 1))

# use headshots for y-axis
ggplot(dfh, aes(y = player_gsis, x = random_value)) +
  geom_col(width = 0.5) +
  theme_minimal() +
  theme(axis.text.y = element_nfl_headshot(size = 1))

# Restore old options
options(old)

#############################################################################
# Wordmarks and other Images
#############################################################################

library(ggplot2)

dt <- data.table::as.data.table(mtcars)[,
  `:=`(
    team = sample(c("LAC", "BUF", "DAL", "ARI"), nrow(mtcars), TRUE),
    player = sample(
      c("00-0033873", "00-0035228", "00-0036355", "00-0019596"),
      nrow(mtcars),
      TRUE
    )
  )
]

ggplot(dt, aes(x = mpg, y = disp)) +
  geom_point() +
  facet_wrap(vars(team)) +
  labs(
    title = tools::toTitleCase("These are random teams and data"),
    subtitle = "I just want to show how the nflplotR theme elements work",
    caption = "https://github.com/nflverse/nflseedR/raw/master/man/figures/caption.png"
  ) +
  theme_minimal() +
  theme(
    plot.title.position = "plot",
    plot.title = element_text(face = "bold"),
    axis.title = element_blank(),
    # make wordmarks of team abbreviations
    strip.text = element_nfl_wordmark(size = 1),
    # load image from url in caption
    plot.caption = element_path(hjust = 1, size = 0.4)
  )

ggplot2 Layer for Visualizing Images from URLs or Local Paths

Description

This geom is used to plot images instead of points in a ggplot. It requires x, y aesthetics as well as a path. It has been outsourced to ggpath and is re-exported in nflplotR for compatibility reasons.

Usage

geom_from_path(...)

Arguments

Details

This function has been outsourced to the ggpath package. See ggpath::geom_from_path for details.

Value

A ggplot2 layer (ggplot2::layer()) that can be added to a plot created with ggplot2::ggplot().

Aesthetics

geom_from_path() understands the following aesthetics (required aesthetics have no default value):

x

The x-coordinate. Required.

y

The y-coordinate. Required.

path

a file path, url, raster object or bitmap array. See magick::image_read() for further information. Required.

alpha = NULL

The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.

colour = NULL

The image will be colorized with this colour. Use the special character "b/w" to set it to black and white. For more information on valid colour names in ggplot2 see https://ggplot2.tidyverse.org/articles/ggplot2-specs.html?q=colour#colour-and-fill

angle = 0

The angle of the image as a numerical value between 0° and 360°.

hjust = 0.5

The horizontal adjustment relative to the given x coordinate. Must be a numerical value between 0 and 1.

vjust = 0.5

The vertical adjustment relative to the given y coordinate. Must be a numerical value between 0 and 1.

width = 1.0

The desired width of the image in npc (Normalised Parent Coordinates). The default value is set to 1.0 which is big but it is necessary because all used values are computed relative to the default. A typical size is width = 0.1 (see below examples).

height = 1.0

The desired height of the image in npc (Normalised Parent Coordinates). The default value is set to 1.0 which is big but it is necessary because all used values are computed relative to the default. A typical size is height = 0.1 (see below examples).

Examples

# example code


library(ggplot2)
library(nflplotR)

# create x-y-coordinates of a pentagon and add nflverse logo urls
df <- data.frame(
  a = c(sin(2 * pi * (0:4) / 5), 0),
  b = c(cos(2 * pi * (0:4) / 5), 0),
  url = c(
    "https://github.com/nflverse/nflfastR/raw/master/man/figures/logo.png",
    "https://github.com/nflverse/nflseedR/raw/master/man/figures/logo.png",
    "https://github.com/nflverse/nfl4th/raw/master/man/figures/logo.png",
    "https://github.com/nflverse/nflreadr/raw/main/data-raw/logo.svg",
    "https://github.com/nflverse/nflplotR/raw/main/man/figures/logo.png",
    "https://github.com/nflverse/nflverse/raw/main/man/figures/logo.png"
  )
)

# plot images directly from url
ggplot(df, aes(x = a, y = b)) +
  geom_from_path(aes(path = url), width = 0.15) +
  coord_cartesian(xlim = c(-2, 2), ylim = c(-1.3, 1.5)) +
  theme_void()

# plot images directly from url and apply transparency
ggplot(df, aes(x = a, y = b)) +
  geom_from_path(aes(path = url), width = 0.15, alpha = 0.5) +
  coord_cartesian(xlim = c(-2, 2), ylim = c(-1.3, 1.5)) +
  theme_void()

# It is also possible and recommended to use the underlying Geom inside a
# ggplot2 annotation
ggplot() +
  annotate(
    ggpath::GeomFromPath,
    x = 0,
    y = 0,
    path = "https://github.com/nflverse/nflplotR/raw/main/man/figures/logo.png",
    width = 0.4
  ) +
  theme_minimal()

ggplot2 Layer for Horizontal and Vertical Reference Lines

Description

These geoms can be used to draw horizontal or vertical reference lines in a ggplot. They use the data in the aesthetics x0 and y0 to compute their median or mean and draw them as a line.

Usage

geom_median_lines(...)

geom_mean_lines(...)

Arguments

Details

These functions have been outsourced to the ggpath package. See ggpath::geom_median_lines and ggpath::geom_mean_lines for details.

Value

A ggplot2 layer (ggplot2::layer()) that can be added to a plot created with ggplot2::ggplot().

Aesthetics

geom_median_lines() and geom_mean_lines() understand the following aesthetics (at least one of the x0 or y0 aesthetics is required):

x0

The variable for which to compute the median/mean that is drawn as vertical line.

y0

The variable for which to compute the median/mean that is drawn as horizontal line.

alpha = NA

The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.

color = "red"

The color of the drawn lines.

linetype = 2

The linetype of the drawn lines.

size = 0.5

The size of the drawn lines. Deprecated as of ggplot2 v3.4.0, use linewidth instead.

linewidth = 0.5

The width of the drawn lines. Starting at ggplot2 v3.4.0.

See Also

The underlying ggplot2 geoms ggplot2::geom_hline and ggplot2::geom_vline

Examples

library(ggplot2)

# inherit top level aesthetics
ggplot(mtcars, aes(x = disp, y = mpg, y0 = mpg, x0 = disp)) +
  geom_point() +
  geom_median_lines() +
  geom_mean_lines(color = "blue") +
  theme_minimal()

# draw horizontal line only
ggplot(mtcars, aes(x = disp, y = mpg, y0 = mpg)) +
  geom_point() +
  geom_median_lines() +
  geom_mean_lines(color = "blue") +
  theme_minimal()

# draw vertical line only
ggplot(mtcars, aes(x = disp, y = mpg, x0 = disp)) +
  geom_point() +
  geom_median_lines() +
  geom_mean_lines(color = "blue") +
  theme_minimal()

# choose your own value
ggplot(mtcars, aes(x = disp, y = mpg)) +
  geom_point() +
  geom_median_lines(x0 = 400, y0 = 15) +
  geom_mean_lines(x0 = 150, y0 = 30, color = "blue") +
  theme_minimal()

ggplot2 Layer for Visualizing NFL Player Headshots

Description

This geom is used to plot NFL player headshots instead of points in a ggplot. It requires x, y aesthetics as well as a valid NFL player gsis id.

Usage

geom_nfl_headshots(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer (ggplot2::layer()) that can be added to a plot created with ggplot2::ggplot().

Aesthetics

geom_nfl_headshots() understands the following aesthetics (required aesthetics have no default value):

x

The x-coordinate. Required.

y

The y-coordinate. Required.

player_gsis

The players' NFL gsis id. Required.

alpha = NULL

The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.

colour = NULL

The image will be colorized with this colour. Use the special character "b/w" to set it to black and white. For more information on valid colour names in ggplot2 see https://ggplot2.tidyverse.org/articles/ggplot2-specs.html?q=colour#colour-and-fill

angle = 0

The angle of the image as a numerical value between 0° and 360°.

hjust = 0.5

The horizontal adjustment relative to the given x coordinate. Must be a numerical value between 0 and 1.

vjust = 0.5

The vertical adjustment relative to the given y coordinate. Must be a numerical value between 0 and 1.

width = 1.0

The desired width of the image in npc (Normalised Parent Coordinates). The default value is set to 1.0 which is big but it is necessary because all used values are computed relative to the default. A typical size is width = 0.075 (see below examples).

height = 1.0

The desired height of the image in npc (Normalised Parent Coordinates). The default value is set to 1.0 which is big but it is necessary because all used values are computed relative to the default. A typical size is height = 0.1 (see below examples).

Examples

library(nflplotR)
library(ggplot2)
# Silence an nflreadr message that is irrelevant here
old <- options(nflreadr.cache_warning = FALSE)

df <- data.frame(
  a = rep(1:3, 3),
  b = sort(rep(1:3, 3), decreasing = TRUE),
  player_gsis = c("00-0033873",
                  "00-0026498",
                  "00-0035228",
                  "00-0031237",
                  "00-0036355",
                  "00-0019596",
                  "00-0033077",
                  "00-0012345",
                  "00-0031280"),
  player_name = c("P.Mahomes",
                  "M.Stafford",
                  "K.Murray",
                  "T.Bridgewater",
                  "J.Herbert",
                  "T.Brady",
                  "D.Prescott",
                  "Non.Match",
                  "D.Carr")
)

# set a custom fill colour for one player
df$colour <- ifelse(df$a == 2 & df$b == 2, NA, "b/w")

# scatterplot of the headshots
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_headshots(aes(player_gsis = player_gsis), height = 0.2) +
  geom_label(aes(label = player_name), nudge_y = -0.35, alpha = 0.5) +
  coord_cartesian(xlim = c(0.75, 3.25), ylim = c(0.7, 3.25)) +
  theme_void()

# apply alpha as constant
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_headshots(aes(player_gsis = player_gsis), height = 0.2, alpha = 0.5) +
  geom_label(aes(label = player_name), nudge_y = -0.35, alpha = 0.5) +
  coord_cartesian(xlim = c(0.75, 3.25), ylim = c(0.7, 3.25)) +
  theme_void()

# apply colour as an aesthetic
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_headshots(aes(player_gsis = player_gsis, colour = colour), height = 0.2) +
  geom_label(aes(label = player_name), nudge_y = -0.35, alpha = 0.5) +
  coord_cartesian(xlim = c(0.75, 3.25), ylim = c(0.7, 3.25)) +
  scale_colour_identity() +
  theme_void()

# Restore old options
options(old)

ggplot2 Layer for Visualizing NFL Team Logos

Description

This geom is used to plot NFL team and conference logos instead of points in a ggplot. It requires x, y aesthetics as well as a valid NFL team abbreviation. The latter can be checked with valid_team_names().

Usage

geom_nfl_logos(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer (ggplot2::layer()) that can be added to a plot created with ggplot2::ggplot().

Aesthetics

geom_nfl_logos() understands the following aesthetics (required aesthetics have no default value):

x

The x-coordinate. Required.

y

The y-coordinate. Required.

team_abbr

The team abbreviation. Should be one of valid_team_names(). The function tries to clean team names internally by calling nflreadr::clean_team_abbrs(). Note: "NFL", "AFC", "NFC" are valid abbreviations! Required.

alpha = NULL

The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.

colour = NULL

The image will be colorized with this colour. Use the special character "b/w" to set it to black and white. For more information on valid colour names in ggplot2 see https://ggplot2.tidyverse.org/articles/ggplot2-specs.html?q=colour#colour-and-fill

angle = 0

The angle of the image as a numerical value between 0° and 360°.

hjust = 0.5

The horizontal adjustment relative to the given x coordinate. Must be a numerical value between 0 and 1.

vjust = 0.5

The vertical adjustment relative to the given y coordinate. Must be a numerical value between 0 and 1.

width = 1.0

The desired width of the image in npc (Normalised Parent Coordinates). The default value is set to 1.0 which is big but it is necessary because all used values are computed relative to the default. A typical size is width = 0.075 (see below examples).

height = 1.0

The desired height of the image in npc (Normalised Parent Coordinates). The default value is set to 1.0 which is big but it is necessary because all used values are computed relative to the default. A typical size is height = 0.1 (see below examples).

Examples

library(nflplotR)
library(ggplot2)

team_abbr <- valid_team_names()
# remove conference logos from this example
team_abbr <- team_abbr[!team_abbr %in% c("AFC", "NFC", "NFL")]

df <- data.frame(
  a = rep(1:8, 4),
  b = sort(rep(1:4, 8), decreasing = TRUE),
  teams = team_abbr
)

# keep alpha == 1 for all teams including an "A"
matches <- grepl("A", team_abbr)
df$alpha <- ifelse(matches, 1, 0.2)
# also set a custom fill colour for the non "A" teams
df$colour <- ifelse(matches, NA, "gray")

# scatterplot of all logos
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_logos(aes(team_abbr = teams), width = 0.075) +
  geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) +
  expand_limits(y = c(0.9, 4.1)) +
  theme_void()

# apply alpha via an aesthetic from inside the dataset `df`
# please note that you have to add scale_alpha_identity() to use the alpha
# values in your dataset!
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_logos(aes(team_abbr = teams, alpha = alpha), width = 0.075) +
  geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) +
  expand_limits(y = c(0.9, 4.1)) +
  scale_alpha_identity() +
  theme_void()

# apply alpha and colour via an aesthetic from inside the dataset `df`
# please note that you have to add scale_alpha_identity() as well as
# scale_color_identity() to use the alpha and colour values in your dataset!
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_logos(aes(team_abbr = teams, alpha = alpha, colour = colour), width = 0.075) +
  geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) +
  expand_limits(y = c(0.9, 4.1)) +
  scale_alpha_identity() +
  scale_color_identity() +
  theme_void()

# apply alpha as constant for all logos
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_logos(aes(team_abbr = teams), width = 0.075, alpha = 0.6) +
  geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) +
  expand_limits(y = c(0.9, 4.1)) +
  theme_void()

# it's also possible to plot NFL and conference logos
dat <- data.frame(a = c(1.5, 1:2), b = c(1, 0, 0), teams = c("NFL", "AFC", "NFC"))
ggplot(dat, aes(x = a, y = b)) +
  geom_nfl_logos(aes(team_abbr = teams), width = 0.25) +
  coord_cartesian(xlim = c(0.5,2.5), ylim = c(-0.75, 1.75)) +
  theme_void()

ggplot2 Layer for Visualizing NFL Team Wordmarks

Description

This geom is used to plot NFL team wordmarks instead of points in a ggplot. It requires x, y aesthetics as well as a valid NFL team abbreviation. The latter can be checked with valid_team_names().

Usage

geom_nfl_wordmarks(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer (ggplot2::layer()) that can be added to a plot created with ggplot2::ggplot().

Aesthetics

geom_nfl_logos() understands the following aesthetics (required aesthetics have no default value):

x

The x-coordinate. Required.

y

The y-coordinate. Required.

team_abbr

The team abbreviation. Should be one of valid_team_names(). The function tries to clean team names internally by calling nflreadr::clean_team_abbrs(). Required.

alpha = NULL

The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.

colour = NULL

The image will be colorized with this colour. Use the special character "b/w" to set it to black and white. For more information on valid colour names in ggplot2 see https://ggplot2.tidyverse.org/articles/ggplot2-specs.html?q=colour#colour-and-fill

angle = 0

The angle of the image as a numerical value between 0° and 360°.

hjust = 0.5

The horizontal adjustment relative to the given x coordinate. Must be a numerical value between 0 and 1.

vjust = 0.5

The vertical adjustment relative to the given y coordinate. Must be a numerical value between 0 and 1.

width = 1.0

The desired width of the image in npc (Normalised Parent Coordinates). The default value is set to 1.0 which is big but it is necessary because all used values are computed relative to the default. A typical size is width = 0.1 (see below examples).

height = 1.0

The desired height of the image in npc (Normalised Parent Coordinates). The default value is set to 1.0 which is big but it is necessary because all used values are computed relative to the default. A typical size is height = 0.1 (see below examples).

Examples

library(nflplotR)
library(ggplot2)

team_abbr <- valid_team_names()
# remove conference logos from this example
team_abbr <- team_abbr[!team_abbr %in% c("AFC", "NFC", "NFL")]

df <- data.frame(
  a = rep(1:8, 4),
  b = sort(rep(1:4, 8), decreasing = TRUE),
  teams = team_abbr
)

# keep alpha == 1 for all teams including an "A"
matches <- grepl("A", team_abbr)
df$alpha <- ifelse(matches, 1, 0.2)
# also set a custom fill colour for the non "A" teams
df$colour <- ifelse(matches, NA, "gray")

# scatterplot of all wordmarks
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_wordmarks(aes(team_abbr = teams), width = 0.12) +
  geom_label(aes(label = teams), nudge_y = -0.20, alpha = 0.5) +
  scale_x_continuous(expand = expansion(add = 0.5)) +
  theme_void()

# apply alpha via an aesthetic from inside the dataset `df`
# please note that you have to add scale_alpha_identity() to use the alpha
# values in your dataset!
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_wordmarks(aes(team_abbr = teams, alpha = alpha), width = 0.12) +
  geom_label(aes(label = teams), nudge_y = -0.20, alpha = 0.5) +
  scale_x_continuous(expand = expansion(add = 0.5)) +
  scale_alpha_identity() +
  theme_void()

# apply alpha and colour via an aesthetic from inside the dataset `df`
# please note that you have to add scale_alpha_identity() as well as
# scale_color_identity() to use the alpha and colour values in your dataset!
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_wordmarks(aes(team_abbr = teams, alpha = alpha, colour = colour), width = 0.12) +
  geom_label(aes(label = teams), nudge_y = -0.20, alpha = 0.5) +
  scale_x_continuous(expand = expansion(add = 0.5)) +
  scale_alpha_identity() +
  scale_color_identity() +
  theme_void()

# apply alpha as constant for all logos
ggplot(df, aes(x = a, y = b)) +
  geom_nfl_wordmarks(aes(team_abbr = teams), width = 0.12, alpha = 0.6) +
  geom_label(aes(label = teams), nudge_y = -0.20, alpha = 0.5) +
  scale_x_continuous(expand = expansion(add = 0.5)) +
  theme_void()

Preview ggplot in Specified Dimensions

Description

This function previews a ggplot in its actual dimensions in order to see how it will look when saved. It is also significantly faster than the default preview in RStudio for ggplots created using nflplotR.

Usage

ggpreview(
  plot = ggplot2::last_plot(),
  width = NA,
  height = NA,
  asp = NULL,
  dpi = 300,
  device = "png",
  units = c("in", "cm", "mm", "px"),
  scale = 1,
  limitsize = TRUE,
  bg = NULL,
  ...
)

Arguments

Value

No return value, called for side effects.

Examples

library(nflplotR)
library(ggplot2)

team_abbr <- valid_team_names()
# remove conference logos from this example
team_abbr <- team_abbr[!team_abbr %in% c("AFC", "NFC", "NFL")]

df <- data.frame(
  random_value = runif(length(team_abbr), 0, 1),
  teams = team_abbr
)

# use logos for x-axis
# note that the plot is assigned to the object "p"
p <- ggplot(df, aes(x = teams, y = random_value)) +
  geom_col(aes(color = teams, fill = teams), width = 0.5) +
  scale_color_nfl(type = "secondary") +
  scale_fill_nfl(alpha = 0.4) +
  theme_minimal() +
  theme(axis.text.x = element_nfl_logo())

# preview p with defined width and aspect ratio (only available in RStudio)
if (rstudioapi::isAvailable()){
  ggpreview(p, width = 5, asp = 16/9)
}

Render Logos, Wordmarks, and Headshots in 'gt' Table Column Labels

Description

Translate NFL team abbreviations into logos and wordmarks or NFL player gsis IDs to player headshots and render these images in column labels of 'gt' tables.

Usage

gt_nfl_cols_label(
  gt_object,
  columns = gt::everything(),
  ...,
  height = 30,
  type = c("logo", "wordmark", "headshot")
)

Arguments

Value

An object of class gt_tbl.

Output of below example

See Also

The article that describes how nflplotR works with the 'gt' package https://nflplotr.nflverse.com/articles/gt.html

The logo and wordmark rendering functions gt_nfl_logos() and gt_nfl_wordmarks().

The player headshot rendering function gt_nfl_headshots().

Examples

library(gt)
label_df <- data.frame(
  "00-0036355" = 1,
  "00-0033873" = 2,
  "LAC" = 11,
  "KC" = 12,
  check.names = FALSE
)

# create gt table and translate player IDs and team abbreviations
# into headshots, logos, and wordmarks
table <- gt::gt(label_df) %>%
  nflplotR::gt_nfl_cols_label(
    columns = gt::starts_with("00"),
    type = "headshot"
  ) %>%
  nflplotR::gt_nfl_cols_label("LAC", type = "wordmark") %>%
  nflplotR::gt_nfl_cols_label("KC", type = "logo")

Render Player Headshots in 'gt' Tables

Description

Translate NFL player gsis IDs to player headshots and render these images in html tables with the 'gt' package.

Usage

gt_nfl_headshots(gt_object, columns, height = 30, locations = NULL)

Arguments

Value

An object of class gt_tbl.

Output of below example

See Also

The logo and wordmark rendering functions gt_nfl_logos() and gt_nfl_wordmarks().

Examples

library(nflplotR)
library(gt)
# Silence an nflreadr message that is irrelevant here
old <- options(nflreadr.cache_warning = FALSE)
df <- data.frame(
  player_gsis = c("00-0033873",
                  "00-0026498",
                  "00-0035228",
                  "00-0031237",
                  "00-0036355",
                  "00-0019596",
                  "00-0033077",
                  "00-0012345",
                  "00-0031280"),
  player_name = c("P.Mahomes",
                  "M.Stafford",
                  "K.Murray",
                  "T.Bridgewater",
                  "J.Herbert",
                  "T.Brady",
                  "D.Prescott",
                  "Non.Match",
                  "D.Carr")
)

# Replace player IDs with headshot images
table <- gt(df) %>%
  gt_nfl_headshots("player_gsis")

# Restore old options
options(old)

Render Logos and Wordmarks in 'gt' Tables

Description

Translate NFL team abbreviations into logos and wordmarks and render these images in html tables with the 'gt' package.

Usage

gt_nfl_logos(gt_object, columns, height = 30, locations = NULL)

gt_nfl_wordmarks(gt_object, columns, height = 30, locations = NULL)

Arguments

Value

An object of class gt_tbl.

Output of below example

See Also

The player headshot rendering function gt_nfl_headshots().

The article that describes how nflplotR works with the 'gt' package https://nflplotr.nflverse.com/articles/gt.html

Examples

library(gt)
library(nflplotR)
teams <- valid_team_names()
# remove conference logos from this example
teams <- teams[!teams %in% c("AFC", "NFC", "NFL")]
# create dataframe with all 32 team names
df <- data.frame(
  team_a = head(teams, 16),
  logo_a = head(teams, 16),
  wordmark_a = head(teams, 16),
  team_b = tail(teams, 16),
  logo_b = tail(teams, 16),
  wordmark_b = tail(teams, 16)
)
# create gt table and translate team names to logo/wordmark images
table <- df %>%
  gt() %>%
  gt_nfl_logos(columns = gt::starts_with("logo")) %>%
  gt_nfl_wordmarks(columns = gt::starts_with("wordmark"))

Render 'gt' Table to Temporary png File

Description

Saves a gt table to a temporary png image file and uses magick to render tables in reproducible examples like reprex::reprex() or in package function examples (see details for further information).

Usage

gt_render_image(gt_tbl, ...)

Arguments

Details

Rendering gt tables in function examples is not trivial because of the behavior of an underlying dependency: chromote. It keeps a process running even if the chromote session is closed. Unfortunately, this causes R CMD Check errors related to open connections after example runs. The only way to avoid this is setting the environment variable ⁠_R_CHECK_CONNECTIONS_LEFT_OPEN_⁠ to "false". How to do that depends on where and how developers check their package. A good way to prevent an example from being executed because the environment variable was not set to "false" can be taken from the source code of this function.

Value

Returns NULL invisibly.

Examples

tbl <- gt::gt_preview(mtcars)
gt_render_image(tbl)

Create Ordered NFL Team Name Factor

Description

Create Ordered NFL Team Name Factor

Usage

nfl_team_factor(teams, ...)

Arguments

Value

Object of class "factor"

Examples

# unsorted vector including NFL team abbreviations
teams <- c("LAC", "LV", "CLE", "BAL", "DEN", "PIT", "CIN", "KC")

# defaults to sort by division and nick name in ascending order
nfl_team_factor(teams)

# can sort by every column in nflreadr::load_teams()
nfl_team_factor(teams, team_abbr)

# descending order by using base::rev()
nfl_team_factor(teams, rev(team_abbr))

######### HOW TO USE IN PRACTICE #########

library(ggplot2)
# load some sample data from the ggplot2 package
plot_data <- mpg
# add a new column by randomly sampling the above defined teams vector
plot_data$team <- sample(teams, nrow(mpg), replace = TRUE)

# Now we plot the data and facet by team abbreviation. ggplot automatically
# converts the team names to a factor and sorts it alphabetically
ggplot(plot_data, aes(displ, hwy)) +
  geom_point() +
  facet_wrap(~team, ncol = 4) +
  theme_minimal()

# We'll change the order of facets by making another team name column and
# converting it to an ordered factor. Again, this defaults to sort by division
# and nick name in ascending order.
plot_data$ordered_team <- nfl_team_factor(sample(teams, nrow(mpg), replace = TRUE))

# Let's check how the facets are ordered now.
ggplot(plot_data, aes(displ, hwy)) +
  geom_point() +
  facet_wrap(~ordered_team, ncol = 4) +
  theme_minimal()

# The facet order looks weird because the defaults is meant to be used with
# NFL team wordmarks. So let's use the actual wordmarks and look at the result.
ggplot(plot_data, aes(displ, hwy)) +
  geom_point() +
  facet_wrap(~ordered_team, ncol = 4) +
  theme_minimal() +
  theme(strip.text = element_nfl_wordmark())

Create NFL Team Tiers

Description

This function sets up a ggplot to visualize NFL team tiers.

Usage

nfl_team_tiers(
  data,
  title = "NFL Team Tiers, 2021 as of Week 4",
  subtitle = "created with the #nflplotR Tiermaker",
  caption = NULL,
  tier_desc = c(`1` = "Super Bowl", `2` = "Very Good", `3` = "Medium", `4` = "Bad", `5` =
    "What are they doing?", `6` = "", `7` = ""),
  presort = FALSE,
  alpha = 0.8,
  width = 0.075,
  no_line_below_tier = NULL,
  devel = FALSE
)

Arguments

Value

A plot object created with ggplot2::ggplot().

Examples

library(ggplot2)
library(data.table)
teams <- nflplotR::valid_team_names()
# remove conference logos from this example
teams <- teams[!teams %in% c("AFC", "NFC", "NFL")]
teams <- sample(teams)

# Build the team tiers data
# This is completely random!
dt <- data.table::data.table(
  tier_no = sample(1:5, length(teams), replace = TRUE),
  team_abbr = teams
)[,tier_rank := sample(1:.N, .N), by = "tier_no"]

# Plot team tiers
nfl_team_tiers(dt)

# Create a combined tier which is useful for tiers with lots of teams that
# should be split up in two or more rows. This is done by setting an empty
# string for the tier 5 description and removing the tier separation line
# below tier number 4.
# This example also shows how to turn off the subtitle and add a caption
nfl_team_tiers(dt,
               subtitle = NULL,
               caption = "This is the caption",
               tier_desc = c("1" = "Super Bowl",
                             "2" = "Very Good",
                             "3" = "Medium",
                             "4" = "A Combined Tier",
                             "5" = ""),
               no_line_below_tier = 4)

# For the development of the tiers, it can be useful to turn off logo image
# rendering as this can take quite a long time. By setting `devel = TRUE`, the
# logo images are replaced by team abbreviations which is much faster
nfl_team_tiers(dt,
               tier_desc = c("1" = "Super Bowl",
                             "2" = "Very Good",
                             "3" = "",
                             "4" = "A Combined Tier",
                             "5" = ""),
               no_line_below_tier = c(2, 4),
               devel = TRUE)

Get a Situation Report on System, nflverse Package Versions and Dependencies

Description

See nflreadr::nflverse_sitrep for details.

Value

Situation report of R and package/dependencies.

Scales for NFL Team Colors

Description

These functions map NFL team names to their team colors in color and fill aesthetics

Usage

scale_color_nfl(
  type = c("primary", "secondary"),
  values = NULL,
  ...,
  aesthetics = "colour",
  breaks = ggplot2::waiver(),
  na.value = "grey50",
  guide = NULL,
  alpha = NA
)

scale_colour_nfl(
  type = c("primary", "secondary"),
  values = NULL,
  ...,
  aesthetics = "colour",
  breaks = ggplot2::waiver(),
  na.value = "grey50",
  guide = NULL,
  alpha = NA
)

scale_fill_nfl(
  type = c("primary", "secondary"),
  values = NULL,
  ...,
  aesthetics = "fill",
  breaks = ggplot2::waiver(),
  na.value = "grey50",
  guide = NULL,
  alpha = NA
)

Arguments

Examples

library(nflplotR)
library(ggplot2)

team_abbr <- valid_team_names()
# remove conference logos from this example
team_abbr <- team_abbr[!team_abbr %in% c("AFC", "NFC", "NFL")]

df <- data.frame(
  random_value = runif(length(team_abbr), 0, 1),
  teams = team_abbr
)
ggplot(df, aes(x = teams, y = random_value)) +
  geom_col(aes(color = teams, fill = teams), width = 0.5) +
  scale_color_nfl(type = "secondary") +
  scale_fill_nfl(alpha = 0.4) +
  theme_minimal() +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))

Output Valid NFL Team Abbreviations

Description

Output Valid NFL Team Abbreviations

Usage

valid_team_names(exclude_duplicates = TRUE)

Arguments

Value

A vector of type "character".

Examples

# List valid team abbreviations excluding duplicates
valid_team_names()

# List valid team abbreviations excluding duplicates
valid_team_names(exclude_duplicates = FALSE)