Format content

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

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)

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

compose function

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

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

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

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

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

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)

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)

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

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

Captions

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

Capacities are different from one format to another. For the Word part, we can produce real auto-numbered captions with a bookmark on the automatic number which can then be used as a reference, i.e. for cross-referencing. For the HTML part, you can produce real captions but without the auto-numbering.

Of course, in a bookdown, we benefit from the cross reference capabilities.

The recommended method to set a caption is via the function set_caption. If this function is used, the caption will be defined from here.

Two other methods are available for knitr and are presented below in order of triggering:

1. with knitr’s chunk options:

   • tab.cap.style: Word style name to use for table captions.
   • tab.cap.pre: Prefix for Word numbering chunk (default to “Table”).
   • tab.cap.sep: Suffix for Word numbering chunk (default to “:”).
   • tab.cap: Caption label.
   • tab.id: Caption Word bookmark (unique identifier).

2. with knitr chunk and bookdown options (if you’re in a bookdown):

   • tab.cap.style: Word style name to use for table captions.
   • tab.cap.pre: Prefix for Word numbering chunk (default to “Table”).
   • tab.cap.sep: Suffix for Word numbering chunk (default to “:”).
   • tab.cap: Caption label.
   • label: Caption reference unique identifier.

(This css instructions is only there to make the caption styled:)

caption {
  color:red;
  line-height: 1.5em;
  font-size: 10px;
}

ft <- set_caption(ft, caption = "this is a caption")
ft

You can have a look at R Markdown document illustrating captions for different supported format here:

system.file(package = "flextable", "examples", "rmd", "captions")

Copy one of these files in your working directory and run knitr:

• captions_html_document2.Rmd
• captions_rdocx_document.Rmd
• captions_word_document.Rmd
• captions_word_document2.Rmd

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)

You can also add footnotes inline using the inline argument and specify a seperator string with sep (default “;”)

ft <- flextable(head(iris))
ft <- autofit(ft)
ft <- footnote( ft, i = 1, j = 1:2,
                value = as_paragraph(
                  c("This is footnote one",
                    "This is footnote two")
                ),
                ref_symbols = c("a", "b"),
                part = "header",inline=T)
ft <- footnote( ft, i = 1, j = 3:4,
                value = as_paragraph(
                  c("This is footnote three",
                    "This is footnote four")
                ),
                ref_symbols = c( "c","d"),
                part = "header",inline=T)
ft

Two lines in a cell

A cell is made of one single paragraph of text. Paragraphs can contain several chunks of text with different formatting but also images. (see keypoints)

When designed, flextable was not supposed to support soft return (a new line in a paragraph). As requested by some users, some workarounds have been implemented to let add some \n as soft break in paragraphs.

With HTML, it works fine. But with Word or PowerPoint it comes with limitations/issues (we are working on it):

• With PowerPoint the padding is also applied where the soft break is written.
• With Word, the text format is lost and the default style is used.