cols_hide: Hide one or more columns

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)

Value

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

Arguments

data

The gt table data object

obj:<gt_tbl> // required

This is the gt table object that is commonly created through use of the gt() function.

columns

Columns to target

<column-targeting expression> // required

The columns to hide in the output display table. Can either be a series of column names provided in c(), a vector of column indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything()).

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

This image of a table was generated from the first code example in the `cols_hide()` help file.

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

This image of a table was generated from the second code example in the `cols_hide()` help file.

Function ID

5-12

Function Introduced

v0.2.0.5 (March 31, 2020)

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.