Package flextable. December 8, 2017

Transcription

1 Type Package Title Functions for Tabular Reporting Version Package fletable December 8, 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 and can be used with R Markdown documents. License GPL-3 LazyData TRUE Imports stats,utils,grdevices, officer (>= 0.2.0), rmarkdown, knitr,htmltools, lazyeval,r6,stringr, gdtools (>= 0.1.6) RoygenNote Suggests ml2, testthat URL BugReports VignetteBuilder knitr NeedsCompilation no Author David Gohel [aut, cre], Maim Nazarov [ctb] (rmarkdown for doc output) Maintainer David Gohel <david.gohel@ardata.fr> Repository CRAN Date/Publication :01:20 UTC R topics documented: add_header align as_image autofit bg

2 2 add_header body_add_fletable bold border color dim.fletable dim_pretty display empty_blanks fletable fontsize height italic knit_print.fletable merge_at merge_h merge_none merge_v minibar padding ph_with_fletable rotate set_formatter set_header_df set_header_labels style tabwid theme_booktabs theme_bo theme_tron theme_tron_legacy theme_vanilla theme_zebra void width Inde 28 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. add_header(, top = TRUE,...)

3 align 3 a fletable object top 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. Details 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 ) Eamples ft <- fletable(mtcars) ft <- align(ft, align = "center")

4 4 autofit 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(officer) img.file <- file.path( R.home("doc"), "html", "logo.jpg" ) myft <- fletable(head( mtcars, n = 10)) myft <- display(myft, 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 autofit Adjusts cell widths and heights compute and apply optimized widths and heights. autofit(, add_w = 0.1, add_h = 0.1)

5 bg 5 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 library(officer) 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. Values are inches. ## 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 in inches. 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 pattern It defined the template used to format the produced strings. Names enclosed by double braces will be evaluated as R code, the corresponding R code is defined with the argument formatters. formatters Each compound is specifying the R code to eecute to produce strings that will be substituted in the pattern argument. An element must be a formula: the left-hand side is a name (matching a name enclosed by double braces in pattern) and the right-hand side is an R epression to be evaluated (that will produce the corresponding strings). fprops A named list of fp_tet. It defines the formatting properties associated to a compound in formatters. If not defined for an element of formatters, the default formatting properties will be applied. Note The function display only works with fletable objects, use set_formatter for regulartable objects. Eamples library(officer) # Formatting data values eample 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

11 fletable 11 Eamples 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 ft <- fletable(head(iris), col_keys = c("species", "break1", "Sepal.Length", "Sepal.Width", "break2", "Petal.Length", "Petal.Width") ) ft <- set_header_df(ft, mapping = typology, key = "col_keys" ) ft <- merge_h(ft, = "header") ft <- theme_vanilla(ft) ft <- empty_blanks(ft) ft <- width(ft, j = c(2, 5), width =.1 ) ft 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 dataset col_keys 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 in inches. fletable object

12 12 fontsize preview... unused argument preview type, one of c("html", "ppt", "doc", "log"). When "log" is used, a description of the fletable is printed. 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 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")

13 height 13 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 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 )

14 14 merge_at Eamples ft <- fletable(mtcars) ft <- italic(ft, italic = TRUE, = "header") knit_print.fletable Render fletable in rmarkdown (including Word output) Function used to render fletable in knitr/rmarkdown documents. HTML and Word outputs are supported. ## S3 method for class 'fletable' knit_print(,...) a fletable object... further arguments, not used. Note For Word (doc) output, if pandoc vesion >= 2.0 is used, a raw XML block with the table code will be inserted. If pandoc vesion < 2.0 is used, an error will be raised. Author(s) Maim Nazarov merge_at Merge fletable cells Merge fletable cells merge_at(, i = NULL, j = NULL, = "body")

15 merge_h 15 fletable object i, j columns and rows to merge name of the table where merge has to be done. Eamples ft_merge <- fletable( head( mtcars ), cwidth =.5 ) ft_merge <- merge_at( ft_merge, 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

16 16 merge_v merge_none Delete fletable merging informations Delete all merging informations from a fletable. merge_none(, = "all") 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.

17 minibar 17 Eamples ft_merge <- fletable(mtcars) ft_merge <- merge_v(ft_merge, j = c("gear", "carb")) ft_merge 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")

18 18 ph_with_fletable i j padding padding.top a fletable object rows selection columns selection padding (shortcut for top, bottom, left and right) padding top padding.bottom padding bottom padding.left padding.right Eamples padding left padding right ft <- fletable(mtcars) ft <- padding(ft, padding.top = 4) name of the table (one of all, body, header ) 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 in inches Note The width and height of the table can not be set with this function. Use functions width, height, autofit and dim_pretty instead. The overall size is resulting from cells, paragraphs and tet properties (i.e. padding, font size, border widths).

19 rotate 19 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" ) 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")

20 20 set_formatter 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") set_formatter_type(, fmt_double = "%.03f", fmt_integer = "%.0f", fmt_date = "%Y-%m-%d", fmt_datetime = "%Y-%m-%d %H:%M:%S", fun_any = "format") a regulartable object... Name-value pairs of functions, names should be eisting col_key values name of the table (one of body or header ) fmt_double, fmt_integer arguments used by sprintf to format double and integer columns. fmt_date, fmt_datetime arguments used by format to format date and date time columns. fun_any function name (character) to use to convert other types of columns as characters. Note that factors and strings are not transformed by this function. set_formatter_type set_formatter_type is an helper function to quickly define formatter functions regarding to column types. Eamples ft <- regulartable( head( iris ) ) ft <- set_formatter( = ft, Sepal.Length = function() sprintf("%.02f", ), Sepal.Width = function() sprintf("%.04f", ) ) ft <- theme_vanilla( ft ) ft

21 set_header_df 21 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 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(,...)

22 22 style 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 ) Eamples library(officer) 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")

23 tabwid 23 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. This function is deprecated. tabwid(,...) fletable object... Unused arguments theme_booktabs Apply booktabs theme Apply theme tron to a fletable theme_booktabs() a fletable object Eamples ft <- fletable(iris) ft <- theme_booktabs(ft)

24 24 theme_tron theme_bo Apply bo theme Apply theme bo to a fletable theme_bo() a fletable object Eamples ft <- fletable(iris) ft <- theme_bo(ft) theme_tron Apply tron theme Apply theme tron to a fletable theme_tron() a fletable object Eamples ft <- fletable(iris) ft <- theme_tron(ft)

25 theme_tron_legacy 25 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) theme_vanilla Apply vanilla theme Apply theme vanilla to a fletable theme_vanilla() a fletable object Eamples ft <- fletable(iris) ft <- theme_vanilla(ft)

26 26 void 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) 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 )

27 width 27 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 Eamples ft <- fletable(iris) ft <- width(ft, width = 1)

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