Global settings"

In formatdown: Formatting Numbers in 'rmarkdown' Documents

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

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,

1. r format_dcml(x, size = "small")

2. r format_dcml(x, delim = "\\(", size = "small")

3. r format_text(txt, size = "small")

4. r format_text(txt, delim = "\\(", size = "small")

Font size

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,

1. r format_dcml(x, size = "scriptsize")

2. r format_dcml(x, size = "small")

3. r format_sci(6.0221e+23, size = "small")

4. r format_text(txt)

5. 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")

Decimal separator

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,

1. r format_dcml(x, 5, decimal_mark = ",", size = "small")

2. r format_sci(y, 5, decimal_mark = ",", size = "small")

Separating digits

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,

1. r format_dcml(w, size = "small")

2. r format_dcml(w, big_mark = "thin", size = "small")

3. r format_dcml(x, big_mark = "\\\\,", size = "small")

4. r format_dcml(y, small_mark = "\\\\,", size = "small")

5. r format_dcml(y, small_mark = "\\\\,", small_interval = 3, size = "small")

6. r format_dcml(z, 12, big_mark = "thin", small_mark = "\\\\,", size = "small")

Preserving text spaces

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,

1. r format_text(txt, size = "small")

2. r format_text(txt, whitespace = "\\\\:", size = "small")

3. r format_text(txt, whitespace = "\\\\ ", size = "small")

Applications

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)

References

formatdown documentation built on May 29, 2024, 8:21 a.m.