knitr::opts_chunk$set( collapse = TRUE, comment = "#>", tidy = TRUE ) # to knit "child" Rmd files knitr::opts_knit$set(root.dir = "../") library(formatdown) library(data.table) library(knitr) options( datatable.print.nrows = 15, datatable.print.topn = 3, datatable.print.class = TRUE )
{width=70%}
option by Mike Lawrence is licensed under CC BY 2.0 DEED https://creativecommons.org/licenses/by/2.0/.
Global options are provided for arguments that users are likely prefer to set once in a document instead of repeating in every function call. For example, some users prefer a comma decimal marker (",") throughout a document.
Globally-set arguments can be overridden locally by assigning them in a function call.
formatdown_options()
Set, examine, or reset several global options which affect the way in which a formatted object is rendered in an R markdown document. The options and their default settings are
formatdown_options(delim = "$", size = NULL, decimal_mark = ".", big_mark = "", big_interval = 3, small_mark = "", small_interval = 5, whitespace = "\\\\>", reset = FALSE)
To reset all formatdown arguments to their default values:
formatdown_options(reset = TRUE)
Usage. For example, get two of the current settings.
formatdown_options("size", "decimal_mark")
Assign new settings; examine result.
# Set formatdown_options(size = "large", decimal_mark = ",") # Examine result formatdown_options("size", "decimal_mark")
Reset to default values; examine result.
# Set to defaults formatdown_options(reset = TRUE) # Examine result formatdown_options("size", "decimal_mark")
Delimiters are characters that surround a formatted expression such that R Markdown renders it as an inline math expression.
Sometimes the default $ ... $
delimiters fail to render correctly. I encountered this once using kableExtra::kbl()
in a .qmd
document. The solution, suggested by the MathJax consortium [@Cervone:2018], is to use the delimiter pair \( ... \)
, hence the built-in alternate, delim = "\\("
.
Left and right custom delimiters can be assigned in a vector, e.g., c("\\[", "\\]")
.
Examples. Note that using format_text()
introduces additional markup inside the delimiters. Details are described in the Format text article.
x <- 101300 txt <- "Hello world!" # 1. Numeric input, default delimiters format_dcml(x) # 2. Numeric input, alternate delimiters format_dcml(x, delim = "\\(") # 3. Character input, default delimiters format_text(txt) # 4. Character input, alternate delimiters format_text(txt, delim = "\\(")
Examples 1--4 (in inline code chunks) render as,
r format_dcml(x, size = "small")
r format_dcml(x, delim = "\\(", size = "small")
r format_text(txt, size = "small")
r format_text(txt, delim = "\\(", size = "small")
Font size is set using LaTeX-style macros inside the math-delimited expression. For example, with size = "small"
(or size = "\\small"
), the formatdown markup of the Avogadro constant would be
"$\\small 6.0221 \\times 10^{23}$",
where the extra backslashes are necessary to escape the backslashes in \small
and \times
. If size = NULL
(default), no size command is added and the font size is equivalent to "normalsize"
.
Examples.
# 5. Numeric input format_dcml(x, size = "scriptsize") # 6. Numeric input format_dcml(x, size = "small") # 7. Power-of-ten number using LaTeX-style size markup format_sci(6.0221e+23, size = "\\small") # 8. Character input, default size format_text(txt) # 9. Character input format_text(txt, size = "large")
Examples 5--9 render as,
r format_dcml(x, size = "scriptsize")
r format_dcml(x, size = "small")
r format_sci(6.0221e+23, size = "small")
r format_text(txt)
r format_text(txt, size = "large")
Available sizes
Comparing decimal notation, scientific notation, and text in possible font sizes (formatdown does not support the sizes: tiny, footnotesize, Large, LARGE, and Huge).
#| echo: false x <- pi y <- 5.3e+3 z <- "The cat" scriptsize <- c( format_dcml(x, 5, size = "scriptsize"), format_sci(y, 1, size = "scriptsize"), format_text(z, size = "scriptsize") ) small <- c( format_dcml(x, 5, size = "small"), format_sci(y, 1, size = "small"), format_text(z, size = "small") ) normalsize <- c( format_dcml(x, 5, size = "normalsize"), format_sci(y, 1, size = "normalsize"), format_text(z, size = "normalsize") ) large <- c( format_dcml(x, 5, size = "large"), format_sci(y, 1, size = "large"), format_text(z, size = "large") ) huge <- c( format_dcml(x, 5, size = "huge"), format_sci(y, 1, size = "huge"), format_text(z, size = "huge") ) DT <- data.table(scriptsize, small, normalsize, large, huge) knitr::kable(DT, align = "r")
For a number written in decimal form, the decimal mark separates the integer part from the fractional part.
A period or dot (".") is the conventional decimal mark in the US, Australia, Canada (English-speaking), Mexico, the UK, much of eastern Asia, and other regions.
A comma (",") is the conventional decimal mark in Brazil, Canada (French-speaking), much of Europe and Latin America, Russia, and other regions.
The decimal mark in formatdown may be reset locally in a function call or globally using formatdown_options()
; it is not affected by the base R option OutDec
.
Examples.
# 10. Decimal markup x <- pi format_dcml(x, 5, decimal_mark = ",") # 11. Power-of-ten markup y <- 1.602176634e-19 format_sci(y, 5, decimal_mark = ",")
Examples 10 and 11 render as,
r format_dcml(x, 5, decimal_mark = ",", size = "small")
r format_sci(y, 5, decimal_mark = ",", size = "small")
The NIST recommends we use a thin space to separate more than 4 digits to the left or to the right of a decimal marker [@NIST:2022, 10.5.3]:
... digits should be separated into groups of three, counting from the decimal marker towards the left and right, by the use of a thin, fixed space. However, this practice is not usually followed for numbers having only four digits on either side of the decimal marker except when uniformity in a table is desired.
Both big_mark
and small_mark
add the horizontal-space characters inside the math delimiters; big_mark
to the integer portion and small_mark
to the fractional portion. The possible values are empty ""
(default), "thin"
, or the thin-space macro itself \\\\,
.
The interval arguments big_interval
and small_interval
set the number of digits separated by thin spaces when big_mark
or small_mark
are not empty. However, formatdown does not encode the exemption for 4-digit groups mentioned in the NIST quote above.
Examples.
w <- 1013 x <- 101300 y <- 0.002456 z <- x + y # 12. 4-digit number, no space format_dcml(w) # 13. 4-digit number, with space format_dcml(w, big_mark = "thin") # 14. Group digits to the left of the decimal format_dcml(x, big_mark = "thin") # 15. Group digits to the right of the decimal format_dcml(y, small_mark = "\\\\,") # 16. Change the small interval format_dcml(y, small_mark = "\\\\,", small_interval = 3) # 17. Group digits to the left and right of the decimal format_dcml(z, 12, big_mark = "thin", small_mark = "thin")
Examples 12--17 render as,
r format_dcml(w, size = "small")
r format_dcml(w, big_mark = "thin", size = "small")
r format_dcml(x, big_mark = "\\\\,", size = "small")
r format_dcml(y, small_mark = "\\\\,", size = "small")
r format_dcml(y, small_mark = "\\\\,", small_interval = 3, size = "small")
r format_dcml(z, 12, big_mark = "thin", small_mark = "\\\\,", size = "small")
The horizontal-space macro is used to preserve spaces in text formatted with format_text()
as well as spaces within physical-unit strings with format_numbers()
. Without it, an inline math markup such as
$\mathrm{This Is Math Text.}$
is rendered in an R markdown document as
$\qquad$ r "$\\small\\mathrm{This Is Math Text.}$"
To preserve such spaces, formatdown substitutes the character string \>
for each space, producing output like the following, where backslashes have been escaped,
"$\\mathrm{This\\>Is\\>Math\\>Text.}$"
rendered as,
$\qquad$ r "$\\small\\mathrm{This\\>Is\\>Math\\>Text.}$"
Because the backslashes must be escaped, the formatdown output is $\small\mathtt{\verb|"\>"|}$, but the the argument value set by the user is whitespace =
$\small\mathtt{\verb|"\\>"|}$. One may also use $\mathtt{\small\verb|"\\:"|}$ or $\mathtt{\small\verb|"\\ "|}$.
Examples.
# 18. Character input, default space "\>" format_text(txt, whitespace = "\\\\>") # 19. Character input, alternate space "\:" format_text(txt, whitespace = "\\\\:") # 20. Character input, alternate space "\ " format_text(txt, whitespace = "\\\\ ")
Examples 18--20 render as,
r format_text(txt, size = "small")
r format_text(txt, whitespace = "\\\\:", size = "small")
r format_text(txt, whitespace = "\\\\ ", size = "small")
Example 21.
In this example, we format different columns of a data frame using decimal_mark
, big_mark
and small_mark
.
#| echo: false formatdown_options(size = "small")
# Set options formatdown_options(decimal_mark = ",", big_mark = "thin", small_mark = "thin") # Use water data included with formatdown DT <- copy(water)[1:6] # Examine the data frame DT[] # Routine decimal formatting DT$temp <- format_dcml(DT$temp) DT$dens <- format_dcml(DT$dens) # Omit big_mark spacing for 4 digits DT$sp_wt <- format_dcml(DT$sp_wt, 4, big_mark = "") # Set significant digits (viscosity) to achieve a consistent string length DT[visc >= 0.001, temp_visc := format_dcml(visc, 5)] DT[visc < 0.001, temp_visc := format_dcml(visc, 4)] DT[, visc := temp_visc] DT[, temp_visc := NULL] # Will appear with big_mark spacing, change from Pa to kPa DT$bulk_mod_kPa <- format_dcml(DT$bulk_mod / 1000, 4) DT$bulk_mod <- NULL knitr::kable(DT, align = "r", caption = "Example 21.") # Set package options to default values formatdown_options(reset = TRUE)
Example 22.
Same table, but using power of ten formatting.
#| echo: false formatdown_options(size = "small")
# Use water data included with formatdown DT <- copy(water)[1:6] # Routine decimal formatting cols <- c("temp", "dens", "sp_wt") DT[, (cols) := lapply(.SD, function(x) format_dcml(x)), .SDcols = cols] # Power of ten DT$bulk_mod <- format_engr(DT$bulk_mod, 3) DT$visc <- format_engr(DT$visc, 4, set_power = -3) knitr::kable(DT, align = "r", caption = "Example 22.")
#| echo: false formatdown_options(reset = TRUE)
Example 23.
The metals
data set includes columns of text and decimal and power-of-ten numbers.
#| echo: false formatdown_options(size = "small")
# Use water data included with formatdown DT <- copy(metals) # Examine the data frame DT[] # Text DT$metal <- format_text(DT$metal) # Decimal cols <- c("dens", "thrm_cond") DT[, (cols) := lapply(.SD, function(x) format_dcml(x)), .SDcols = cols] # Power of ten cols <- c("elast_mod", "thrm_exp") DT[, (cols) := lapply(.SD, function(x) format_engr(x, 3)), .SDcols = cols] knitr::kable(DT, align = "lrrrr", caption = "Example 23.")
#| echo: false formatdown_options(reset = TRUE)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.