kable_coloring: Extend kableExtra colorization of 'Rmarkdown' tables
In jamba: Just Analysis Methods Base

kable_coloring

R Documentation

Extend kableExtra colorization of 'Rmarkdown' tables

Description

Extend kableExtra colorization of 'Rmarkdown' tables

Usage

kable_coloring(
  df,
  colorSub = NULL,
  background_as_tile = TRUE,
  color_cells = TRUE,
  row_color_by = NULL,
  sep = "_",
  border_left = "1px solid #DDDDDD",
  border_right = FALSE,
  extra_css = "white-space: nowrap;",
  format = "html",
  format.args = list(trim = TRUE, big.mark = ","),
  row.names = NA,
  align = NULL,
  return_type = c("kable", "data.frame"),
  verbose = FALSE,
  ...
)

Arguments

`df`	`data.frame` input. Note that `kable` input is not supported.
`colorSub`	one of the following inputs: `character` vector of R colors, whose names match entries in the `data.frame` which are given these assigned colors `function` that takes column values as input, and returns a `character` vector with one color per value, using `NA` or `NULL` to indicate `"transparent"` `list` whose names match `colnames(df)`, where each entry contains either `character` or `function` option as described above. A `character` vector should be named by values expected in each column. A `function` should take column values as input, and return a `character` vector with same length of R colors.
`background_as_tile`	`logical` default `TRUE`, whether the cell background color will appear as a rounded tile (`TRUE`) or a rectangle (`FALSE`). Either way, the color does not fill the entire whitespace of the table cell, but only around the text itself.
`color_cells`	`logical` indicating whether to color individual cells, default `TRUE`. This may be `FALSE` when also applying `row_color_by`, so the entire row will be colorized.
`row_color_by`	`character` vector with one or more `colnames`, indicating how to colorize entire rows of a table. When one column is defined, colors in `colorSub` are used as normal. When multiple columns are defined, values from each column are concatenated using `sep` delimiter. Then resulting values are compared with `colorSub`.
`sep`	`character` delimiter used to combine values in multiple columns when `row_color_by` is supplied and contains multiple `colnames`. The delimited character strings are compared to `colorSub` to assign colors.
`border_left`, `border_right`, `extra_css`	`character` values optionally passed to `kableExtra::column_spec()` as a convenient way to apply borders for each column (`border_left`, `border_right`) or enable or disable word-wrapping by column. Some helpful examples: `border_left=FALSE`: disables left border `border_left="1px solid #DDDDDD"`: light gray 1 pixel left border `border_right=FALSE`: disables right border `border_right="1px solid #DDDDDD"`: light gray 1 pixel right border `extra_css=NULL`: disables word-wrap `extra_css="whitespace: nowrap;"`: enables text word-wrap when all options above contain only `FALSE` or `NULL`, then `kableExtra::column_spec()` is not applied.
`format`	`character` passed to `knitr::kable()`, default `"html"` which is the intended format for most scenarios. It can be set to `NULL` to enable auto-detection of the format.
`format.args`	`list` of arguments passed to `base::format()` intended mainly for `numeric` columns.
`row.names`	`logical` indicating whether to include `rownames(df)`. When `row.names=NA` the default is to display rownames if they are not `NULL` and not equal to `1:nrow(df)`.
`align`	`character` passed to `kableExtra::kable()` to define alignment of each column.
`return_type`	`character` string indicating the type of data to return. `return_type="kable"`: (default) returns object with class `⁠"kableExtra", "knitr_kable"⁠` suitable for downstream processing. `return_type="data.frame"`: returns a `data.frame` whose cells contain HTML markup with corresponding colors defined.
`verbose`	boolean indicating whether to print verbose output.
`...`	additional arguments are passed to `kableExtra::kable()` which allows the usual customizations on the initial call.

Details

This function extends the kableExtra package, and is only available for use if the kableExtra package is installed. It is intended to allow specific color assignment of elements in a data.frame, but otherwise uses the kableExtra functions to apply those colors.

The use case is to provide colorized HTML output for 'Rmarkdown', it has not been tested with other format output.

The argument colorSub accepts:

character vector input where names should match column values
function that accepts column values and returns a character vector of colors of equal length
list input where names should match colnames(df), and where each list element should contain either a character vector, or function as described above.

Value

object with class c("kableExtra", "knitr_kable") by default when return_type="kable", suitable to render inside an 'Rmarkdown' or HTML context. Or returns data.frame when return_type="data.frame".

Examples


expt_df <- data.frame(
   Sample_ID="",
   Treatment=rep(c("Vehicle", "Dex"), each=6),
   Genotype=rep(c("Wildtype", "Knockout"), each=3),
   Rep=paste0("rep", c(1:3)))
expt_df$Sample_ID <- pasteByRow(expt_df[, 2:4])

# define colors
colorSub <- c(Vehicle="palegoldenrod",
   Dex="navy",
   Wildtype="gold",
   Knockout="firebrick",
   nameVector(
      color2gradient("grey48", n=3, dex=10),
      rep("rep", 3),
      suffix=""),
   nameVector(
      color2gradient(n=3,
         c("goldenrod1", "indianred3", "royalblue3", "darkorchid4")),
      expt_df$Sample_ID))
kbl <- kable_coloring(
   expt_df,
   caption="Experiment design table showing categorical color assignment.",
   colorSub)
# Note that the HTML table is rendered in 'Rmarkdown', not pkgdown
kbl

# return_type="data.frame" is a data.frame with HTML contents
kdf3 <- kable_coloring(
   return_type="data.frame",
   df=expt_df,
   colorSub=colorSub)
kdf3;

jamba documentation built on April 4, 2025, 5:14 a.m.