License
@@ -138,31 +69,28 @@License
MIT License
@@ -134,39 +65,49 @@MIT License
Copyright (c) 2020 Atsushi Yasumoto
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +“Software”), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions:
+The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-
+
@@ -85,14 +81,14 @@
-
+
@@ -101,31 +97,36 @@
Format columns as markdown
- Source:vignettes/format_columns.Rmd+ Source:vignettes/format_columns.Rmdformat_columns.RmdFormat columns as markdown
This vignette introduces how to format columns in flextable.
--+-Why markdown?
-The flextable package is an excellent package that allows fine controls on styling tables, and export it to variety of formats (HTML, MS Word, PDF). Especially, when output format is MS Word, this package is the best solution in R.
-On the other hand, styling texts with the flextable package often require large efforts. The following example subscripts numeric values in chemical formulas.
+library(flextable) +library(ftExtra)+Why markdown? +
+The flextable package is an excellent package that +allows fine controls on styling tables, and export it to variety of +formats (HTML, MS Word, PDF). Especially, when output format is MS Word, +this package is the best solution in R.
+On the other hand, styling texts with the flextable +package often require large efforts. The following example subscripts +numeric values in chemical formulas.
--
df <- data.frame(Oxide = c("SiO2", "Al2O3"), stringsAsFactors = FALSE) -ft <- flextable::flextable(df) +df <- data.frame(Oxide = c("SiO2", "Al2O3"), stringsAsFactors = FALSE) +ft <- flextable::flextable(df) -ft %>% - flextable::compose( +ft %>% + flextable::compose( i = 1, j = "Oxide", - value = flextable::as_paragraph( - "SiO", as_sub("2") + value = flextable::as_paragraph( + "SiO", as_sub("2") ) - ) %>% - flextable::compose( + ) %>% + flextable::compose( i = 2, j = "Oxide", - value = flextable::as_paragraph( - "Al", as_sub("2"), "O", as_sub("3") + value = flextable::as_paragraph( + "Al", as_sub("2"), "O", as_sub("3") ) )- --
Oxide
+
- +Oxide
SiO2
Al2O3
SiO2
Al2O3
The ftExtra package provides easy solution by introducing markdown. As markdown texts self-explain their formats by plain texts, what users have to do is manipulations of character columns with their favorite tools such as the famous dplyr and stringr packages.
+The ftExtra package provides easy solution by +introducing markdown. As markdown texts self-explain their formats by +plain texts, what users have to do is manipulations of character columns +with their favorite tools such as the famous dplyr and +stringr packages.
- Preprocess a data frame to decorate texts with markdown syntax. -
- Convert the data frame into a flextable object with the
flextablefunction oras_flextablefunction.
+ - Convert the data frame into a flextable object with the
+
flextablefunction oras_flextable+function. - Format markdown columns with
colformat_md
The following example elegantly simplifies the prior example.
--
df <- data.frame(Oxide = c("SiO2", "Fe2O3"), stringsAsFactors = FALSE) +df <- data.frame(Oxide = c("SiO2", "Fe2O3"), stringsAsFactors = FALSE) -df %>% - dplyr::mutate(Oxide = stringr::str_replace_all(Oxide, "([2-9]+)", "~\\1~")) %>% - flextable::flextable() %>% +df %>% + dplyr::mutate(Oxide = stringr::str_replace_all(Oxide, "([2-9]+)", "~\\1~")) %>% + flextable::flextable() %>% ftExtra::colformat_md()- --
Oxide
+
- +Oxide
SiO2
Fe2O3
SiO2
Fe2O3
The
-colformat_mdfunction is smart enough to detect character columns, so users can start without learning its arguments. Of course, it is possible to chose columns.Another workflow is to read a markdown-formatted table from a external file. Again, markdown is by design a plain text, and can easily be embed in any formats such as CSV and Excel. So users can do something like
+The
+colformat_mdfunction is smart enough to detect +character columns, so users can start without learning its arguments. Of +course, it is possible to chose columns.Another workflow is to read a markdown-formatted table from a +external file. Again, markdown is by design a plain text, and can easily +be embed in any formats such as CSV and Excel. So users can do something +like
--
readr::read_csv("example.csv") %>% - flextable::flextable() %>% +readr::read_csv("example.csv") %>% + flextable::flextable() %>% ftExtra::colformat_md()By default, the ftExtra package employs Pandoc’s markdown, which is also employed by R Markdown. This enables consistent user experience when using the ftExtra package in R Markdown.
+By default, the ftExtra package employs Pandoc’s +markdown, which is also employed by R Markdown. This enables consistent +user experience when using the ftExtra package in R +Markdown.
---Basic examples
-The example below shows that
+colformat_md()function parses markdown texts in the flextable object.+Basic examples +
+The example below shows that
colformat_md()function +parses markdown texts in the flextable object.--
data.frame( - a = c("**bold**", "*italic*"), - b = c("^superscript^", "~subscript~"), - c = c("`code`", "[underline]{.underline}"), - d = c("*[**~ft~^Extra^**](https://ftextra.atusy.net/) is*", +data.frame( + a = c("**bold**", "*italic*"), + b = c("^superscript^", "~subscript~"), + c = c("`code`", "[underline]{.underline}"), + d = c("*[**~ft~^Extra^**](https://ftextra.atusy.net/) is*", "[Cool]{.underline shading.color='skyblue'}"), stringsAsFactors = FALSE -) %>% - as_flextable() %>% +) %>% + as_flextable() %>% colformat_md()- -+ +
- +- a
b
c
d
a
b
c
d
- bold
superscript
code
+ bold
superscript
code
- italic
subscript
underline
Cool
italic
subscript
underline
Cool
The table header can also be formatted by specifying
+part = "header"or"all"tocolformat_md()The table header can also be formatted by specifying +
part = "header"or"all"to +colformat_md()Supported syntax are
- bold @@ -476,23 +499,25 @@
- other syntax may result in unexpected behaviors. -
- multiple paragraphs are collapsed to a single paragraph with a separator given to the
.separgument (default:"\n\n").
+ - multiple paragraphs are collapsed to a single paragraph with a
+separator given to the
.separgument (default: +"\n\n"). - Format columns as markdown -
- -
- Group rows -
- -
- Create multi level headers -
- -
Notes:
--Footnotes
++Footnotes +
An easy way to add a footnote is inline footnote.
--
data.frame( +data.frame( package = "ftExtra", description = "Extensions for 'Flextable'^[Supports of footnotes]", stringsAsFactors = FALSE -) %>% - as_flextable() %>% - colformat_md() %>% - flextable::autofit(add_w = 0.5)- -+ +
- +- package
description
package
description
- -ftExtra
Extensions for ‘Flextable’1
ftExtra
Extensions for ‘Flextable’1
1Supports of footnotes
1Supports of footnotes
Reference symbols can be configured by
+footnote_options(). Of course, markdown can be used inside footnotes as well.Reference symbols can be configured by +
footnote_options(). Of course, markdown can be used inside +footnotes as well.--
data.frame( +data.frame( package = "ftExtra^[Short of *flextable extra*]", description = "Extensions for 'Flextable'^[Supports of footnotes]", stringsAsFactors = FALSE -) %>% - as_flextable() %>% +) %>% + as_flextable() %>% colformat_md( .footnote_options = footnote_options(ref = "i", prefix = '[', @@ -569,9 +596,9 @@start = 2, inline = TRUE, sep = "; ") - ) %>% - flextable::autofit(add_w = 0.5)
- -+ +
- +- package
description
package
description
- -ftExtra[ii]
Extensions for ‘Flextable’[iii]
ftExtra[ii]
Extensions for ‘Flextable’[iii]
2Short of flextable extra; 3Supports of footnotes
2Short of flextable extra; 3Supports of footnotes
In order to add multiple footnotes to a cell, use normal footnotes syntax.
+In order to add multiple footnotes to a cell, use normal footnotes +syntax.
--
data.frame(x = +data.frame(x = "foo[^a]^,^ [^b] [^a]: aaa [^b]: bbb", stringsAsFactors = FALSE -) %>% - as_flextable() %>% +) %>% + as_flextable() %>% colformat_md()- --
x
foo1, 2
+
- + -x
foo1, 2
1aaa
2bbb
1aaa
2bbb
--Images
-Images can be inserted optionally with width and/or height attributes. Specifying one of them changes the other while keeping the aspect ratio.
++Images +
+Images can be inserted optionally with width and/or height +attributes. Specifying one of them changes the other while keeping the +aspect ratio.
--
data.frame( - R = sprintf("", file.path( R.home("doc"), "html", "logo.jpg" )), +data.frame( + R = sprintf("", file.path( R.home("doc"), "html", "logo.jpg" )), stringsAsFactors = FALSE -) %>% - as_flextable() %>% - colformat_md() %>% - flextable::autofit()- --
R
+
- +R
The R logo is distributed by The R Foundation with the CC-BY-SA 4.0 license.
+The R logo is distributed by The R Foundation with the CC-BY-SA 4.0 +license.
---Line breaks
++Line breaks +
By default, soft line breaks becomes spaces.
--
data.frame(linebreak = c("a\nb"), stringsAsFactors = FALSE) %>% - as_flextable() %>% +data.frame(linebreak = c("a\nb"), stringsAsFactors = FALSE) %>% + as_flextable() %>% colformat_md()- --
linebreak
a b
+
- +linebreak
a b
Pandoc’s markdown supports hard line breaks by adding a backslash or double spaces at the end of a line.
+Pandoc’s markdown supports hard line breaks by adding a backslash or +double spaces at the end of a line.
--
data.frame(linebreak = c("a\\\nb"), stringsAsFactors = FALSE) %>% - as_flextable() %>% +data.frame(linebreak = c("a\\\nb"), stringsAsFactors = FALSE) %>% + as_flextable() %>% colformat_md()- --
linebreak
a
b+
- +linebreak
a
bIt is also possible to make
+\nas a hard line break by extending Pandoc’s Markdown.It is also possible to make
\nas a hard line break by +extending Pandoc’s Markdown.--
data.frame(linebreak = c("a\nb"), stringsAsFactors = FALSE) %>% - as_flextable() %>% +data.frame(linebreak = c("a\nb"), stringsAsFactors = FALSE) %>% + as_flextable() %>% colformat_md(md_extensions = "+hard_line_breaks")- --
linebreak
a
b+
- +linebreak
a
bMarkdown treats continuous linebreaks as a separator of blocks such as paragraphs. However, flextable package lacks the support for multiple paragraphs in a cell. To workaround,
+colformat_mdcollapses them to a single paragraph with a separator given to.sep(default:\n\n).Markdown treats continuous linebreaks as a separator of blocks such +as paragraphs. However, flextable package lacks the +support for multiple paragraphs in a cell. To workaround, +
colformat_mdcollapses them to a single paragraph with a +separator given to.sep(default:\n\n).--
data.frame(linebreak = c("a\n\nb"), stringsAsFactors = FALSE) %>% - as_flextable() %>% +data.frame(linebreak = c("a\n\nb"), stringsAsFactors = FALSE) %>% + as_flextable() %>% colformat_md(.sep = "\n\n")- --
linebreak
a
b+
- + -linebreak
a
b--Citations
-Citations is experimentally supported. Note that there are no citation lists. It is expected to be produced by using R Markdown.
++Citations +
+Citations is experimentally supported. Note that there are no +citation lists. It is expected to be produced by using R Markdown.
First, create a
-ftExtra.bibfile like below.+@Manual{R-ftExtra, - title = {ftExtra: Extensions for Flextable}, - author = {Atsushi Yasumoto}, - year = {2022}, - note = {https://ftextra.atusy.net}, -}@Manual{R-ftExtra, + title = {ftExtra: Extensions for Flextable}, + author = {Atsushi Yasumoto}, + year = {2022}, + note = {https://ftextra.atusy.net}, +}Second, specify it within the YAML front matter.
- +--- +bibliography: ftExtra.bib +---Finally, cite the references within tables.
--
data.frame( - Cite = c("@R-ftExtra", "[@R-ftExtra]", "[-@R-ftExtra]"), +data.frame( + Cite = c("@R-ftExtra", "[@R-ftExtra]", "[-@R-ftExtra]"), stringsAsFactors = FALSE -) %>% - as_flextable() %>% - colformat_md() %>% - flextable::autofit(add_w = 0.2)- --
Cite
+
- +Cite
Yasumoto (2022)
(Yasumoto 2022)
(2022)
Yasumoto (2022)
(Yasumoto 2022)
(2022)
If citation style such as Vancouver requires citations be numbered sequentially and consistently with the body, manually offset the number for example by
+colformat_md(.cite_offset = 5).If citation style such as Vancouver requires citations be numbered +sequentially and consistently with the body, manually offset the number +for example by
-colformat_md(.cite_offset = 5).--Math
++Math +
The rendering of math is also possible.
--
data.frame(math = "$e^{i\\theta} = \\cos \\theta + i \\sin \\theta$", - stringsAsFactors = FALSE) %>% - as_flextable() %>% - colformat_md() %>% - flextable::autofit(add_w = 0.2)- --
math
eiθ = cos θ + isin θ
+
- +math
eiθ = cos θ + isin θ
Note that results can be insufficient. This feature relies on Pandoc’s HTML writer, which
+Note that results can be insufficient. This feature relies on +Pandoc’s HTML writer, which
-
-render TeX math as far as possible using Unicode characters
+
https://pandoc.org/MANUAL.html#math-rendering-in-htmlrender TeX math as far as possible using Unicode characters
https://pandoc.org/MANUAL.html#math-rendering-in-html--Emoji
-Pandoc’s markdown provides an extension,
+emoji. To use it withcolformat_md(), specifymd_extensions="+emoji".+Emoji +
+Pandoc’s markdown provides an extension,
emoji. To use +it withcolformat_md(), specify +md_extensions="+emoji".--
data.frame(emoji = c(":+1:"), stringsAsFactors = FALSE) %>% - as_flextable() %>% +data.frame(emoji = c(":+1:"), stringsAsFactors = FALSE) %>% + as_flextable() %>% colformat_md(md_extensions = "+emoji")- --
emoji
👍
+
- + -emoji
👍
--Other input formats
-
+colformat_mdsupports variety of formats. They can even be HTML despite the name of the function.+Other input formats +
+colformat_mdsupports variety of formats. They can even +be HTML despite the name of the function.--
data.frame( +data.frame( x = "H<sub>2</sub>O", stringsAsFactors = FALSE -) %>% - as_flextable() %>% +) %>% + as_flextable() %>% colformat_md(.from = "html")- --
x
H2O
+
- +x
H2O
Note that multiple paragraphs are not supported if
+.fromis not"markdown". Below is an example with commonmark.Note that multiple paragraphs are not supported if
.from+is not"markdown". Below is an example with commonmark.--
data.frame( +data.frame( x = "foo\n\nbar", stringsAsFactors = FALSE -) %>% - as_flextable() %>% +) %>% + as_flextable() %>% colformat_md(.from = "commonmark")- --
x
foobar
+
- + +x
foobar
-This vignette introduces nice and easy way to display grouped data frame created by
+dplyr::group_by.This vignette introduces nice and easy way to display grouped data +frame created by
+dplyr::group_by.library(ftExtra) +library(dplyr)--
grouped_iris <- iris %>% - group_by(Species) %>% - slice(1, 2) +grouped_iris <- iris %>% + group_by(Species) %>% + slice(1, 2) -grouped_mtcars <- mtcars %>% - mutate(model = rownames(mtcars)) %>% - head %>% - select(model, cyl, mpg, disp, am) %>% - group_by(am, cyl)--Groups as titles
--+-Single grouping columns
+grouped_mtcars <- mtcars %>% + mutate(model = rownames(mtcars)) %>% + head %>% + select(model, cyl, mpg, disp, am) %>% + group_by(am, cyl)+Groups as titles +
++Single grouping columns +
--
grouped_iris %>% as_flextable()- -+ +
- +- -Sepal.Length
Sepal.Width
Petal.Length
Petal.Width
Sepal.Length
Sepal.Width
Petal.Length
Petal.Width
Species: setosa
Species: setosa
- 5.1
3.5
1.4
0.2
5.1
3.5
1.4
0.2
- -4.9
3.0
1.4
0.2
4.9
3.0
1.4
0.2
Species: versicolor
Species: versicolor
- 7.0
3.2
4.7
1.4
7.0
3.2
4.7
1.4
- -6.4
3.2
4.5
1.5
6.4
3.2
4.5
1.5
Species: virginica
Species: virginica
- 6.3
3.3
6.0
2.5
6.3
3.3
6.0
2.5
- 5.8
2.7
5.1
1.9
5.8
2.7
5.1
1.9
--
grouped_iris %>% as_flextable(hide_grouplabel = TRUE)- -+ +
- + -- -Sepal.Length
Sepal.Width
Petal.Length
Petal.Width
Sepal.Length
Sepal.Width
Petal.Length
Petal.Width
setosa
setosa
- 5.1
3.5
1.4
0.2
5.1
3.5
1.4
0.2
- -4.9
3.0
1.4
0.2
4.9
3.0
1.4
0.2
versicolor
versicolor
- 7.0
3.2
4.7
1.4
7.0
3.2
4.7
1.4
- -6.4
3.2
4.5
1.5
6.4
3.2
4.5
1.5
virginica
virginica
- 6.3
3.3
6.0
2.5
6.3
3.3
6.0
2.5
- 5.8
2.7
5.1
1.9
5.8
2.7
5.1
1.9
--Multiple grouping columns
++Multiple grouping columns +
--
grouped_mtcars %>% as_flextable()- -+ +
- + -- -model
mpg
disp
model
mpg
disp
am: 1.0
cyl: 6.0
am: 1.0
cyl: 6.0
- Mazda RX4
21.0
160
Mazda RX4
21.0
160
- -Mazda RX4 Wag
21.0
160
Mazda RX4 Wag
21.0
160
cyl: 4.0
cyl: 4.0
- -Datsun 710
22.8
108
Datsun 710
22.8
108
am: 0.0
cyl: 6.0
am: 0.0
cyl: 6.0
- -Hornet 4 Drive
21.4
258
Hornet 4 Drive
21.4
258
cyl: 8.0
cyl: 8.0
- -Hornet Sportabout
18.7
360
Hornet Sportabout
18.7
360
cyl: 6.0
cyl: 6.0
- Valiant
18.1
225
Valiant
18.1
225
--Groups as merged columns
-By specifying
-as_flextable(groups_to = 'merged'), grouping variables are merged vertically. In this case, the default theme is changed toflextable::theme_vanillabecause the booktab theme is not intuitive.--Single grouping variable
++Groups as merged columns +
+By specifying
+as_flextable(groups_to = 'merged'), +grouping variables are merged vertically. In this case, the default +theme is changed toflextable::theme_vanillabecause the +booktab theme is not intuitive.+Single grouping variable +
--
grouped_iris %>% - as_flextable(groups_to = "merged")- -+ +
- + -- Species
Sepal.Length
Sepal.Width
Petal.Length
Petal.Width
Species
Sepal.Length
Sepal.Width
Petal.Length
Petal.Width
- setosa
5.1
3.5
1.4
0.2
setosa
5.1
3.5
1.4
0.2
- 4.9
3.0
1.4
0.2
4.9
3.0
1.4
0.2
- versicolor
7.0
3.2
4.7
1.4
versicolor
7.0
3.2
4.7
1.4
- 6.4
3.2
4.5
1.5
6.4
3.2
4.5
1.5
- virginica
6.3
3.3
6.0
2.5
virginica
6.3
3.3
6.0
2.5
- 5.8
2.7
5.1
1.9
5.8
2.7
5.1
1.9
--Multiple grouping variables
++Multiple grouping variables +
--
grouped_mtcars %>% - as_flextable(groups_to = "merged") %>% - flextable::theme_vanilla()- -+ +
- + -- am
cyl
model
mpg
disp
am
cyl
model
mpg
disp
- 1
6
Mazda RX4
21.0
160
1
6
Mazda RX4
21.0
160
- Mazda RX4 Wag
21.0
160
Mazda RX4 Wag
21.0
160
- Datsun 710
22.8
108
Datsun 710
22.8
108
- 0
6
Hornet 4 Drive
21.4
258
0
6
Hornet 4 Drive
21.4
258
- Hornet Sportabout
18.7
360
Hornet Sportabout
18.7
360
- Valiant
18.1
225
Valiant
18.1
225
--Position of grouping variables
-Grouping variables are moved to left by default. If you want to keep their positions, specify
+group_pos = 'asis'.+Position of grouping variables +
+Grouping variables are moved to left by default. If you want to keep +their positions, specify
group_pos = 'asis'.--
grouped_mtcars %>% - as_flextable(groups_to = "merged", groups_pos = "asis") %>% - flextable::theme_vanilla()- -+ +
- + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- model
cyl
mpg
disp
am
model
cyl
mpg
disp
am
- Mazda RX4
6
21.0
160
1
Mazda RX4
6
21.0
160
1
- Mazda RX4 Wag
21.0
160
Mazda RX4 Wag
21.0
160
- Datsun 710
22.8
108
Datsun 710
22.8
108
- Hornet 4 Drive
6
21.4
258
0
Hornet 4 Drive
6
21.4
258
0
- Hornet Sportabout
18.7
360
Hornet Sportabout
18.7
360
- Valiant
18.1
225
Valiant
18.1
225
Articles • ftExtra - + + - - - --- - + + diff --git a/docs/articles/transform-headers.html b/docs/articles/transform-headers.html index ae068c1..fe65c8d 100644 --- a/docs/articles/transform-headers.html +++ b/docs/articles/transform-headers.html @@ -19,6 +19,8 @@ + +- - - -+-+Articles
@@ -135,35 +66,32 @@Articles
All vignettes
--
-