Package 'flextable'

Description

The flextable package facilitates access to and manipulation of tabular reporting elements from R.

The documentation of functions can be opened with command help(package = "flextable").

flextable() function is producing flexible tables where each cell can contain several chunks of text with their own set of formatting properties (bold, font color, etc.). Function mk_par() lets customise text of cells.

Each cell holds a single paragraph composed of inline chunks (see as_paragraph()). This means cell content is strictly inline: bold, italic, links, images, equations, inline code, etc. Block-level structures (multiple paragraphs, bullet lists, headings or fenced code blocks) cannot be placed inside a cell. Soft line breaks (⁠\n⁠) are however supported.

The as_flextable() function is used to transform specific objects into flextable objects. For example, you can transform a crosstab produced with the 'tables' package into a flextable which can then be formatted, annotated or augmented with footnotes.

In order to reduce the homogenization efforts and the number of functions to be called, it is recommended to define formatting properties such as font, border color, number of decimals displayed which will then be applied by default. See set_flextable_defaults() for more details.

Table Structure

A flextable is composed of three distinct parts:

• header: By default, contains one row with the column names from the data.frame

• body: Contains the actual data from the data.frame

• footer: Empty by default, but can contain content (commonly used for footnotes or #' summary rows)

       HEADER         <- Column names, labels, spanning headers
--------------------
        BODY          <- Data rows
--------------------
       FOOTER         <- Summary rows, notes, footnotes (optional)

A basic flextable has:

• in the part 'header': 1 row with column names

• in the part 'body': as many rows as there are in the input data.frame

• no footer

Rows and columns can be added or removed to the basic flextable:

• Add new rows in header with add_header(), add_header_row(), add_header_lines() and set_header_labels().

• Add new rows in footer with add_footer(), add_footer_lines(), set_header_footer_df() and add_footer_row().

• Add new rows in body with add_body() and add_body_row().

• Delete columns with delete_columns().

• Delete a part with delete_part().

• Use column names to separate a simple header row into multiple nested rows with separate_header().

Selectors in flextable

Selectors are a core feature of flextable that allow you to specify which parts (part), rows (i) and columns (j) should be affected by formatting, styling, or content operations. See the corresponding manual: <Selectors in flextable>.

Author(s)

Maintainer: David Gohel [email protected]

Authors:

• David Gohel [email protected]

• Panagiotis Skintzos [email protected]

Other contributors:

• ArData [copyright holder]

• Clementine Jager [contributor]

• Eli Daniels [contributor]

• Quentin Fazilleau [contributor]

• Maxim Nazarov [contributor]

• Titouan Robert [contributor]

• Michael Barrowman [contributor]

• Atsushi Yasumoto [contributor]

• Paul Julian [contributor]

• Sean Browning [contributor]

• Rémi Thériault (ORCID) [contributor]

• Samuel Jobert [contributor]

• Keith Newman [contributor]

See Also

https://davidgohel.github.io/flextable/, https://ardata-fr.github.io/flextable-book/, flextable()

Description

Add new rows to the body where each value maps to a named column, preserving the original column data types. Unlike add_body_row() where labels can span multiple columns, here each value fills exactly one column.

If some columns are not provided, they will be replaced by NA and displayed as empty.

Usage

add_body(x, top = TRUE, ..., values = NULL)

Arguments

See Also

flextable()

Other row and column operations: add_body_row(), add_footer(), add_footer_lines(), add_footer_row(), add_header(), add_header_lines(), add_header_row(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

ft <- flextable(head(iris),
  col_keys = c(
    "Species", "Sepal.Length", "Petal.Length",
    "Sepal.Width", "Petal.Width"
  )
)

ft <- add_body(
  x = ft, Sepal.Length = 1:5,
  Sepal.Width = 1:5 * 2, Petal.Length = 1:5 * 3,
  Petal.Width = 1:5 + 10, Species = "Blah", top = FALSE
)

ft <- theme_booktabs(ft)
ft

Description

Add a single row to the body where labels can span multiple columns (merged cells) via the colwidths argument.

Labels are associated with a number of columns to merge that default to one if not specified. In this case, you have to make sure that the number of labels is equal to the number of columns displayed.

The function can add only one single row by call.

Labels can also be formatted with as_paragraph().

Usage

add_body_row(x, top = TRUE, values = list(), colwidths = integer(0))

Arguments

See Also

flextable(), set_caption()

Other row and column operations: add_body(), add_footer(), add_footer_lines(), add_footer_row(), add_header(), add_header_lines(), add_header_row(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

library(flextable)

ft01 <- fp_text_default(color = "red")
ft02 <- fp_text_default(color = "orange")

pars <- as_paragraph(
  as_chunk(c("(1)", "(2)"), props = ft02), " ",
  as_chunk(
    c(
      "My tailor is rich",
      "My baker is rich"
    ),
    props = ft01
  )
)

ft_1 <- flextable(head(mtcars))
ft_1 <- add_body_row(ft_1,
  values = pars,
  colwidths = c(5, 6), top = FALSE
)
ft_1 <- add_body_row(ft_1,
  values = pars,
  colwidths = c(3, 8), top = TRUE
)
ft_1 <- theme_box(ft_1)
ft_1

ft_2 <- flextable(head(airquality))
ft_2 <- add_body_row(ft_2,
  values = c("blah", "bleeeh"),
  colwidths = c(4, 2), top = TRUE
)
ft_2 <- theme_box(ft_2)
ft_2

Description

Add new rows to the footer where each value maps to a named column. Unlike add_footer_row() where labels can span multiple columns, here each value fills exactly one column.

If some columns are not provided, they will be replaced by NA and displayed as empty.

Usage

add_footer(x, top = TRUE, ..., values = NULL)

Arguments

See Also

Other row and column operations: add_body(), add_body_row(), add_footer_lines(), add_footer_row(), add_header(), add_header_lines(), add_header_row(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

new_row <- as.list(colMeans(iris[, -5]))
new_row$Species <- "Means"

formatter <- function(x) sprintf("%.1f", x)

ft <- flextable(data = head(iris))
ft <- add_footer(ft, values = new_row)

# cosmetics
ft <- compose(
  x = ft, j = 1:4,
  value = as_paragraph(
    as_chunk(., formatter = formatter)
  ),
  part = "footer", use_dot = TRUE
)
ft <- align(ft, part = "footer", align = "right", j = 1:4)
ft

Description

Add one or more rows to the footer where each label spans all columns (all cells merged into one). Useful for adding footnotes or source notes below the table.

Usage

add_footer_lines(x, values = character(0), top = FALSE)

Arguments

See Also

Other row and column operations: add_body(), add_body_row(), add_footer(), add_footer_row(), add_header(), add_header_lines(), add_header_row(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

ft_1 <- flextable(head(iris))
ft_1 <- add_footer_lines(ft_1,
  values = c("blah 1", "blah 2")
)
ft_1

Description

Add a single row to the footer where labels can span multiple columns (merged cells) via the colwidths argument.

Labels are associated with a number of columns to merge that default to one if not specified. In this case, you have to make sure that the number of labels is equal to the number of columns displayed.

The function can add only one single row by call.

Labels can be formatted with as_paragraph().

Usage

add_footer_row(x, top = TRUE, values = character(0), colwidths = integer(0))

Arguments

See Also

flextable(), set_caption()

Other row and column operations: add_body(), add_body_row(), add_footer(), add_footer_lines(), add_header(), add_header_lines(), add_header_row(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

library(flextable)

ft01 <- fp_text_default(color = "red")
ft02 <- fp_text_default(color = "orange")

pars <- as_paragraph(
  as_chunk(c("(1)", "(2)"), props = ft02), " ",
  as_chunk(
    c(
      "My tailor is rich",
      "My baker is rich"
    ),
    props = ft01
  )
)

ft_1 <- flextable(head(mtcars))
ft_1 <- add_footer_row(ft_1,
  values = pars,
  colwidths = c(5, 6), top = FALSE
)
ft_1 <- add_footer_row(ft_1,
  values = pars,
  colwidths = c(3, 8), top = TRUE
)
ft_1

ft_2 <- flextable(head(airquality))
ft_2 <- add_footer_row(ft_2,
  values = c("Measure", "Time"),
  colwidths = c(4, 2), top = TRUE
)
ft_2 <- theme_box(ft_2)
ft_2

Description

Add new rows to the header where each value maps to a named column. Unlike add_header_row() where labels can span multiple columns, here each value fills exactly one column.

If some columns are not provided, they will be replaced by NA and displayed as empty.

Usage

add_header(x, top = TRUE, ..., values = NULL)

Arguments

Note

when repeating values, they can be merged together with function merge_h() and merge_v().

See Also

Other row and column operations: add_body(), add_body_row(), add_footer(), add_footer_lines(), add_footer_row(), add_header_lines(), add_header_row(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

library(flextable)

fun <- function(x) {
  paste0(
    c("min: ", "max: "),
    formatC(range(x))
  )
}
new_row <- list(
  Sepal.Length = fun(iris$Sepal.Length),
  Sepal.Width =  fun(iris$Sepal.Width),
  Petal.Width =  fun(iris$Petal.Width),
  Petal.Length = fun(iris$Petal.Length)
)

ft_1 <- flextable(data = head(iris))
ft_1 <- add_header(ft_1, values = new_row, top = FALSE)
ft_1 <- append_chunks(ft_1, part = "header", i = 2, )
ft_1 <- theme_booktabs(ft_1, bold_header = TRUE)
ft_1 <- align(ft_1, align = "center", part = "all")
ft_1

Description

Add one or more rows to the header where each label spans all columns (all cells merged into one). Useful for adding titles or subtitles above the column headers.

Usage

add_header_lines(x, values = character(0), top = TRUE)

Arguments

See Also

Other row and column operations: add_body(), add_body_row(), add_footer(), add_footer_lines(), add_footer_row(), add_header(), add_header_row(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

# ex 1----
ft_1 <- flextable(head(iris))
ft_1 <- add_header_lines(ft_1, values = "blah blah")
ft_1 <- add_header_lines(ft_1, values = c("blah 1", "blah 2"))
ft_1 <- autofit(ft_1)
ft_1

# ex 2----
ft01 <- fp_text_default(color = "red")
ft02 <- fp_text_default(color = "orange")
ref <- c("(1)", "(2)")
pars <- as_paragraph(
  as_chunk(ref, props = ft02), " ",
  as_chunk(rep("My tailor is rich", length(ref)), props = ft01)
)

ft_2 <- flextable(head(mtcars))
ft_2 <- add_header_lines(ft_2, values = pars, top = FALSE)
ft_2 <- add_header_lines(ft_2, values = ref, top = TRUE)
ft_2 <- add_footer_lines(ft_2, values = "blah", top = TRUE)
ft_2 <- add_footer_lines(ft_2, values = pars, top = TRUE)
ft_2 <- add_footer_lines(ft_2, values = ref, top = FALSE)
ft_2 <- autofit(ft_2)
ft_2

Description

Add a single row to the header where labels can span multiple columns (merged cells) via the colwidths argument.

Labels are associated with a number of columns to merge that default to one if not specified. In this case, you have to make sure that the number of labels is equal to the number of columns displayed.

The function can add only one single row by call.

Labels can also be formatted with as_paragraph().

Usage

add_header_row(x, top = TRUE, values = character(0), colwidths = integer(0))

Arguments

See Also

flextable(), set_caption()

Other row and column operations: add_body(), add_body_row(), add_footer(), add_footer_lines(), add_footer_row(), add_header(), add_header_lines(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

library(flextable)

ft01 <- fp_text_default(color = "red")
ft02 <- fp_text_default(color = "orange")

pars <- as_paragraph(
  as_chunk(c("(1)", "(2)"), props = ft02), " ",
  as_chunk(c(
    "My tailor is rich",
    "My baker is rich"
  ), props = ft01)
)

ft_1 <- flextable(head(mtcars))
ft_1 <- add_header_row(ft_1,
  values = pars,
  colwidths = c(5, 6), top = FALSE
)
ft_1 <- add_header_row(ft_1,
  values = pars,
  colwidths = c(3, 8), top = TRUE
)
ft_1

ft_2 <- flextable(head(airquality))
ft_2 <- add_header_row(ft_2,
  values = c("Measure", "Time"),
  colwidths = c(4, 2), top = TRUE
)
ft_2 <- theme_box(ft_2)
ft_2

Description

Change the text alignment of selected rows and columns of a flextable.

Usage

align(
  x,
  i = NULL,
  j = NULL,
  align = "left",
  part = c("body", "header", "footer", "all")
)

align_text_col(x, align = "left", header = TRUE, footer = TRUE)

align_nottext_col(x, align = "right", header = TRUE, footer = TRUE)

Arguments

See Also

Other formatting shortcuts: bg(), bold(), color(), empty_blanks(), font(), fontsize(), highlight(), italic(), keep_with_next(), line_spacing(), padding(), rotate(), style(), tab_settings(), valign()

Examples

# Table of 6 columns
ft_car <- flextable(head(mtcars)[, 2:7])

# All 6 columns right aligned
align(ft_car, align = "right", part = "all")

# Manually specify alignment of each column
align(
  ft_car,
  align = c("left", "right", "left", "center", "center", "right"),
  part = "all"
)

# Center-align column 2 and left-align column 5
align(ft_car, j = c(2, 5), align = c("center", "left"), part = "all")

# Alternate left and center alignment across columns 1-4 for header only
align(ft_car, j = 1:4, align = c("left", "center"), part = "header")
ftab <- flextable(mtcars)
ftab <- align_text_col(ftab, align = "left")
ftab <- align_nottext_col(ftab, align = "right")
ftab

Description

append chunks (for example chunk as_chunk()) in a flextable.

Usage

append_chunks(x, ..., i = NULL, j = NULL, part = "body")

Arguments

See Also

as_chunk(), as_sup(), as_sub(), colorize()

Other functions to compose cell content: as_paragraph(), compose(), footnote(), labelizor(), prepend_chunks(), void()

Examples

library(flextable)
img.file <- file.path(R.home("doc"), "html", "logo.jpg")

ft_1 <- flextable(head(cars))

ft_1 <- append_chunks(ft_1,
  # where to append
  i = c(1, 3, 5),
  j = 1,
  # what to append
  as_chunk(" "),
  as_image(src = img.file, width = .20, height = .15)
)
ft_1 <- set_table_properties(ft_1, layout = "autofit")
ft_1

Description

The function is producing a chunk with bold font.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

Usage

as_b(x)

Arguments

See Also

Other chunk elements for paragraph: as_bracket(), as_chunk(), as_equation(), as_highlight(), as_i(), as_image(), as_qmd(), as_strike(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

ft <- flextable(head(iris),
  col_keys = c("Sepal.Length", "dummy")
)

ft <- compose(ft,
  j = "dummy",
  value = as_paragraph(
    as_b(Sepal.Length)
  )
)

ft

Description

The function is producing a chunk by pasting values and add the result in brackets.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

Usage

as_bracket(..., sep = ", ", p = "(", s = ")")

Arguments

See Also

Other chunk elements for paragraph: as_b(), as_chunk(), as_equation(), as_highlight(), as_i(), as_image(), as_qmd(), as_strike(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

ft <- flextable(head(iris),
  col_keys = c("Species", "Sepal", "Petal")
)
ft <- set_header_labels(ft, Sepal = "Sepal", Petal = "Petal")
ft <- compose(ft,
  j = "Sepal",
  value = as_paragraph(as_bracket(Sepal.Length, Sepal.Width))
)
ft <- compose(ft,
  j = "Petal",
  value = as_paragraph(as_bracket(Petal.Length, Petal.Width))
)
ft

Description

The function lets add formated text in flextable cells.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

It should be used inside a call to as_paragraph().

Usage

as_chunk(x, props = NULL, formatter = format_fun, ...)

Arguments

See Also

Other chunk elements for paragraph: as_b(), as_bracket(), as_equation(), as_highlight(), as_i(), as_image(), as_qmd(), as_strike(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

library(officer)

ft <- flextable(head(iris))

ft <- compose(ft,
  j = "Sepal.Length",
  value = as_paragraph(
    "Sepal.Length value is ",
    as_chunk(Sepal.Length, props = fp_text(color = "red"))
  ),
  part = "body"
)
ft <- color(ft, color = "gray40", part = "all")
ft <- autofit(ft)
ft

Description

This function is used to insert equations into flextable.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

To use this function, package 'equatags' is required; also equatags::mathjax_install() must be executed only once to install necessary dependencies.

Usage

as_equation(x, width = 1, height = 0.2, unit = "in", props = NULL)

Arguments

See Also

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_highlight(), as_i(), as_image(), as_qmd(), as_strike(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

library(flextable)
if (require("equatags")) {
  eqs <- c(
    "(ax^2 + bx + c = 0)",
    "a \\ne 0",
    "x = {-b \\pm \\sqrt{b^2-4ac} \\over 2a}"
  )
  df <- data.frame(formula = eqs)
  df


  ft <- flextable(df)
  ft <- compose(
    x = ft, j = "formula",
    value = as_paragraph(as_equation(formula, width = 2, height = .5))
  )
  ft <- align(ft, align = "center", part = "all")
  ft <- width(ft, width = 2)
  ft
}

Description

This is a convenient function to let users create flextable bindings from any objects. Users should consult documentation of corresponding method to understand the details and see what arguments can be used.

Usage

as_flextable(x, ...)

Arguments

See Also

Other flextable constructors: flextable()

Description

compact_summary objects can be transformed into a flextable with method as_flextable().

Numeric columns are formatted with formatC() using the digits value stored in the object and the current flextable defaults for big.mark and decimal.mark.

Usage

## S3 method for class 'compact_summary'
as_flextable(x, ...)

Arguments

Value

A flextable() object.

See Also

Other as_flextable methods: as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

z <- compact_summary(iris, show_type = TRUE, show_na = TRUE)
as_flextable(z)

Description

It displays the first rows and shows the column types. If there is only one row, a simplified vertical table is produced.

Usage

## S3 method for class 'data.frame'
as_flextable(
  x,
  max_row = 10,
  split_colnames = FALSE,
  short_strings = FALSE,
  short_size = 35,
  short_suffix = "...",
  do_autofit = TRUE,
  show_coltype = TRUE,
  color_coltype = "#999999",
  ...
)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

as_flextable(mtcars)

Description

produce a flextable describing a generalized additive model produced by function mgcv::gam.

Usage

## S3 method for class 'gam'
as_flextable(x, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

if (require("mgcv")) {
  set.seed(2)

  # Simulated data
  dat <- gamSim(1, n = 400, dist = "normal", scale = 2)

  # basic GAM model
  b <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat)

  ft <- as_flextable(b)
  ft
}

Description

produce a flextable describing a generalized linear model produced by function glm.

You can remove significance stars by setting options options(show.signif.stars = FALSE).

Usage

## S3 method for class 'glm'
as_flextable(x, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

if (require("broom")) {
  dat <- attitude
  dat$high.rating <- (dat$rating > 70)
  probit.model <- glm(high.rating ~ learning + critical +
    advance, data = dat, family = binomial(link = "probit"))
  ft <- as_flextable(probit.model)
  ft
}

Description

Produce a flextable from a table produced by function as_grouped_data().

Usage

## S3 method for class 'grouped_data'
as_flextable(x, col_keys = NULL, hide_grouplabel = FALSE, ...)

Arguments

See Also

as_grouped_data()

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

library(data.table)
CO2 <- CO2
setDT(CO2)
CO2$conc <- as.integer(CO2$conc)

data_co2 <- dcast(CO2, Treatment + conc ~ Type,
  value.var = "uptake", fun.aggregate = mean
)
data_co2 <- as_grouped_data(x = data_co2, groups = c("Treatment"))

ft <- as_flextable(data_co2)
ft <- add_footer_lines(ft, "dataset CO2 has been used for this flextable")
ft <- add_header_lines(ft, "mean of carbon dioxide uptake in grass plants")
ft <- set_header_labels(ft, conc = "Concentration")
ft <- autofit(ft)
ft <- width(ft, width = c(1, 1, 1))
ft

Description

produce a flextable describing an object oof class htest.

Usage

## S3 method for class 'htest'
as_flextable(x, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

if (require("stats")) {
  M <- as.table(rbind(c(762, 327, 468), c(484, 239, 477)))
  dimnames(M) <- list(
    gender = c("F", "M"),
    party = c("Democrat", "Independent", "Republican")
  )
  ft_1 <- as_flextable(chisq.test(M))
  ft_1
}

Description

produce a flextable describing a kmeans object. The function is only using package 'broom' that provides the data presented in the resulting flextable.

Usage

## S3 method for class 'kmeans'
as_flextable(x, digits = 4, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

if (require("stats")) {
  cl <- kmeans(scale(mtcars[1:7]), 5)
  ft <- as_flextable(cl)
  ft
}

Description

produce a flextable describing a linear model produced by function lm.

You can remove significance stars by setting options options(show.signif.stars = FALSE).

Usage

## S3 method for class 'lm'
as_flextable(x, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

if (require("broom")) {
  lmod <- lm(rating ~ complaints + privileges +
    learning + raises + critical, data = attitude)
  ft <- as_flextable(lmod)
  ft
}

Description

produce a flextable describing a mixed model. The function is only using package 'broom.mixed' that provides the data presented in the resulting flextable.

You can remove significance stars by setting options options(show.signif.stars = FALSE).

Usage

## S3 method for class 'merMod'
as_flextable(x, add.random = TRUE, ...)

## S3 method for class 'lme'
as_flextable(x, add.random = TRUE, ...)

## S3 method for class 'gls'
as_flextable(x, add.random = TRUE, ...)

## S3 method for class 'nlme'
as_flextable(x, add.random = TRUE, ...)

## S3 method for class 'brmsfit'
as_flextable(x, add.random = TRUE, ...)

## S3 method for class 'glmmTMB'
as_flextable(x, add.random = TRUE, ...)

## S3 method for class 'glmmadmb'
as_flextable(x, add.random = TRUE, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

if (require("broom.mixed") && require("nlme")) {
  m1 <- lme(distance ~ age, data = Orthodont)
  ft <- as_flextable(m1)
  ft
}

Description

produce a flextable describing a pam object. The function is only using package 'broom' that provides the data presented in the resulting flextable.

Usage

## S3 method for class 'pam'
as_flextable(x, digits = 4, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

if (require("cluster")) {
  dat <- as.data.frame(scale(mtcars[1:7]))
  cl <- pam(dat, 3)
  ft <- as_flextable(cl)
  ft
}

Description

summarizor object should be transformed into a flextable with method as_flextable().

Usage

## S3 method for class 'summarizor'
as_flextable(x, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

z <- summarizor(CO2[-c(1, 4)],
  by = "Treatment",
  overall_label = "Overall"
)
ft_1 <- as_flextable(z, spread_first_col = TRUE)
ft_1 <- prepend_chunks(ft_1,
  i = ~ is.na(variable), j = 1,
  as_chunk("\t")
)
ft_1 <- autofit(ft_1)
ft_1

Description

produce a flextable describing a count table produced by function table().

This function uses the proc_freq() function.

Usage

## S3 method for class 'table'
as_flextable(x, ...)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.tabular(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

tab <- with(warpbreaks, table(wool, tension))
ft <- as_flextable(tab)
ft

Description

produce a flextable from a TableTree or ElementaryTable object produced with the 'rtables' package.

The conversion uses formatters::matrix_form() to extract the formatted content, column spans, alignments, indentation and footnotes, then maps them to flextable features.

Indentation of row labels is rendered with left padding.

Label rows (LabelRow) are displayed in bold in the first column. Content rows (ContentRow) are displayed entirely in bold.

When LabelRow groups exist, paginate() is applied so that all rows belonging to the same group are kept together on the same page in Word and RTF output.

To paginate the resulting flextable into multiple pages, use split_to_pages(), split_rows(), or split_columns() after calling as_flextable().

Usage

## S3 method for class 'TableTree'
as_flextable(x, indent_padding = 4, ...)

## S3 method for class 'ElementaryTable'
as_flextable(x, indent_padding = 4, ...)

Arguments

Value

a flextable object.

See Also

split_to_pages(), split_rows(), split_columns()

Examples

if (require("rtables", character.only = TRUE, quietly = TRUE)) {
  library(rtables)

  lyt <- basic_table(title = "Demographic Summary") %>%
    split_cols_by("ARM") %>%
    split_rows_by("SEX") %>%
    analyze("AGE", afun = mean, format = "xx.x")

  tbl <- build_table(lyt, DM)
  as_flextable(tbl)
}

Description

Produce a flextable from a 'tabular' object produced with function tables::tabular().

When as_flextable.tabular=TRUE, the first column is used as row separator acting as a row title. It can be formated with arguments fp_p (the formatting properties of the paragraph) and row_title that specifies the content and eventually formattings of the content.

Two hidden columns can be used for conditional formatting after the creation of the flextable (use only when spread_first_col=TRUE):

• The column .row_title that contains the title label

• The column .type that can contain the following values:

  • "one_row": Indicates that there is only one row for this group. In this case, the row is not expanded with a title above.

  • "list_title": Indicates a row that serves as a title for the data that are displayed after it.

  • "list_data": Indicates rows that follow a title and contain data to be displayed.

The result is paginated (see paginate()).

Usage

## S3 method for class 'tabular'
as_flextable(
  x,
  spread_first_col = FALSE,
  fp_p = fp_par(text.align = "center", padding.top = 4),
  row_title = as_paragraph(as_chunk(.row_title)),
  add_tab = FALSE,
  ...
)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabulator(), as_flextable.xtable(), compact_summary()

Examples

if (require("tables")) {
  set.seed(42)
  genders <- c("Male", "Female")
  status <- c("low", "medium", "high")
  Sex <- factor(sample(genders, 100, rep = TRUE))
  Status <- factor(sample(status, 100, rep = TRUE))
  z <- rnorm(100) + 5
  fmt <- function(x) {
    s <- format(x, digits = 2)
    even <- ((1:length(s)) %% 2) == 0
    s[even] <- sprintf("(%s)", s[even])
    s
  }
  tab <- tabular(
    Justify(c) * Heading() * z *
      Sex * Heading(Statistic) *
      Format(fmt()) *
      (mean + sd) ~ Status
  )
  as_flextable(tab)
}

if (require("tables")) {
  tab <- tabular(
    (Species + 1) ~ (n = 1) + Format(digits = 2) *
      (Sepal.Length + Sepal.Width) * (mean + sd),
    data = iris
  )
  as_flextable(tab)
}

if (require("tables")) {
  x <- tabular((Factor(gear, "Gears") + 1)
  * ((n = 1) + Percent()
      + (RowPct = Percent("row"))
      + (ColPct = Percent("col")))
  ~ (Factor(carb, "Carburetors") + 1)
    * Format(digits = 1), data = mtcars)

  ft <- as_flextable(
    x,
    spread_first_col = TRUE,
    row_title = as_paragraph(
      colorize("Gears: ", color = "#666666"),
      colorize(as_b(.row_title), color = "red")
    )
  )
  ft
}

if (require("tables")) {
  tab <- tabular(
    (mean + mean) * (Sepal.Length + Sepal.Width) ~ 1,
    data = iris
  )
  as_flextable(tab)
}

Description

tabulator() object can be transformed as a flextable with method as_flextable().

Usage

## S3 method for class 'tabulator'
as_flextable(
  x,
  separate_with = character(0),
  big_border = fp_border_default(width = 1.5),
  small_border = fp_border_default(width = 0.75),
  rows_alignment = "left",
  columns_alignment = "center",
  label_rows = x$rows,
  spread_first_col = FALSE,
  expand_single = FALSE,
  sep_w = 0.05,
  unit = "in",
  ...
)

Arguments

See Also

summarizor(), as_grouped_data()

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.xtable(), compact_summary()

Examples

## Not run: 
library(flextable)

set_flextable_defaults(digits = 2, border.color = "gray")

if (require("stats")) {
  dat <- aggregate(breaks ~ wool + tension,
    data = warpbreaks, mean
  )

  cft_1 <- tabulator(
    x = dat,
    rows = "wool",
    columns = "tension",
    `mean` = as_paragraph(as_chunk(breaks)),
    `(N)` = as_paragraph(
      as_chunk(length(breaks))
    )
  )

  ft_1 <- as_flextable(cft_1, sep_w = .1)
  ft_1
}

if (require("stats")) {
  set_flextable_defaults(
    padding = 1, font.size = 9,
    border.color = "orange"
  )

  ft_2 <- as_flextable(cft_1, sep_w = 0)
  ft_2
}

if (require("stats")) {
  set_flextable_defaults(
    padding = 6, font.size = 11,
    border.color = "white",
    font.color = "white",
    background.color = "#333333"
  )

  ft_3 <- as_flextable(
    x = cft_1, sep_w = 0,
    rows_alignment = "center",
    columns_alignment = "right"
  )
  ft_3
}

init_flextable_defaults()

## End(Not run)

Description

Get a flextable object from a xtable object.

Usage

## S3 method for class 'xtable'
as_flextable(
  x,
  text.properties = fp_text_default(),
  format.args = getOption("xtable.format.args", NULL),
  rowname_col = "rowname",
  hline.after = getOption("xtable.hline.after", c(-1, 0, nrow(x))),
  NA.string = getOption("xtable.NA.string", ""),
  include.rownames = TRUE,
  rotate.colnames = getOption("xtable.rotate.colnames", FALSE),
  ...
)

Arguments

See Also

Other as_flextable methods: as_flextable.compact_summary(), as_flextable.data.frame(), as_flextable.gam(), as_flextable.glm(), as_flextable.grouped_data(), as_flextable.htest(), as_flextable.kmeans(), as_flextable.lm(), as_flextable.merMod(), as_flextable.pam(), as_flextable.summarizor(), as_flextable.table(), as_flextable.tabular(), as_flextable.tabulator(), compact_summary()

Examples

library(officer)
if( require("xtable") ){

  data(tli)
  tli.table <- xtable(tli[1:10, ])
  align(tli.table) <- rep("r", 6)
  align(tli.table) <- "|r|r|clr|r|"
  ft_1 <- as_flextable(
    tli.table,
    rotate.colnames = TRUE,
    include.rownames = FALSE)
  ft_1 <- height(ft_1, i = 1, part = "header", height = 1)
  ft_1

  
  Grade3 <- c("A","B","B","A","B","C","C","D","A","B",
    "C","C","C","D","B","B","D","C","C","D")
  Grade6 <- c("A","A","A","B","B","B","B","B","C","C",
    "A","C","C","C","D","D","D","D","D","D")
  Cohort <- table(Grade3, Grade6)
  ft_2 <- as_flextable(xtable(Cohort))
  ft_2 <- set_header_labels(ft_2, rowname = "Grade 3")
  ft_2 <- autofit(ft_2)
  ft_2 <- add_header(ft_2, A = "Grade 6")
  ft_2 <- merge_at(ft_2, i = 1, j = seq_len( ncol(Cohort) ) + 1,
    part = "header" )
  ft_2 <- bold(ft_2, j = 1, bold = TRUE, part = "body")
  ft_2 <- height_all(ft_2, part = "header", height = .4)
  ft_2

  temp.ts <- ts(cumsum(1 + round(rnorm(100), 0)),
    start = c(1954, 7), frequency = 12)
  ft_3 <- as_flextable(x = xtable(temp.ts, digits = 0),
    NA.string = "-")
  ft_3
  
  detach("package:xtable", unload = TRUE)
}

Description

Repeated consecutive values of group columns will be used to define the title of the groups and will be added as a row title.

Usage

as_grouped_data(x, groups, columns = NULL, expand_single = TRUE)

Arguments

See Also

as_flextable.grouped_data()

Examples

# as_grouped_data -----
library(data.table)
CO2 <- CO2
setDT(CO2)
CO2$conc <- as.integer(CO2$conc)

data_co2 <- dcast(CO2, Treatment + conc ~ Type,
  value.var = "uptake", fun.aggregate = mean
)
data_co2
data_co2 <- as_grouped_data(x = data_co2, groups = c("Treatment"))
data_co2

Description

The function is producing a chunk with an highlight chunk.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

Usage

as_highlight(x, color)

Arguments

See Also

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_equation(), as_i(), as_image(), as_qmd(), as_strike(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

ft <- flextable(head(iris),
  col_keys = c("Sepal.Length", "dummy")
)

ft <- compose(ft,
  j = "dummy",
  value = as_paragraph(as_highlight(Sepal.Length, color = "yellow"))
)

ft

Description

The function is producing a chunk with italic font.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

Usage

as_i(x)

Arguments

See Also

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_equation(), as_highlight(), as_image(), as_qmd(), as_strike(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

ft <- flextable(head(iris),
  col_keys = c("Sepal.Length", "dummy")
)

ft <- compose(ft,
  j = "dummy",
  value = as_paragraph(as_i(Sepal.Length))
)

ft

Description

The function lets add images within flextable objects with functions:

• compose() and as_paragraph(),

• append_chunks(),

• prepend_chunks()

Usage

as_image(
  src,
  width = NULL,
  height = NULL,
  unit = "in",
  guess_size = TRUE,
  alt = "",
  ...
)

Arguments

Note

This chunk option requires package officedown in a R Markdown context with Word output format.

PowerPoint cannot mix images and text in a paragraph, images are removed when outputing to PowerPoint format.

See Also

compose(), as_paragraph()

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_equation(), as_highlight(), as_i(), as_qmd(), as_strike(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

img.file <- file.path(
  R.home("doc"),
  "html", "logo.jpg"
)
if (require("magick")) {
  myft <- flextable(head(iris))
  myft <- compose(myft,
    i = 1:3, j = 1,
    value = as_paragraph(
      as_image(src = img.file),
      " ",
      as_chunk(Sepal.Length,
        props = fp_text_default(color = "red")
      )
    ),
    part = "body"
  )
  ft <- autofit(myft)
  ft
}

Description

as_paragraph() assembles one or more chunks into a single paragraph that defines the content of a flextable cell. Each cell in a flextable contains exactly one paragraph; a paragraph is an ordered sequence of chunks.

Chunks are the smallest content units and can be created with as_chunk() (formatted text), as_b() / as_i() (bold / italic shortcuts), minibar() (inline bar), as_image() (image), gg_chunk() (ggplot), as_equation() (equation) or hyperlink_text() (link). Plain character strings passed to as_paragraph() are automatically converted to chunks via as_chunk().

The resulting paragraph is passed to the value argument of compose(), mk_par(), add_header_lines(), add_footer_lines() or footnote() to set cell content.

Usage

as_paragraph(..., list_values = NULL)

Arguments

See Also

as_chunk(), minibar(), as_image(), hyperlink_text()

Other functions to compose cell content: append_chunks(), compose(), footnote(), labelizor(), prepend_chunks(), void()

Examples

library(flextable)
ft <- flextable(airquality[sample.int(150, size = 10), ])
ft <- compose(ft,
  j = "Wind",
  value = as_paragraph(
    as_chunk(Wind, props = fp_text_default(color = "orange")),
    " ",
    minibar(value = Wind, max = max(airquality$Wind), barcol = "orange", bg = "black", height = .15)
  ),
  part = "body"
)
ft <- autofit(ft)
ft

Description

as_qmd() creates a chunk for inline Quarto markdown content (text-level) that fits within a table cell paragraph. This enables cross-references (⁠@fig-xxx⁠, ⁠@tbl-xxx⁠), links, bold/italic, math, inline code, shortcodes and other inline Quarto markdown features inside flextable cells.

It is not designed for block-level elements such as headings, bullet lists or fenced code blocks.

The chunk is used with compose(), append_chunks() or prepend_chunks(). It requires the flextable-qmd Lua filter extension (see use_flextable_qmd()) and works with HTML, PDF and Word (docx) Quarto output formats.

Usage

as_qmd(x, display = x)

Arguments

Setup

1. Install the extension once per project:

flextable::use_flextable_qmd()

1. Add the filter to your Quarto document YAML. For HTML and PDF, a single line is enough:

filters:
  - flextable-qmd

For Word (docx), an additional post-render filter removes the wrapper table that Quarto adds around labelled flextables:

filters:
  - flextable-qmd
  - at: post-render
    path: _extensions/flextable-qmd/unwrap-float.lua

Supported markdown

• Cross-references: ⁠@fig-xxx⁠, ⁠@tbl-xxx⁠

• Bold / italic: ⁠**bold**⁠, ⁠*italic*⁠

• Inline code: `code`

• Links: ⁠[text](url)⁠ (internal and external)

• Math: ⁠$\\alpha + \\beta$⁠

• Shortcodes and other Quarto markdown constructs

Limitations

Each table cell in a flextable contains a single paragraph built from inline chunks (see as_paragraph()). There is no mechanism to insert block-level structures (multiple paragraphs, lists, headings, fenced code blocks, callouts, etc.) inside a cell. Because as_qmd() produces one of these inline chunks, only inline markdown is supported.

See Also

use_flextable_qmd() to install the Lua filter extension, knit_print.flextable() for rendering options in knitr documents.

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_equation(), as_highlight(), as_i(), as_image(), as_strike(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

library(flextable)

dat <- data.frame(
  label = c("Bold", "Link", "Code"),
  content = c(
    "This is **bold** text",
    "Visit [Quarto](https://quarto.org)",
    "Use `print()` here"
  )
)
ft <- flextable(dat)
ft <- mk_par(ft, j = "content",
  value = as_paragraph(as_qmd(content)))
ft

Description

The function is producing a chunk with strikethrough font.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

Usage

as_strike(x)

Arguments

See Also

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_equation(), as_highlight(), as_i(), as_image(), as_qmd(), as_sub(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

ft <- flextable(head(iris),
  col_keys = c("Sepal.Length", "dummy")
)

ft <- compose(ft,
  j = "dummy",
  value = as_paragraph(
    as_strike(Sepal.Length)
  )
)

ft

Description

The function is producing a chunk with subscript vertical alignment.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

Usage

as_sub(x)

Arguments

See Also

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_equation(), as_highlight(), as_i(), as_image(), as_qmd(), as_strike(), as_sup(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

ft <- flextable(head(iris), col_keys = c("dummy"))

ft <- compose(ft,
  i = 1, j = "dummy", part = "header",
  value = as_paragraph(
    as_sub("Sepal.Length"),
    " anything "
  )
)

ft <- autofit(ft)
ft

Description

The function is producing a chunk with superscript vertical alignment.

It is used to add it to the content of a cell of the flextable with the functions compose(), append_chunks() or prepend_chunks().

Usage

as_sup(x)

Arguments

Note

This is a sugar function that ease the composition of complex labels made of different formattings. It should be used inside a call to as_paragraph().

See Also

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_equation(), as_highlight(), as_i(), as_image(), as_qmd(), as_strike(), as_sub(), as_word_field(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

ft <- flextable(head(iris), col_keys = c("dummy"))

ft <- compose(ft,
  i = 1, j = "dummy", part = "header",
  value = as_paragraph(
    " anything ",
    as_sup("Sepal.Width")
  )
)

ft <- autofit(ft)
ft

Description

as_word_field() inserts a Word field code (e.g. page numbers, dates, cross-references) as a chunk inside a flextable cell. Field codes are Word's mechanism for auto-computed values; see Microsoft's field-code reference for the available codes.

The chunk is used with compose(), append_chunks() or prepend_chunks(). It only has an effect in Word (docx) output; other formats ignore it. To apply it conditionally, use the post-processing step (see set_flextable_defaults(post_process_docx = ...)).

Important: fields are inserted but not computed. After opening the document in Word, select all text and press F9 (on macOS: Fn + F9) to refresh the field values.

Usage

as_word_field(x, props = NULL, width = 0.1, height = 0.15, unit = "in")

Arguments

See Also

Other chunk elements for paragraph: as_b(), as_bracket(), as_chunk(), as_equation(), as_highlight(), as_i(), as_image(), as_qmd(), as_strike(), as_sub(), as_sup(), colorize(), gg_chunk(), grid_chunk(), hyperlink_text(), linerange(), minibar(), plot_chunk()

Examples

library(flextable)

# define some default values ----
set_flextable_defaults(font.size = 22, border.color = "gray")

# an example with append_chunks ----
pp_docx <- function(x) {
  x <- add_header_lines(x, "Page ")
  x <- append_chunks(
    x = x, i = 1, part = "header", j = 1,
    as_word_field(x = "Page")
  )
  align(x, part = "header", align = "left")
}
ft_1 <- flextable(cars)
ft_1 <- autofit(ft_1)
ft_1 <- pp_docx(ft_1)

## or:
# set_flextable_defaults(post_process_docx = pp_docx)
## to prevent this line addition when output is not docx

# print(ft_1, preview = "docx")

# an example with compose ----

library(officer)
ft_2 <- flextable(head(cars))
ft_2 <- add_footer_lines(ft_2, "temp text")
ft_2 <- compose(
  x = ft_2, part = "footer", i = 1, j = 1,
  as_paragraph(
    "p. ",
    as_word_field(x = "Page", width = .05),
    " on ", as_word_field(x = "NumPages", width = .05)
  )
)
ft_2 <- autofit(ft_2, part = c("header", "body"))

doc <- read_docx()
doc <- body_add_flextable(doc, ft_2)
doc <- body_add_break(doc)
doc <- body_add_flextable(doc, ft_2)
outfile <- print(doc, target = tempfile(fileext = ".docx"))

# reset default values ----
init_flextable_defaults()

Description

Compute and apply the minimum widths and heights needed to display each cell's content on a single line, with an optional extra margin (add_w, add_h).

This function sizes columns to fit their content. It does not constrain the table to a given total width. To enforce a maximum width, use fit_columns() (wraps text) or fit_to_width() (shrinks font size).

Note that this function is not related to 'Microsoft Word' Autofit feature.

There is an alternative to fixed-width layouts that works well with HTML and Word output that can be set with set_table_properties(layout = "autofit"), see set_table_properties().

Usage

autofit(
  x,
  add_w = 0.1,
  add_h = 0.1,
  part = c("body", "header"),
  unit = "in",
  hspans = "none"
)

Arguments

See Also

Other functions for flextable size management: dim.flextable(), dim_pretty(), fit_columns(), fit_to_width(), flextable_dim(), height(), hrule(), ncol_keys(), nrow_part(), set_table_properties(), width()

Examples

ft_1 <- flextable(head(mtcars))
ft_1
ft_2 <- autofit(ft_1)
ft_2

Description

Returns a logical vector indicating which elements of x appear before the first occurrence of any of the entries values. Useful as a row selector in hline() to insert a border above a summary row such as "Total".

Usage

before(x, entries)

Arguments

See Also

hline()

Examples

library(flextable)
library(officer)

dat <- data.frame(
  stringsAsFactors = FALSE,
  check.names = FALSE,
  Level = c("setosa", "versicolor", "virginica", "<NA>", "Total"),
  Freq = as.integer(c(50, 50, 50, 0, 150)),
  `% Valid` = c(
    100 / 3,
    100 / 3, 100 / 3, NA, 100
  ),
  `% Valid Cum.` = c(100 / 3, 100 * 2 / 3, 100, NA, 100),
  `% Total` = c(
    100 / 3,
    100 / 3, 100 / 3, 0, 100
  ),
  `% Total Cum.` = c(
    100 / 3,
    100 * 2 / 3, 100, 100, 100
  )
)

ft <- flextable(dat)
ft <- hline(ft,
  i = ~ before(Level, "Total"),
  border = fp_border_default(width = 2)
)
ft

Description

Change the background color of selected rows and columns of a flextable. A function can be used instead of fixed colors.

When bg is a function, it is possible to color cells based on values located in other columns; using hidden columns (those not used by argument colkeys) is a common use case. The argument source must be used to define the columns to be used for the color definition, and the argument j must be used to define where to apply the colors and only accepts values from colkeys.

Usage

bg(x, i = NULL, j = NULL, bg, part = "body", source = j)

Arguments

Note

Word does not allow you to apply transparency to table cells or paragraph shading.

See Also

Other formatting shortcuts: align(), bold(), color(), empty_blanks(), font(), fontsize(), highlight(), italic(), keep_with_next(), line_spacing(), padding(), rotate(), style(), tab_settings(), valign()

Examples

ft_1 <- flextable(head(mtcars))
ft_1 <- bg(ft_1, bg = "wheat", part = "header")
ft_1 <- bg(ft_1, i = ~ qsec < 18, bg = "#EFEFEF", part = "body")
ft_1 <- bg(ft_1, j = "drat", bg = "#606060", part = "all")
ft_1 <- color(ft_1, j = "drat", color = "white", part = "all")
ft_1

if (require("scales")) {
  ft_2 <- flextable(head(iris))
  colourer <- col_numeric(
    palette = c("wheat", "red"),
    domain = c(0, 7)
  )
  ft_2 <- bg(ft_2,
    j = c(
      "Sepal.Length", "Sepal.Width",
      "Petal.Length", "Petal.Width"
    ),
    bg = colourer, part = "body"
  )
  ft_2
}

Description

Add a flextable into a Word document created with 'officer'.

Usage

body_add_flextable(
  x,
  value,
  align = NULL,
  pos = "after",
  split = NULL,
  topcaption = TRUE,
  keepnext = NULL
)

Arguments

Details

Use the paginate() function to define whether the table should be displayed on one or more pages, and whether the header should be displayed with the first lines of the table body on the same page.

Use the set_caption() function to define formatted captions (with as_paragraph()) or simple captions (with a string). topcaption can be used to insert the caption before the table (default) or after the table (use FALSE).

See Also

knit_print.flextable(), save_as_docx()

Other functions for officer integration: body_replace_flextable_at_bkm(), ph_with.flextable(), rtf_add.flextable()

Examples

library(officer)

# define global settings
set_flextable_defaults(
  split = TRUE,
  table_align = "center",
  table.layout = "autofit"
)

# produce 3 flextable
ft_1 <- flextable(head(airquality, n = 20))
ft_1 <- color(ft_1, i = ~ Temp > 70, color = "red", j = "Temp")
ft_1 <- highlight(ft_1, i = ~ Wind < 8, color = "yellow", j = "Wind")
ft_1 <- set_caption(
  x = ft_1,
  autonum = run_autonum(seq_id = "tab"),
  caption = "Daily air quality measurements"
)
ft_1 <- paginate(ft_1, init = TRUE, hdr_ftr = TRUE)

ft_2 <- proc_freq(mtcars, "vs", "gear")
ft_2 <- set_caption(
  x = ft_2,
  autonum = run_autonum(seq_id = "tab", bkm = "mtcars"),
  caption = as_paragraph(
    as_b("mtcars"), " ",
    colorize("table", color = "orange")
  ),
  fp_p = fp_par(keep_with_next = TRUE)
)
ft_2 <- paginate(ft_2, init = TRUE, hdr_ftr = TRUE)

ft_3 <- summarizor(iris, by = "Species")
ft_3 <- as_flextable(ft_3, spread_first_col = TRUE)
ft_3 <- set_caption(
  x = ft_3,
  autonum = run_autonum(seq_id = "tab"),
  caption = "iris summary"
)
ft_3 <- paginate(ft_3, init = TRUE, hdr_ftr = TRUE)

# add the 3 flextable in a new Word document
doc <- read_docx()
doc <- body_add_flextable(doc, value = ft_1)
doc <- body_add_par(doc, value = "")
doc <- body_add_flextable(doc, value = ft_2)
doc <- body_add_par(doc, value = "")
doc <- body_add_flextable(doc, value = ft_3)

fileout <- tempfile(fileext = ".docx")
print(doc, target = fileout)

Description

Use this function if you want to replace a paragraph containing a bookmark with a flextable. As a side effect, the bookmark will be lost.

Usage

body_replace_flextable_at_bkm(
  x,
  bookmark,
  value,
  align = "center",
  split = FALSE
)

Arguments

See Also

Other functions for officer integration: body_add_flextable(), ph_with.flextable(), rtf_add.flextable()

Description

Change the font weight of selected rows and columns of a flextable.

Usage

bold(x, i = NULL, j = NULL, bold = TRUE, part = "body")

Arguments

See Also

Other formatting shortcuts: align(), bg(), color(), empty_blanks(), font(), fontsize(), highlight(), italic(), keep_with_next(), line_spacing(), padding(), rotate(), style(), tab_settings(), valign()

Examples

ft <- flextable(head(iris))
ft <- bold(ft, bold = TRUE, part = "header")

Description

The function is applying a vertical and horizontal borders to inner content of one or all parts of a flextable.

Usage

border_inner(x, border = NULL, part = "all")

Arguments

See Also

Other borders management: border_inner_h(), border_inner_v(), border_outer(), border_remove(), hline(), hline_bottom(), hline_top(), surround(), vline(), vline_left(), vline_right()

Examples

library(officer)
std_border <- fp_border(color = "orange", width = 1)

dat <- iris[c(1:5, 51:55, 101:105), ]
ft <- flextable(dat)
ft <- border_remove(x = ft)

# add inner vertical borders
ft <- border_inner(ft, border = std_border)
ft

Description

The function is applying a border to inner content of one or all parts of a flextable.

Usage

border_inner_h(x, border = NULL, part = "body")

Arguments

See Also

Other borders management: border_inner(), border_inner_v(), border_outer(), border_remove(), hline(), hline_bottom(), hline_top(), surround(), vline(), vline_left(), vline_right()

Examples

library(officer)
std_border <- fp_border(color = "orange", width = 1)

dat <- iris[c(1:5, 51:55, 101:105), ]
ft <- flextable(dat)
ft <- border_remove(x = ft)

# add inner horizontal borders
ft <- border_inner_h(ft, border = std_border)
ft