Format content

By default, the displayed content of each cell will be the result of a simple formatting. The content can also be composed as the result of a concatenation of several chunks.

There are formatter functions to define how columns content will be display (e.g. to define the number of decimal). This is a column-wise operation.

User can also have more control over displayed content by using function compose. The function enable to define the elements composing the paragraph and their respective formats. It can also be used to mix text chunks and images.

Simple functions for formatting content

Theses are high level functions that should satisfy most of the usual needs. They can be used to define the formatting of one or more columns and eventually on a subset of rows.

Each accept a prefix and suffix argument that can be used to add a currency symbol for example. Also they all have na_str argument (defaut to ""), the string to use when data are not available.

colformat_num() with arguments digits and big.mark
colformat_int() with arguments big.mark
colformat_char()

dat <- head(mtcars, n = 10)
dat[3:7, 1] <- NA
dat[, 2] <- dat[, 6] * 1000000

ft <- flextable(dat)
ft

mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
21.0	2620000	160.0	110	3.90	2.620	16.46	0	1	4	4
21.0	2875000	160.0	110	3.90	2.875	17.02	0	1	4	4
NA	2320000	108.0	93	3.85	2.320	18.61	1	1	4	1
NA	3215000	258.0	110	3.08	3.215	19.44	1	0	3	1
NA	3440000	360.0	175	3.15	3.440	17.02	0	0	3	2
NA	3460000	225.0	105	2.76	3.460	20.22	1	0	3	1
NA	3570000	360.0	245	3.21	3.570	15.84	0	0	3	4
24.4	3190000	146.7	62	3.69	3.190	20.00	1	0	4	2
22.8	3150000	140.8	95	3.92	3.150	22.90	1	0	4	2
19.2	3440000	167.6	123	3.92	3.440	18.30	1	0	4	4

num_keys <- c("mpg", "disp", "drat", "wt", "qsec")
int_keys <- c("cyl", "hp", "vs", "am", "gear", "carb")

ft <- colformat_num(x = ft, col_keys = num_keys, big.mark = ",", digits = 2, na_str = "missing")
#> Warning in colformat_num.flextable(x = ft, col_keys = num_keys, big.mark =
#> ",", : argument col_keys is deprecated in favor of argument j
ft <- colformat_int(x = ft, col_keys = int_keys, big.mark = ",")
#> Warning in colformat_int.flextable(x = ft, col_keys = int_keys, big.mark = ","):
#> argument col_keys is deprecated in favor of argument j
autofit(ft)

mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
21.00	2,620,000	160.00	110	3.90	2.62	16.46	0	1	4	4
21.00	2,875,000	160.00	110	3.90	2.88	17.02	0	1	4	4
missing	2,320,000	108.00	93	3.85	2.32	18.61	1	1	4	1
missing	3,215,000	258.00	110	3.08	3.21	19.44	1	0	3	1
missing	3,440,000	360.00	175	3.15	3.44	17.02	0	0	3	2
missing	3,460,000	225.00	105	2.76	3.46	20.22	1	0	3	1
missing	3,570,000	360.00	245	3.21	3.57	15.84	0	0	3	4
24.40	3,190,000	146.70	62	3.69	3.19	20.00	1	0	4	2
22.80	3,150,000	140.80	95	3.92	3.15	22.90	1	0	4	2
19.20	3,440,000	167.60	123	3.92	3.44	18.30	1	0	4	4

Their names is col_format_* as the first version was not working with rows subset. This limitation is no more true and the functions should then be named format_int, format_num… as they can operate on rows and columns.

set_formatter function

It is possible to define the functions that will be used to format the data.frame values into strings. set_formatter set column formatter functions.

ft <- flextable(head(mtcars, n = 10 ), 
                   col_keys = c("gear", "mpg", "qsec"))
ft <- set_formatter(ft, 
    mpg = function(x) sprintf("%.04f", x),
    gear = function(x) sprintf("%.0f gears", x)
  )
ft <- theme_booktabs(ft)
ft <- autofit(ft)
ft

gear	mpg	qsec
4 gears	21.0000	16.46
4 gears	21.0000	17.02
4 gears	22.8000	18.61
3 gears	21.4000	19.44
3 gears	18.7000	17.02
3 gears	18.1000	20.22
3 gears	14.3000	15.84
4 gears	24.4000	20.00
4 gears	22.8000	22.90
4 gears	19.2000	18.30

compose function

Usage

flextable content can be defined with function compose.

It lets user control the formated content at the cell level of the table. It is possible to define a content for a row subset and a column as well as on the whole column. One can mix images and text (but not with PowerPoint because PowerPoint can not do it).

Below the starting point of next illustrations:

myft <- flextable( head(mtcars), 
  col_keys = c("am", "separator", "gear", "mpg", "drat", "qsec" ))
myft <- bold(myft, part = "header")
myft <- border(myft, border = fp_border( width = 0), 
  border.top = fp_border(), border.bottom = fp_border(), 
  part = "all")
myft <- align(myft, align = "right", part = "all" )
myft <- border(myft, j = ~ separator, border = fp_border(width=0), part = "all")
myft <- width(myft, j = ~ separator, width = .1)
myft

am	gear	mpg	drat	qsec
1	4	21.0	3.90	16.46
1	4	21.0	3.90	17.02
1	4	22.8	3.85	18.61
0	3	21.4	3.08	19.44
0	3	18.7	3.15	17.02
0	3	18.1	2.76	20.22

The function requires a call to as_paragraph which will concatenate text or images chunks as a paragraph.

The following example shows how to control the format of displayed values and how to associate them with specific text formatting properties (bold red text):

myft <- compose( 
  myft, j = "mpg", 
  value = as_paragraph(
    "mpg value is ", 
    as_chunk(sprintf("%.01f", mpg), props = fp_text(color = "red", bold = TRUE) ) )
  )
myft <- autofit(myft)
myft

am	gear	mpg	drat	qsec
1	4	mpg value is 21.0	3.90	16.46
1	4	mpg value is 21.0	3.90	17.02
1	4	mpg value is 22.8	3.85	18.61
0	3	mpg value is 21.4	3.08	19.44
0	3	mpg value is 18.7	3.15	17.02
0	3	mpg value is 18.1	2.76	20.22

With that system, it’s easy to concatenate multiple values:

myft <- compose( 
  myft, j = "mpg", 
  value = as_paragraph(
    "mpg value is ", 
    as_chunk(sprintf("%.01f", mpg), props = fp_text(color = "red", bold = TRUE) ), 
    " with ",
    as_chunk(sprintf("# %.0f", carb), props = fp_text(color = "gray", italic = TRUE) )
    )
  )

myft <- autofit(myft)
myft

am	gear	mpg	drat	qsec
1	4	mpg value is 21.0 with # 4	3.90	16.46
1	4	mpg value is 21.0 with # 4	3.90	17.02
1	4	mpg value is 22.8 with # 1	3.85	18.61
0	3	mpg value is 21.4 with # 1	3.08	19.44
0	3	mpg value is 18.7 with # 2	3.15	17.02
0	3	mpg value is 18.1 with # 1	2.76	20.22

Or to define specific title headers:

myft <- compose( 
  myft, j = "mpg", part = "header",
  value = as_paragraph(
    "Miles/(US) gallon ", 
    as_chunk("* with num of carb.", props = fp_text(color = "gray", vertical.align = "superscript") )
    )
  )

myft <- autofit(myft)
myft

am	gear	Miles/(US) gallon * with num of carb.	drat	qsec
1	4	mpg value is 21.0 with # 4	3.90	16.46
1	4	mpg value is 21.0 with # 4	3.90	17.02
1	4	mpg value is 22.8 with # 1	3.85	18.61
0	3	mpg value is 21.4 with # 1	3.08	19.44
0	3	mpg value is 18.7 with # 2	3.15	17.02
0	3	mpg value is 18.1 with # 1	2.76	20.22

Limitation for PowerPoint

Using images in flextable is not supported when output format is PowerPoint. This is not a choice nor a unimplemented feature. This is because PowerPoint is not able to embed images in a table cell. That’s a PowerPoint limitation.

If beeing able to display images in PowerPoint table is important to you, you can use the plot function or the save_as_image and embed the result in the PowerPoint. You will of course loose ability to edit the table in PowerPoint.

Images

Function compose supports images insertion. Use function as_image in as_paragraph call:

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

myft <- compose( myft, i = ~ qsec > 18, j = "qsec", 
  value = as_paragraph(as_image( src = img.file, width = .20, height = .15))
)
myft <- autofit(myft)
myft

am	gear	Miles/(US) gallon * with num of carb.	drat	qsec
1	4	mpg value is 21.0 with # 4	3.90	16.46
1	4	mpg value is 21.0 with # 4	3.90	17.02
1	4	mpg value is 22.8 with # 1	3.85
0	3	mpg value is 21.4 with # 1	3.08
0	3	mpg value is 18.7 with # 2	3.15	17.02
0	3	mpg value is 18.1 with # 1	2.76

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

minibar

Function compose supports mini barplots insertion. Use function minibar in as_paragraph call:

myft <- flextable( head(iris, n = 10 ))

myft <- compose( myft, j = 1,
  value = as_paragraph(
    minibar(value = Sepal.Length, max = max(Sepal.Length))
  ),
  part = "body")

autofit(myft)

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species
	3.5	1.4	0.2	setosa
	3.0	1.4	0.2	setosa
	3.2	1.3	0.2	setosa
	3.1	1.5	0.2	setosa
	3.6	1.4	0.2	setosa
	3.9	1.7	0.4	setosa
	3.4	1.4	0.3	setosa
	3.4	1.5	0.2	setosa
	2.9	1.4	0.2	setosa
	3.1	1.5	0.1	setosa

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

linerange

Function compose supports mini linerange insertion. Use function linerange in as_paragraph call:

myft <- flextable( head(iris, n = 10 ))

myft <- compose( myft, j = 1,
  value = as_paragraph(
    linerange(value = Sepal.Length, max = max(Sepal.Length))
  ),
  part = "body")

autofit(myft)

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species
	3.5	1.4	0.2	setosa
	3.0	1.4	0.2	setosa
	3.2	1.3	0.2	setosa
	3.1	1.5	0.2	setosa
	3.6	1.4	0.2	setosa
	3.9	1.7	0.4	setosa
	3.4	1.4	0.3	setosa
	3.4	1.5	0.2	setosa
	2.9	1.4	0.2	setosa
	3.1	1.5	0.1	setosa

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

Sugar functions for complex formatting

Functions as_b, as_i, as_sub, as_sup are special functions that can be used together. They set a value as bold, italic, subscripted or superscripted. This is particularly useful when the headers need complex formatting.

data <- structure(list(Species = structure(1:3, .Label = c("setosa", 
"versicolor", "virginica"), class = "factor"), col1 = c(5.006, 
5.936, 6.588)), class = "data.frame", row.names = c(NA, -3L))

ft <- flextable(data)
ft

Species	col1
setosa	5.006
versicolor	5.936
virginica	6.588

ft <- compose(ft, part = "header", j = "Species", 
    value = as_paragraph(as_i(as_b("Species"))))
ft <- compose(ft, part = "header", j = "col1", 
    value = as_paragraph(as_b("µ"), as_sup("blah")))
ft

Species	µblah
setosa	5.006
versicolor	5.936
virginica	6.588

footnotes

Adding footnotes is possible by using function compose but it requires a two step approach (add the reference symbol and add the corresponding footnote in the footer part).

To make the process simpler, use function footnote that will ease the addition of footnotes.

ft <- flextable(head(iris))
ft <- footnote( ft, i = 1, j = 1:3,
            value = as_paragraph(
              c("This is footnote one",
                "This is footnote two",
                "This is footnote three")
            ),
            ref_symbols = c("a", "b", "c"),
            part = "header")
ft <- valign(ft, valign = "bottom", part = "header")
autofit(ft)

Sepal.Lengtha	Sepal.Widthb	Petal.Lengthc	Petal.Width	Species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa
aThis is footnote one
bThis is footnote two
cThis is footnote three

Format content

Simple functions for formatting content

set_formatter function

compose function

Usage

Limitation for PowerPoint

Images

minibar

linerange

Sugar functions for complex formatting

footnotes

Two lines in a cell