Package 'gt'

Description

The adjust_luminance() function can brighten or darken a palette of colors by an arbitrary number of steps, which is defined by a real number between -2.0 and 2.0. The transformation of a palette by a fixed step in this function will tend to apply greater darkening or lightening for those colors in the midrange compared to any very dark or very light colors in the input palette.

Usage

adjust_luminance(colors, steps)

Arguments

Details

This function can be useful when combined with the data_color() function's palette argument, which can use a vector of colors or any of the ⁠col_*⁠ functions from the scales package (all of which have a palette argument).

Value

A vector of color values.

Examples

Get a palette of 8 pastel colors from the RColorBrewer package.

pal <- RColorBrewer::brewer.pal(8, "Pastel2")

Create lighter and darker variants of the base palette (one step lower, one step higher).

pal_darker  <- pal |> adjust_luminance(-1.0)
pal_lighter <- pal |> adjust_luminance(+1.0)

Create a tibble and make a gt table from it. Color each column in order of increasingly darker palettes (with data_color()).

dplyr::tibble(a = 1:8, b = 1:8, c = 1:8) |>
  gt() |>
  data_color(
    columns = a,
    colors = scales::col_numeric(
      palette = pal_lighter,
      domain = c(1, 8)
    )
  ) |>
  data_color(
    columns = b,
    colors = scales::col_numeric(
      palette = pal,
      domain = c(1, 8)
    )
  ) |>
  data_color(
    columns = c,
    colors = scales::col_numeric(
      palette = pal_darker,
      domain = c(1, 8)
    )
  )

Function ID

8-9

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other helper functions: cell_borders(), cell_fill(), cell_text(), currency(), default_fonts(), escape_latex(), from_column(), google_font(), gt_latex_dependencies(), html(), md(), nanoplot_options(), pct(), px(), random_id(), row_group(), stub(), system_fonts(), unit_conversion()

Description

as_gtable() performs the transformation of a gt_tbl object to a gtable object.

Usage

as_gtable(data, plot = FALSE, text_grob = grid::textGrob)

Arguments

Value

A gtable object.

Function ID

13-6

Function Introduced

v0.11.0 (July 9, 2024)

See Also

Other table export functions: as_latex(), as_raw_html(), as_rtf(), as_word(), extract_body(), extract_cells(), extract_summary(), gtsave()

Description

Get the LaTeX content from a gt_tbl object as a knit_asis object. This object contains the LaTeX code and attributes that serve as LaTeX dependencies (i.e., the LaTeX packages required for the table). Using as.character() on the created object will result in a single-element vector containing the LaTeX code.

Usage

as_latex(data)

Arguments

Details

LaTeX packages required to generate tables are: booktabs, caption, longtable, colortbl, array, anyfontsize, multirow.

In the event packages are not automatically added during the render phase of the document, please create and include a style file to load them.

Inside the document's YAML metadata, please include:

output:
  pdf_document: # Change to appropriate LaTeX template
    includes:
      in_header: 'gt_packages.sty'

The gt_packages.sty file would then contain the listed dependencies above:

  \usepackage{booktabs, caption, longtable, colortbl, array}

Examples

Use a subset of the gtcars dataset to create a gt table. Add a header with tab_header() and then export the table as LaTeX code using the as_latex() function.

tab_latex <-
  gtcars |>
  dplyr::select(mfr, model, msrp) |>
  dplyr::slice(1:5) |>
  gt() |>
  tab_header(
    title = md("Data listing from **gtcars**"),
    subtitle = md("`gtcars` is an R dataset")
  ) |>
  as_latex()

What's returned is a knit_asis object, which makes it easy to include in R Markdown documents that are knit to PDF. We can use as.character() to get just the LaTeX code as a single-element vector.

Function ID

13-3

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other table export functions: as_gtable(), as_raw_html(), as_rtf(), as_word(), extract_body(), extract_cells(), extract_summary(), gtsave()

Description

Get the HTML content from a gt_tbl object as a single-element character vector. By default, the generated HTML will have inlined styles, where CSS styles (that were previously contained in CSS rule sets external to the ⁠<table> element⁠) are included as style attributes in the HTML table's tags. This option is preferable when using the output HTML table in an emailing context.

Usage

as_raw_html(data, inline_css = TRUE)

Arguments

Examples

Use a subset of the gtcars dataset to create a gt table. Add a header with tab_header() and then export the table as HTML code with inlined CSS styles using as_raw_html().

tab_html <-
  gtcars |>
  dplyr::select(mfr, model, msrp) |>
  dplyr::slice_head(n = 5) |>
  gt() |>
  tab_header(
    title = md("Data listing from **gtcars**"),
    subtitle = md("`gtcars` is an R dataset")
  ) |>
  as_raw_html()

What's returned is a single-element vector containing the HTML for the table. It has only the ⁠<table>...</table>⁠ part so it's not a complete HTML document but rather an HTML fragment.

Function ID

13-2

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other table export functions: as_gtable(), as_latex(), as_rtf(), as_word(), extract_body(), extract_cells(), extract_summary(), gtsave()

Description

Get the RTF content from a gt_tbl object as as a single-element character vector. This object can be used with writeLines() to generate a valid .rtf file that can be opened by RTF readers.

Usage

as_rtf(
  data,
  incl_open = TRUE,
  incl_header = TRUE,
  incl_page_info = TRUE,
  incl_body = TRUE,
  incl_close = TRUE
)

Arguments

Examples

Use a subset of the gtcars dataset to create a gt table. Add a header with tab_header() and then export the table as RTF code using the as_rtf() function.

tab_rtf <-
  gtcars |>
  dplyr::select(mfr, model) |>
  dplyr::slice(1:2) |>
  gt() |>
  tab_header(
    title = md("Data listing from **gtcars**"),
    subtitle = md("`gtcars` is an R dataset")
  ) |>
  as_rtf()

Function ID

13-4

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other table export functions: as_gtable(), as_latex(), as_raw_html(), as_word(), extract_body(), extract_cells(), extract_summary(), gtsave()

Description

Get the Open Office XML table tag content from a gt_tbl object as a single-element character vector.

Usage

as_word(
  data,
  align = "center",
  caption_location = c("top", "bottom", "embed"),
  caption_align = "left",
  split = FALSE,
  keep_with_next = TRUE
)

Arguments

Examples

Use a subset of the gtcars dataset to create a gt table. Add a header with tab_header() and then export the table as OOXML code for Word using as_word()

tab_rtf <-
  gtcars |>
  dplyr::select(mfr, model) |>
  dplyr::slice(1:2) |>
  gt() |>
  tab_header(
    title = md("Data listing from **gtcars**"),
    subtitle = md("`gtcars` is an R dataset")
  ) |>
  as_word()

Function ID

13-5

Function Introduced

v0.7.0 (August 25, 2022)

See Also

Other table export functions: as_gtable(), as_latex(), as_raw_html(), as_rtf(), extract_body(), extract_cells(), extract_summary(), gtsave()

Description

cell_borders() is to be used with tab_style(), which itself allows for the setting of custom styles to one or more cells. Specifically, the call to cell_borders() should be bound to the styles argument of tab_style(). The sides argument is where we define which borders should be modified (e.g., "left", "right", etc.). With that selection, the color, style, and weight of the selected borders can then be modified.

Usage

cell_borders(sides = "all", color = "#000000", style = "solid", weight = px(1))

Arguments

Value

A list object of class cell_styles.

Examples

We can add horizontal border lines for all table body rows in a gt table based on the exibble dataset. For this, we need to use tab_style() (targeting all cells in the table body with cells_body()) in conjunction with cell_borders() in the style argument. Both top and bottom borders will be added as "solid" and "red" lines with a line width of 1.5 px.

exibble |>
  gt() |>
  tab_style(
    style = cell_borders(
      sides = c("top", "bottom"),
      color = "red",
      weight = px(1.5),
      style = "solid"
    ),
    locations = cells_body()
  )

It's possible to incorporate different horizontal and vertical ("left" and "right") borders at several different locations. This uses multiple cell_borders() and cells_body() calls within their own respective lists.

exibble |>
  gt() |>
  tab_style(
    style = list(
      cell_borders(
        sides = c("top", "bottom"),
        color = "#FF0000",
        weight = px(2)
      ),
      cell_borders(
        sides = c("left", "right"),
        color = "#0000FF",
        weight = px(2)
      )
    ),
    locations = list(
      cells_body(
        columns = num,
        rows = is.na(num)
      ),
      cells_body(
        columns = currency,
        rows = is.na(currency)
      )
    )
  )

Function ID

8-27

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other helper functions: adjust_luminance(), cell_fill(), cell_text(), currency(), default_fonts(), escape_latex(), from_column(), google_font(), gt_latex_dependencies(), html(), md(), nanoplot_options(), pct(), px(), random_id(), row_group(), stub(), system_fonts(), unit_conversion()

Description

cell_fill() is to be used with tab_style(), which itself allows for the setting of custom styles to one or more cells. Specifically, the call to cell_fill() should be bound to the styles argument of tab_style().

Usage

cell_fill(color = "#D3D3D3", alpha = NULL)

Arguments

Value

A list object of class cell_styles.

Examples

Let's use the exibble dataset to create a simple, two-column gt table (keeping only the num and currency columns). Styles are added with tab_style() in two separate calls (targeting different body cells with the cells_body() helper function). With the cell_fill() helper function we define cells with a "lightblue" background in one instance, and "gray85" in the other.

exibble |>
  dplyr::select(num, currency) |>
  gt() |>
  fmt_number(decimals = 1) |>
  tab_style(
    style = cell_fill(color = "lightblue"),
    locations = cells_body(
      columns = num,
      rows = num >= 5000
    )
  ) |>
  tab_style(
    style = cell_fill(color = "gray85"),
    locations = cells_body(
      columns = currency,
      rows = currency < 100
    )
  )

Function ID

8-26

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other helper functions: adjust_luminance(), cell_borders(), cell_text(), currency(), default_fonts(), escape_latex(), from_column(), google_font(), gt_latex_dependencies(), html(), md(), nanoplot_options(), pct(), px(), random_id(), row_group(), stub(), system_fonts(), unit_conversion()

Description

This helper function can be used with tab_style(), which itself allows for the setting of custom styles to one or more cells. We can also define several styles within a single call of cell_text() and tab_style() will reliably apply those styles to the targeted element.

Usage

cell_text(
  color = NULL,
  font = NULL,
  size = NULL,
  align = NULL,
  v_align = NULL,
  style = NULL,
  weight = NULL,
  stretch = NULL,
  decorate = NULL,
  transform = NULL,
  whitespace = NULL,
  indent = NULL
)

Arguments

Value

A list object of class cell_styles.

Examples

Let's use the exibble dataset to create a simple, two-column gt table (keeping only the num and currency columns). With tab_style() (called twice), we'll selectively add style to the values formatted with fmt_number(). We do this by using cell_text() in the style argument of tab_style().

exibble |>
  dplyr::select(num, currency) |>
  gt() |>
  fmt_number(decimals = 1) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_body(
      columns = num,
      rows = num >= 5000
    )
  ) |>
  tab_style(
    style = cell_text(style = "italic"),
    locations = cells_body(
      columns = currency,
      rows = currency < 100
    )
  )

Function ID

8-25

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other helper functions: adjust_luminance(), cell_borders(), cell_fill(), currency(), default_fonts(), escape_latex(), from_column(), google_font(), gt_latex_dependencies(), html(), md(), nanoplot_options(), pct(), px(), random_id(), row_group(), stub(), system_fonts(), unit_conversion()

Description

cells_body() is used to target the data cells in the table body. The function can be used to apply a footnote with tab_footnote(), to add custom styling with tab_style(), or the transform the targeted cells with text_transform(). The function is expressly used in each of those functions' locations argument. The 'body' location is present by default in every gt table.

Usage

cells_body(columns = everything(), rows = everything())

Arguments

Value

A list object with the classes cells_body and location_cells.

Targeting cells with columns and rows

Targeting of values is done through columns and additionally by rows (if nothing is provided for rows then entire columns are selected). The columns argument allows us to target a subset of cells contained in the resolved columns. We say resolved because aside from declaring column names in c() (with bare column names or names in quotes) we can use tidyselect-style expressions. This can be as basic as supplying a select helper like starts_with(), or, providing a more complex incantation like

where(~ is.numeric(.x) & max(.x, na.rm = TRUE) > 1E6)

which targets numeric columns that have a maximum value greater than 1,000,000 (excluding any NAs from consideration).

Once the columns are targeted, we may also target the rows within those columns. This can be done in a variety of ways. If a stub is present, then we potentially have row identifiers. Those can be used much like column names in the columns-targeting scenario. We can use simpler tidyselect-style expressions (the select helpers should work well here) and we can use quoted row identifiers in c(). It's also possible to use row indices (e.g., c(3, 5, 6)) though these index values must correspond to the row numbers of the input data (the indices won't necessarily match those of rearranged rows if row groups are present). One more type of expression is possible, an expression that takes column values (can involve any of the available columns in the table) and returns a logical vector.

Examples

Let's use a subset of the gtcars dataset to create a gt table. Add a footnote (with tab_footnote()) that targets a single data cell via the use of cells_body() in locations (rows = hp == max(hp) will target a single row in the hp column).

gtcars |>
  dplyr::filter(ctry_origin == "United Kingdom") |>
  dplyr::select(mfr, model, year, hp) |>
  gt() |>
  tab_footnote(
    footnote = "Highest horsepower.",
    locations = cells_body(
      columns = hp,
      rows = hp == max(hp)
    ),
    placement = "right"
  ) |>
  opt_footnote_marks(marks = c("*", "+"))

Function ID

8-18

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_column_labels() is used to target the table's column labels when applying a footnote with tab_footnote() or adding custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The 'column_labels' location is present by default in every gt table.

Usage

cells_column_labels(columns = everything())

Arguments

Value

A list object with the classes cells_column_labels and location_cells.

Targeting columns with the columns argument

The columns argument allows us to target a subset of columns contained in the table. We can declare column names in c() (with bare column names or names in quotes) or we can use tidyselect-style expressions. This can be as basic as supplying a select helper like starts_with(), or, providing a more complex incantation like

where(~ is.numeric(.x) & max(.x, na.rm = TRUE) > 1E6)

which targets numeric columns that have a maximum value greater than 1,000,000 (excluding any NAs from consideration).

Examples

Let's use a small portion of the sza dataset to create a gt table. Add footnotes to the column labels with tab_footnote() and cells_column_labels() in locations.

sza |>
  dplyr::filter(
    latitude == 20 & month == "jan" &
      !is.na(sza)
  ) |>
  dplyr::select(-latitude, -month) |>
  gt() |>
  tab_footnote(
    footnote = "True solar time.",
    locations = cells_column_labels(
      columns = tst
    )
  ) |>
  tab_footnote(
    footnote = "Solar zenith angle.",
    locations = cells_column_labels(
      columns = sza
    )
  )

Function ID

8-15

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_body(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_column_spanners() is used to target the cells that contain the table column spanners. This is useful when applying a footnote with tab_footnote() or adding custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The 'column_spanners' location is generated by one or more uses of tab_spanner() or tab_spanner_delim().

Usage

cells_column_spanners(spanners = everything(), levels = NULL)

Arguments

Value

A list object with the classes cells_column_spanners and location_cells.

Examples

Use the exibble dataset to create a gt table. We'll add a spanner column label over three columns (date, time, and datetime) with tab_spanner(). The spanner column label can be styled with tab_style() by using the cells_column_spanners() function in locations. In this example, we are making the text of the column spanner label appear as bold.

exibble |>
  dplyr::select(-fctr, -currency, -group) |>
  gt(rowname_col = "row") |>
  tab_spanner(
    label = "dates and times",
    columns = c(date, time, datetime),
    id = "dt"
  ) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_column_spanners(spanners = "dt")
  )

Use the exibble dataset to create a gt table. We'll add two spanners for the column combinations of (num, char) and time related columns (time and datetime). Furthermore we add another level of spanners with a column label over all date- and time related columns (date, time, and datetime). We want all spanner labels with "time" in their name to be bold. Additionally we want the text to be red of the spanner that is both time- related and on level 1.

exibble |>
  dplyr::select(-fctr, -currency, -group) |>
  gt(rowname_col = "row") |>
  tab_spanner(
    label = "time related cols",
    columns = c(datetime, time)
  ) |>
  tab_spanner(
    label = "num and char",
    columns = c(num, char)
  ) |>
  tab_spanner(
    label = "date and time cols",
    columns = c(date, time, datetime)
  ) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_column_spanners(spanners = tidyselect::contains("time"))
  ) |>
  tab_style(
    style = cell_text(color = "red"),
    locations = cells_column_spanners(
      spanners = tidyselect::contains("time"),
      levels = 1
    )
  )

Function ID

8-14

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_footnotes() is used to target all footnotes in the footer section of the table. This is useful for adding custom styles to the footnotes with tab_style() (using the locations argument). The 'footnotes' location is generated by one or more uses of tab_footnote(). This location helper function cannot be used for the locations argument of tab_footnote() and doing so will result in a warning (with no change made to the table).

Usage

cells_footnotes()

Value

A list object with the classes cells_footnotes and location_cells.

Examples

Using a subset of the sza dataset, let's create a gt table. We'd like to color the sza column so that's done with the data_color() function. We can add a footnote with tab_footnote() and we can also style the footnotes section. The styling is done with tab_style() and locations = cells_footnotes().

sza |>
  dplyr::filter(
    latitude == 20 &
      month == "jan" &
      !is.na(sza)
  ) |>
  dplyr::select(-latitude, -month) |>
  gt() |>
  data_color(
    columns = sza,
    palette = c("white", "yellow", "navyblue"),
    domain = c(0, 90)
  ) |>
  tab_footnote(
    footnote = "Color indicates height of sun.",
    locations = cells_column_labels(columns = sza)
  ) |>
  tab_options(table.width = px(320)) |>
  tab_style(
    style = list(
      cell_text(size = "smaller"),
      cell_fill(color = "gray90")
      ),
    locations = cells_footnotes()
  )

Function ID

8-23

Function Introduced

v0.3.0 (May 12, 2021)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_grand_summary() is used to target the cells in a grand summary and it is useful when applying a footnote with tab_footnote() or adding custom styles with tab_style(). The function is expressly used in each of those functions' locations argument. The 'grand_summary' location is generated by grand_summary_rows().

Usage

cells_grand_summary(columns = everything(), rows = everything())

Arguments

Value

A list object with the classes cells_grand_summary and location_cells.

Targeting cells with columns and rows

Targeting of grand summary cells is done through the columns and rows arguments. The columns argument allows us to target a subset of grand summary cells contained in the resolved columns. We say resolved because aside from declaring column names in c() (with bare column names or names in quotes) we can use tidyselect-style expressions. This can be as basic as supplying a select helper like starts_with(), or, providing a more complex incantation like

where(~ is.numeric(.x) & max(.x, na.rm = TRUE) > 1E6)

which targets numeric columns that have a maximum value greater than 1,000,000 (excluding any NAs from consideration).

Once the columns are targeted, we may also target the rows of the grand summary. Grand summary cells in the stub will have ID values that can be used much like column names in the columns-targeting scenario. We can use simpler tidyselect-style expressions (the select helpers should work well here) and we can use quoted row identifiers in c(). It's also possible to use row indices (e.g., c(3, 5, 6)) that correspond to the row number of a grand summary row.

Examples

Use a portion of the countrypops dataset to create a gt table. Add some styling to a grand summary cells with tab_style() and cells_grand_summary() in the locations argument.

countrypops |>
  dplyr::filter(country_name == "Spain", year < 1970) |>
  dplyr::select(-contains("country")) |>
  gt(rowname_col = "year") |>
  fmt_number(
    columns = population,
    decimals = 0
  ) |>
  grand_summary_rows(
    columns = population,
    fns = change ~ max(.) - min(.),
    fmt = ~ fmt_integer(.)
  ) |>
  tab_style(
    style = list(
      cell_text(style = "italic"),
      cell_fill(color = "lightblue")
    ),
    locations = cells_grand_summary(
      columns = population,
      rows = 1
    )
  )

Function ID

8-20

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_row_groups() is used to target the table's row groups when applying a footnote with tab_footnote() or adding custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The 'row_groups' location can be generated by the specifying a groupname_col in gt(), by introducing grouped data to gt() (via dplyr::group_by()), or, by specifying groups with tab_row_group().

Usage

cells_row_groups(groups = everything())

Arguments

Value

A list object with the classes cells_row_groups and location_cells.

Targeting cells with groups

By default groups is set to everything(), which means that all available groups will be considered. Providing the ID values (in quotes) of row groups in c() will serve to constrain the targeting to that subset of groups.

Examples

Let's use a summarized version of the pizzaplace dataset to create a gt table with grouped data. Add a summary with summary_rows() and then add a footnote to the "peppr_salami" row group label with tab_footnote(); the targeting is done with cells_row_groups() in the locations argument.

pizzaplace |>
  dplyr::filter(name %in% c("soppressata", "peppr_salami")) |>
  dplyr::group_by(name, size) |>
  dplyr::summarize(`Pizzas Sold` = dplyr::n(), .groups = "drop") |>
  gt(rowname_col = "size", groupname_col = "name") |>
  summary_rows(
    columns = `Pizzas Sold`,
    fns = list(label = "TOTAL", fn = "sum"),
    fmt = ~ fmt_integer(.)
  ) |>
  tab_footnote(
    footnote = "The Pepper-Salami.",
    cells_row_groups(groups = "peppr_salami")
  )

Function ID

8-16

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_source_notes() is used to target all source notes in the footer section of the table. This is useful for adding custom styles to the source notes with tab_style() (using the locations argument). The 'source_notes' location is generated by tab_source_note().

Usage

cells_source_notes()

Value

A list object with the classes cells_source_notes and location_cells.

Examples

Let's use a subset of the gtcars dataset to create a gt table. Add a source note (with tab_source_note()) and style the source notes section inside tab_style() with locations = cells_source_notes().

gtcars |>
  dplyr::select(mfr, model, msrp) |>
  dplyr::slice(1:5) |>
  gt() |>
  tab_source_note(source_note = "From edmunds.com") |>
  tab_style(
    style = cell_text(
      color = "#A9A9A9",
      size = "small"
    ),
    locations = cells_source_notes()
  )

Function ID

8-24

Function Introduced

v0.3.0 (May 12, 2021)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_stub() is used to target the table's stub cells and it is useful when applying a footnote with tab_footnote() or adding a custom style with tab_style(). The function is expressly used in each of those functions' locations argument. Here are several ways that a stub location might be available in a gt table: (1) through specification of a rowname_col in gt(), (2) by introducing a data frame with row names to gt() with rownames_to_stub = TRUE, or (3) by using summary_rows() or grand_summary_rows() with neither of the previous two conditions being true.

Usage

cells_stub(rows = everything())

Arguments

Value

A list object with the classes cells_stub and location_cells.

Examples

Using a transformed version of the sza dataset, let's create a gt table. Color all of the month values in the table stub with tab_style(), using cells_stub() in locations.

sza |>
  dplyr::filter(latitude == 20 & tst <= "1000") |>
  dplyr::select(-latitude) |>
  dplyr::filter(!is.na(sza)) |>
  tidyr::spread(key = "tst", value = sza) |>
  gt(rowname_col = "month") |>
  sub_missing(missing_text = "") |>
  tab_style(
    style = list(
      cell_fill(color = "darkblue"),
      cell_text(color = "white")
      ),
    locations = cells_stub()
  )

Function ID

8-17

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_stub_grand_summary() is used to target the stub cells of a grand summary and it is useful when applying a footnote with tab_footnote() or adding custom styles with tab_style(). The function is expressly used in each of those functions' locations argument. The 'stub_grand_summary' location is generated by grand_summary_rows().

Usage

cells_stub_grand_summary(rows = everything())

Arguments

Value

A list object with the classes cells_stub_grand_summary and location_cells.

Targeting grand summary stub cells with rows

Targeting the stub cells of a grand summary row is done through the rows argument. Grand summary cells in the stub will have ID values that can be used much like column names in the columns-targeting scenario. We can use simpler tidyselect-style expressions (the select helpers should work well here) and we can use quoted row identifiers in c(). It's also possible to use row indices (e.g., c(3, 5, 6)) that correspond to the row number of a grand summary row.

Examples

Use a portion of the countrypops dataset to create a gt table. Add some styling to a grand summary stub cell with tab_style() and using cells_stub_grand_summary() in the locations argument.

countrypops |>
  dplyr::filter(country_name == "Spain", year < 1970) |>
  dplyr::select(-contains("country")) |>
  gt(rowname_col = "year") |>
  fmt_number(
    columns = population,
    decimals = 0
  ) |>
  grand_summary_rows(
    columns = population,
    fns = list(change = ~max(.) - min(.)),
    fmt = ~ fmt_integer(.)
  ) |>
  tab_style(
    style = cell_text(weight = "bold", transform = "uppercase"),
    locations = cells_stub_grand_summary(rows = "change")
  )

Function ID

8-22

Function Introduced

v0.3.0 (May 12, 2021)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_stub_summary() is used to target the stub cells of summary and it is useful when applying a footnote with tab_footnote() or adding custom styles with tab_style(). The function is expressly used in each of those functions' locations argument. The 'stub_summary' location is generated by summary_rows().

Usage

cells_stub_summary(groups = everything(), rows = everything())

Arguments

Value

A list object with the classes cells_stub_summary and location_cells.

Targeting summary stub cells with groups and rows

Targeting the stub cells of group summary rows is done through the groups and rows arguments. By default groups is set to everything(), which means that all available groups will be considered. Providing the ID values (in quotes) of row groups in c() will serve to constrain the targeting to that subset of groups.

Once the groups are targeted, we may also target the rows of the summary. Summary cells in the stub will have ID values that can be used much like column names in the columns-targeting scenario. We can use simpler tidyselect-style expressions (the select helpers should work well here) and we can use quoted row identifiers in c(). It's also possible to use row indices (e.g., c(3, 5, 6)) that correspond to the row number of a summary row in a row group (numbering restarts with every row group).

Examples

Use a portion of the countrypops dataset to create a gt table. Add some styling to the summary data stub cells with tab_style() and cells_stub_summary() in the locations argument.

countrypops |>
  dplyr::filter(country_name == "Japan", year < 1970) |>
  dplyr::select(-contains("country")) |>
  dplyr::mutate(decade = paste0(substr(year, 1, 3), "0s")) |>
  gt(
    rowname_col = "year",
    groupname_col = "decade"
  ) |>
  fmt_integer(columns = population) |>
  summary_rows(
    groups = "1960s",
    columns = population,
    fns = list("min", "max"),
    fmt = ~ fmt_integer(.)
  ) |>
  tab_style(
    style = list(
      cell_text(
        weight = "bold",
        transform = "capitalize"
      ),
      cell_fill(
        color = "lightblue",
        alpha = 0.5
      )
    ),
    locations = cells_stub_summary(
      groups = "1960s"
    )
  )

Function ID

8-21

Function Introduced

v0.3.0 (May 12, 2021)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stubhead(), cells_summary(), cells_title(), location-helper

Description

cells_stubhead() is used to target the table stubhead location when applying a footnote with tab_footnote() or adding custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The 'stubhead' location is always present alongside the 'stub' location.

Usage

cells_stubhead()

Value

A list object with the classes cells_stubhead and location_cells.

Examples

Using a summarized version of the pizzaplace dataset, let's create a gt table. Add a stubhead label with tab_stubhead() and then style it with tab_style() in conjunction with the use of cells_stubhead() in the locations argument.

pizzaplace |>
  dplyr::mutate(month = as.numeric(substr(date, 6, 7))) |>
  dplyr::group_by(month, type) |>
  dplyr::summarize(sold = dplyr::n(), .groups = "drop") |>
  dplyr::filter(month %in% 1:2) |>
  gt(rowname_col = "type") |>
  tab_stubhead(label = "type") |>
  tab_style(
    style = cell_fill(color = "lightblue"),
    locations = cells_stubhead()
  )

Function ID

8-13

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_summary(), cells_title(), location-helper

Description

cells_summary() is used to target the cells in a group summary and it is useful when applying a footnote with tab_footnote() or adding a custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The 'summary' location is generated by summary_rows().

Usage

cells_summary(
  groups = everything(),
  columns = everything(),
  rows = everything()
)

Arguments

Value

A list object with the classes cells_summary and location_cells.

Targeting cells with columns, rows, and groups

Targeting of summary cells is done through the groups, columns, and rows arguments. By default groups is set to everything(), which means that all available groups will be considered. Providing the ID values (in quotes) of row groups in c() will serve to constrain the targeting to that subset of groups.

The columns argument allows us to target a subset of summary cells contained in the resolved columns. We say resolved because aside from declaring column names in c() (with bare column names or names in quotes) we can use tidyselect-style expressions. This can be as basic as supplying a select helper like starts_with(), or, providing a more complex incantation like

where(~ is.numeric(.x) & max(.x, na.rm = TRUE) > 1E6)

which targets numeric columns that have a maximum value greater than 1,000,000 (excluding any NAs from consideration).

Once the groups and columns are targeted, we may also target the rows of the summary. Summary cells in the stub will have ID values that can be used much like column names in the columns-targeting scenario. We can use simpler tidyselect-style expressions (the select helpers should work well here) and we can use quoted row identifiers in c(). It's also possible to use row indices (e.g., c(3, 5, 6)) that correspond to the row number of a summary row in a row group (numbering restarts with every row group).

Examples

Use a portion of the countrypops dataset to create a gt table. Add some styling to the summary data cells with tab_style(), using cells_summary() in the locations argument.

countrypops |>
  dplyr::filter(country_name == "Japan", year < 1970) |>
  dplyr::select(-contains("country")) |>
  dplyr::mutate(decade = paste0(substr(year, 1, 3), "0s")) |>
  gt(
    rowname_col = "year",
    groupname_col = "decade"
  ) |>
  fmt_number(
    columns = population,
    decimals = 0
  ) |>
  summary_rows(
    groups = "1960s",
    columns = population,
    fns = list("min", "max"),
    fmt = ~ fmt_integer(.)
  ) |>
  tab_style(
    style = list(
      cell_text(style = "italic"),
      cell_fill(color = "lightblue")
    ),
    locations = cells_summary(
      groups = "1960s",
      columns = population,
      rows = 1
    )
  ) |>
  tab_style(
    style = list(
      cell_text(style = "italic"),
      cell_fill(color = "lightgreen")
    ),
    locations = cells_summary(
      groups = "1960s",
      columns = population,
      rows = 2
    )
  )

Function ID

8-19

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_title(), location-helper

Description

cells_title() is used to target the table title or subtitle when applying a footnote with tab_footnote() or adding custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The header location where the title and optionally the subtitle reside is generated by the tab_header() function.

Usage

cells_title(groups = c("title", "subtitle"))

Arguments

Value

A list object of classes cells_title and location_cells.

Examples

Use a subset of the sp500 dataset to create a small gt table. Add a header with a title, and then add a footnote to the title with tab_footnote() and cells_title() (in locations).

sp500 |>
  dplyr::filter(date >= "2015-01-05" & date <= "2015-01-10") |>
  dplyr::select(-c(adj_close, volume, high, low)) |>
  gt() |>
  tab_header(title = "S&P 500") |>
  tab_footnote(
    footnote = "All values in USD.",
    locations = cells_title(groups = "title")
  )

Function ID

8-12

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other location helper functions: cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_summary(), location-helper

Description

We can add new columns to a table with cols_add() and it works quite a bit like dplyr::mutate() does. The idea is that you supply name-value pairs where the name is the new column name and the value part describes the data that will go into the column. The latter can: (1) be a vector where the length of the number of rows in the data table, (2) be a single value (which will be repeated all the way down), or (3) involve other columns in the table (as they represent vectors of the correct length). The new columns are added to the end of the column series by default but can instead be added internally by using either the .before or .after arguments. If entirely empty (i.e., all NA) columns need to be added, you can use any of the NA types (e.g., NA, NA_character_, NA_real_, etc.) for such columns.

Usage

cols_add(.data, ..., .before = NULL, .after = NULL)

Arguments

Value

An object of class gt_tbl.

Targeting the column for insertion with .before or .after

The targeting of a column for insertion is done through the .before or .after arguments (only one of these options should be used). While tidyselect-style expressions or indices can used to target a column, it's advised that a single column name be used. This is to avoid the possibility of inadvertently resolving multiple columns (since the requirement is for a single column).

Examples

Let's take a subset of the exibble dataset and make a simple gt table with it (using the row column for labels in the stub). We'll add a single column to the right of all the existing columns and call it country. This new column needs eight values and these will be supplied when using cols_add().

exibble |>
  dplyr::select(num, char, datetime, currency, group) |>
  gt(rowname_col = "row") |>
  cols_add(
    country = c("TL", "PY", "GL", "PA", "MO", "EE", "CO", "AU")
  )

We can add multiple columns with a single use of cols_add(). The columns generated can be formatted and otherwise manipulated just as any column could be in a gt table. The following example extends the first one by adding more columns and immediately using them in various function calls like fmt_flag() and fmt_units().

exibble |>
  dplyr::select(num, char, datetime, currency, group) |>
  gt(rowname_col = "row") |>
  cols_add(
    country = c("TL", "PY", "GL", "PA", "MO", "EE", "CO", "AU"),
    empty = NA_character_,
    units = c(
      "k m s^-2", "N m^-2", "degC", "m^2 kg s^-2",
      "m^2 kg s^-3", "/s", "A s", "m^2 kg s^-3 A^-1"
    ),
    big_num = num ^ 3
  ) |>
  fmt_flag(columns = country) |>
  sub_missing(columns = empty, missing_text = "") |>
  fmt_units(columns = units) |>
  fmt_scientific(columns = big_num)

In this table generated from a portion of the towny dataset, we add two new columns (land_area and density) through a single use of cols_add(). The new land_area column is a conversion of land area from square kilometers to square miles and the density column is calculated by through division of population_2021 by that new land_area column. We hide the now unneeded land_area_km2 with cols_hide() and also perform some column labeling and adjustments to column widths with cols_label() and cols_width().

towny |>
  dplyr::select(name, population_2021, land_area_km2) |>
  dplyr::filter(population_2021 > 100000) |>
  dplyr::slice_max(population_2021, n = 10) |>
  gt() |>
  cols_add(
    land_area = land_area_km2 / 2.58998811,
    density = population_2021 / land_area
  ) |>
  fmt_integer() |>
  cols_hide(columns = land_area_km2) |>
  cols_label(
    population_2021 = "Population",
    density = "Density, {{*persons* / sq mi}}",
    land_area ~ "Area, {{mi^2}}"
  ) |>
  cols_width(everything() ~ px(120))

It's possible to start with an empty table (i.e., no columns and no rows) and add one or more columns to that. You can, for example, use dplyr::tibble() or data.frame() to create a completely empty table. The first cols_add() call for an empty table can have columns of arbitrary length but subsequent uses of cols_add() must adhere to the rule of new columns being the same length as existing.

dplyr::tibble() |>
  gt() |>
  cols_add(
    num = 1:5,
    chr = vec_fmt_spelled_num(1:5)
  )

Tables can contain no rows, yet have columns. In the following example, we'll create a zero-row table with three columns (num, chr, and ext) and perform the same cols_add()-based addition of two columns of data. This is another case where the function allows for arbitrary-length columns (since always adding zero-length columns is impractical). Furthermore, here we can reference columns that already exist (num and chr) and add values to them.

dplyr::tibble(
  num = numeric(0),
  chr = character(0),
  ext = character(0)
) |>
  gt() |>
  cols_add(
    num = 1:5,
    chr = vec_fmt_spelled_num(1:5)
  )

We should note that the ext column did not receive any values from cols_add() but the table was expanded to having five rows nonetheless. So, each cell of ext was by necessity filled with an NA value.

Function ID

5-7

Function Introduced

v0.10.0 (October 7, 2023)

See Also

Other column modification functions: cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

The individual alignments of columns (which includes the column labels and all of their data cells) can be modified. We have the option to align text to the left, the center, and the right. In a less explicit manner, we can allow gt to automatically choose the alignment of each column based on the data type (with the auto option).

Usage

cols_align(
  data,
  align = c("auto", "left", "center", "right"),
  columns = everything()
)

Arguments

Details

When you create a gt table object using gt(), automatic alignment of column labels and their data cells is performed. By default, left-alignment is applied to columns of class character, Date, or POSIXct; center-alignment is for columns of class logical, factor, or list; and right-alignment is used for the numeric and integer columns.

Value

An object of class gt_tbl.

Examples

Let's use countrypops to create a small gt table. We can change the alignment of the population column with cols_align(). In this example, the label and body cells of population will be aligned to the left.

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(
    country_name == "San Marino",
    year %in% 2017:2021
  ) |>
  gt(
    rowname_col = "year",
    groupname_col = "country_name"
  ) |>
  cols_align(
    align = "left",
    columns = population
  )

Function ID

5-1

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

For numeric columns that contain values with decimal portions, it is sometimes useful to have them lined up along the decimal mark for easier readability. We can do this with cols_align_decimal() and provide any number of columns (the function will skip over columns that don't require this type of alignment).

Usage

cols_align_decimal(data, columns = everything(), dec_mark = ".", locale = NULL)

Arguments

Value

An object of class gt_tbl.

Examples

Let's put together a two-column table to create a gt table. The first column char just contains letters whereas the second column, num, has a collection of numbers and NA values. We could format the numbers with fmt_number() and elect to drop the trailing zeros past the decimal mark with drop_trailing_zeros = TRUE. This can leave formatted numbers that are hard to scan through because the decimal mark isn't fixed horizontally. We could remedy this and align the numbers by the decimal mark with cols_align_decimal().

dplyr::tibble(
  char = LETTERS[1:9],
  num = c(1.2, -33.52, 9023.2, -283.527, NA, 0.401, -123.1, NA, 41)
) |>
  gt() |>
  fmt_number(
    columns = num,
    decimals = 3,
    drop_trailing_zeros = TRUE
  ) |>
  cols_align_decimal()

Function ID

5-2

Function Introduced

v0.8.0 (November 16, 2022)

See Also

Other column modification functions: cols_add(), cols_align(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

cols_hide() allows us to hide one or more columns from appearing in the final output table. While it's possible and often desirable to omit columns from the input table data before introduction to gt(), there can be cases where the data in certain columns is useful (as a column reference during formatting of other columns) but the final display of those columns is not necessary.

Usage

cols_hide(data, columns)

Arguments

Details

The hiding of columns is internally a rendering directive, so, all columns that are 'hidden' are still accessible and useful in any expression provided to a rows argument. Furthermore, cols_hide() (as with many gt functions) can be placed anywhere in a pipeline of gt function calls (acting as a promise to hide columns when the timing is right). However, there's perhaps greater readability when placing this call closer to the end of such a pipeline. cols_hide() quietly changes the visible state of a column (much like cols_unhide()) and doesn't yield warnings or messages when changing the state of already-invisible columns.

Value

An object of class gt_tbl. data will be unaltered if columns is not supplied.

Examples

Let's use a small portion of the countrypops dataset to create a gt table. We can hide the country_code_2 and country_code_3 columns with the cols_hide() function.

countrypops |>
  dplyr::filter(
    country_name == "Egypt",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_hide(columns = c(country_code_2, country_code_3))

Using another countrypops-based gt table, we can use the population column to provide the conditional placement of footnotes. Then, we'll hide that column along with the country_code_3 column. Note that the order of cols_hide() and tab_footnote() has no effect on the final display of the table.

countrypops |>
  dplyr::filter(
    country_name == "Pakistan",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_hide(columns = c(country_code_3, population)) |>
  tab_footnote(
    footnote = "Population above 220,000,000.",
    locations = cells_body(
      columns = year,
      rows = population > 220E6
    )
  )

Function ID

5-12

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

cols_unhide() to perform the inverse operation.

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

Column labels can be modified from their default values (the names of the columns from the input table data). When you create a gt table object using gt(), column names effectively become the column labels. While this serves as a good first approximation, column names as label defaults aren't often as appealing in a gt table as the option for custom column labels. cols_label() provides the flexibility to relabel one or more columns and we even have the option to use md() or html() for rendering column labels from Markdown or using HTML.

Usage

cols_label(.data, ..., .list = list2(...), .fn = NULL, .process_units = NULL)

Arguments

Value

An object of class gt_tbl.

A note on column names and column labels

It's important to note that while columns can be freely relabeled, we continue to refer to columns by their original column names. Column names in a tibble or data frame must be unique whereas column labels in gt have no requirement for uniqueness (which is useful for labeling columns as, say, measurement units that may be repeated several times—usually under different spanner labels). Thus, we can still easily distinguish between columns in other gt function calls (e.g., in all of the ⁠fmt*()⁠ functions) even though we may lose distinguishability between column labels once they have undergone relabeling.

Incorporating units with gt's units notation

Measurement units are often seen as part of column labels and indeed it can be much more straightforward to include them here rather than using other devices to make readers aware of units for specific columns. The gt package offers the function cols_units() to apply units to various columns with an interface that's similar to that of this function. However, it is also possible to define units here along with the column label, obviating the need for pattern syntax that joins the two text components. To do this, we have to surround the portion of text in the label that corresponds to the units definition with "{{"/"}}".

Now that we know how to mark text for units definition, we know need to know how to write proper units with the notation. Such notation uses a succinct method of writing units and it should feel somewhat familiar though it is particular to the task at hand. Each unit is treated as a separate entity (parentheses and other symbols included) and the addition of subscript text and exponents is flexible and relatively easy to formulate. This is all best shown with a few examples:

• "m/s" and "m / s" both render as "m/s"

• "m s^-1" will appear with the "-1" exponent intact

• "m /s" gives the same result, as "/<unit>" is equivalent to "<unit>^-1"

• "E_h" will render an "E" with the "h" subscript

• "t_i^2.5" provides a t with an "i" subscript and a "2.5" exponent

• "m[_0^2]" will use overstriking to set both scripts vertically

• "g/L %C6H12O6%" uses a chemical formula (enclosed in a pair of "%" characters) as a unit partial, and the formula will render correctly with subscripted numbers

• Common units that are difficult to write using ASCII text may be implicitly converted to the correct characters (e.g., the "u" in "ug", "um", "uL", and "umol" will be converted to the Greek mu symbol; "degC" and "degF" will render a degree sign before the temperature unit)

• We can transform shorthand symbol/unit names enclosed in ":" (e.g., ":angstrom:", ":ohm:", etc.) into proper symbols

• Greek letters can added by enclosing the letter name in ":"; you can use lowercase letters (e.g., ":beta:", ":sigma:", etc.) and uppercase letters too (e.g., ":Alpha:", ":Zeta:", etc.)

• The components of a unit (unit name, subscript, and exponent) can be fully or partially italicized/emboldened by surrounding text with "*" or "**"

Examples

Let's use a portion of the countrypops dataset to create a gt table. We can relabel all the table's columns with the cols_label() function to improve its presentation. In this simple case we are supplying the name of the column on the left-hand side, and the label text on the right-hand side.

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(
    country_name == "Uganda",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_label(
    country_name = "Name",
    year = "Year",
    population = "Population"
  )

Using the countrypops dataset again, we label columns similarly to before but this time making the column labels be bold through Markdown formatting (with the md() helper function). It's possible here to use either a = or a ~ between the column name and the label text.

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(
    country_name == "Uganda",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_label(
    country_name = md("**Name**"),
    year = md("**Year**"),
    population ~ md("**Population**")
  )

With a select portion of the metro dataset, let's create a small gt table with three columns. Within cols_label() we'd like to provide column labels that contain line breaks. For that, we can use ⁠<br>⁠ to indicate where the line breaks should be. We also need to use the md() helper function to signal to gt that this text should be interpreted as Markdown. Instead of calling md() on each of labels as before, we can more conveniently use the .fn argument and provide the bare function there (it will be applied to each label defined in the cols_label() call).

metro |>
  dplyr::select(name, lines, passengers, connect_other) |>
  dplyr::slice_max(passengers, n = 10) |>
  gt() |>
  cols_hide(columns = passengers) |>
  cols_label(
    name = "Name of<br>Metro Station",
    lines = "Metro<br>Lines",
    connect_other = "Train<br>Services",
    .fn = md
  )

Using a subset of the towny dataset, we can create an interesting gt table. First, only certain columns are selected from the dataset, some filtering of rows is done, rows are sorted, and then only the first 10 rows are kept. After the data is introduced to gt(), we then apply some spanner labels using two calls of tab_spanner(). Below those spanners, we want to label the columns by the years of interest. Using cols_label() and select expressions on the left side of the formulas, we can easily relabel multiple columns with common label text. Note that we cannot use an = sign in any of the expressions within cols_label(); because the left-hand side is not a single column name, we must use formula syntax (i.e., with the ~).

towny |>
  dplyr::select(
    name, ends_with("2001"), ends_with("2006"), matches("2001_2006")
  ) |>
  dplyr::filter(population_2001 > 100000) |>
  dplyr::arrange(desc(pop_change_2001_2006_pct)) |>
  dplyr::slice_head(n = 10) |>
  gt() |>
  fmt_integer() |>
  fmt_percent(columns = matches("change"), decimals = 1) |>
  tab_spanner(label = "Population", columns = starts_with("population")) |>
  tab_spanner(label = "Density", columns = starts_with("density")) |>
  cols_label(
    ends_with("01") ~ "2001",
    ends_with("06") ~ "2006",
    matches("change") ~ md("Population Change,<br>2001 to 2006")
  ) |>
  cols_width(everything() ~ px(120))

Here's another table that uses the towny dataset. The big difference compared to the previous gt table is that cols_label() as used here incorporates unit notation text (within "{{"/"}}").

towny |>
  dplyr::select(
    name, population_2021, density_2021, land_area_km2, latitude, longitude
  ) |>
  dplyr::filter(population_2021 > 100000) |>
  dplyr::arrange(desc(population_2021)) |>
  dplyr::slice_head(n = 10) |>
  gt() |>
  fmt_integer(columns = population_2021) |>
  fmt_number(
    columns = c(density_2021, land_area_km2),
    decimals = 1
  ) |>
  fmt_number(columns = latitude, decimals = 2) |>
  fmt_number(columns = longitude, decimals = 2, scale_by = -1) |>
  cols_label(
    starts_with("population") ~ "Population",
    starts_with("density") ~ "Density, {{*persons* km^-2}}",
    land_area_km2 ~ "Area, {{km^2}}",
    latitude ~ "Latitude, {{:degrees:N}}",
    longitude ~ "Longitude, {{:degrees:W}}"
  ) |>
  cols_width(everything() ~ px(120))

The illness dataset has units within the units column. They're formatted in just the right way for gt too. Let's do some text manipulation through dplyr::mutate() and some pivoting with tidyr::pivot_longer() and tidyr::pivot_wider() in order to include the units as part of the column names in the reworked table. These column names are in a format where the units are included within "{{"/"}}", so, we can use cols_label() with the .process_units = TRUE option to register the measurement units. In addition to this, because there is a ⁠<br>⁠ included (for a line break), we should use the .fn option and provide the md() helper function (as a bare function name). This ensures that any line breaks will materialize.

illness |>
  dplyr::mutate(test = paste0(test, ",<br>{{", units, "}}")) |>
  dplyr::slice_head(n = 8) |>
  dplyr::select(-c(starts_with("norm"), units)) |>
  tidyr::pivot_longer(
    cols = starts_with("day"),
    names_to = "day",
    names_prefix = "day_",
    values_to = "value"
  ) |>
  tidyr::pivot_wider(
    names_from = test,
    values_from = value
  ) |>
  gt(rowname_col = "day") |>
  tab_stubhead(label = "Day") |>
  cols_label(
    .fn = md,
    .process_units = TRUE
  ) |>
  cols_width(
    stub() ~ px(50),
    everything() ~ px(120)
  )

Function ID

5-4

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

Column labels can be modified from their default values (the names of the columns from the input table data). When you create a gt table object using gt(), column names effectively become the column labels. While this serves as a good first approximation, you may want to make adjustments so that the columns names present better in the gt output table. The cols_label_with() function allows for modification of column labels through a supplied function. By default, the function will be invoked on all column labels but this can be limited to a subset via the columns argument. With the fn argument, we provide either a bare function name, a RHS formula (with . representing the vector of column labels), or, an anonymous function (e.g., function(x) tools::toTitleCase(x)).

Usage

cols_label_with(data, columns = everything(), fn)

Arguments

Value

An object of class gt_tbl.

A note on column names and column labels

It's important to note that while columns can be freely relabeled, we continue to refer to columns by their original column names. Column names in a tibble or data frame must be unique whereas column labels in gt have no requirement for uniqueness (which is useful for labeling columns as, say, measurement units that may be repeated several times—usually under different spanner labels). Thus, we can still easily distinguish between columns in other gt function calls (e.g., in all of the ⁠fmt*()⁠ functions) even though we may lose distinguishability in column labels once they have been relabeled.

Examples

Use a subset of the sp500 dataset to create a gt table. We want all the column labels to be entirely capitalized versions of the default labels but, instead of using cols_label() and rewriting each label manually in capital letters we can use cols_label_with() and instruct it to apply the toupper() function to all column labels.

sp500 |>
  dplyr::filter(
    date >= "2015-12-01" &
      date <= "2015-12-15"
  ) |>
  dplyr::select(-c(adj_close, volume)) |>
  gt() |>
  cols_label_with(fn = toupper)

Use the countrypops dataset to create a gt table. To improve the presentation of the table, we are again going to change the default column labels via function calls supplied within cols_label_with(). We can, if we prefer, apply multiple types of column label changes in sequence with multiple calls of cols_label_with(). Here, we use the make_clean_names() functions from the janitor package and follow up with the removal of a numeral with gsub().

countrypops |>
  dplyr::filter(year == 2021) |>
  dplyr::filter(grepl("^C", country_code_3)) |>
  dplyr::select(-country_code_2, -year) |>
  head(8) |>
  gt() |>
  cols_move_to_start(columns = country_code_3) |>
  fmt_integer(columns = population) |>
  cols_label_with(
    fn = ~ janitor::make_clean_names(., case = "title")
  ) |>
  cols_label_with(
    fn = ~ gsub("[0-9]", "", .)
  )

We can make a svelte gt table with the pizzaplace dataset. There are ways to use one instance of cols_label_with() with multiple functions called on the column labels. In the example, we use an anonymous function call (with the function(x) { ... } construction) to perform multiple mutations of x (the vector of column labels). We can even use the md() helper function with that to signal to gt that the column label should be interpreted as Markdown text.

pizzaplace |>
  dplyr::mutate(month = substr(date, 6, 7)) |>
  dplyr::count(month, name = "pizze_vendute") |>
  dplyr::mutate(frazione_della_quota = pizze_vendute / 4000) |>
  dplyr::mutate(date = paste0("2015/", month, "/01")) |>
  dplyr::select(-month) |>
  gt(rowname_col = "date") |>
  fmt_date(date, date_style = "month", locale = "it") |>
  fmt_percent(columns = frazione_della_quota) |>
  fmt_integer(columns = pizze_vendute) |>
  cols_width(everything() ~ px(100)) |>
  cols_label_with(
    fn = function(x) {
      janitor::make_clean_names(x, case = "title") |>
        toupper() |>
        stringr::str_replace_all("^|$", "**") |>
        md()
    }
  )

Function ID

5-5

Function Introduced

v0.9.0 (March 31, 2023)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

This function takes input from two or more columns and allows the contents to be merged into a single column by using a pattern that specifies the arrangement. We can specify which columns to merge together in the columns argument. The string-combining pattern is to be provided in the pattern argument. The first column in the columns series operates as the target column (i.e., the column that will undergo mutation) whereas all following columns will be untouched. There is the option to hide the non-target columns (i.e., second and subsequent columns given in columns). The formatting of values in different columns will be preserved upon merging.

Usage

cols_merge(
  data,
  columns,
  hide_columns = columns[-1],
  rows = everything(),
  pattern = NULL
)

Arguments

Value

An object of class gt_tbl.

How the pattern works

There are two types of templating for the pattern string:

1. { } for arranging single column values in a row-wise fashion

2. ⁠<< >>⁠ to surround spans of text that will be removed if any of the contained { } yields a missing value

Integer values are placed in { } and those values correspond to the columns involved in the merge, in the order they are provided in the columns argument. So the pattern "{1} ({2}-{3})" corresponds to the target column value listed first in columns and the second and third columns cited (formatted as a range in parentheses). With hypothetical values, this might result as the merged string "38.2 (3-8)".

Because some values involved in merging may be missing, it is likely that something like "38.2 (3-NA)" would be undesirable. For such cases, placing sections of text in ⁠<< >>⁠ results in the entire span being eliminated if there were to be an NA value (arising from { } values). We could instead opt for a pattern like "{1}<< ({2}-{3})>>", which results in "38.2" if either columns {2} or {3} have an NA value. We can even use a more complex nesting pattern like "{1}<< ({2}-<<{3}>>)>>" to retain a lower limit in parentheses (where {3} is NA) but remove the range altogether if {2} is NA.

One more thing to note here is that if sub_missing() is used on values in a column, those specific values affected won't be considered truly missing by cols_merge() (since it's been handled with substitute text). So, the complex pattern "{1}<< ({2}-<<{3}>>)>>" might result in something like "38.2 (3-limit)" if sub_missing(..., missing_text = "limit") were used on the third column supplied in columns.

Comparison with other column-merging functions

There are three other column-merging functions that offer specialized behavior that is optimized for common table tasks: cols_merge_range(), cols_merge_uncert(), and cols_merge_n_pct(). These functions operate similarly, where the non-target columns can be optionally hidden from the output table through the autohide option.

Examples

Use a subset of the sp500 dataset to create a gt table. Use the cols_merge() function to merge the open & close columns together, and, the low & high columns (putting an em dash between both). Relabel the columns with cols_label().

sp500 |>
  dplyr::slice(50:55) |>
  dplyr::select(-volume, -adj_close) |>
  gt() |>
  cols_merge(
    columns = c(open, close),
    pattern = "{1}—{2}"
  ) |>
  cols_merge(
    columns = c(low, high),
    pattern = "{1}—{2}"
  ) |>
  cols_label(
    open = "open/close",
    low = "low/high"
  )

Use a portion of gtcars to create a gt table. Use the cols_merge() function to merge the trq & trq_rpm columns together, and, the mpg_c & mpg_h columns. Given the presence of NA values, we can use patterns that drop parts of the output text whenever missing values are encountered.

gtcars |>
  dplyr::filter(year == 2017) |>
  dplyr::select(mfr, model, starts_with(c("trq", "mpg"))) |>
  gt() |>
  fmt_integer(columns = trq_rpm) |>
  cols_merge(
    columns = starts_with("trq"),
    pattern = "{1}<< ({2} rpm)>>"
  ) |>
  cols_merge(
    columns = starts_with("mpg"),
    pattern = "<<{1} city<</{2} hwy>>>>"
  ) |>
  cols_label(
    mfr = "Manufacturer",
    model = "Car Model",
    trq = "Torque",
    mpg_c = "MPG"
  )

Function ID

5-14

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

cols_merge_n_pct() is a specialized variant of cols_merge(), It operates by taking two columns that constitute both a count (col_n) and a fraction of the total population (col_pct) and merges them into a single column. What results is a column containing both counts and their associated percentages (e.g., ⁠12 (23.2%)⁠). The column specified in col_pct is dropped from the output table.

Usage

cols_merge_n_pct(data, col_n, col_pct, rows = everything(), autohide = TRUE)

Arguments

Value

An object of class gt_tbl.

Comparison with other column-merging functions

This function could be somewhat replicated using cols_merge(), however, cols_merge_n_pct() employs the following specialized semantics for NA and zero-value handling:

1. NAs in col_n result in missing values for the merged column (e.g., NA + ⁠10.2%⁠ = NA)

2. NAs in col_pct (but not col_n) result in base values only for the merged column (e.g., 13 + NA = 13)

3. NAs both col_n and col_pct result in missing values for the merged column (e.g., NA + NA = NA)

4. If a zero (0) value is in col_n then the formatted output will be "0" (i.e., no percentage will be shown)

Any resulting NA values in the col_n column following the merge operation can be easily formatted using sub_missing(). Separate calls of sub_missing() can be used for the col_n and col_pct columns for finer control of the replacement values. It is the responsibility of the user to ensure that values are correct in both the col_n and col_pct columns (this function neither generates nor recalculates values in either). Formatting of each column can be done independently in separate fmt_number() and fmt_percent() calls.

This function is part of a set of four column-merging functions. The other three are the general cols_merge() function and the specialized cols_merge_uncert() and cols_merge_range() functions. These functions operate similarly, where the non-target columns can be optionally hidden from the output table through the hide_columns or autohide options.

Examples

Using a summarized version of the pizzaplace dataset, let's create a gt table that displays the counts and percentages of the top 3 pizzas sold by pizza category in 2015. The cols_merge_n_pct() function is used to merge the n and frac columns (and the frac column is formatted using fmt_percent()).

pizzaplace |>
  dplyr::count(name, type, price, sort = TRUE) |>
  dplyr::mutate(frac = prop.table(n)) |>
  dplyr::slice_max(n, n = 3, by = type) |>
  dplyr::arrange(type) |>
  gt(
    rowname_col = "name",
    groupname_col = "type"
  ) |>
  fmt_currency(price) |>
  fmt_percent(frac) |>
  cols_merge_n_pct(
    col_n = n,
    col_pct = frac
  ) |>
  cols_label(
    n = md("*N* (%)"),
    price = "Price"
  ) |>
  tab_style(
    style = cell_text(font = "monospace"),
    locations = cells_stub()
  ) |>
  tab_stubhead(md("Cat. and  \nPizza Code")) |>
  tab_header(title = "Top 3 Pizzas Sold by Category in 2015") |>
  tab_options(table.width = px(512))

Function ID

5-17

Function Introduced

v0.3.0 (May 12, 2021)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

cols_merge_range() is a specialized variant of cols_merge(). It operates by taking a two columns that constitute a range of values (col_begin and col_end) and merges them into a single column. What results is a column containing both values separated by an em dash. The column specified in col_end is dropped from the output table.

Usage

cols_merge_range(
  data,
  col_begin,
  col_end,
  rows = everything(),
  autohide = TRUE,
  sep = NULL,
  locale = NULL
)

Arguments

Value

An object of class gt_tbl.

Comparison with other column-merging functions

This function could be somewhat replicated using cols_merge(), however, cols_merge_range() employs the following specialized operations for NA handling:

1. NAs in col_begin (but not col_end) result in a display of only

2. NAs in col_end (but not col_begin) result in a display of only the col_begin values only for the merged column (this is the converse of the previous)

3. NAs both in col_begin and col_end result in missing values for the merged column

Any resulting NA values in the col_begin column following the merge operation can be easily formatted using sub_missing(). Separate calls of sub_missing() can be used for the col_begin and col_end columns for finer control of the replacement values.

This function is part of a set of four column-merging functions. The other three are the general cols_merge() function and the specialized cols_merge_uncert() and cols_merge_n_pct() functions. These functions operate similarly, where the non-target columns can be optionally hidden from the output table through the hide_columns or autohide options.

Examples

Let's use a subset of the gtcars dataset to create a gt table, keeping only the model, mpg_c, and mpg_h columns. Merge the "mpg*" columns together as a single range column (which is labeled as MPG, in italics) using the cols_merge_range() function. After the merging process, the column label for the mpg_c column is updated with cols_label() to better describe the content.

gtcars |>
  dplyr::select(model, starts_with("mpg")) |>
  dplyr::slice(1:8) |>
  gt() |>
  cols_merge_range(
    col_begin = mpg_c,
    col_end = mpg_h
  ) |>
  cols_label(mpg_c = md("*MPG*"))

Function ID

5-16

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

cols_merge_uncert() is a specialized variant of cols_merge(). It takes as input a base value column (col_val) and either: (1) a single uncertainty column, or (2) two columns representing lower and upper uncertainty bounds. These columns will be essentially merged in a single column (that of col_val). What results is a column with values and associated uncertainties, and any columns specified in col_uncert are hidden from appearing the output table.

Usage

cols_merge_uncert(
  data,
  col_val,
  col_uncert,
  rows = everything(),
  sep = " +/- ",
  autohide = TRUE
)

Arguments

Value

An object of class gt_tbl.

Comparison with other column-merging functions

This function could be somewhat replicated using cols_merge() in the case where a single column is supplied for col_uncert, however, cols_merge_uncert() employs the following specialized semantics for NA handling:

1. NAs in col_val result in missing values for the merged column (e.g., NA + 0.1 = NA)

2. NAs in col_uncert (but not col_val) result in base values only for the merged column (e.g., 12.0 + NA = 12.0)

3. NAs both col_val and col_uncert result in missing values for the merged column (e.g., NA + NA = NA)

Any resulting NA values in the col_val column following the merge operation can be easily formatted using sub_missing().

This function is part of a set of four column-merging functions. The other three are the general cols_merge() function and the specialized cols_merge_range() and cols_merge_n_pct() functions. These functions operate similarly, where the non-target columns can be optionally hidden from the output table through the hide_columns or autohide options.

Examples

Let's use the exibble dataset to create a simple, two-column gt table (keeping only the num and currency columns). We'll format the num column with the fmt_number() function. Next we merge the currency and num columns into the currency column; this will contain a base value and an uncertainty and it's all done using the cols_merge_uncert() function. After the merging process, the column label for the currency column is updated with cols_label() to better describe the content.

exibble |>
  dplyr::select(num, currency) |>
  dplyr::slice(1:7) |>
  gt() |>
  fmt_number(
    columns = num,
    decimals = 3,
    use_seps = FALSE
  ) |>
  cols_merge_uncert(
    col_val = currency,
    col_uncert = num
  ) |>
  cols_label(currency = "value + uncert.")

Function ID

5-15

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

On those occasions where you need to move columns this way or that way, we can make use of the cols_move() function. While it's true that the movement of columns can be done upstream of gt, it is much easier and less error prone to use the function provided here. The movement procedure here takes one or more specified columns (in the columns argument) and places them to the right of a different column (the after argument). The ordering of the columns to be moved is preserved, as is the ordering of all other columns in the table.

Usage

cols_move(data, columns, after)

Arguments

Details

The columns supplied in columns must all exist in the table and none of them can be in the after argument. The after column must also exist and only one column should be provided here. If you need to place one or more columns at the beginning of the column series, the cols_move_to_start() function should be used. Similarly, if those columns to move should be placed at the end of the column series then use cols_move_to_end().

Value

An object of class gt_tbl.

Examples

Use the countrypops dataset to create a gt table. We'll choose to position the population column after the country_name column by using the cols_move() function.

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(
    country_name == "Japan",
    year %in% 2012:2021
  ) |>
  gt() |>
  cols_move(
    columns = population,
    after = country_name
  ) |>
  fmt_integer(columns = population)

Function ID

5-9

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

It's possible to move a set of columns to the end of the column series, we only need to specify which columns are to be moved. While this can be done upstream of gt, this function makes to process much easier and it's less error prone. The ordering of the columns that are moved to the end is preserved (same with the ordering of all other columns in the table).

Usage

cols_move_to_end(data, columns)

Arguments

Details

The columns supplied in columns must all exist in the table. If you need to place one or columns at the start of the column series, cols_move_to_start() should be used. More control is offered with cols_move(), where columns could be placed after a specific column.

Value

An object of class gt_tbl.

Examples

For this example, we'll use a portion of the countrypops dataset to create a simple gt table. Let's move the year column, which is the middle column, to the end of the column series with cols_move_to_end().

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(
    country_name == "Benin",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_move_to_end(columns = year)

We can also move multiple columns at a time. With the same countrypops-based table, let's move both the year and country_name columns to the end of the column series.

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(
    country_name == "Benin",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_move_to_end(columns = c(year, country_name))

Function ID

5-11

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

We can easily move set of columns to the beginning of the column series and we only need to specify which columns. It's possible to do this upstream of gt, however, it is easier with this function and it presents less possibility for error. The ordering of the columns that are moved to the start is preserved (same with the ordering of all other columns in the table).

Usage

cols_move_to_start(data, columns)

Arguments

Details

The columns supplied in columns must all exist in the table. If you need to place one or columns at the end of the column series, cols_move_to_end() should be used. More control is offered with cols_move(), where columns could be placed after a specific column.

Value

An object of class gt_tbl.

Examples

For this example, we'll use a portion of the countrypops dataset to create a simple gt table. Let's move the year column, which is the middle column, to the start of the column series with cols_move_to_start().

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(
    country_name == "Fiji",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_move_to_start(columns = year)

We can also move multiple columns at a time. With the same countrypops-based table, let's move both the year and population columns to the start of the column series.

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(
    country_name == "Fiji",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_move_to_start(columns = c(year, population))

Function ID

5-10

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_nanoplot(), cols_unhide(), cols_units(), cols_width()

Description

Nanoplots are tiny plots you can use in your gt table. They are simple by design, mainly because there isn't a lot of space to work with. With that simplicity, however, you do get a set of very succinct data visualizations that adapt nicely to the amount of data you feed into them. With cols_nanoplot() you take data from one or more columns as the basic inputs for the nanoplots and generate a new column containing the plots. The nanoplots are robust against missing values, and multiple strategies are available for handling missingness.

Nanoplots try to show individual data with reasonably good visibility. Interactivity is included as a basic feature so one can hover over the data points and vertical guides will display the value ascribed to each data point. Because gt knows all about numeric formatting, values will be compactly formatted so as to not take up valuable real estate. If you need to create a nanoplot based on monetary values, that can be handled by providing the currency code to the nanoplot_options() helper (then hook that up to the options argument). A guide on the left-hand side of the plot area will appear on hover and display the minimal and maximal y values.

There are three types of nanoplots available: "line", "bar", "boxplot". A line plot shows individual data points and has smooth connecting lines between them to allow for easier scanning of values. You can opt for straight-line connections between data points, or, no connections at all (it's up to you). You can even eschew the data points and just have a simple line. Regardless of how you mix and match difference plot layers, the plot area focuses on the domain of the data points with the goal of showing you the overall trend of the data. The data you feed into a line plot can consist of a single vector of values (resulting in equally-spaced y values), or, you can supply two vectors representative of x and y.

A bar plot is built a little bit differently. The focus is on evenly-spaced bars (requiring a single vector of values) that project from a zero line, clearly showing the difference between positive and negative values. By default, any type of nanoplot will have basic interactivity. One can hover over the data points and vertical guides will display values ascribed to each. A guide on the left-hand side of the plot area will display the minimal and maximal y values on hover.

Every box plot will take the collection of values for a row and construct the plot horizontally. This is essentially a standard box-and-whisker diagram where outliers are automatically displayed outside the left and right fences.

While basic customization options are present in the cols_nanoplot(), many more opportunities for customizing nanoplots on a more granular level are possible with the nanoplot_options() helper function. That function should be invoked at the options argument of cols_nanoplot(). Through that helper, layers of the nanoplots can be selectively removed and the aesthetics of the remaining plot components can be modified.

Usage

cols_nanoplot(
  data,
  columns,
  rows = everything(),
  plot_type = c("line", "bar", "boxplot"),
  plot_height = "2em",
  missing_vals = c("gap", "marker", "zero", "remove"),
  autoscale = FALSE,
  autohide = TRUE,
  columns_x_vals = NULL,
  reference_line = NULL,
  reference_area = NULL,
  expand_x = NULL,
  expand_y = NULL,
  new_col_name = NULL,
  new_col_label = NULL,
  before = NULL,
  after = NULL,
  options = NULL
)

Arguments

Value

An object of class gt_tbl.

Targeting cells with columns and rows

Targeting of values to insert into the nanoplots is done through columns and additionally by rows (if nothing is provided for rows then entire columns are selected). Aside from declaring column names in c() (with bare column names or names in quotes) we can use also tidyselect-style expressions. This can be as basic as supplying a select helper like starts_with(), or, providing a more complex incantation like

where(~ is.numeric(.x) & max(.x, na.rm = TRUE) > 1E6)

which targets numeric columns that have a maximum value greater than 1,000,000 (excluding any NAs from consideration).

Once the columns are targeted, we may also target the rows within those columns. This can be done in a variety of ways. If a stub is present, then we potentially have row identifiers. Those can be used much like column names in the columns-targeting scenario. We can use simpler tidyselect-style expressions (the select helpers should work well here) and we can use quoted row identifiers in c(). It's also possible to use row indices (e.g., c(3, 5, 6)) though these index values must correspond to the row numbers of the input data (the indices won't necessarily match those of rearranged rows if row groups are present). One more type of expression is possible, an expression that takes column values (can involve any of the available columns in the table) and returns a logical vector.

How to supply data for nanoplots

The input data for nanoplots naturally needs to be numeric and there are two major ways to formulate that data: (1) from single values across many columns, and (2) using text-based value streams. It's pretty easy to rationalize the first, and we may already have wide data in the input data frame anyway (take a look at the illness and towny datasets for examples of this). There's one data value per column so the key thing here is to reference the columns in the correct order. With a select helper, good column naming, and the columns being in the intended order, this is a snap.

The second option is to use text-based value streams. Sometimes you simply don't want or don't need multiple columns and so a single column with all of the data might be more practical. To make this work, you'd need to have a set of numerical values separated by some sort of delimiter (could be a comma, a space, a semicolon, you get the idea). Here's an example with three numbers, written three ways: "3.6 -2.44 1.98", "3.6, -2.44, 1.98", and "3.6;-2.44;1.98". You can include NA values, not a problem, and here's an example of that: "6.232 NA 3.7 0.93". Another form of value stream involves using datetimes in the ISO 8601 form of ⁠YYYY-MM-DD HH:MM:SS⁠. These will be internally converted to numeric values (seconds elapsed since "1970-01-01 00:00:00"). An example of a datetime-based value stream is: "2012-06-12 08:24:13, 2012-06-12 10:37:08, 2012-06-12 14:03:24".

Value streams can be pretty big if you want them to be, and you don't have to deal with containing individual values across multiple columns. For the case where you need to provide two sets of values (x and y, for line plots with columns and columns_x_vals), have two equivalently sized value streams in two columns. Value streams can also be concatenated together by referencing columns having their own separate value streams.

Reference line and reference area

Neither a horizontal reference line nor a reference area is present in the default view but these can be added by providing valid input values in the reference_line and reference_area arguments. A reference line can be either be a static numeric value (supply any number to reference_line), or it can be a keyword that computes the reference line y value using the data values for each nanoplot. The following keywords can be used:

1. "mean": The mean of the data values

2. "median": Median of data values

3. "min": Minimum value in set of data values

4. "max": The maximum value

5. "q1": The first, or lower, quartile of the data values

6. "q3": The third quartile, otherwise known as the upper quartile

7. "first": The first data value

8. "last": The last data value

The reference area accepts two inputs, and this can be two of the above keywords, a keyword and a static numeric value, or two numeric values.

Examples

Let's make some nanoplots with the illness dataset. The columns beginning with 'day' all contain ordered measurement values, comprising seven individual daily results. Using cols_nanoplot() we create a new column to hold the nanoplots (with new_col_name = "nanoplots"), referencing the columns containing the data (with columns = starts_with("day")). It's also possible to define a column label here using the new_col_label argument.

illness |>
  dplyr::slice_head(n = 10) |>
  gt(rowname_col = "test") |>
  tab_header("Partial summary of daily tests performed on YF patient") |>
  tab_stubhead(label = md("**Test**")) |>
  cols_hide(columns = starts_with("norm")) |>
  fmt_units(columns = units) |>
  cols_nanoplot(
    columns = starts_with("day"),
    new_col_name = "nanoplots",
    new_col_label = md("*Progression*")
  ) |>
  cols_align(align = "center", columns = nanoplots) |>
  cols_merge(columns = c(test, units), pattern = "{1} ({2})") |>
  tab_footnote(
    footnote = "Measurements from Day 3 through to Day 8.",
    locations = cells_column_labels(columns = nanoplots)
  )

The previous table showed us some line-based nanoplots. We can also make very small bar plots with cols_nanoplot(). Let's take the pizzaplace dataset and make a small summary table showing daily pizza sales by type (there are four types). This will be limited to the first ten days of pizza sales in 2015, so, there will be ten rows in total. We can use plot_type = "bar" to make bar plots from the daily sales counts in the chicken, classic, supreme, and veggie columns. Because we know there will always be four bars (one for each type of pizza) we can be a little creative and apply colors to each of the bars through use of the data_bar_fill_color argument in nanoplot_options().

pizzaplace |>
  dplyr::count(type, date) |>
  tidyr::pivot_wider(names_from = type, values_from = n) |>
  dplyr::slice_head(n = 10) |>
  gt(rowname_col = "date") |>
  tab_header(
    title = md("First Ten Days of Pizza Sales in 2015")
  ) |>
  cols_nanoplot(
    columns = c(chicken, classic, supreme, veggie),
    plot_type = "bar",
    autohide = FALSE,
    new_col_name = "pizzas_sold",
    new_col_label = "Sales by Type",
    options = nanoplot_options(
      show_data_line = FALSE,
      show_data_area = FALSE,
      data_bar_stroke_color = "transparent",
      data_bar_fill_color = c("brown", "gold", "purple", "green")
    )
  ) |>
  cols_width(pizzas_sold ~ px(150)) |>
  cols_align(columns = -date, align = "center") |>
  fmt_date(columns = date, date_style = "yMMMEd") |>
  opt_all_caps()

Now we'll make another table that contains two columns of nanoplots. Starting from the towny dataset, we first reduce it down to a subset of columns and rows. All of the columns related to either population or density will be used as input data for the two nanoplots. Both nanoplots will use a reference line that is generated from the median of the input data. And by naming the new nanoplot-laden columns in a similar manner as the input data columns, we can take advantage of select helpers (e.g., when using tab_spanner()). Many of the input data columns are now redundant because of the plots, so we'll elect to hide most of those with cols_hide().

towny |>
  dplyr::select(name, starts_with("population"), starts_with("density")) |>
  dplyr::filter(population_2021 > 200000) |>
  dplyr::arrange(desc(population_2021)) |>
  gt() |>
  fmt_integer(columns = starts_with("population")) |>
  fmt_number(columns = starts_with("density"), decimals = 1) |>
  cols_nanoplot(
    columns = starts_with("population"),
    reference_line = "median",
    autohide = FALSE,
    new_col_name = "population_plot",
    new_col_label = md("*Change*")
  ) |>
  cols_nanoplot(
    columns = starts_with("density"),
    plot_type = "bar",
    autohide = FALSE,
    new_col_name = "density_plot",
    new_col_label = md("*Change*")
  ) |>
  cols_hide(columns = matches("2001|2006|2011|2016")) |>
  tab_spanner(
    label = "Population",
    columns = starts_with("population")
  ) |>
  tab_spanner(
    label = "Density ({{*persons* km^-2}})",
    columns = starts_with("density")
  ) |>
  cols_label_with(
    columns = -matches("plot"),
    fn = function(x) gsub("[^0-9]+", "", x)
  ) |>
  cols_align(align = "center", columns = matches("plot")) |>
  cols_width(
    name ~ px(140),
    everything() ~ px(100)
  ) |>
  opt_horizontal_padding(scale = 2)

The sza dataset can, with just some use of dplyr and tidyr, give us a wide table full of nanoplottable values. We'll transform the solar zenith angles to solar altitude angles and create a column of nanoplots using the newly calculated values. There are a few NA values during periods where the sun hasn't risen (usually before 06:30 in the winter months) and those values will be replaced with 0 using missing_vals = "zero". We'll also elect to create bar plots using the plot_type = "bar" option. The height of the plots will be bumped up to "2.5em" from the default of "2em". Finally, we will use nanoplot_options() to modify the coloring of the data bars.

sza |>
  dplyr::filter(latitude == 20 & tst <= "1200") |>
  dplyr::select(-latitude) |>
  dplyr::filter(!is.na(sza)) |>
  dplyr::mutate(saa = 90 - sza) |>
  dplyr::select(-sza) |>
  tidyr::pivot_wider(
    names_from = tst,
    values_from = saa,
    names_sort = TRUE
  ) |>
  gt(rowname_col = "month") |>
  tab_header(
    title = "Solar Altitude Angles",
    subtitle = "Average values every half hour from 05:30 to 12:00"
  ) |>
  cols_nanoplot(
    columns = matches("0"),
    plot_type = "bar",
    missing_vals = "zero",
    new_col_name = "saa",
    plot_height = "2.5em",
    options = nanoplot_options(
      data_bar_stroke_color = "GoldenRod",
      data_bar_fill_color = "DarkOrange"
    )
  ) |>
  tab_options(
    table.width = px(400),
    column_labels.hidden = TRUE
  ) |>
  cols_align(
    align = "center",
    columns = everything()
  ) |>
  tab_source_note(
    source_note = "The solar altitude angle is the complement to
    the solar zenith angle. TMYK."
  )

You can use number and time streams as data for nanoplots. Let's demonstrate how we can make use of them with some creative transformation of the pizzaplace dataset. A value stream is really a string with delimited numeric values, like this: "7.24,84.2,14". A value stream can also contain dates and/or datetimes, and here's an example of that: "2020-06-02 13:05:13,2020-06-02 14:24:05,2020-06-02 18:51:37". Having data in this form can often be more convenient since different nanoplots might have varying amounts of data (and holding different amounts of data in a fixed number of columns is cumbersome). There are date and time columns in this dataset and we'll use that to get x values denoting high-resolution time instants: the second of the day that a pizza was sold (this is true pizza analytics). We also have the sell price for a pizza, and that'll serve as the y values. The pizzas belong to four different groups (in the type column) and we'll group by that and create value streams with paste(..., collapse = ",") inside the dplyr::summarize() call. With two value streams in each row (having the same number of values) we can now make a gt table with nanoplots.

pizzaplace |>
  dplyr::filter(date == "2015-01-01") |>
  dplyr::mutate(date_time = paste(date, time)) |>
  dplyr::select(type, date_time, price) |>
  dplyr::group_by(type) |>
  dplyr::summarize(
    date_time = paste(date_time, collapse = ","),
    sold = paste(price, collapse = ",")
  ) |>
  gt(rowname_col = "type") |>
  tab_header(
    title = md("Pizzas sold on **January 1, 2015**"),
    subtitle = "Between the opening hours of 11:30 to 22:30"
  ) |>
  cols_nanoplot(
    columns = sold,
    columns_x_vals = date_time,
    expand_x = c("2015-01-01 11:30", "2015-01-01 22:30"),
    reference_line = "median",
    new_col_name = "pizzas_sold",
    new_col_label = "Pizzas Sold",
    options = nanoplot_options(
      show_data_line = FALSE,
      show_data_area = FALSE,
      currency = "USD"
    )
  ) |>
  cols_width(pizzas_sold ~ px(200)) |>
  cols_align(columns = pizzas_sold, align = "center") |>
  opt_all_caps()

Notice that the columns containing the value streams are hid due to the default argument autohide = TRUE because, while useful, they don't need to be displayed to anybody viewing a table. Since we have a lot of data points and a connecting line is not as valuable here, we also set show_data_line = FALSE in nanoplot_options(). It's more interesting to see the clusters of the differently priced pizzas over the entire day. Specifying a currency in nanoplot_options() is a nice touch since the y values are sale prices in U.S. Dollars (hovering over data points gives correctly formatted values). Finally, having a reference line based on the median gives pretty useful information. Seems like customers preferred getting the "chicken"-type pizzas in large size!

Using the gibraltar dataset, let's make a series of nanoplots across the meteorological parameters of temperature, humidity, and wind speed. We'll want to customize the appearance of the plots across three columns and we can make this somewhat simpler by assigning a common set of options through nanoplot_options(). In this table we want to make comparisons across nanoplots in a particular column easier, so, we'll set autoscale = TRUE so that there is a common y-axis scale for each of the parameters (based on the extents of the data).

nanoplot_options_list <-
  nanoplot_options(
    data_point_radius = px(4),
    data_point_stroke_width = px(2),
    data_point_stroke_color = "black",
    data_point_fill_color = "white",
    data_line_stroke_width = px(4),
    data_line_stroke_color = "gray",
    show_data_line = TRUE,
    show_data_points = TRUE,
    show_data_area = FALSE,
  )

gibraltar |>
  dplyr::filter(date <= "2023-05-14") |>
  dplyr::mutate(time = as.numeric(hms::as_hms(paste0(time, ":00")))) |>
  dplyr::mutate(humidity = humidity * 100) |>
  dplyr::select(date, time, temp, humidity, wind_speed) |>
  dplyr::group_by(date) |>
  dplyr::summarize(
    time = paste(time, collapse = ","),
    temp = paste(temp, collapse = ","),
    humidity = paste(humidity, collapse = ","),
    wind_speed = paste(wind_speed, collapse = ","),
  ) |>
  dplyr::mutate(is_satsun = lubridate::wday(date) %in% c(1, 7)) |>
  gt(rowname_col = "date") |>
  tab_header(
    title = "Meteorological Summary of Gibraltar Station",
    subtitle = "Data taken from May 1-14, 2023."
  ) |>
  fmt_date(columns = stub(), date_style = "wd_m_day_year") |>
  cols_nanoplot(
    columns = temp,
    columns_x_vals = time,
    expand_x = c(0, 86400),
    autoscale = TRUE,
    new_col_name = "temperature_nano",
    new_col_label = "Temperature",
    options = nanoplot_options_list
  ) |>
  cols_nanoplot(
    columns = humidity,
    columns_x_vals = time,
    expand_x = c(0, 86400),
    autoscale = TRUE,
    new_col_name = "humidity_nano",
    new_col_label = "Humidity",
    options = nanoplot_options_list
  ) |>
  cols_nanoplot(
    columns = wind_speed,
    columns_x_vals = time,
    expand_x = c(0, 86400),
    autoscale = TRUE,
    new_col_name = "wind_speed_nano",
    new_col_label = "Wind Speed",
    options = nanoplot_options_list
  ) |>
  cols_units(
    temperature_nano = ":degree:C",
    humidity_nano = "% (RH)",
    wind_speed_nano = "m s^-1"
  ) |>
  cols_hide(columns = is_satsun) |>
  tab_style_body(
    style = cell_fill(color = "#E5FEFE"),
    values = TRUE,
    targets = "row",
    extents = c("body", "stub")
  ) |>
  tab_style(
    style = cell_text(align = "center"),
    locations = cells_column_labels()
  )

Box plots can be generated, and we just need to use plot_type = "boxplot" to make that type of nanoplot. Using a small portion of the pizzaplace dataset, we will create a simple table that displays a box plot of pizza sales for a selection of days. By converting the string-time 24-hour-clock time values to the number of seconds elapsed in a day, we get continuous values that can be incorporated into each box plot. And, by supplying a function to the y_val_fmt_fn argument within nanoplot_options(), we can transform the integer seconds values back to clock times for display on hover.

pizzaplace |>
  dplyr::filter(date <= "2015-01-14") |>
  dplyr::mutate(time = as.numeric(hms::as_hms(time))) |>
  dplyr::summarize(time = paste(time, collapse = ","), .by = date) |>
  dplyr::mutate(is_weekend = lubridate::wday(date) %in% 6:7) |>
  gt() |>
  tab_header(title = "Pizza Sales in Early January 2015") |>
  fmt_date(columns = date, date_style = 2) |>
  cols_nanoplot(
    columns = time,
    plot_type = "boxplot",
    options = nanoplot_options(y_val_fmt_fn = function(x) hms::as_hms(x))
  ) |>
  cols_hide(columns = is_weekend) |>
  cols_width(everything() ~ px(250)) |>
  cols_align(align = "center", columns = nanoplots) |>
  cols_align(align = "left", columns = date) |>
  tab_style(
    style = cell_borders(
      sides = "left", color = "gray"),
    locations = cells_body(columns = nanoplots)
  ) |>
  tab_style_body(
    style = cell_fill(color = "#E5FEFE"),
    values = TRUE,
    targets = "row"
  ) |>
  tab_options(column_labels.hidden = TRUE)

Function ID

5-8

Function Introduced

v0.10.0 (October 7, 2023)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_unhide(), cols_units(), cols_width()

Description

cols_unhide() allows us to take one or more hidden columns (usually done via cols_hide()) and make them visible in the final output table. This may be important in cases where the user obtains a gt_tbl object with hidden columns and there is motivation to reveal one or more of those.

Usage

cols_unhide(data, columns)

Arguments

Details

The hiding and unhiding of columns is internally a rendering directive, so, all columns that are 'hidden' are still accessible and useful in any expression provided to a rows argument. The cols_unhide() function quietly changes the visible state of a column (much like the cols_hide() function) and doesn't yield warnings or messages when changing the state of already-visible columns.

Value

An object of class gt_tbl.

Examples

Let's use a small portion of the countrypops dataset to create a gt table. We'll hide the country_code_2 and country_code_3 columns with cols_hide().

tab_1 <-
  countrypops |>
  dplyr::filter(
    country_name == "Singapore",
    year %in% 2017:2021
  ) |>
  gt() |>
  cols_hide(columns = c(country_code_2, country_code_3))

tab_1

If the tab_1 object is provided without the code or source data to regenerate it, and, the user wants to reveal otherwise hidden columns then cols_unhide() becomes useful.

tab_1 |> cols_unhide(columns = country_code_2)

Function ID

5-13

Function Introduced

v0.3.0 (May 12, 2021)

See Also

cols_hide() to perform the inverse operation.

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_units(), cols_width()

Description

Column labels can sometimes contain measurement units, and these might range from easy to define and typeset (e.g., "m/s") to very difficult. Such difficulty can arise from the need to include subscripts or superscripts, non-ASCII symbols, etc. The cols_units() function tries to make this task easier by letting you apply text pertaining to units to various columns. This takes advantage of gt's specialized units notation (e.g., "J Hz^-1 mol^-1" can be used to generate units for the molar Planck constant). The notation here provides several conveniences for defining units, letting you produce the correct formatting no matter what the table output format might be (i.e., HTML, LaTeX, RTF, etc.). Details pertaining to the units notation can be found in the section entitled How to use gt's units notation.

Usage

cols_units(.data, ..., .list = list2(...), .units_pattern = NULL)

Arguments

Value

An object of class gt_tbl.

How to use gt's units notation

The units notation involves a shorthand of writing units that feels familiar and is fine-tuned for the task at hand. Each unit is treated as a separate entity (parentheses and other symbols included) and the addition of subscript text and exponents is flexible and relatively easy to formulate. This is all best shown with examples:

• "m/s" and "m / s" both render as "m/s"

• "m s^-1" will appear with the "-1" exponent intact

• "m /s" gives the same result, as "/<unit>" is equivalent to "<unit>^-1"

• "E_h" will render an "E" with the "h" subscript

• "t_i^2.5" provides a t with an "i" subscript and a "2.5" exponent

• "m[_0^2]" will use overstriking to set both scripts vertically

• "g/L %C6H12O6%" uses a chemical formula (enclosed in a pair of "%" characters) as a unit partial, and the formula will render correctly with subscripted numbers

• Common units that are difficult to write using ASCII text may be implicitly converted to the correct characters (e.g., the "u" in "ug", "um", "uL", and "umol" will be converted to the Greek mu symbol; "degC" and "degF" will render a degree sign before the temperature unit)

• We can transform shorthand symbol/unit names enclosed in ":" (e.g., ":angstrom:", ":ohm:", etc.) into proper symbols

• Greek letters can added by enclosing the letter name in ":"; you can use lowercase letters (e.g., ":beta:", ":sigma:", etc.) and uppercase letters too (e.g., ":Alpha:", ":Zeta:", etc.)

• The components of a unit (unit name, subscript, and exponent) can be fully or partially italicized/emboldened by surrounding text with "*" or "**"

Examples

Let's analyze some pizzaplace data with dplyr and then make a gt table. Here we are separately defining new column labels with cols_label() and then defining the units (to combine to those labels) through cols_units(). The default pattern for combination is "{1}, {2}" which is acceptable here.

pizzaplace |>
  dplyr::mutate(month = lubridate::month(date, label = TRUE, abbr = TRUE)) |>
  dplyr::group_by(month) |>
  dplyr::summarize(
    n_sold = dplyr::n(),
    rev = sum(price)
  ) |>
  dplyr::mutate(chg = (rev - dplyr::lag(rev)) / dplyr::lag(rev)) |>
  dplyr::mutate(month = as.character(month)) |>
  gt(rowname_col = "month") |>
  fmt_integer(columns = n_sold) |>
  fmt_currency(columns = rev, use_subunits = FALSE) |>
  fmt_percent(columns = chg) |>
  sub_missing() |>
  cols_label(
    n_sold = "Number of Pizzas Sold",
    rev = "Revenue Generated",
    chg = "Monthly Changes in Revenue"
  ) |>
  cols_units(
    n_sold = "units month^-1",
    rev = "USD month^-1",
    chg = "% change *m*/*m*"
  ) |>
  cols_width(
    stub() ~ px(40),
    everything() ~ px(200)
  )

The sza dataset has a wealth of information and here we'll generate a smaller table that contains the average solar zenith angles at noon for different months and at different northern latitudes. The column labels are numbers representing the latitudes and it's convenient to apply units of 'degrees north' to each of them with cols_units(). The extra thing we wanted to do here was to ensure that the units are placed directly after the column labels, and we do that with .units_pattern = "{1}{2}". This append the units ("{2}") right to the column label ("{1}").

sza |>
  dplyr::filter(tst == "1200") |>
  dplyr::select(-tst) |>
  dplyr::arrange(desc(latitude)) |>
  tidyr::pivot_wider(
    names_from = latitude,
    values_from = sza
  ) |>
  gt(rowname_col = "month") |>
  cols_units(
    everything() ~ ":degree:N",
    .units_pattern = "{1}{2}"
  ) |>
  tab_spanner(
    label = "Solar Zenith Angle",
    columns = everything()
  ) |>
  text_transform(
    fn = toupper,
    locations = cells_stub()
  ) |>
  tab_style(
    style = cell_text(align = "right"),
    locations = cells_stub()
  )

Taking a portion of the towny dataset, let's use spanners to describe what's in the columns and use only measurement units for the column labels. The columns labels that have to do with population and density information will be replaced with units defined in cols_units(). We'll use a .units_pattern value of "{2}", which means that only the units will be present (the "{1}", representing the column label text, is omitted). Spanners added through several invocations of tab_spanner() will declare what the last four columns contain.

towny |>
  dplyr::select(
    name, land_area_km2,
    ends_with("2016"), ends_with("2021")
  ) |>
  dplyr::slice_max(population_2021, n = 10) |>
  gt(rowname_col = "name") |>
  tab_stubhead(label = "City") |>
  fmt_integer() |>
  cols_label(
    land_area_km2 ~ "Area, {{km^2}}",
    starts_with("population") ~ "",
    starts_with("density") ~ ""
  ) |>
  cols_units(
    starts_with("population") ~ "*ppl*",
    starts_with("density") ~ "*ppl* km^-2",
    .units_pattern = "{2}"
  ) |>
  tab_spanner(
    label = "Population",
    columns = starts_with("population"),
    gather = FALSE
  ) |>
  tab_spanner(
    label = "Density",
    columns = starts_with("density"),
    gather = FALSE
  ) |>
  tab_spanner(
    label = "2016",
    columns = ends_with("2016"),
    gather = FALSE
  ) |>
  tab_spanner(
    label = "2021",
    columns = ends_with("2021"),
    gather = FALSE
  ) |>
  tab_style(
    style = cell_text(align = "center"),
    locations = cells_column_labels(
      c(starts_with("population"), starts_with("density"))
    )
  ) |>
  cols_width(everything() ~ px(120)) |>
  opt_horizontal_padding(scale = 3)

Function ID

5-6

Function Introduced

v0.10.0 (October 7, 2023)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_width()

Description

Manual specifications of column widths can be performed using the cols_width() function. We choose which columns get specific widths. This can be in units of pixels (easily set by use of the px() helper function), or, as percentages (where the pct() helper function is useful). Width assignments are supplied in ... through two-sided formulas, where the left-hand side defines the target columns and the right-hand side is a single dimension.

Usage

cols_width(.data, ..., .list = list2(...))

Arguments

Details

Column widths can be set as absolute or relative values (with px and percentage values). Those columns not specified are treated as having variable width. The sizing behavior for column widths depends on the combination of value types, and, whether a table width has been set (which could, itself, be expressed as an absolute or relative value). Widths for the table and its container can be individually modified with the table.width and container.width arguments within tab_options()).

Value

An object of class gt_tbl.

Examples

Use select columns from the exibble dataset to create a gt table. We can specify the widths of columns with cols_width(). This is done with named arguments in ..., specifying the exact widths for table columns (using everything() at the end will capture all remaining columns).

exibble |>
  dplyr::select(
    num, char, date,
    datetime, row
  ) |>
  gt() |>
  cols_width(
    num ~ px(150),
    ends_with("r") ~ px(100),
    starts_with("date") ~ px(200),
    everything() ~ px(60)
  )

Function ID

5-3

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_add(), cols_align(), cols_align_decimal(), cols_hide(), cols_label(), cols_label_with(), cols_merge(), cols_merge_n_pct(), cols_merge_range(), cols_merge_uncert(), cols_move(), cols_move_to_end(), cols_move_to_start(), cols_nanoplot(), cols_unhide(), cols_units()

Description

This dataset contains values for over 300 basic fundamental constants in nature. The values originate from the 2018 adjustment which is based on the latest relevant precision measurements and improvements of theoretical calculations. Such work has been carried out under the authority of the Task Group on Fundamental Constants (TGFC) of the Committee on Data of the International Science Council (CODATA). These updated values became available on May 20, 2019. They are published at http://physics.nist.gov/constants, a website of the Fundamental Constants Data Center of the National Institute of Standards and Technology (NIST), Gaithersburg, Maryland, USA.

Usage

constants

Format

A tibble with 354 rows and 4 variables:

name

The name of the constant.

value

The value of the constant.

uncert

The uncertainty associated with the value. If NA then the value is seen as an 'exact' value (e.g., an electron volt has the exact value of 1.602 176 634 e-19 J).

sf_value,sf_uncert

The number of significant figures associated with the value and any uncertainty value.

units

The units associated with the constant.

Dataset ID and Badge

DATA-12

Dataset Introduced

v0.10.0 (October 7, 2023)

See Also

Other datasets: countrypops, exibble, films, gibraltar, gtcars, illness, metro, nuclides, peeps, photolysis, pizzaplace, reactions, rx_addv, rx_adsl, sp500, sza, towny

Examples

dplyr::glimpse(constants)

Description

A dataset that presents yearly, total populations of countries. Total population is based on counts of all residents regardless of legal status or citizenship. Country identifiers include the English-language country names, and the 2- and 3-letter ISO 3166-1 country codes. Each row contains a population value for a given year (from 1960 to 2023). Any NA values within population indicate the non-existence of the entity during that year.

Usage

countrypops

Format

A tibble with 13,760 rows and 5 variables:

country_name

The name of the country.

country_code_2, country_code_3

The 2- and 3-letter ISO 3166-1 country codes.

year

The year for the population estimate.

population

The population estimate, midway through the year.

Dataset ID and Badge

DATA-1

Dataset Introduced

v0.2.0.5 (March 31, 2020)

Source

https://data.worldbank.org/indicator/SP.POP.TOTL

See Also

Other datasets: constants, exibble, films, gibraltar, gtcars, illness, metro, nuclides, peeps, photolysis, pizzaplace, reactions, rx_addv, rx_adsl, sp500, sza, towny

Description

The currency() helper function makes it easy to specify a context-aware currency symbol to currency argument of fmt_currency(). Since gt can render tables to several output formats, currency() allows for different variations of the custom symbol based on the output context (which are html, latex, rtf, and default). The number of decimal places for the custom currency defaults to 2, however, a value set for the decimals argument of fmt_currency() will take precedence.

Usage

currency(..., .list = list2(...))

Arguments

Details

We can use any combination of html, latex, rtf, and default as named arguments for the currency text in each of the namesake contexts. The default value is used as a fallback when there doesn't exist a dedicated currency text value for a particular output context (e.g., when a table is rendered as HTML and we use currency(latex = "LTC", default = "ltc"), the currency symbol will be "ltc". For convenience, if we provide only a single string without a name, it will be taken as the default (i.e., currency("ltc") is equivalent to currency(default = "ltc")). However, if we were to specify currency strings for multiple output contexts, names are required each and every context.

Value

A list object of class gt_currency.

Examples

Use the exibble dataset to create a gt table. Within the fmt_currency() call, we'll format the currency column to have currency values in guilder (a defunct Dutch currency). We can register this custom currency with the currency() helper function, supplying the "ƒ" HTML entity for html outputs and using "f" for any other type of gt output.

exibble |>
  gt() |>
  fmt_currency(
    columns = currency,
    currency = currency(
      html = "ƒ",
      default = "f"
    ),
    decimals = 2
  )

Function ID

8-6

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other helper functions: adjust_luminance(), cell_borders(), cell_fill(), cell_text(), default_fonts(), escape_latex(), from_column(), google_font(), gt_latex_dependencies(), html(), md(), nanoplot_options(), pct(), px(), random_id(), row_group(), stub(), system_fonts(), unit_conversion()

Description

It's possible to add color to data cells according to their values with data_color(). There is a multitude of ways to perform data cell colorizing here:

• targeting: we can constrain which columns and rows should receive the colorization treatment (through the columns and rows arguments)

• direction: ordinarily we perform coloring in a column-wise fashion but there is the option to color data cells in a row-wise manner (this is controlled by the direction argument)

• coloring method: data_color() automatically computes colors based on the column type but you can choose a specific methodology (e.g., with bins or quantiles) and the function will generate colors accordingly; the method argument controls this through keywords and other arguments act as inputs to specific methods

• coloring function: a custom function can be supplied to the fn argument for finer control over color evaluation with data; the ⁠scales::col_*()⁠ color mapping functions can be used here or any function you might want to define

• color palettes: with palette we could supply a vector of colors, a viridis or RColorBrewer palette name, or, a palette from the paletteer package

• value domain: we can either opt to have the range of values define the domain, or, specify one explicitly with the domain argument

• indirect color application: it's possible to compute colors from one column and apply them to one or more different columns; we can even perform a color mapping from multiple source columns to the same multiple of target columns

• color application: with the apply_to argument, there's an option for whether to apply the cell-specific colors to the cell background or the cell text

• text autocoloring: if colorizing the cell background, data_color() will automatically recolor the foreground text to provide the best contrast (can be deactivated with autocolor_text = FALSE)

data_color() won't fail with the default options used, but that won't typically provide you the type of colorization you really need. You can however safely iterate through a collection of different options without running into too many errors.

Usage

data_color(
  data,
  columns = everything(),
  rows = everything(),
  direction = c("column", "row"),
  target_columns = NULL,
  method = c("auto", "numeric", "bin", "quantile", "factor"),
  palette = NULL,
  domain = NULL,
  bins = 8,
  quantiles = 4,
  levels = NULL,
  ordered = FALSE,
  na_color = NULL,
  alpha = NULL,
  reverse = FALSE,
  fn = NULL,
  apply_to = c("fill", "text"),
  autocolor_text = TRUE,
  contrast_algo = c("apca", "wcag"),
  colors = NULL
)

Arguments

Value

An object of class gt_tbl.

Color computation methods

data_color() offers four distinct methods for computing color based on cell data values. They are set by the method argument and the options go by the keywords "numeric", "bin", "quantile", and "factor". There are other arguments in data_color() that variously support these methods (e.g., bins for the "bin" method, etc.). Here we'll go through each method, providing a short explanation of what each one does and which options are available.

"numeric"

The "numeric" method provides a simple linear mapping from continuous numeric data to an interpolated palette. Internally, this uses scales::col_numeric(). This method is suited for numeric data cell values and can make use of a supplied domain value, in the form of a two-element numeric vector describing the range of values, if provided.

"bin"

The "bin" method provides a mapping of continuous numeric data to value-based bins. Internally, this uses scales::col_bin() which itself uses base::cut(). As with the "numeric" method, "bin" is meant for numeric data cell values. The use of a domain value is supported with this method. The bins argument in data_color() is specific to this method, offering the ability to: (1) specify the number of bins, or (2) provide a vector of cut points.

"quantile"

The "quantile" method provides a mapping of continuous numeric data to quantiles. Internally, this uses scales::col_quantile() which itself uses stats::quantile(). Input data cell values should be numeric, as with the "numeric" and "bin" methods. A numeric domain value is supported with this method. The quantiles argument in data_color() controls the number of equal-size quantiles to use.

"factor"

The "factor" method provides a mapping of factors to colors. With discrete palettes, color interpolation is used when the number of factors does not match the number of colors in the palette. Internally, this uses scales::col_factor(). Input data cell values can be of any type (i.e., factor, character, numeric values, and more are supported). The optional input to domain should take the form of categorical data. The levels and ordered arguments in data_color() support this method.

Color palette access from RColorBrewer and viridis

All palettes from the RColorBrewer package and select palettes from viridis can be accessed by providing the palette name in palette. RColorBrewer has 35 available palettes:

We can access four colorblind-friendly palettes from viridis: "viridis", "magma", "plasma", and "inferno". Simply provide any one of those names to palette.

Color palette access from paletteer

Choosing the right color palette can often be difficult because it's both hard to discover suitable palettes and then obtain the vector of colors. To make this process easier we can elect to use the paletteer package, which makes a wide range of palettes from various R packages readily available. The info_paletteer() information table allows us to easily inspect all of the discrete color palettes available in paletteer. We only then need to specify the palette and associated package using the ⁠<package>::<palette>⁠ syntax (e.g., "tvthemes::Stannis") for the palette argument.

A requirement for using paletteer in this way is that the package must be installed (gt doesn't import paletteer currently). This can be easily done with install.packages("paletteer"). Not having this package installed with result in an error when using the ⁠<package>::<palette>⁠ syntax in palette.

Foreground text and background fill

By default, gt will choose the ideal text color (for maximal contrast) when colorizing the background of data cells. This option can be disabled by setting autocolor_text to FALSE. The contrast_algo argument lets us choose between two color contrast algorithms: "apca" (Accessible Perceptual Contrast Algorithm, the default algo) and "wcag" (Web Content Accessibility Guidelines).

Examples

data_color() can be used without any supplied arguments to colorize a gt table. Let's do this with the exibble dataset:

exibble |>
  gt() |>
  data_color()

What's happened is that data_color() applies background colors to all cells of every column with the default palette in R (accessed through palette()). The default method for applying color is "auto", where numeric values will use the "numeric" method and character or factor values will use the "factor" method. The text color undergoes an automatic modification that maximizes contrast (since autocolor_text is TRUE by default).

You can use any of the available method keywords and gt will only apply color to the compatible values. Let's use the "numeric" method and supply palette values of "red" and "green".