About me

Why flextable?

• Tables, just like graphs, can be a very good way to provide synthetic and clear information.

• They are easy to read by our public.

• They must be easy to produce from R.

• My customers always ask for nice tables, in Word, PowerPoint or HTML (not so much for PDF).

Package overview

History

A first example

flextable(airquality[ sample.int(5),]) %>% 
  add_header_row(colwidths = c(4, 2), values = c("Air quality", "Time")) %>% 
  theme_vanilla() %>% 
  add_footer_lines("Daily measurements in New York, May to September 1973.") %>% 
  color(part = "footer", color = "#666666") %>% 
  set_caption(caption = "New York Air Quality Measurements")

New York Air Quality Measurements

Parts of a flextable

A flextable is composed of 3 parts:

Columns to display

dat <- head(airquality, n = 3)
flextable(dat)

flextable(data = dat, 
 col_keys = c("Ozone", "Temp", 
              "Month", "Day"))

flextable(data = dat, 
 col_keys = c("Month", "Day", 
              "dummy", "Ozone"))

Selectors

ft <- flextable(dat)
ft %>% 
  color(
    i = ~ Ozone < 40,
    j = c("Ozone", "Solar.R"),
    color = "orange")

Cell content

By default, the cells of the flextable are filled with the content of the data.frame cells.

ft <- flextable(dat)
ft

ft <- colformat_double(ft, digits = 2) %>% 
  colformat_int(prefix = "#") 
ft

Cell with multi-content

The cells of the flextable are filled with more than a content.

ft <- flextable(dat, 
  col_keys = c("Month", "Day", "Solar.R"))
ft <- compose(ft, 
  j = "Solar.R",
  value = as_paragraph(
    Solar.R, " (", as_b(Ozone), ")"
  )
)
ft

ft <- compose(ft, 
  j = "Solar.R", i = 1, part = "header",
  value = as_paragraph(
    as_i("Solar"), " ",
    colorize(as_sup("R"), "red"))
)
ft

As flextable

Function as_flextable is a generic function to cast objects into flextable.

So far, this method exist for objects lm, glm, mgcv::gam, xtable, htest, as_grouped_data.

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

Header labels

This is the bottom row of the header part (or the only row by default).

ft <- flextable(head(airquality), 
  col_keys = c("Month", "Day", "Solar.R")) %>% 
  set_header_labels(Solar.R = "Solar R (lang)")
ft

Set default values to ease your work

The default formatting properties (see get_flextable_defaults()) are automatically applied to every flextable you produce. Use set_flextable_defaults() to override them. Use init_flextable_defaults() to re-init all values with the package defaults.

set_flextable_defaults(font.size = 10, 
  padding = 5, 
  font.family = "Arial", 
  na_str = "", 
  # eastasia.family =
  post_process_html = function(x){
    x <- theme_booktabs(x)
    autofit(x, part = "body")
  })
ft <- flextable(head(airquality), 
  col_keys = c("Month", "Day", "Solar.R")) %>% 
  set_header_labels(
    Solar.R = "Solar R (lang)")

Add more rows

ft <- flextable(head(airquality))

ft <- add_header_row(
  x = ft, 
  values = c("measurements", "time"),
  colwidths = c(4, 2))

Sugar function: add lines

ft <- add_header_lines(ft,
  values = c(
    "this is a first line",
    "this is a second line"
  )
)

Hidden statistics of Mario Kart characters?

In Mario Kart 8 Deluxe on Switch, each character has its own set of statistics, but unlike karts and customization elements, they are not displayed directly on the screen.

Characters all have their own very precise statistics: speed (different according to the environment), maneuverability, power of mini-turbos, absolute speed, ...

These parameters are rated out of 6 and have been listed by the community of fans of the game.

We will use flextable to present the detail of these statistics by characters.

Data are available here: https://docs.google.com/spreadsheets/d/1g7A-38tn9UAIbB2B3sZI-MpILsS3ZS870UTVMRRxh4Q/edit#gid=0

Expected result

The flextable code

Open codes/mario.R

With officer technology

Inserting a flextable in a document can be done in different ways:

• For Word, use flextable::body_add_flextable() function.

• For PowerPoint, use officer::ph_with() function.

read_docx() %>% 
  body_add_flextable(ft) %>%
  print(target = "reports/mario-officer.docx")
read_pptx() %>% 
  add_slide() %>% 
  ph_with(ft, location = ph_location_type()) %>%
  print(target = "reports/mario-officer.pptx")

Easy exportation

save_as_docx(ft, path = "reports/mario.docx",
 pr_section = prop_section(
  page_size = page_size(
    width = 15, height = 11, 
    orient = "landscape"),
  type = "continuous"))
save_as_pptx(ft, path = "reports/mario.pptx")
# print(ft, preview = "pptx")

plot(ft)

With "R Markdown" technology

Usual way:

ft <- qflextable( head( airquality ))
ft

Loops

[...] for, while, and repeat loops always return an invisible NULL, so nothing will be printed automatically [...]
https://yihui.org/en/2017/06/top-level-r-expressions/

Use chunk option results='asis' and function flextable_to_rmd:

for(i in seq_along(ft_list)){
  flextable_to_rmd(ft_list[[i]])
}

Documentation

User guide: https://ardata-fr.github.io/flextable-book/

Cross-references and captions

Captions are supported for HTML, PDF and Word output (also from a bookdown project with its specificities taken into account).

The recommended method to set a caption is with function set_caption.

ft <- set_caption(ft, "a correlation matrix", 
  autonum = run_autonum(seq_id = "tab", 
                        bkm = "corr-table"))

But the knitr chunk options can be use instead:

• tab.cap: Caption label
• tab.id or label: Caption reference unique identifier, the latest is for compliance with bookdown syntax.

https://ardata-fr.github.io/flextable-book/captions-and-cross-references.html

PDF output

flextable supported outputs were HTML, Word and PowerPoint. This has just been extended to PDF.

• Overall is good
• Need some work with widths and heights management
• No issues about that, it's not yet used by users

Less verbose is cool

• set_flextable_defaults() should let you to not use font, fontsize, padding, colformat_double, etc.

• compose gained argument use_dot: when using as_paragraph, value is evaluated within a data.frame augmented of a column named . containing the jth column.

gg_bars <- function(z) {
  z <- na.omit(scale(z))
  z <- data.frame(x = seq_along(z), z = z, w = z < 0)
  ggplot(z, aes(x = x, y = z, fill = w)) +
    geom_col(show.legend = FALSE) + theme_void()
}
dat <- as.data.table(mtcars)
z <- dat[,
  lapply(.SD, function(x) list(gg_bars(x))),
  by = c("vs", "am"), 
  .SDcols = c("mpg", "disp")
]
ft <- flextable(z)

compose(ft, 
  j = c("mpg", "disp"),
  value = as_paragraph(
    gg_chunk(value = .,
             height = .15, width = 1)
  ),
  use_dot = TRUE
)

Use flextable as default table output

See https://cran.r-project.org/web/packages/knitr/vignettes/knit_print.html

table_print = function(x, ...) {
  flextable(x) %>% theme_vanilla()
}
# register the method
registerS3method("knit_print", "data.frame", table_print)
registerS3method("knit_print", "grouped_df", table_print)
registerS3method("knit_print", "spec_tbl_df", table_print)
registerS3method("knit_print", "tbl", table_print)

Miscellaneous

set_flextable_defaults(
  font.family="Arial", 
  cs.family = "Symbol", 
  eastasia.family = "仿宋")
df = data.frame(
  `标题Title`='微软MS',
  `内容Content`='无题lorem',
  stringsAsFactors = FALSE)
print(flextable(df), preview = "docx")

Tabular packages with flextable output

• ftExtra: https://cran.r-project.org/package=ftExtra

• flexpivot: https://dreamrs.github.io/flexpivot/

• gtsummary: http://www.danieldsjoberg.com/gtsummary/

• crosstable: https://CRAN.R-project.org/package=crosstable

• compareGroups: https://CRAN.R-project.org/package=compareGroups

• ...

Maintenance and support

Using the package, questions and help: https://stackoverflow.com/questions/tagged/flextable

Found a bug, feature request: https://github.com/davidgohel/flextable/issues

• Questions from users: documentation will be completed

• Bugs: fix them - usually fixed within a month

• Evolutions: if possible, no time commitment