Type:	Package
Title:	Conditional Formatting in Data Frames
Version:	0.10.1
Date:	2023-10-08
URL:	https://zeehio.github.io/condformat/, https://github.com/zeehio/condformat
BugReports:	https://github.com/zeehio/condformat/issues
Description:	Apply and visualize conditional formatting to data frames in R. It renders a data frame with cells formatted according to criteria defined by rules, using a tidy evaluation syntax. The table is printed either opening a web browser or within the 'RStudio' viewer if available. The conditional formatting rules allow to highlight cells matching a condition or add a gradient background to a given column. This package supports both 'HTML' and 'LaTeX' outputs in 'knitr' reports, and exporting to an 'xlsx' file.
License:	BSD_3_clause + file LICENSE
NeedsCompilation:	no
Imports:	dplyr (≥ 0.7.7), grDevices, gridExtra (≥ 2.3), gtable (≥ 0.2.0), htmlTable (≥ 1.9), htmltools (≥ 0.3.6), knitr (≥ 1.20), magrittr (≥ 1.5), openxlsx (≥ 4.1.5), rmarkdown (≥ 1.10), rlang (≥ 0.3.0), scales (≥ 1.0.0), tibble (≥ 1.3.4), tidyselect (≥ 1.0.0)
Suggests:	promises, shiny (≥ 1.0.5), testthat (≥ 1.0), vdiffr (≥ 1.0.4)
VignetteBuilder:	knitr
Encoding:	UTF-8
RoxygenNote:	7.2.3
Packaged:	2023-10-08 06:34:48 UTC; sergio
Author:	Sergio Oller Moreno [aut, cph, cre]
Maintainer:	Sergio Oller Moreno <sergioller@gmail.com>
Repository:	CRAN
Date/Publication:	2023-10-08 07:00:02 UTC

How to export a cf_field to CSS

Description

This method is exported so package users can generate their own rules

Usage

cf_field_to_css(cf_field, xview, css_fields, unlocked)

Arguments

Value

A list with two elements: css_fields and unlocked (with updated values)

How to export a cf_field to grob

Description

This method is exported so package users can generate their own rules

Usage

cf_field_to_gtable(
  cf_field,
  xview,
  gridobj,
  unlocked,
  has_rownames,
  has_colnames
)

Arguments

Value

A list with two elements: gridobj and unlocked (with updated values)

How to export cf values to latex

Description

How to export cf values to latex

Usage

cf_field_to_latex(cf_field, xview, unlocked)

Arguments

Value

A list with two character matrices named before and after. Both of these matrices must be of the same size as xview.

Conditional formatting for data frames

Description

A condformat_tbl object is a data frame with attributes regarding the formatting of their cells, that can be viewed when the condformat_tbl object is printed.

Usage

condformat(x)

Arguments

Value

The condformat_tbl object. This object can be piped to apply conditional formatting rules. It can also be used as a conventional data frame.

The condformat_tbl print method generates an htmlTable, to be viewed using the 'RStudio Viewer' or an 'HTML browser', as available.

Examples

data(iris)
cf <- condformat(iris[1:5,])
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[1:5,]) %>% rule_fill_gradient(Sepal.Length)
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[1:5,]) %>%
 rule_fill_discrete(Sepal.Length, expression=Sepal.Width > 2)
## Not run: 
print(cf)

## End(Not run)

Shiny bindings for condformat

Description

Output and render functions for using condformat within Shiny applications and interactive Rmd documents.

Usage

condformatOutput(outputId, ...)

renderCondformat(expr, env = parent.frame(), quoted = FALSE)

condformat_example(display.mode = "normal")

Arguments

Writes the table to an Excel workbook

Description

Writes the table to an Excel workbook

Usage

condformat2excel(
  x,
  filename,
  sheet_name = "Sheet1",
  overwrite_wb = FALSE,
  overwrite_sheet = TRUE
)

Arguments

Converts the table to a grid object

Description

Converts the table to a grid object

Usage

condformat2grob(x, draw = TRUE)

Arguments

Value

the grid object

Examples

library(condformat)
data.frame(Student = c("Alice", "Bob", "Charlie"),
           Evaluation = c("Great", "Well done", "Good job!")) %>%
 condformat() %>%
 condformat2grob()

Converts the table to a htmlTable object

Description

Converts the table to a htmlTable object

Usage

condformat2html(x)

Arguments

Value

the htmlTable object

Examples

data(iris)
cf <- condformat2html(condformat(iris[1:5,]))
## Not run: 
print(cf)

## End(Not run)

Converts the table to LaTeX code

Description

Converts the table to LaTeX code

Usage

condformat2latex(x)

Arguments

Value

A character vector of the table source code

Converts the table to a htmlTableWidget

Description

Converts the table to a htmlTableWidget

Usage

condformat2widget(x, ...)

Arguments

Value

the htmlTable widget

Examples

## Not run: 
data(iris)
cf <- condformat2widget(condformat(iris[1:5,]))
\dontrun{
print(cf)
}

## End(Not run)

Print method for knitr, exporting to HTML or LaTeX as needed

Description

Print method for knitr, exporting to HTML or LaTeX as needed

Usage

## S3 method for class 'condformat_tbl'
knit_print(x, ...)

Arguments

Prints the data frame in an HTML page and shows it.

Description

Prints the data frame in an HTML page and shows it.

Usage

## S3 method for class 'condformat_tbl'
print(x, ..., paginate = TRUE)

Arguments

Value

the value returned by htmlTable::htmlTable()

Examples

data(iris)
## Not run: 
print(condformat(iris[1:5,]))

## End(Not run)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

magrittr

%>%

Apply a CSS style property as a conditional formatting rule

Description

Apply a CSS style property as a conditional formatting rule

Usage

rule_css(x, columns, expression, css_field, na.value = "", lockcells = FALSE)

Arguments

See Also

Other rule: rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient2(), rule_fill_gradient(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 51:55, 101:105),]) %>%
  rule_css(Species, expression = ifelse(Species == "setosa", "red", "darkgreen"),
           css_field = "color")
## Not run: 
print(cf)

## End(Not run)

Fill column with a bar of a length proportional to a value

Description

Fills the background of a column cell using a bar proportional to the value of the cell

Usage

rule_fill_bar(
  x,
  columns,
  expression,
  low = "darkgreen",
  high = "white",
  background = "white",
  na.value = "gray",
  limits = NA,
  lockcells = FALSE
)

Arguments

Value

The condformat_tbl object, with the added formatting information

See Also

Other rule: rule_css(), rule_fill_discrete(), rule_fill_gradient2(), rule_fill_gradient(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) %>% rule_fill_bar("Sepal.Length")
## Not run: 
print(cf)

## End(Not run)

Fill column with discrete colors

Description

Fills a column or columns of a data frame using a discrete colour palette, based on an expression.

Usage

rule_fill_discrete(
  x,
  columns,
  expression,
  colours = NA,
  na.value = "#FFFFFF",
  h = c(0, 360) + 15,
  c = 100,
  l = 65,
  h.start = 0,
  direction = 1,
  lockcells = FALSE
)

Arguments

Value

The condformat_tbl object, with the added formatting information

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_gradient2(), rule_fill_gradient(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) %>%
 rule_fill_discrete("Species", colours = c("setosa" = "red",
                                         "versicolor" = "blue",
                                         "virginica" = "green")) %>%
 rule_fill_discrete("Sepal.Length", expression = Sepal.Length > 4.6,
                    colours=c("TRUE"="red"))
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) %>%
 rule_fill_discrete(c(starts_with("Sepal"), starts_with("Petal")),
                    expression = Sepal.Length > 4.6,
                    colours=c("TRUE"="red"))
## Not run: 
print(cf)

## End(Not run)

Fill column with sequential colour gradient

Description

Fills the background color of a column using a gradient based on the values given by an expression

Usage

rule_fill_gradient(
  x,
  columns,
  expression,
  low = "#132B43",
  high = "#56B1F7",
  space = "Lab",
  na.value = "#7F7F7F",
  limits = NA,
  lockcells = FALSE
)

Arguments

Value

The condformat_tbl object, with the added formatting information

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient2(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) %>%
  rule_fill_gradient(Sepal.Length) %>%
  rule_fill_gradient(Species, expression=Sepal.Length - Sepal.Width)
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) %>%
  rule_fill_gradient("Petal.Length") %>%
  rule_fill_gradient(starts_with("Sepal"), expression=Sepal.Length - Sepal.Width)
## Not run: 
print(cf)

## End(Not run)

Fill column with sequential color gradient

Description

Fills the background color of a column using a gradient based on the values given by an expression

Usage

rule_fill_gradient2(
  x,
  columns,
  expression,
  low = scales::muted("red"),
  mid = "white",
  high = scales::muted("blue"),
  midpoint = NA,
  space = "Lab",
  na.value = "#7F7F7F",
  limits = NA,
  lockcells = FALSE
)

Arguments

Value

The condformat_tbl object, with the added formatting information

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) %>%
 rule_fill_gradient2(Sepal.Length) %>%
 rule_fill_gradient2(Species, expression=Sepal.Length - Sepal.Width)
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) %>%
  rule_fill_gradient2("Petal.Length") %>%
  rule_fill_gradient2(starts_with("Sepal"), expression=Sepal.Length - Sepal.Width)
## Not run: 
print(cf)

## End(Not run)

Use bold text if a condition is met

Description

Use bold text if a condition is met

Usage

rule_text_bold(x, columns, expression, na.bold = FALSE, lockcells = FALSE)

Arguments

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient2(), rule_fill_gradient(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 51:55, 101:105),]) %>%
  rule_text_bold(Species, expression = Species == "setosa")
## Not run: 
print(cf)

## End(Not run)

Give a color to the text according to some expression

Description

Give a color to the text according to some expression

Usage

rule_text_color(x, columns, expression, na.color = "", lockcells = FALSE)

Arguments

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient2(), rule_fill_gradient(), rule_text_bold()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 51:55, 101:105),]) %>%
  rule_text_color(Species, expression = ifelse(Species == "setosa", "blue", ""))
## Not run: 
print(cf)

## End(Not run)

Selects the variables to be printed

Description

Keeps the variables you mention in the printed table. Compared to dplyr::select(), show_columns does not remove the columns from the data frame, so formatting rules can still depend on them.

Usage

show_columns(x, columns, col_names)

Arguments

Value

The condformat object with the rule added

See Also

dplyr::select()

Examples

data(iris)
x <- head(iris)

# Include some columns:
cf <- condformat(x) %>% show_columns(c(Sepal.Length, Sepal.Width, Species))
## Not run: 
print(cf)

## End(Not run)
cf <- condformat(x) %>% show_columns(c("Sepal.Length", "Sepal.Width", "Species"))
## Not run: 
print(cf)

## End(Not run)

# Rename columns:
cf <- condformat(x) %>%
  show_columns(c(Sepal.Length, Species),
               col_names = c("Length", "Spec."))
## Not run: 
print(cf)

## End(Not run)

# Exclude some columns:
cf <- condformat(x) %>% show_columns(c(-Petal.Length, -Petal.Width))
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(x) %>% show_columns(c(starts_with("Petal"), Species))
## Not run: 
print(cf)

## End(Not run)

petal_width <- "Petal.Width"
cf <- condformat(x) %>% show_columns(!! petal_width)
## Not run: 
print(cf)

## End(Not run)

Selects the rows to be printed

Description

Keeps the rows you mention in the printed table. Compared to dplyr::filter(), show_rows does not remove the rows from the actual data frame, they are removed only for printing.

Usage

show_rows(x, ...)

Arguments

Value

A condformat_show_rows object, usually to be added to a condformat_tbl object as shown in the examples

See Also

dplyr::filter()

Examples

library(condformat)
data(iris)
x <- head(iris)
cf <- condformat(x) %>% show_rows(Sepal.Length > 4.5, Species == "setosa")
## Not run: 
print(cf)

## End(Not run)
# Use it programatically
expr_as_text <- 'Sepal.Length > 4.5'
expr <- rlang::parse_expr(expr_as_text)
cf <- condformat(x) %>% show_rows(!! expr)
## Not run: 
print(cf)

## End(Not run)
# With multiple arguments:
expr_as_text <- c('Sepal.Length > 4.5', 'Species == "setosa"')
exprs <- lapply(expr_as_text, rlang::parse_expr)
cf <- condformat(x) %>% show_rows(!!! exprs)
## Not run: 
print(cf)

## End(Not run)

Sets the caption of a condformat object

Description

The advantage with respect to theme_htmlTable(caption = "My table") is that this works with HTML and LaTeX outputs

Usage

theme_caption(x, caption = "")

Arguments

Examples

data(iris)
cf <- condformat(head(iris)) %>%
  theme_caption(caption = "My Caption")
## Not run: 
print(cf)

## End(Not run)

Customizes appearance of condformat object

Description

This is only used on grob output.

Usage

theme_grob(x, ...)

Arguments

See Also

gridExtra::tableGrob()

Examples

data(iris)
cf <- condformat(head(iris)) %>%
  theme_grob(
    rows = NULL,
    theme = gridExtra::ttheme_default(base_size = 10, base_colour = "red")
  )
condformat2grob(cf)

Customizes appearance of condformat object

Description

Customizes appearance of condformat object

Usage

theme_htmlTable(x, ...)

Arguments

See Also

htmlTable::htmlTable()

Examples

data(iris)
cf <- condformat(head(iris)) %>%
  theme_htmlTable(caption="Table 1: My iris table", rnames=FALSE)
## Not run: 
print(cf)

## End(Not run)

Customizes appearance of condformat object

Description

Customizes appearance of condformat object

Usage

theme_htmlWidget(x, ...)

Arguments

See Also

htmlTable::htmlTable()

Examples

data(iris)
cf <- condformat(head(iris)) %>%
  theme_htmlWidget(number_of_entries = c(10, 25, 100),
                   width = NULL, height = NULL, elementId = NULL)
## Not run: 
print(cf)

## End(Not run)

Customizes appearance of condformat object

Description

This is only used on LaTeX output.

Usage

theme_kable(x, ...)

Arguments

See Also

knitr::kable()

Examples

data(iris)
cf <- condformat(head(iris)) %>%
  theme_kable(booktabs = TRUE, caption = "My Caption")
## Not run: 
print(cf)

## End(Not run)