Package flextable. September 5, 2017

Transcription

1 Type Package Title Functions for Tabular Reporting Version Package fletable September 5, 2017 Create pretty tables for 'Microsoft Word', 'Microsoft PowerPoint' and 'HTML' documents. Functions are provided to let users create tables, modify and format their content. It etends package 'officer' that does not contain any feature for customized tabular reporting. Function tabwid() produces an 'htmlwidget' ready to be used in 'Shiny' or 'R Markdown (*.Rmd)' documents. License GPL-3 LazyData TRUE Depends officer Imports stats,utils,grdevices,magrittr, lazyeval,purrr,tibble,r6,stringr, htmltools,htmlwidgets, gdtools (>= 0.1.6) RoygenNote Suggests rmarkdown, knitr, ml2, dplyr, testthat URL BugReports VignetteBuilder knitr NeedsCompilation no Author David Gohel [aut, cre] Maintainer David Gohel Repository CRAN Date/Publication :56:54 UTC R topics documented: add_header align

2 2 add_header as_image autofit bg body_add_fletable bold border color dim.fletable dim_pretty display empty_blanks fletable fontsize height italic merge_at merge_h merge_none merge_v minibar padding ph_with_fletable rotate set_formatter set_header_df set_header_labels style tabwid tabwid-shiny theme_booktabs theme_bo theme_tron theme_tron_legacy theme_vanilla theme_zebra void width Inde 27 add_header Add a row of labels in headers Add a single row of labels in the fletable s header. It can be inserted at the top or the bottom of header.

3 align 3 add_header(, top = TRUE,...) top Details a fletable object should the row be inserted at the top or the bottom.... a named list (names are data colnames) of strings specifying corresponding labels to add. An horizontal and a vertical merge are performed automatically. Use merge_none to drop theses merging instructions. Eamples ft <- fletable( head( iris ), col_keys = c("species", "Sepal.Length", "Petal.Length", "Sepal.Width", "Petal.Width") ) ft <- add_header( = ft, Sepal.Length = "length", Sepal.Width = "width", Petal.Length = "length", Petal.Width = "width", Species = "Species", top = FALSE ) ft <- add_header(ft, Sepal.Length = "Inches", Sepal.Width = "Inches", Petal.Length = "Inches", Petal.Width = "Inches", Species = "Species", top = TRUE ) ft <- merge_h(ft, = "header") ft align Set tet alignment change tet alignment of selected rows and columns of a fletable. align(, i = NULL, j = NULL, align = "left", = "body") i j align a fletable object rows selection columns selection tet alignment - a single character value, epected value is one of left, right, center, justify. name of the table (one of all, body, header )

4 4 as_image Eamples ft <- fletable(mtcars) ft <- align(ft, align = "center") as_image image wrapper The function has to be used with function display(). It lets add images within fletable. as_image(, src, width = 1, height = 0.2) src width, height image will be repeated while iterating this variable. The variable should be one of the original data frame. Note its values are not used, only its size. image filename size of the png file in inches See Also display Eamples library(magrittr) img.file <- file.path( Sys.getenv("R_HOME"), "doc", "html", "logo.jpg" ) myft <- fletable(head( mtcars, n = 10)) myft <- myft %>% display( i = ~ qsec > 18, col_key = "qsec", pattern = "{{r_logo}}", formatters = list( r_logo ~ as_image(qsec, src = img.file, width =.20, height =.15)), fprops = list(qsec = fp_tet(color = "orange")) ) myft

5 autofit 5 autofit Adjusts cell widths and heights compute and apply optimized widths and heights. autofit(, add_w = 0.1, add_h = 0.1) add_w add_h fletable object etra width to add in inches etra height to add in inches Eamples ft <- fletable(mtcars) ft <- autofit(ft) ft bg Set background color change background color of selected rows and columns of a fletable. bg(, i = NULL, j = NULL, bg, = "body") i j bg a fletable object rows selection columns selection color to use as background color name of the table (one of all, body, header ) Eamples ft <- fletable(mtcars) ft <- bg(ft, bg = "#DDDDDD", = "header")

6 6 bold body_add_fletable wml table code produces the wml of a fletable body_add_fletable(, value, align = "center", pos = "after") value align pos a doc object fletable object left (default), center or right. where to add the fletable relative to the cursor, one of "after", "before", "on" (end of line). Eamples library(officer) ft <- fletable(head(mtcars)) ft <- theme_zebra(ft) ft <- autofit(ft) doc <- read_doc() doc <- body_add_fletable(doc, value = ft) print(doc, target = "test.doc") bold Set bold font change font weight of selected rows and columns of a fletable. bold(, i = NULL, j = NULL, bold = TRUE, = "body") i j bold a fletable object rows selection columns selection boolean value name of the table (one of all, body, header )

7 border 7 Eamples ft <- fletable(mtcars) ft <- bold(ft, bold = TRUE, = "header") border Set cell borders change borders of selected rows and columns of a fletable. border(, i = NULL, j = NULL, border = NULL, border.top = NULL, border.bottom = NULL, border.left = NULL, border.right = NULL, = "body") i j border border.top border.bottom border.left border.right a fletable object rows selection columns selection border (shortcut for top, bottom, left and right) border top border bottom border left border right name of the table (one of all, body, header ) Eamples ft <- fletable(mtcars) ft <- border(ft, border.top = fp_border(color = "orange") )

8 8 dim.fletable color Set font color change font color of selected rows and columns of a fletable. color(, i = NULL, j = NULL, color, = "body") i j color a fletable object rows selection columns selection color to use as font color name of the table (one of all, body, header ) Eamples ft <- fletable(mtcars) ft <- color(ft, color = "orange", = "header") dim.fletable Get fletable dimensions returns widths and heights for each table columns and rows. ## S3 method for class 'fletable' dim() fletable object

9 dim_pretty 9 dim_pretty Calculate pretty dimensions return minimum estimated widths and heights for each table columns and rows. dim_pretty() fletable object Eamples ft <- fletable(mtcars) dim_pretty(ft) display Define fletable displayed values Modify fletable displayed values by specifying a string epression. Function is handling comple formatting as well as image insertion. display(, i = NULL, col_key, pattern, formatters = list(), fprops = list(), = "body") i col_key pattern formatters fprops a fletable object rows selection column to modify, a single character string to format a list of formula, left side for the name, right side for the content. a named list of fp_tet name of the table (one of all, body, header )

10 10 empty_blanks Eamples # Formatting data values eample library(magrittr) ft <- fletable(head( mtcars, n = 10)) ft <- display(ft, col_key = "carb", i = ~ drat > 3.5, pattern = "# {{carb}}", formatters = list(carb ~ sprintf("%.1f", carb)), fprops = list(carb = fp_tet(color="orange") ) ) ft <- autofit(ft) empty_blanks make blank columns as transparent blank columns are set as transparent. This is a shortcut function that will delete top and bottom borders, change background color to transparent and display empty content. empty_blanks() a fletable object Eamples library(magrittr) typology <- data.frame( col_keys = c( "Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", "Species" ), what = c("sepal", "Sepal", "Petal", "Petal", " "), measure = c("length", "Width", "Length", "Width", "Species"), stringsasfactors = FALSE ) typology head(iris) %>% fletable( col_keys = c("species", "break1", "Sepal.Length", "Sepal.Width", "break2", "Petal.Length", "Petal.Width") ) %>% set_header_df(mapping = typology, key = "col_keys" ) %>% merge_h( = "header") %>% theme_vanilla() %>% empty_blanks() %>% width(j = c(2, 5), width =.1 )

11 fletable 11 fletable fletable creation Create a fletable object with function fletable. fletable are designed to make tabular reporting easier for R users. Functions are available to let you format tet, paragraphs and cells; table cells can be merge vertically or horizontally, row headers can easilly be defined, rows heights and columns widths can be manually set or automatically computed. fletable(data, col_keys = names(data), cwidth = 0.75, cheight = 0.25) ## S3 method for class 'fletable' print(, preview = "html",...) regulartable(data, col_keys = names(data), cwidth = 0.75, cheight = 0.25) data col_keys dataset columns names/keys to display. If some column names are not in the dataset, they will be added as blank columns by default. cwidth, cheight initial width and height to use for cell sizes. preview fletable object... unused argument preview type, one of c("html", "ppt", "doc"). Details A fletable is made of 2 s: header and body. Most functions have an argument named that will be used to specify what of of the table should be modified. Eamples ft <- fletable(mtcars) ft

12 12 height fontsize Set font size change font size of selected rows and columns of a fletable. fontsize(, i = NULL, j = NULL, size = 11, = "body") i j size a fletable object rows selection columns selection integer value (points) name of the table (one of all, body, header ) Eamples ft <- fletable(mtcars) ft <- fontsize(ft, size = 14, = "header") height Set fletable rows height control rows height height(, i = NULL, height, = "body") i height fletable object rows selection height in inches name of the table

13 italic 13 Eamples ft <- fletable(iris) ft <- height(ft, height =.3) italic Set italic font change font decoration of selected rows and columns of a fletable. italic(, i = NULL, j = NULL, italic = TRUE, = "body") i j italic a fletable object rows selection columns selection boolean value name of the table (one of all, body, header ) Eamples ft <- fletable(mtcars) ft <- italic(ft, italic = TRUE, = "header") merge_at Merge fletable cells Merge fletable cells merge_at(, i = NULL, j = NULL, = "body") fletable object i, j columns and rows to merge name of the table where merge has to be done.

14 14 merge_none Eamples library(officer) library(magrittr) ft_merge <- head( mtcars ) %>% fletable( cwidth =.5 ) %>% merge_at( i = 1:2, j = 1:3) ft_merge merge_h Merge fletable cells horizontally Merge fletable cells horizontally when consecutive cells have identical values. merge_h(, i = NULL, = "body") i fletable object rows where cells have to be merged. name of the table where merge has to be done. Eamples dummy_df <- data.frame( col1 = letters, col2 = letters, stringsasfactors = FALSE ) ft_merge <- fletable(dummy_df) ft_merge <- merge_h( = ft_merge) ft_merge merge_none Delete fletable merging informations Delete all merging informations from a fletable. merge_none(, = "all")

15 merge_v 15 fletable object name of the table where merge has to be done. Eamples typology <- data.frame( col_keys = c( "Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", "Species" ), what = c("sepal", "Sepal", "Petal", "Petal", "Species"), measure = c("length", "Width", "Length", "Width", "Species"), stringsasfactors = FALSE ) ft <- fletable( head( iris ) ) ft <- set_header_df(ft, mapping = typology, key = "col_keys" ) ft <- merge_v(ft, j = c("species")) ft <- theme_tron_legacy( merge_none( ft ) ) ft merge_v Merge fletable cells vertically Merge fletable cells vertically when consecutive cells have identical values. merge_v(, j = NULL, = "body") j fletable object columns names/keys where cells have to be merged. name of the table where merge has to be done. Eamples ft_merge <- fletable(mtcars) ft_merge <- merge_v(ft_merge, j = c("gear", "carb")) ft_merge

16 16 padding minibar draw a single bar This function is used to insert bars into fletable with function display minibar(value, ma, barcol = "#CCCCCC", bg = "transparent", width = 1, height = 0.2) value ma barcol bg width, height bar height ma bar height bar color background color size of the resulting png file in inches padding Set paragraph paddings change paddings of selected rows and columns of a fletable. padding(, i = NULL, j = NULL, padding = NULL, padding.top = NULL, padding.bottom = NULL, padding.left = NULL, padding.right = NULL, = "body") a fletable object i rows selection j columns selection padding padding (shortcut for top, bottom, left and right) padding.top padding top padding.bottom padding bottom padding.left padding left padding.right padding right name of the table (one of all, body, header )

17 ph_with_fletable 17 Eamples ft <- fletable(mtcars) ft <- padding(ft, padding.top = 4) ph_with_fletable add fletable into a PowerPoint slide add a fletable as a new shape in the current slide. ph_with_fletable(, value, type = "body", inde = 1) ph_with_fletable_at(, value, left, top) value type inde left, top a ppt device fletable object placeholder type placeholder inde (integer). This is to be used when a placeholder type is not unique in the current slide, e.g. two placeholders with type body. location of fletable on the slide Eamples library(officer) ft <- fletable(head(mtcars)) doc <- read_ppt() doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme") doc <- ph_with_fletable(doc, value = ft, type = "body") doc <- ph_with_fletable_at(doc, value = ft, left = 4, top = 5) print(doc, target = "test.ppt" )

18 18 set_formatter rotate rotate cell tet apply a rotation to cell tet rotate(, i = NULL, j = NULL, rotation, align = "center", = "body") i j rotation align a fletable object rows selection columns selection one of "lrtb", "tbrl", "btlr" one of "center" or "top" or "bottom" name of the table (one of all, body, header ) Eamples ft <- fletable(mtcars) ft <- rotate(ft, rotation = "lrtb", align = "top", = "header") set_formatter set column formatter functions Define formatter functions associated to each column key. Functions have a single argument (the vector) and are returning the formatted values as a character vector. set_formatter(,..., = "body") a fletable object... Name-value pairs of functions, names should be eisting col_key values name of the table (one of body or header )

19 set_header_df 19 Eamples ft <- regulartable( head( iris ) ) ft <- set_formatter( = ft, Sepal.Length = function() sprintf("%.02f", ), Sepal.Width = function() sprintf("%.04f", ) ) ft <- theme_vanilla( ft ) ft set_header_df Set fletable s header rows Use a data.frame to specify fletable s header rows. The data.frame must contain a column whose values match fletable col_keys argument, this column will be used as join key. The other columns will be displayed as header rows. The leftmost column is used as the top header row and the rightmost column is used as the bottom header row. set_header_df(, mapping = NULL, key = "col_keys") mapping key a fletable object a data.frame specyfing for each colname content of the column. column to use as key when joigning data_mapping. Eamples typology <- data.frame( col_keys = c( "Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", "Species" ), what = c("sepal", "Sepal", "Petal", "Petal", "Species"), measure = c("length", "Width", "Length", "Width", "Species"), stringsasfactors = FALSE ) ft <- fletable( head( iris )) ft <- set_header_df(ft, mapping = typology, key = "col_keys" ) ft <- merge_h(ft, = "header") ft <- merge_v(ft, j = "Species", = "header") ft <- theme_vanilla(ft) ft

20 20 style set_header_labels Set fletable s headers labels This function set labels for specified columns in a single row header of a fletable. set_header_labels(,...) a fletable object... a named list (names are data colnames), each element is a single character value specifying label to use. Eamples ft_1 <- fletable( head( iris )) ft_1 <- set_header_labels(ft_1, Sepal.Length = "Sepal length", Sepal.Width = "Sepal width", Petal.Length = "Petal length", Petal.Width = "Petal width" ) ft_1 style Set fletable style Modify fletable tet, paragraphs and cells formatting properties. style(, i = NULL, j = NULL, pr_t = NULL, pr_p = NULL, pr_c = NULL, = "body") i j pr_t pr_p pr_c a fletable object rows selection columns selection object(s) of class fp_tet object(s) of class fp_par object(s) of class fp_cell name of the table (one of all, body, header )

21 tabwid 21 Eamples def_cell <- fp_cell(border = fp_border(color="#00ffff")) def_par <- fp_par(tet.align = "center") ft <- fletable(mtcars) ft <- style( ft, pr_c = def_cell, pr_p = def_par, = "all") ft <- style(ft, ~ drat > 3.5, ~ vs + am + gear + carb, pr_t = fp_tet(color="red", italic = TRUE) ) ft tabwid htmlwidget for fletable htmlwidget for fletable tabwid(, width = NULL, height = NULL) fletable object width widget width. Unused argument, columns widths are managed by function width. height widget height Unused argument, rows heights are managed by function height. tabwid-shiny Shiny bindings for tabwid Output and render functions for using tabwid within Shiny applications and interactive Rmd documents. tabwidoutput(outputid, width = "100%", height = "400p") rendertabwid(epr, env = parent.frame(), quoted = FALSE)

22 22 theme_bo outputid width, height epr env quoted output variable to read from Must be a valid CSS unit (like '100%', '400p', 'auto') or a number, which will be coerced to a string and have 'p' appended. An epression that generates a tabwid The environment in which to evaluate epr. Is epr a quoted epression (with quote())? This is useful if you want to save an epression in a variable. theme_booktabs Apply booktabs theme Apply theme tron to a fletable theme_booktabs() a fletable object Eamples ft <- fletable(iris) ft <- theme_booktabs(ft) theme_bo Apply bo theme Apply theme bo to a fletable theme_bo() a fletable object Eamples ft <- fletable(iris) ft <- theme_bo(ft)

23 theme_tron 23 theme_tron Apply tron theme Apply theme tron to a fletable theme_tron() a fletable object Eamples ft <- fletable(iris) ft <- theme_tron(ft) theme_tron_legacy Apply tron legacy theme Apply theme tron legacy to a fletable theme_tron_legacy() a fletable object Eamples ft <- fletable(iris) ft <- theme_tron_legacy(ft)

24 24 theme_zebra theme_vanilla Apply vanilla theme Apply theme vanilla to a fletable theme_vanilla() a fletable object Eamples ft <- fletable(iris) ft <- theme_vanilla(ft) theme_zebra Apply zebra theme Apply theme zebra to a fletable theme_zebra(, odd_header = "#CFCFCF", odd_body = "#EFEFEF", even_header = "transparent", even_body = "transparent") a fletable object odd_header, odd_body, even_header, even_body odd/even colors for table header and body Eamples ft <- fletable(iris) ft <- theme_zebra(ft)

25 void 25 void Delete fletable content Set content display as a blank " ". void(, j = NULL, = "body") j fletable object columns selection name of the table Eamples ft <- fletable(mtcars) ft <- void(ft, ~ vs + am + gear + carb ) width Set fletable columns width control columns width width(, j = NULL, width) j width fletable object columns selection width in inches Details Heights are not used when fletable is been rendered into HTML. See Also fletable

26 26 width Eamples ft <- fletable(iris) ft <- width(ft, width = 1)

27 Inde add_header, 2 align, 3 as_image, 4 autofit, 5 bg, 5 body_add_fletable, 6 bold, 6 border, 7 color, 8 dim.fletable, 8 dim_pretty, 9 display, 4, 9 empty_blanks, 10 fletable, 11, 25 fontsize, 12 fp_tet, 9 set_formatter, 18 set_header_df, 19 set_header_labels, 20 style, 20 tabwid, 21 tabwid-shiny, 21 tabwidoutput (tabwid-shiny), 21 theme_booktabs, 22 theme_bo, 22 theme_tron, 23 theme_tron_legacy, 23 theme_vanilla, 24 theme_zebra, 24 void, 25 width, 25 height, 12 italic, 13 merge_at, 13 merge_h, 14 merge_none, 3, 14 merge_v, 15 minibar, 16 padding, 16 ph_with_fletable, 17 ph_with_fletable_at (ph_with_fletable), 17 print.fletable (fletable), 11 regulartable (fletable), 11 rendertabwid (tabwid-shiny), 21 rotate, 18 27