---
title: "Global settings"
vignette: >
  %\VignetteIndexEntry{Global settings}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output: rmarkdown::html_vignette
bibliography: ../inst/REFERENCES.bib
csl: ../inst/information-science-and-technology.csl
link-citations: yes
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

# 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
)
```

![](../man/figures/options-img.png){width=70%}    
<small>*option* by Mike Lawrence is licensed under CC BY 2.0 DEED <https://creativecommons.org/licenses/by/2.0/>.</small>

<br>

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

```r
formatdown_options(delim = "$",
                   size = NULL,
                   decimal_mark = ".",
                   big_mark = "",
                   big_interval = 3,
                   small_mark = "",
                   small_interval = 5,
                   whitespace = "\\\\>", 
                   multiply_mark = "\\times", 
                   reset = FALSE)
```

To reset all formatdown arguments to their default values: 

```r
    formatdown_options(reset = TRUE)
```



<br>

*Usage.* &nbsp; For example, get two of the current settings.

```{r}
formatdown_options("size", "decimal_mark")
```

Assign new settings; examine result. 

```{r}
# Set
formatdown_options(size = "large", decimal_mark = ",")

# Examine result
formatdown_options("size", "decimal_mark")
```

Reset to default values; examine result.

```{r}
# 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("\\[", "\\]")`.

<br>

*Examples.* &nbsp; Note that using `format_text()` introduces additional markup inside the delimiters. Details are described in the [Format text](format_text.html) article. 

```{r}
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 = "\\(")
```

<br>

Examples 1--4 (in inline code chunks) render as, 

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

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

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

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

<br>


## 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"`. 



<br>

*Examples.*

```{r}
# 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")
```

<br>

Examples 5--9 render as, 

5. `r format_dcml(x, size = "scriptsize")`

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

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

5. `r format_text(txt)`

5. `r format_text(txt, size = "large")`

<br>


*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).  

```{r}
#| 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`. 

<br>

*Examples.*

```{r}
# 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 = ",")
```


<br>

Examples 10 and 11 render as, 

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

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

<br>



## 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.  

<br>


*Examples.*

```{r}
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")
```


<br>

Examples 12--17 render as, 

12. `r format_dcml(w, size = "small")`

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

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

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

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

12. `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|"\\\\ "|}$. 


<br>

*Examples.*

```{r}
# 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 = "\\\\ ")
```

<br>

Examples 18--20 render as, 

18. `r format_text(txt, size = "small")` 

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

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



## Multiplication symbol

The default symbol used in power of ten notation is "$\small\times$", as in $\small 3.14 \times 10^{-3}$. An alternate---often used when the decimal marker is a comma---is the centered dot, e.g., $\small 3,14 \cdot 10^{-3}$. 

The symbol is set using the `multiply_mark` argument. The default setting is `"\\times"`; the alternate, centered-dot setting, is `"\\cdot"`. 

<br>

*Examples.*

```{r}
# 21. Alternate multiplication symbol
y <- 1.602176634e-19
format_sci(y, 5, decimal_mark = ",", multiply_mark = "\\cdot")
```

<br>

Example 21 renders as:

21. `r format_sci(y, 5, decimal_mark = ",", multiply_mark = "\\cdot", size = "small")`

<br>

## Applications


*Example 22.*

In this example, we format different columns of a data frame using `decimal_mark`, `big_mark` and `small_mark`. 

```{r}
#| echo: false
formatdown_options(size = "small")
```

```{r}
# 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 22.")

# Set package options to default values
formatdown_options(reset = TRUE)
```

<br>

*Example 23.*

Same table, but using power of ten formatting. 

```{r}
#| echo: false
formatdown_options(size = "small")
```

```{r}
# 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 23.")
```

```{r}
#| echo: false
formatdown_options(reset = TRUE)
```

<br>

*Example 24.*

The `metals` data set includes columns of text and  decimal and power-of-ten numbers. 

```{r}
#| echo: false
formatdown_options(size = "small")
```

```{r}
# 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 24.")
```

```{r}
#| echo: false
formatdown_options(reset = TRUE)
```





## References