tidyHtmlTable: Generate an htmlTable using tidy data as input

Description

This function maps columns from the input data, x, to htmlTable() parameters. It's designed to provide a fluent interface for those familiar with the tidyverse ecosystem.

Usage

tidyHtmlTable(
  x,
  value,
  header,
  rnames,
  rgroup,
  hidden_rgroup,
  cgroup,
  tspanner,
  hidden_tspanner,
  skip_removal_warning = getOption("htmlTable.skip_removal_warning", FALSE),
  rnames_unique,
  table_fn = htmlTable,
  ...
)

Value

Returns the HTML code that, when rendered, displays a formatted table.

Arguments

x: Tidy data used to build the htmlTable
value: Column containing values for individual table cells. Defaults to "value" (same as tidyr::pivot_wider).
header: Column in x specifying column headings
rnames: Column in x specifying row names. Defaults to "name" (same as tidyr::pivot_wider()).
rgroup: Column in x specifying row groups.
hidden_rgroup: Strings indicating rgroup values to be hidden.
cgroup: Columns in x specifying the column groups.
tspanner: Column in x specifying tspanner groups.
hidden_tspanner: Strings indicating tspanner values to be hidden.
skip_removal_warning: Boolean to suppress warnings when removing NA columns.
rnames_unique: Designates unique row names when regular names lack uniqueness.
table_fn: Function to format the table, defaults to htmlTable().
...: Additional arguments passed to htmlTable().

Column-mapping

Columns from x are mapped (transformed) to specific parameters of the htmlTable() The following columns are converted to match the intended input structure:

value
header
rnames
rgroup
cgroup
tspanner

Each combination of the variables in x should be unique to map correctly to the output table.

Row uniqueness

Usually each row should have a unique combination of the mappers. Sometimes though rows come in a distinct order and the order identifies the row more than the name. E.g. if we are identifying bone fractures using the AO-classification we will have classes ranging in the form of:

A
A1
A1.1
A2
A2.1
A2.2
B
...

we can simplify the names while retaining the key knowledge to:

A
.1
...1
.2
...1
...2
B
...

This will though result in non-unique rows and thus we need to provide the original names in addition to the rnames argument. To do this we have rnames_unique as a parameter, without this tidyHtmlTable we risk unintended merging of cells, generating > 1 value per cell.

Note it is recommended that you verify with the full names just to make sure that any unexpected row order change has happened in the underlying pivot functions.

Sorting

Rows can be pre-sorted using dplyr::arrange() before passing to tidyHtmlTable. Column sorting is based on arrange(cgroup, header). If you want to sort in non-alphabetic order you can provide a factor variable and that information will be retained.

Hidden values

htmlTable Allows for some values within rgroup, cgroup, etc. to be specified as "". The following parameters allow for specific values to be treated as if they were a string of length zero in the htmlTable function.

hidden_rgroup
hidden_tspanner

Simple tibble output

The tibble discourages the use of row names. There is therefore a convenience option for tidyHtmlTable where you can use the function just as you would with htmlTable() where rnames is populated with the rnames argument provided using tidyselect syntax (defaults to the "names" column if present int the input data).

Additional dependencies

In order to run this function you also must have dplyr, tidyr, tidyselect and purrr packages installed. These have been removed due to the additional 20 Mb that these dependencies added (issue #47). Note: if you use tidyverse it will already have all of these and you do not need to worry.

Examples

Run this code

library(tibble)
library(dplyr)
library(tidyr)

# Prep and select basic data
data("mtcars")
base_data <- mtcars %>%
  rownames_to_column() %>%
  mutate(gear = paste(gear, "Gears"),
         cyl = paste(cyl, "Cylinders")) %>%
  select(rowname, cyl, gear, wt, mpg, qsec)

base_data %>%
  pivot_longer(names_to = "per_metric",
               cols = c(wt, mpg, qsec)) %>%
  group_by(cyl, gear, per_metric) %>%
  summarise(value_Mean = round(mean(value), 1),
            value_Min = round(min(value), 1),
            value_Max = round(max(value), 1),
            .groups = "drop") %>%
  pivot_wider(names_from = per_metric,
              values_from = starts_with("value_")) %>%
  # Round the values into a nicer format where we want the weights to have two decimals
  txtRound(ends_with("_wt"), digits = 2) %>%
  txtRound(starts_with("value") & !ends_with("_wt"), digits = 1) %>%
  # Convert into long format
  pivot_longer(cols = starts_with("value_"), names_prefix = "value_") %>%
  separate(name, into = c("summary_stat", "per_metric")) %>%
  # Without sorting the row groups wont appear right
  # If the columns end up in the wrong order you may want to change the columns
  # into factors
  arrange(per_metric) %>%
  addHtmlTableStyle(align = "r") %>%
  tidyHtmlTable(
    header = gear,
    cgroup = cyl,
    rnames = summary_stat,
    rgroup = per_metric,
    skip_removal_warning = TRUE)

Run the code above in your browser using DataLab