Package 'sdvplotR'

Description

Places team marks on a plotly::plot_ly() chart at data coordinates, as layout images. The R counterpart of sdvplot's plotly adapter. Works on native plotly charts; plotly::ggplotly() drops layout images, so draw a ggplot with geom_sdv_logos() or geom_sdv_logos_interactive() instead.

Usage

add_sdv_logos(
  p,
  x,
  y,
  team,
  league,
  size = 0.08,
  season = NULL,
  variant = "default",
  id_system = "auto",
  strict = FALSE,
  xref = "x",
  yref = "y"
)

add_sdv_wordmarks(
  p,
  x,
  y,
  team,
  league,
  size = 0.08,
  season = NULL,
  variant = "default",
  id_system = "auto",
  strict = FALSE,
  xref = "x",
  yref = "y"
)

add_sdv_headshots(
  p,
  x,
  y,
  player_id,
  league,
  size = 0.08,
  id_system = "espn",
  xref = "x",
  yref = "y"
)

Arguments

Details

Images are placed in data units and fitted by height: each is sized to size times the y-axis span, as sdvplot's plotly adapter sizes them. The span is the axis range when one is set, and otherwise everything the chart's traces on that axis cover plus the new marks (the number of categories on a categorical axis), so marks for a subset of the plotted points are sized against the whole axis. Images already on the chart, including ones set with plotly::layout(), are kept. Date axes are not supported yet.

Value

The plotly object (an htmlwidget) with the images added.

Examples

if (requireNamespace("plotly", quietly = TRUE)) {
  d <- data.frame(
    team = c("KC", "BUF", "BAL"), off = c(0.12, 0.15, 0.18), def = c(-0.05, 0.02, -0.08)
  )
  plotly::plot_ly(d, x = ~off, y = ~def, type = "scatter", mode = "markers", text = ~team) |>
    add_sdv_logos(d$off, d$def, d$team, "nfl")
}

Description

Adds a marker per row with the team's logo as its icon. A row whose team has no logo keeps leaflet's default marker, so no point is dropped silently.

Usage

addSdvLogoMarkers(
  map,
  lng,
  lat,
  team,
  league,
  size = 32,
  season = NULL,
  variant = "default",
  id_system = "auto",
  strict = FALSE,
  data = leaflet::getMapData(map),
  ...
)

Arguments

Value

The leaflet map (an htmlwidget) with the markers added.

Examples

if (requireNamespace("leaflet", quietly = TRUE)) {
  d <- data.frame(team = c("KC", "BUF"), lon = c(-94.48, -78.79), lat = c(39.05, 42.77))
  leaflet::leaflet(d) |>
    leaflet::addTiles() |>
    addSdvLogoMarkers(~lon, ~lat, ~team, league = "nfl", label = ~team)
}

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_sdv_logo(): draws team logos instead of their abbreviations.

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

• element_sdv_headshot(): draws player headshots instead of their IDs.

• element_sdv_raster(): draws a single image in a rectangular theme element such as plot.background. A thin wrapper around ggpath::element_raster().

Usage

element_sdv_logo(
  league,
  alpha = NULL,
  colour = NA,
  color = NULL,
  hjust = NULL,
  vjust = NULL,
  size = 0.5,
  season = NULL,
  id_system = "auto"
)

element_sdv_wordmark(
  league,
  alpha = NULL,
  colour = NA,
  color = NULL,
  hjust = NULL,
  vjust = NULL,
  size = 0.5,
  season = NULL,
  id_system = "auto"
)

element_sdv_headshot(
  league,
  alpha = NULL,
  colour = NA,
  color = NULL,
  hjust = NULL,
  vjust = NULL,
  size = 0.5,
  id_system = "espn"
)

element_sdv_raster(
  image_path,
  x = grid::unit(0.5, "npc"),
  y = grid::unit(0.5, "npc"),
  width = grid::unit(1, "npc"),
  height = grid::unit(1, "npc"),
  just = "centre",
  hjust = 0.5,
  vjust = 0.5,
  interpolate = TRUE,
  ...
)

Arguments

Details

The elements translate team abbreviations or player IDs into logo images or player headshots for the specified league. Rendering is delegated to ggpath::element_path(), which they extend. Set on a parent element such as axis.text.x, they also replace the position children (axis.text.x.bottom, axis.text.y.left, ...) that complete themes like ggplot2::theme_minimal() set, keeping the child's spacing.

Value

element_sdv_logo(), element_sdv_wordmark() and element_sdv_headshot() return a theme element extending ggpath::element_path(); element_sdv_raster() returns a ggpath::element_raster().

See Also

ggpath::element_path(), ggpath::element_raster()

Examples

library(sdvplotR)
library(ggplot2)

team_abbr <- sdv_teams("nfl")$abbr[1:16]

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_sdv(league = "nfl", which = "secondary") +
  scale_fill_sdv(league = "nfl", alpha = 0.4) +
  theme_minimal() +
  theme(axis.text.x = element_sdv_logo(league = "nfl"))

Description

This geom is used to plot player headshots instead of points in a ggplot. It requires x, y aesthetics as well as a valid player identifier: an ESPN athlete ID by default, in every league. Set id_system to plot IDs from another source (nflverse's gsis IDs, or the league's own player IDs). A team's ESPN athlete IDs come with its roster: hoopR::espn_mbb_team_roster() and espn_nba_team_roster(), wehoop::espn_wbb_team_roster() and espn_wnba_team_roster(), and cfbfastR::espn_cfb_team_roster() each return an athlete_id column.

Usage

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

GeomSDVheadshot

Arguments

Details

ESPN and league IDs are plain digits, so a mismatch draws the wrong player or no image rather than an error. League CDNs draw a silhouette for an unknown ID, and the NBA and WNBA CDNs refuse requests from datacenter IPs, so a plot drawn on CI or a server can come back without those headshots.

Value

A ggplot2 layer.

Aesthetics

geom_sdv_headshots() understands the following aesthetics (required aesthetics are in bold):

x

- The x-coordinate.

y

- The y-coordinate.

player_id

- The player's ID: ESPN athlete ID, or as id_system says.

alpha = NULL

- The alpha channel.

colour = NULL

- The image will be colorized with this colour. Use "b/w" for black and white.

angle = 0

- The angle of the image.

hjust = 0.5

- The horizontal adjustment.

vjust = 0.5

- The vertical adjustment.

width = 1.0

- The desired width in npc.

height = 1.0

- The desired height in npc.

Examples

library(sdvplotR)
library(ggplot2)

df <- data.frame(
  a = 1:3,
  b = 3:1,
  player_id = c("3139477", "12483", "3917315"),
  player_name = c("P.Mahomes", "M.Stafford", "K.Murray")
)

ggplot(df, aes(x = a, y = b)) +
  geom_sdv_headshots(aes(player_id = player_id), league = "nfl", height = 0.2) +
  geom_label(aes(label = player_name), nudge_y = -0.35, alpha = 0.5) +
  coord_cartesian(xlim = c(0.5, 3.5), ylim = c(0.5, 3.5)) +
  theme_void()

Description

This geom is used to plot sports team logos instead of points in a ggplot. It requires x, y aesthetics as well as a valid team identifier: anything sdv_resolve() accepts, or a conference or league key. A league's teams are listed by sdv_teams().

Usage

geom_sdv_logos(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  league,
  id_system = "auto",
  strict = FALSE,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

GeomSDVlogo

Arguments

Value

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

Aesthetics

geom_sdv_logos() understands the following aesthetics (required aesthetics are in bold):

x

- The x-coordinate.

y

- The y-coordinate.

team

- The team: an abbreviation, name or id, resolved by sdv_resolve().

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.

angle = 0

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

hjust = 0.5

- The horizontal adjustment relative to the given x coordinate.

vjust = 0.5

- The vertical adjustment relative to the given y coordinate.

width = 1.0

- The desired width of the image in npc (Normalised Parent Coordinates). A typical size is width = 0.075.

height = 1.0

- The desired height of the image in npc. A typical size is height = 0.1.

season = NA

- The season whose logo to draw: the ending year for the NHL (1990 for 1989-90), the year elsewhere. NA draws the team's logo today. See the Historical logos section.

Historical logos

Given a season, a team is drawn with the mark it wore that season where the SportsDataverse logo archive dates its marks, and with its current mark otherwise. The season also picks the team a reused code meant then (see sdv_resolve()). The images are copies kept in the archive, so they don't change when a league reuses a file name. SVG marks are read with the 'rsvg' package. season takes single years: the ending year for split seasons (2005 for 2004-05).

Examples

library(sdvplotR)
library(ggplot2)

team_abbr <- sdv_teams("nfl")$abbr[1:8]

df <- data.frame(
  a = rep(1:4, 2),
  b = rep(2:1, each = 4),
  teams = team_abbr
)

ggplot(df, aes(x = a, y = b)) +
  geom_sdv_logos(aes(team = teams), league = "nfl", width = 0.075) +
  geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) +
  theme_void()

# the logo each team wore that season (NHL seasons are ending years;
# the NHL's marks are SVG files, read with the 'rsvg' package)
if (requireNamespace("rsvg", quietly = TRUE)) {
  old <- data.frame(
    x = 1:4, y = 1,
    team = c("QUE", "HFD", "ATL", "WPG"),
    season = c(1990, 1995, 2005, 2015)
  )
  ggplot(old, aes(x = x, y = y)) +
    geom_sdv_logos(aes(team = team, season = season), league = "nhl", width = 0.2) +
    theme_void()
}

Description

geom_sdv_logos() and its siblings with ggiraph's interactivity: map tooltip, data_id or onclick, then render with ggiraph::girafe(). Each returns two layers: the images, and an invisible interactive point over each that takes the hover.

Usage

geom_sdv_logos_interactive(
  mapping = NULL,
  data = NULL,
  ...,
  league,
  hover_size = 8,
  max_px = 160,
  id_system = "auto",
  strict = FALSE,
  inherit.aes = TRUE
)

geom_sdv_wordmarks_interactive(
  mapping = NULL,
  data = NULL,
  ...,
  league,
  hover_size = 8,
  max_px = 160,
  id_system = "auto",
  strict = FALSE,
  inherit.aes = TRUE
)

geom_sdv_headshots_interactive(
  mapping = NULL,
  data = NULL,
  ...,
  league,
  hover_size = 8,
  max_px = 160,
  id_system = "espn",
  inherit.aes = TRUE
)

Arguments

Value

A list of two ggplot2 layers, to add with +.

Examples

if (requireNamespace("ggiraph", quietly = TRUE)) {
  library(ggplot2)
  d <- data.frame(x = 1:3, y = c(2, 3, 1), team = c("KC", "BUF", "BAL"))
  p <- ggplot(d, aes(x, y)) +
    geom_sdv_logos_interactive(
      aes(team = team, tooltip = team, data_id = team),
      league = "nfl", width = 0.1
    )
  ggiraph::girafe(ggobj = p)
}

Description

This geom is used to plot sports team wordmarks instead of points in a ggplot. It requires x, y aesthetics as well as a valid team identifier: anything sdv_resolve() accepts. A league's teams are listed by sdv_teams().

Usage

geom_sdv_wordmarks(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  league,
  id_system = "auto",
  strict = FALSE,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

GeomSDVwordmark

Arguments

Value

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

Aesthetics

geom_sdv_wordmarks() understands the following aesthetics (required aesthetics are in bold):

x

- The x-coordinate.

y

- The y-coordinate.

team

- The team: an abbreviation, name or id, resolved by sdv_resolve().

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 "b/w" for black and white.

angle = 0

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

hjust = 0.5

- The horizontal adjustment relative to the given x coordinate.

vjust = 0.5

- The vertical adjustment relative to the given y coordinate.

width = 1.0

- The desired width of the image in npc. A typical size is width = 0.12.

height = 1.0

- The desired height of the image in npc. A typical size is height = 0.1.

season = NA

- The season whose wordmark to draw, as for geom_sdv_logos().

Examples

library(sdvplotR)
library(ggplot2)

team_abbr <- sdv_teams("nfl")$abbr[1:8]

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

ggplot(df, aes(x = a, y = b)) +
  geom_sdv_wordmarks(aes(team = teams), league = "nfl", 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()

Description

These functions work together to place an image to the left or right of the title in a ggplot. ggtitle_image() is the main function but must be used with theme_title_image(), which renders the title as markdown and centers the image on the title text.

Usage

ggtitle_image(
  title_image = ggplot2::waiver(),
  title = ggplot2::waiver(),
  image_height = 15,
  image_side = c("left", "right"),
  subtitle = ggplot2::waiver(),
  league
)

theme_title_image(...)

Arguments

Details

The title is markdown with an inline ⁠<img>⁠ tag. 'gridtext' draws inline images on the text baseline and ignores CSS vertical-align, so a logo taller than the text would rise above it (ESPN's marks, padded with transparent space, can sit wholly above the title). theme_title_image() lines the middle of each image up with the middle of the capital letters on its line. Setting plot.title to a plain ggtext::element_markdown() instead also renders the image, on the baseline.

Style the title through theme_title_image(...) (size, face, hjust, ...), never with a later theme(plot.title = ...): adding theme(plot.title = ggtext::element_markdown(hjust = 0.5)) after it replaces the centering element with a plain markdown one, so the image drops back to the baseline, and theme(plot.title = element_text(...)) is an error. Add theme_title_image() after any complete theme such as ggplot2::theme_minimal(), which replaces every element.

Value

A ggplot2 labs object (for ggtitle_image) or theme object (for theme_title_image).

See Also

theme_title_image()

Examples

library(sdvplotR)
library(ggplot2)

nfl <- subset(sdv_example_standings, league == "nfl")
p <- ggplot(nfl, aes(x = points_for, y = points_against)) +
  geom_point() +
  labs(
    title = "This Title will be overwritten",
    subtitle = "Points scored and allowed, 2025 regular season"
  )

if (requireNamespace("ggtext", quietly = TRUE)) {
  p +
    ggtitle_image(
      title_image = "SEA",
      title = "Seattle Seahawks Analysis",
      image_height = 20,
      image_side = "left",
      league = "nfl"
    ) +
    theme_title_image(size = 20, hjust = 0.5)
}

Description

Adds a caption block beneath the table with a rule under its top line, in the style of FiveThirtyEight tables. The top_caption renders as a footnote with a border drawn under it, and the bottom_caption renders as a right-aligned source note below it. Both accept markdown.

Usage

gt_538_caption(
  gt_object,
  top_caption = NULL,
  bottom_caption = NULL,
  rule_color = NULL,
  rule_width = 1,
  size = 12,
  align = "right",
  ...
)

Arguments

Details

The top caption is attached with gt::tab_footnote() on the column labels, which places it in the table footer. Scoped CSS then hides the footnote mark and draws a bottom border under the footnote, so it reads as a ruled caption rather than a numbered note. When rule_color is NULL the border color is taken from the first text color found in the rendered table (via htmltools::as.tags()), so it tracks the theme across light and dark color modes, and falls back to a neutral gray when the render carries no color. The rules are keyed on the table id. If the table has none, one is generated and assigned.

Apply the theme before this function. The rule color is read off the rendered table, so calling it first on a dark theme borrows a near-black (⁠#333333⁠) and the rule disappears into the background. Pass rule_color to sidestep the question entirely.

Value

Returns a modified gt table with the styled captions.

Examples

library(gt)

nfc_north <- subset(
  sdv_example_standings, division == "NFC North",
  c(team_name, wins:points_against)
)

gt(nfc_north) |>
  gt_538_caption(
    top_caption = "The NFC North in 2025",
    bottom_caption = "Source: *nflreadr* schedules, ranked by *nflseedR*"
  )

Description

Bolds the body cells of chosen rows, with an option to recolor their text and fill their background. Rows are chosen by index or by a filter expression; with neither, every row is bolded.

Usage

gt_bold_rows(
  gt_object,
  rows = NULL,
  text_color = "black",
  highlight_color = NULL
)

Arguments

Details

rows is evaluated against the table's underlying data, so rows = wins > 10 bolds the rows where that is TRUE; a numeric vector picks rows by index. The styling is applied with a single gt::tab_style() over gt::cells_body(), so it covers every column of the chosen rows.

Value

Returns a modified gt table with the chosen rows bolded.

Examples

library(gt)

nfc_west <- subset(
  sdv_example_standings, division == "NFC West",
  c(team_name, wins:points_against)
)

# bold every row
gt(nfc_west) |> gt_bold_rows()

# bold and fill the teams with a winning record
gt(nfc_west) |>
  gt_bold_rows(rows = win_pct > 0.5, highlight_color = "#FFF3B0")

Description

Adds a row of horizontal color bars below a gt table from a vector of hex colors, optionally carrying an image and a line of text. The bars are attached as a source note, so they sit below everything else. It is the bottom-edge counterpart to gt_border_bars_top().

Usage

gt_border_bars_bottom(
  gt_object,
  colors,
  bar_height = 10,
  bar_width = "100%",
  bar_align = "center",
  img = NULL,
  img_width = 30,
  img_height = 30,
  img_padding = 10,
  img_align = "right",
  text = NULL,
  text_weight = "bold",
  text_color = "#FFFFFF",
  text_size = 18,
  text_align = "left",
  text_padding = 10
)

Arguments

Details

The bars are added with gt::tab_source_note(), and a table id is resolved or generated so scoped CSS can zero the source-note padding. With neither img nor text, each entry in colors becomes its own full-width bar stacked in a block. When img or text is supplied, a single bar is drawn in the first color as a flex row with the text at one end and the image at the other. The text font is read from the table's source-note styling and imported as a Google Font, falling back to the inherited font when none is set, so it renders in an exported table.

Value

Returns a modified gt table with a row of bars below it.

Examples

library(gt)

afc_north <- subset(
  sdv_example_standings, division == "AFC North",
  c(team_name, wins:points_against)
)
gt(afc_north) |>
  gt_border_bars_bottom(c("#1B7837", "#FFFFFF", "#B2182B"))

# a single bar carrying a credit line
atlantic <- subset(
  sdv_example_standings, division == "Atlantic",
  c(team_name, wins, losses, win_pct:points_against)
)
gt(atlantic) |>
  gt_border_bars_bottom("#22223B", text = "Source: hoopR", bar_height = 28)

Description

Adds a row of horizontal color bars above a gt table from a vector of hex colors, optionally carrying an image and a line of text. The bars are attached as the table caption, so they sit above everything else.

Usage

gt_border_bars_top(
  gt_object,
  colors,
  bar_height = 10,
  bar_width = "100%",
  bar_align = "center",
  img = NULL,
  img_width = 30,
  img_height = 30,
  img_padding = 10,
  img_align = "right",
  text = NULL,
  text_weight = "bold",
  text_color = "#FFFFFF",
  text_size = 18,
  text_align = "left",
  text_padding = 10
)

Arguments

Details

The bars are added with gt::tab_caption(), and a table id is resolved or generated so scoped CSS can zero the caption padding. With neither img nor text, each entry in colors becomes its own full-width bar stacked in a block. When img or text is supplied, a single bar is drawn in the first color as a flex row with the text at one end and the image at the other. The text font is read from the table's title styling and imported as a Google Font, falling back to the inherited font when none is set, so it renders in an exported table.

Value

Returns a modified gt table with a row of bars above it.

Examples

library(gt)

afc_north <- subset(
  sdv_example_standings, division == "AFC North",
  c(team_name, wins:points_against)
)
gt(afc_north) |>
  gt_border_bars_top(c("#1B7837", "#FFFFFF", "#B2182B"))

# a single bar carrying a title
atlantic <- subset(
  sdv_example_standings, division == "Atlantic",
  c(team_name, wins, losses, win_pct:points_against)
)
gt(atlantic) |>
  gt_border_bars_top("#22223B", text = "Atlantic Division, 2025-26", bar_height = 34)

Description

Draws borders between every column and every row of a gt table, giving it a full grid, with an option to extend the borders around the column and row labels.

Usage

gt_border_grid(gt_object, color = "black", weight = 1, include_labels = FALSE)

Arguments

Details

Column borders are drawn as right cell borders on every column but the last, and the row borders are added as scoped CSS on the .gt_row top border. A table id is resolved or generated first, since that CSS is keyed on ⁠#<table_id>⁠.

Value

Returns a modified gt table with the grid borders applied.

Examples

library(gt)

afc_south <- subset(
  sdv_example_standings, division == "AFC South",
  c(team_name, wins:points_against)
)
gt(afc_south) |> gt_border_grid()

# heavier gray lines, including around the labels
pacific <- subset(
  sdv_example_standings, division == "Pacific",
  c(team_name, wins, losses, win_pct:points_against)
)
gt(pacific) |>
  gt_border_grid(color = "#BBBBBB", weight = 2, include_labels = TRUE)

Description

Renders values as rounded color pills, filled from a palette by either the raw value or the ordinal rank. Accepts a plain vector of hex colors or a paletteer palette, and an explicit domain or one taken from the data. gt_color_ranks() fills the whole cell background instead of a pill.

Usage

gt_color_pills(
  gt_object,
  columns,
  rows = NULL,
  palette = c("#C84630", "#5DA271"),
  fill_type = "continuous",
  rank_order = "desc",
  digits = NULL,
  domain = NULL,
  format_type = "number",
  scale_percent = TRUE,
  suffix = "",
  reverse = FALSE,
  outline_color = NULL,
  outline_width = 0.25,
  pal_type = "discrete",
  pill_height = 25,
  text_color = NULL,
  na_color = NULL,
  ...
)

Arguments

Details

Pills are drawn as HTML spans through gt::text_transform(), so they survive gtsave(). The fill is mapped with scales::col_numeric() over domain, and the text is set to black or white, whichever measures higher contrast against that fill, unless text_color is set. A missing value takes an na_color pill, or is left blank when na_color is NULL.

Selecting several columns maps them all onto one domain, taken from the selection as a whole when domain is unset, so their colors stay comparable. Pill width is worked out per column, in ch units, so each column's pills line up with each other rather than with the widest value in the selection. With fill_type = "rank", each column is ranked against itself.

When fill_type is "rank", ranks are computed with rank() using averaged ties, then flipped when rank_order is "desc" so the top value anchors the high end of the palette. Leaving domain unset falls back to the observed range and warns, since the color mapping then depends on the data present.

Value

Returns a modified gt table with color pills in the selected columns.

See Also

gt_color_ranks() for filling the whole cell, and gt_legend_continuous() for a legend explaining the scale.

Examples

library(gt)

# the AFC's seven playoff teams
afc <- subset(
  sdv_example_standings, conference == "AFC" & conference_rank <= 7,
  c(team_name, wins, losses, points_for, points_against)
)

gt(afc) |> gt_color_pills(wins, domain = c(0, 17))

# several columns on one shared domain
gt(afc) |> gt_color_pills(c(points_for, points_against), domain = c(250, 550))

# tidyselect works too
gt(afc) |> gt_color_pills(starts_with("points"), domain = c(250, 550))

# only the rows that clear a threshold; the rest keep their raw value
gt(afc) |> gt_color_pills(wins, rows = wins >= 13, domain = c(0, 17))

# color by rank rather than value, with a paletteer palette
if (requireNamespace("paletteer", quietly = TRUE)) {
  gt(afc) |>
    gt_color_pills(points_for,
      fill_type = "rank", palette = "viridis::mako",
      domain = c(1, 7), digits = 0
    )
}

Description

A shorthand around gt::data_color() for filling columns that already hold rank values, where 1 is best. It takes either a plain vector of hex colors or a paletteer palette, and either an explicit domain or one derived from the data. Values are colored as they are; no ranking is computed for you.

Usage

gt_color_ranks(
  gt_object,
  columns,
  rows = NULL,
  palette = c("#3D8B6E", "#9DC5A7", "#EDE0CC", "#DB9070", "#BE4D3A"),
  domain = NULL,
  reverse = FALSE,
  na_color = "white",
  autocolor_text = TRUE,
  pal_type = "discrete",
  ...
)

Arguments

Details

The whole cell background is filled. gt_color_pills() does the same job with rounded pill spans instead.

Value

Returns a modified gt table with the selected columns filled by value.

See Also

gt_legend_continuous() for explaining the scale, and gt_color_pills() for a pill treatment instead of a full-cell fill.

Examples

library(gt)

west <- subset(sdv_example_standings, league == "nba" & conference == "Western")
ranked <- data.frame(
  team = west$team_name,
  offense_rank = rank(-west$points_for, ties.method = "min"),
  defense_rank = rank(west$points_against, ties.method = "min")
)

gt(ranked) |> gt_color_ranks(c(offense_rank, defense_rank))

# a paletteer palette, reversed
if (requireNamespace("paletteer", quietly = TRUE)) {
  gt(ranked) |>
    gt_color_ranks(offense_rank,
      palette = "viridis::mako", pal_type = "continuous",
      reverse = TRUE
    )
}

Description

Fills and recolors each row according to a result read from a column. Results can be encoded as "W" and "L" or as 1 and 0, with an optional tie state. Rows holding none of the values are left unchanged.

Usage

gt_color_results(
  gt_object,
  result_column = "result",
  win_color = "#5DA271",
  loss_color = "#C84630",
  tie_color = NULL,
  wins_text_color = "white",
  loss_text_color = "white",
  tie_text_color = "white",
  tie_value = "T",
  result_type = "wl"
)

Arguments

Details

A gt::tab_style() pass fills and recolors the body rows whose result_column equals the win value, then the loss value, and then, when tie_color is set, the tie_value. Under result_type = "wl" the win and loss values compared are "W" and "L"; under "binary" they are 1 and 0. Any row matching none of the values keeps its existing styling.

Value

Returns a modified gt table with winning and losing rows colored.

Examples

library(gt)

results <- data.frame(
  game = paste("Game", 1:4),
  pts = c(88, 74, 102, 65),
  result = c("W", "L", "W", "L")
)

gt(results) |> gt_color_results()

# binary encoding, with custom colors
results$result <- c(1, 0, 1, 0)
gt(results) |>
  gt_color_results(
    result_type = "binary", win_color = "#1B7837",
    loss_color = "#762A83"
  )

Description

Replaces each column label with a two-line header: a main heading stacked over a smaller subtitle. The heading and subtitle colors and font weights are set through arguments, and the per-column heading and subtitle text is supplied through ....

Usage

gt_column_subheaders(
  gt_object,
  heading_color = "black",
  subtitle_color = "#808080",
  heading_weight = "bold",
  subtitle_weight = "normal",
  heading_size = 14,
  subtitle_size = 10,
  font = NULL,
  ...
)

Arguments

Details

Every column in the table is relabeled, not only the ones named in .... The loop walks the full set of column names, looks each one up in ..., and builds an HTML label holding the heading at heading_size over the subtitle at subtitle_size, joined by a line break. A column with no entry in ... falls back to its own name as the heading and a non-breaking space as the subtitle, so the second line still takes vertical space and the headers stay aligned. Labels are applied with gt::cols_label(), so call this after any other label changes or they will be overwritten.

Value

Returns a modified gt table with stacked headers and subtitles.

Examples

library(gt)

sdv_example_standings |>
  subset(division == "AFC West", c(team_name, wins, points_for)) |>
  gt() |>
  gt_column_subheaders(
    wins = list(heading = "Wins", subtitle = "W"),
    points_for = list(heading = "Points", subtitle = "PF"),
    heading_color = "blue", subtitle_color = "gray"
  )

Description

Draws a rule across the table after a given row, with an optional label on it. This is the cut line convention used in ranked and sorted tables to mark a cutoff or qualifying threshold.

Usage

gt_cutline(
  gt_object,
  after,
  label = NULL,
  color = "#A6081A",
  weight = 2,
  style = "dashed",
  label_color = NULL,
  label_size = 9,
  label_position = c("below", "above"),
  gap = 0
)

Arguments

Details

The line is positional, not data-driven. gt::tab_row_group() splits a table on a value in the data and turns the result into labeled sections with heading rows. A cut line leaves the table flowing and marks a fixed row number.

The label is drawn as an inline SVG background image on the row, because gt's CSS inliner strips the ⁠::before⁠ and ⁠::after⁠ pseudo-elements this would normally be built with. That costs two things. An SVG background cannot use the page's webfonts, so the label renders in a system sans-serif rather than the theme's font. And a background image cannot straddle a border, so the labeled row is given extra padding for the label to sit in.

The labeled row's cell backgrounds are cleared, since row striping and themed body fills would otherwise cover the label. The row's own color is then reapplied to the row itself, so a striped theme such as gt_theme_almanac() keeps an unbroken stripe pattern. Colors set on individual cells in that row, such as gt_color_ranks() or gt_color_pills() fills, are cleared too; on a table with colored cells, draw the line unlabeled and describe it in a caption.

Labeled lines assume the table has no row groups, since group heading rows shift the row positions the label CSS targets. The rule itself is unaffected.

Apply the theme before this function. The stripe color is read from the table's options, so a line labeled first loses the stripe under its own row.

Value

Returns a modified gt table with the cut line or lines added.

See Also

gt_spotlight() for drawing attention to a row.

Examples

library(gt)

east <- subset(
  sdv_example_standings, league == "nba" & conference == "Eastern",
  c(conference_rank, team_name, wins, losses, win_pct)
)
east <- east[order(east$conference_rank), ]

# mark where the six teams that skip the play-in end
gt(east) |>
  gt_theme_broadsheet() |>
  gt_cutline(after = 6, label = "Playoffs")

# the play-in line as well, unlabeled
gt(east) |>
  gt_cutline(after = c(6, 10), label = c("Playoffs", NA), color = "#0054AD")

Description

Takes two numeric columns and inserts a new column holding the change between them, signed and colored by direction. The change is to minus from, so a later period as to and an earlier one as from gives a positive number when the value has grown. The arithmetic, the formatting, and the sign coloring happen in one call.

Usage

gt_delta(
  gt_object,
  from,
  to,
  column_label = "Change",
  percent = FALSE,
  decimals = 1,
  arrows = FALSE,
  color = TRUE,
  color_positive = "#1B7837",
  color_negative = "#B2182B",
  color_neutral = NULL,
  force_sign = TRUE,
  after = NULL
)

Arguments

Details

gt::fmt_number(force_sign = TRUE) formats a difference you have already worked out, and gtExtras::gt_fa_rank_change() handles movement in a rank column. This computes the delta from two columns, formats it, and colors it by sign together.

A row is left blank where either from or to is missing, and where a percent change divides by a from of zero. When arrows is TRUE the value is shown as a magnitude behind the triangle, so a decrease reads as a down triangle in front of a positive number.

Value

Returns a modified gt table with the change column added.

See Also

gt_scale_note() for disclosing a divided scale.

Examples

library(gt)

nfc_north <- subset(
  sdv_example_standings, division == "NFC North",
  c(team_name, last_season_wins, wins)
)

# the change in wins from 2024, colored by sign
gt(nfc_north) |> gt_delta(last_season_wins, wins)

# as a percent of last season's wins, with arrows
gt(nfc_north) |> gt_delta(last_season_wins, wins, percent = TRUE, arrows = TRUE)

Description

Turns plain integers into ordinals: 1 becomes 1st, 2 becomes 2nd, 23 becomes 23rd. The suffix can be rendered as superscript, which is the usual treatment in a ranked column.

Usage

gt_fmt_rank(gt_object, columns, superscript = TRUE, suffix_size = "0.7em")

Arguments

Details

Teens are handled correctly, so 11, 12 and 13 take "th" and not "st", "nd" and "rd". Values that are not numeric are left alone.

Value

Returns a modified gt table with ordinal formatting applied.

Examples

library(gt)

nfc <- subset(
  sdv_example_standings, conference == "NFC" & conference_rank <= 5,
  c(team_name, conference_rank)
)
nfc <- nfc[order(nfc$conference_rank), ]

gt(nfc) |> gt_fmt_rank(conference_rank)

# flat, without the superscript
gt(nfc) |> gt_fmt_rank(conference_rank, superscript = FALSE)

Description

Merges two or more count columns into one "32-5" style cell, optionally with one of them shown as a share of the row total. Any set of tallies works, from wins and losses to tests passed and failed.

Usage

gt_fmt_tally(
  gt_object,
  columns,
  separator = "-",
  label = NULL,
  share = FALSE,
  share_of = 1,
  share_location = c("inline", "column"),
  share_decimals = 1,
  share_label = "%",
  share_prefix = " (",
  share_suffix = ")",
  ...
)

Arguments

Details

The counts are written into the first column and the rest are hidden, or the last one is reused to carry the share, so the table ends up narrower than it started.

gt::cols_merge() will join columns with a pattern and gt::cols_merge_n_pct() will pair a count with a percentage column you have already built. The difference here is that the share is computed for you from the counts themselves.

A row is left alone if any of its counts are missing, so a partial tally is never shown. The share is also left blank where the counts sum to zero.

Value

Returns a modified gt table with the counts combined.

See Also

gt_fmt_rank() for ordinal formatting.

Examples

library(gt)

atlantic <- subset(
  sdv_example_standings, division == "Atlantic",
  c(team_name, wins, losses)
)

# renders as "56-26"
gt(atlantic) |> gt_fmt_tally(c(wins, losses), label = "Record")

# renders as "56-26 (68.3%)"
gt(atlantic) |> gt_fmt_tally(c(wins, losses), share = TRUE)

# the losing share instead, in its own column
gt(atlantic) |>
  gt_fmt_tally(c(wins, losses),
    share = TRUE, share_of = "losses",
    share_location = "column", share_label = "Loss rate"
  )

# three counts, as in an NFL standings table
nfc_east <- subset(
  sdv_example_standings, division == "NFC East",
  c(team_name, wins, losses, ties)
)

gt(nfc_east) |> gt_fmt_tally(c(wins, losses, ties), label = "W-L-T")

Description

Lays a list of tables out in rows and columns as small multiples, one table per region or per quarter. gtExtras::gt_two_column_layout() handles exactly two tables and gt_stack_tables() stacks any number of them vertically. This covers the rest.

Usage

gt_grid(
  tables = NULL,
  ncol = 2,
  labels = NULL,
  label_style = list(),
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  source_note = NULL,
  caption_rule = FALSE,
  title_style = list(),
  subtitle_style = list(),
  caption_style = list(),
  source_note_style = list(),
  gap = 24,
  align = c("top", "center", "bottom"),
  file = NULL,
  bg = "white",
  whitespace = 50,
  zoom = 2
)

Arguments

Details

Unlike most of this package, this does not return a gt table. Separate tables have their own columns, widths, and headers, so there is no single table to hand back; the grid is assembled as HTML. That makes it a last step, after each table is themed and formatted, and it is why saving happens here through file rather than through gt_save_crop().

Each table also keeps its own heading. Use title when the tables are blocks of a single thing, as with a long ranking split in two, and per-table gt::tab_header()s when they are genuinely separate exhibits.

Saving needs the webshot2 package.

Value

An htmltools::browsable() tag list of the grid, which prints in the viewer; with file, invisibly file after writing the PNG to it.

See Also

gt_stack_tables() for a vertical stack, and gt_snake() for folding a single long table into blocks.

Examples

library(gt)

afc <- subset(sdv_example_standings, conference == "AFC")
by_division <- lapply(split(afc, afc$division), function(d) {
  gt(d[c("team_name", "wins", "losses", "points_for")]) |>
    gt_theme_broadsheet() |>
    tab_header(title = d$division[[1]])
})

gt_grid(by_division, ncol = 2)

# one heading over the whole sheet
gt_grid(by_division,
  ncol = 2, title = "The AFC by division",
  subtitle = "2025 NFL regular season", caption = "Data: nflreadr"
)

# a 538-style split caption under the whole sheet
gt_grid(by_division,
  ncol = 2,
  title = "The AFC by division",
  caption = gt::md("Teams are grouped by **division**."),
  source_note = "Data: nflreadr | Andrew Weatherman",
  caption_rule = TRUE
)

# tighten the subtitle up under the title, and open the gap to the grid
gt_grid(by_division,
  ncol = 2, title = "The AFC", subtitle = "2025 regular season",
  title_style = list(margin_bottom = -2),
  subtitle_style = list(margin_bottom = 24)
)

# styled without writing any css
gt_grid(by_division,
  ncol = 2,
  title = "The AFC by division",
  subtitle = "2025 NFL regular season",
  title_style = list(font = "Oswald", size = 34, transform = "uppercase"),
  subtitle_style = list(italic = TRUE, color = "#8A8A8A")
)


# straight to an image; saving needs a headless Chrome (webshot2)

gt_grid(by_division, ncol = 2, file = tempfile(fileext = ".png"), bg = "#FBFAF7")

Description

Shades every other row group, so each group reads as a block. gt::opt_row_striping() bands every other row, which fights the grouping on a table that is already divided into sections.

Usage

gt_group_stripes(gt_object, color = "#F5F5F5", start = 2, include_stub = TRUE)

Arguments

Details

Groups are banded in the order they render, so this follows gt::row_group_order() rather than the order the groups happen to appear in the data.

The fill is applied to body cells rather than through CSS, because a group heading occupies a row of its own and shifts every nth-child count below it. Group heading rows are left alone; gt::tab_options(row_group.background.color) sets those, and it sets all of them at once.

Value

Returns a modified gt table with alternate groups banded.

Examples

library(gt)

afc <- subset(
  sdv_example_standings, conference == "AFC",
  c(team_name, division, wins, losses, points_for)
)

gt(afc, groupname_col = "division") |>
  gt_theme_broadsheet() |>
  gt_group_stripes()

# shade from the first group instead, in a warmer tone
gt(afc, groupname_col = "division") |>
  gt_group_stripes(color = "#FBF3E4", start = 1)

Description

Fills each cell in a block of columns that meets a condition and leaves the rest alone. It is the per-cell counterpart to gtExtras::gt_highlight_cols() and gtExtras::gt_highlight_rows(), which fill a whole column or a whole row. The condition is tested against every cell on its own, so a scattered set of cells can be filled in one call.

Usage

gt_highlight_cells(
  gt_object,
  columns,
  condition,
  fill = "#FFF3B0",
  text_color = NULL,
  bold = FALSE,
  ...
)

Arguments

Details

A single gt::tab_style() with gt::cells_body() cannot do this, since it reads rows and columns as a rectangle, every selected row crossed with every selected column. Filling a diagonal, a checker pattern, or any scatter otherwise takes a loop over the columns, one pass each. This wraps that loop.

Each selected column is filled independently, so the pattern can be a diagonal, a checker, or any scatter of cells.

The condition reads the underlying data rather than the rendered cell, so a test like ~ grepl("home", .x) sees whatever value the column holds, HTML and all. A formula or function must return one logical per row, and NA counts as not matched. For more than one color, layer the calls, one per color.

Value

Returns a modified gt table with the matching cells filled.

See Also

gtExtras::gt_highlight_cols() and gtExtras::gt_highlight_rows() for whole-column and whole-row fills.

Examples

library(gt)

# a correlation matrix: flag strong pairs, but not the diagonal of ones
nba <- subset(sdv_example_standings, league == "nba")
nba$point_diff <- nba$points_for - nba$points_against
vars <- c("wins", "point_diff", "points_for", "points_against", "conference_rank")
m <- round(cor(nba[vars]), 2)
cordf <- data.frame(var = rownames(m), m, row.names = NULL, check.names = FALSE)
cordf |>
  gt(rowname_col = "var") |>
  gt_highlight_cells(-var, ~ .x > 0.7 & .x < 1, fill = "#FFD1A9") |>
  gt_highlight_cells(-var, ~ .x < -0.7, fill = "#A9D0FF")

# a grid of team keys, one column per division in finishing order: playoff
# teams one color, the conference's top seed another
afc <- subset(sdv_example_standings, conference == "AFC")
grid <- data.frame(split(afc$team, afc$division), check.names = FALSE)
playoffs <- afc$team[afc$conference_rank <= 7]
top_seed <- afc$team[afc$conference_rank == 1]
gt(grid) |>
  gt_highlight_cells(everything(), ~ .x %in% playoffs, fill = "#CCE7F5") |>
  gt_highlight_cells(everything(), ~ .x == top_seed, fill = "#FCCF10")

Description

Highlights missing cells and can relabel them in the same call. gt::sub_missing() substitutes text only, and only for real NA values.

Usage

gt_highlight_na(
  gt_object,
  columns = gt::everything(),
  fill = "#F0F0F0",
  text_color = NULL,
  bold = FALSE,
  italic = FALSE,
  missing_text = NULL,
  na_strings = "NA",
  ignore_case = FALSE,
  ...
)

Arguments

Details

Alongside real NA, this also catches values that are literally the string "NA", a common artifact of reading a CSV and a frequent reason sub_missing() appears to do nothing. Widen na_strings to catch other placeholders such as "-" or "N/A".

Value

Returns a modified gt table with missing values styled.

See Also

gt_outliers() for flagging values that are present but suspect.

Examples

library(gt)

# playoff_wins is NA for the teams that missed the playoffs
afc <- subset(
  sdv_example_standings, conference == "AFC",
  c(team_name, wins, losses, conference_rank, playoff_wins)
)

gt(afc) |> gt_highlight_na(playoff_wins)

# relabel as well as highlight
gt(afc) |>
  gt_highlight_na(playoff_wins,
    missing_text = "missed playoffs",
    italic = TRUE, fill = "#FFF8E1"
  )

# also catch placeholder strings left behind by a CSV import
gt(afc) |>
  gt_highlight_na(everything(), na_strings = c("NA", "N/A", "-"))

Description

Replaces column values with colored boxes, filled when a value meets a rule and left neutral otherwise. By default the box is colored when a value equals the second element of indicator_vals (1) and left color_no when it equals the first (0); supply indicator_rule for any other test. Name the columns to convert with columns, or the ones to leave alone with key_columns.

Usage

gt_indicator_boxes(
  gt_object,
  columns = NULL,
  key_columns = NULL,
  indicator_vals = c(0, 1),
  indicator_rule = function(x) x == indicator_vals[2],
  color_yes = "#FCCF10",
  color_no = "#EEEEEE",
  show_na_as_na = FALSE,
  show_text = FALSE,
  show_only = NULL,
  per_column_formats = NULL,
  color_na = NULL,
  border_color = NULL,
  border_width = 0.25,
  box_width = 20,
  box_height = 20,
  text_size = 12,
  text_weight = "bold"
)

Arguments

Details

Every column outside key_columns is replaced with an HTML span through gt::text_transform(), and the transformed columns are then center-aligned. The rule is applied to the numeric coercion of each column, so text values become NA; NA cells take color_na (falling back to color_no) unless show_na_as_na keeps them labeled NA. Box text is set to black or white, whichever measures higher contrast against the fill.

When show_text is TRUE the box widens to fit the widest formatted value in the column; otherwise it is fixed at box_width. indicator_rule may accept a second argument, the column name, which allows a different test per column.

Value

Returns a modified gt table with the converted columns shown as colored boxes.

Examples

library(gt)

roster <- data.frame(
  player = c("A", "B", "C"),
  starter = c(1, 0, 1),
  injured = c(0, 0, 1),
  captain = c(1, 0, 0)
)

gt(roster) |> gt_indicator_boxes(key_columns = "player")

# print the underlying values and draw a border
gt(roster) |>
  gt_indicator_boxes(
    key_columns = "player", show_text = TRUE,
    border_color = "#333333"
  )

Description

Draws a legend for a column colored with gt_color_ranks() or gt::data_color(). Pass it the same columns and palette you colored with and the legend will match the table, including the domain it takes from the data. For a hand-built key of labeled swatches, use gt_legend_discrete().

Usage

gt_legend_continuous(
  gt_object,
  columns = NULL,
  palette = c("#3D8B6E", "#9DC5A7", "#EDE0CC", "#DB9070", "#BE4D3A"),
  domain = NULL,
  reverse = FALSE,
  pal_type = "discrete",
  type = c("continuous", "steps", "blocks"),
  n_bins = 5,
  labels = NULL,
  digits = 0,
  title = NULL,
  title_position = c("top", "bottom", "left", "right"),
  title_style = list(),
  labels_style = list(),
  labels_position = c("bottom", "top", "none"),
  location = c("bottom", "top"),
  align = c("center", "left", "right"),
  width = 200,
  height = 10,
  border_color = NULL,
  border_width = 1,
  radius = 2,
  gap = 3,
  title_gap = 4,
  block_gap = 2
)

Arguments

Details

The bar can be a smooth gradient, a stepped ramp, or separated blocks. The title can sit on any side of it, and the title and bound labels are styled independently through title_style and labels_style.

The bar is drawn as a series of solid color segments instead of a CSS gradient. gt's inline-CSS path, used by the RStudio Viewer, Quarto and R Markdown, strips gradient backgrounds, and the legend would disappear. Segment colors come from scales::col_numeric, the same function gt::data_color() uses, so the ramp matches the cells exactly.

gt_title_header() calls gt::tab_header(), which replaces the whole header. With location = "top", call gt_title_header() first or it will overwrite the legend.

Value

Returns a modified gt table with the legend added.

Styling

title_style and labels_style are named lists following the same convention as gt_grid() and gt_title_header(). Recognized keys are font (a Google font name), size, color, weight, italic, spacing (letter spacing), transform (such as "uppercase"), and align, plus line_height, margin_top, margin_bottom, padding_top, and padding_bottom. Any length takes a number, read as pixels, or a CSS string.

Picking up the scale

gt_color_ranks(), gt_color_pills() and gt_percentile_bar() record the columns, palette, domain, reverse and pal_type they used on the table. This function reads any of those the caller did not supply, so a legend can be added with no arguments and cannot disagree with the cells it explains:

gt(df) |>
  gt_color_ranks(net, palette = "viridis::mako", domain = c(-10, 12)) |>
  gt_legend_continuous()

Anything passed explicitly wins over the recorded value. With several coloring calls, the most recent one is the one recorded. The record is an attribute on the table and survives the rest of a pipeline, apart from gt_snake(), which rebuilds the table from its data; add the legend before snaking, or pass the arguments directly.

See Also

gt_color_ranks(), and gt_legend_discrete() for a discrete key.

Examples

library(gt)

# the legend matches whatever gt_color_ranks() drew
nfc_east <- subset(
  sdv_example_standings, division == "NFC East",
  c(team_name, wins, losses, points_for)
)
gt(nfc_east) |>
  gt_color_ranks(columns = points_for) |>
  gt_legend_continuous(columns = points_for, title = "Points scored")

# discrete blocks, labeled at every bin edge, title to the left
west <- subset(
  sdv_example_standings, league == "nba" & conference == "Western",
  c(team_name, wins, losses)
)
gt(west) |>
  gt_color_ranks(columns = wins) |>
  gt_legend_continuous(
    columns = wins, type = "blocks", n_bins = 5, labels = "edges",
    title = "Wins", title_position = "left",
    title_style = list(
      weight = 600, transform = "uppercase",
      spacing = "0.08em", size = "10px"
    ),
    labels_style = list(size = "9px", color = "#999999")
  )

Description

Draws a legend of labeled color swatches, the categorical counterpart to gt_legend_continuous(), which draws a continuous ramp. Give it the colors and labels you used elsewhere in the table, such as the fills from gt_highlight_cells() or gt_indicator_boxes(), and it renders a color key. After gt_tiers(), which records its mapping on the table, key_info can be left out entirely.

Usage

gt_legend_discrete(
  gt_object,
  key_info = NULL,
  heading = NULL,
  subtitle = NULL,
  label_placement = c("outside", "inside"),
  location = c("top", "bottom"),
  shape = c("square", "rounded", "circle"),
  swatch_size = 14,
  border = TRUE,
  border_color = NULL,
  border_width = 1,
  gap = 14,
  direction = c("horizontal", "vertical"),
  align = c("center", "left", "right"),
  heading_style = list(),
  subtitle_style = list(),
  label_style = list()
)

Arguments

Details

The key can sit above the table or below it, run in a row or a column, and take square, rounded, or circular swatches. An optional heading and subtitle can ride along above the swatches, each styled through its own list.

The key is passed as either a named vector, c("Home" = "#cce7f5", "Bye" = "#eeeeee"), where the names are the labels, or a data frame with a color column and a label column.

When label_placement is "inside", each label takes black or white by whichever contrasts better with its swatch, so a color in label_style is ignored in that mode.

gt_title_header() and anything else calling gt::tab_header() replaces the whole header. With location = "top", add those first or they will overwrite the key.

Value

Returns a modified gt table with the key added.

Styling

heading_style, subtitle_style, and label_style are named lists following the same convention as gt_grid() and gt_title_header(). Recognized keys are font (a Google font name), size, color, weight, italic, spacing (letter spacing), transform (such as "uppercase"), and align, plus line_height, margin_top, margin_bottom, padding_top, and padding_bottom. Any length takes a number, read as pixels, or a CSS string. Any key left out keeps its default. Colors left unset are derived from the table background, so the key reads on light and dark themes. Apply the theme first, since an unthemed table reports a white background and the heading and subtitle come out near-black on whatever ground the theme sets later.

See Also

gt_legend_continuous() for a continuous ramp.

Examples

library(gt)

afc_west <- subset(
  sdv_example_standings, division == "AFC West",
  c(team_name, wins, losses, playoff_wins)
)

# a named vector is the quickest way in
gt(afc_west) |>
  gt_legend_discrete(c("Playoffs" = "#CCE7F5", "Missed" = "#F5CCCC"))

# rounded swatches below the table, labels on the swatches
gt(afc_west) |>
  gt_legend_discrete(
    c("Yes" = "#FCCF10", "No" = "#EEEEEE"),
    heading = "Qualified",
    label_placement = "inside",
    location = "bottom",
    shape = "rounded"
  )

# style the heading and labels through lists, the same way gt_grid() does
gt(afc_west) |>
  gt_legend_discrete(
    c("Home" = "#CCE7F5", "Away" = "#FFFFFF", "Bye" = "#EEEEEE"),
    heading = "2025 Schedule",
    heading_style = list(font = "Oswald", size = 20, transform = "uppercase"),
    label_style = list(size = 13, color = "#444444")
  )

Description

Styles a text column as commentary instead of data. It applies a muted color, italics, a hairline separating the notes from the figures, a blank column label, and a width constraint so the prose wraps instead of stretching the table.

Usage

gt_marginalia(
  gt_object,
  columns,
  width = 220,
  label = "",
  italic = TRUE,
  color = NULL,
  size = "0.92em",
  rule = TRUE,
  rule_color = NULL,
  align = "left"
)

Arguments

Details

A text column with no width set runs to a single long line, so width is what wraps the prose. On a three-row example, that is the difference between a table 625 pixels wide and one 482 pixels wide.

Colors are derived from the table background instead of being hard-coded, so the treatment also reads correctly on a dark theme. That means the theme has to be applied first. An unthemed table reports a white background, and the notes come out too dark to read once a dark theme lands on top. Pass color and rule_color to fix them regardless of order.

Value

Returns a modified gt table with the selected columns styled as margin notes.

See Also

gt_cutline() for a labeled break between rows.

Examples

library(gt)

nfc_west <- subset(
  sdv_example_standings, division == "NFC West",
  c(team_name, wins, losses, conference_rank, playoff_wins)
)

# a note on each team's postseason, written from its own row
nfc_west$note <- with(nfc_west, ifelse(
  is.na(playoff_wins),
  "Missed the playoffs.",
  paste0(
    "The No. ", conference_rank, " seed; ", playoff_wins, " playoff win",
    ifelse(playoff_wins == 1, "", "s"), "."
  )
))

gt(nfc_west) |>
  gt_theme_broadsheet() |>
  gt_marginalia(note)

# keep a heading, widen it, and drop the italics
gt(nfc_west) |>
  gt_marginalia(note, label = "Postseason", width = 280, italic = FALSE)

Description

Takes an existing gt table and merges column 1 and column 2, stacking column 1's text on top of column 2's. Top text is in all caps with black bold text, while the lower text is smaller and colored by the team name.

Usage

gt_merge_stack_team_color(
  gt_object,
  col1,
  col2,
  team_col,
  league,
  font_size_top = 14,
  font_size_bottom = 12,
  color = "black",
  background = NULL,
  season = NULL,
  id_system = "auto"
)

Arguments

Details

The lower text takes the team's primary color when it clears a 4.5:1 contrast ratio (WCAG AA) against the cell background, else the secondary color, else the primary darkened (or lightened, on a dark background) until it does, so a light primary such as Missouri's gold stays readable on a white table and keeps its gold on a dark one.

Value

An object of class gt_tbl.

Examples

library(gt)
library(sdvplotR)

df <- data.frame(
  team = c("KC", "BUF", "SF"),
  mascot = c("Chiefs", "Bills", "49ers"),
  wins = c(11, 10, 12)
)

df |>
  gt() |>
  gt_merge_stack_team_color(team, mascot, team, league = "nfl")

Description

Marks cells that fall outside a threshold, either beyond an interquartile fence, beyond a number of standard deviations, or outside bounds you supply.

Usage

gt_outliers(
  gt_object,
  columns,
  method = c("iqr", "sd", "bounds"),
  threshold = NULL,
  bounds = NULL,
  side = c("both", "high", "low"),
  fill = NULL,
  color = NULL,
  bold = TRUE,
  symbol = NULL,
  note = NULL
)

Arguments

Details

gt::data_color() shades a continuous scale; this flags a value as unusual. Thresholds are computed separately for each column, so every column is judged against its own distribution.

The default rule is the interquartile fence, not standard deviations, because an SD fence is built from a spread that the outlier itself inflates. On c(10.2, 10.4, 10.1, 19.8, 10.3, 10.0) the mean is 11.8 and the standard deviation 3.92, so a three-SD fence reaches 23.6 and misses the 19.8. The quartiles barely move, so the IQR fence stops at 10.75 and catches it. The masking is worst in small samples. Use method = "sd" if you want it anyway.

Value

Returns a modified gt table with outlying values marked.

See Also

gt_highlight_na() for missing values, and gt_spotlight() for drawing attention to whole rows.

Examples

library(gt)

nba <- subset(
  sdv_example_standings, league == "nba",
  c(team_name, points_for, points_against)
)

# the default fence (1.5 times the IQR) catches the league's lowest scorer
gt(nba) |> gt_outliers(c(points_for, points_against), note = TRUE)

# an explicit acceptance range, flagging only the high side
gt(nba) |>
  gt_outliers(c(points_for, points_against),
    method = "bounds", bounds = c(NA, 9800),
    side = "high", fill = "#FDECEA", symbol = "†"
  )

# works on wider data too
nfl <- subset(
  sdv_example_standings, league == "nfl",
  c(team_name, wins, points_for, points_against)
)
gt(nfl) |> gt_outliers(c(wins, points_for, points_against))

Description

Draws a percentile as a filled track with a circular marker at the tip of the fill, the value printed inside it. The bar, the marker, and the number are all CSS, so the whole thing stays vector at any export scale.

Usage

gt_percentile_bar(
  gt_object,
  columns,
  rows = NULL,
  domain = c(0, 100),
  scale = "auto",
  palette = c("#3661AD", "#C9C9C9", "#D22D49"),
  reverse = FALSE,
  pal_type = "discrete",
  track_color = "#E9E9E9",
  track_height = 6,
  marker_size = 22,
  text_color = "#FFFFFF",
  font_size = NULL,
  ring_color = NULL,
  ring_width = 2,
  full_track = TRUE,
  na_label = "—",
  na_track_color = NULL,
  na_text_color = "#9A9A9A",
  decimals = 0,
  width = 220
)

Arguments