kable_coloring function

Extend kableExtra colorization of 'Rmarkdown' tables

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.

Returns

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".

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.

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;

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Other jam practical functions: breakDensity(), call_fn_ellipsis(), checkLightMode(), check_pkg_installed(), colNum2excelName(), color_dither(), exp2signed(), getAxisLabel(), isFALSEV(), isTRUEV(), jargs(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()