kable_coloring: Extend kableExtra colorization of Rmarkdown tables
In jmw86069/jamba: Jam Base Methods

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

data.frame or class with "kableExtra" dependent upon the return_type argument. Note that even the data.frame returned will have colors encoded into each cell using HTML.

Examples


new_colorSub <- list(
   column_A=nameVector(rainbow(5), LETTERS[1:5]),
   column_B=nameVector(rev(rainbow(5)), LETTERS[1:5]),
   column_C=circlize::colorRamp2(
      colors=getColorRamp("Reds", n=6),
      breaks=0:5 * 1000))
testdf <- data.frame(column_A=LETTERS[1:5],
   row.names=LETTERS[1:5],
   column_B=LETTERS[1:5],
   column_C=1:5 * 1000)

# kableExtra output with colored tiles inside table cells
kdf1 <- kable_coloring(
   df=testdf,
   colorSub=new_colorSub)
print(class(kdf1));
kdf1;

# kableExtra output with colored rows
kdf2 <- kable_coloring(
   row_color_by=3,
   df=testdf,
   colorSub=new_colorSub)
class(kdf2);
kdf2;

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

jmw86069/jamba documentation built on Oct. 9, 2024, 10:52 a.m.