formatdown: Formatting Numbers in 'rmarkdown' Documents

Description

Provides a small set of tools for formatting numbers in R-markdown documents. Convert a numerical vector to character strings in power-of-ten form, decimal form, or measurement-units form; convert symbols for chemical isotopes from hyphenated form to nuclear form; all are math-delimited for rendering as inline equations. Can also convert text into math-delimited text to match the font face and size of math-delimited numbers. Useful for rendering single numbers in inline R code chunks and for rendering columns in tables.

Author(s)

Maintainer: Richard Layton graphdoctor@gmail.com

See Also

Useful links:

• https://github.com/graphdr/formatdown/

• https://graphdr.github.io/formatdown/

• https://CRAN.R-project.org/package=formatdown

• Report bugs at https://github.com/graphdr/formatdown/issues

Air density measurements

Description

Table of air properties at room temperature and pressure, simulating multiple measurements at approximately steady state,

Usage

data(air_meas, package = "formatdown")

Format

Classes data.table and data.frame with 5 observations of 7 variables:

date

"Date" class format "YYYY-MM-DD".

trial

Character, label "a" through "e".

humid

Factor, humidity, "low", "med", or "high."

temp

Numeric, measured temperature (K).

pres

Numeric, measured atmospheric pressure (Pa).

sp_gas

Numeric, specific gas constant in mass form R_{sp}, ideal gas reference value, (J kg^{-1}K^{-1}).

dens

Numeric, calculated air density \rho = pR_{sp}^{-1}T^{-1} (kg m^{-3}).

Properties of standard atmosphere

Description

Table of atmospheric properties as a function of altitude, sea level to 1000 km.

Usage

data(atmos, package = "formatdown")

Format

Classes data.table and data.frame with 20 observations of 5 variables:

alt

Numeric, altitude (km)

temp

Numeric, air temperature (K)

pres

Numeric, atmospheric pressure (Pa)

dens

Numeric, air density (kg m^{-3})

sound

Numeric, speed of sound (m/s)

Source

Marks' Standard Handbook for Mechanical Engineers 9/e (1987) E.A. Avallone and T. Baumeister (ed.), "Table 4.2.2 International Standard Atmosphere", pp. 4-38, McGraw-Hill, NY.

Chemical elements

Description

Table of 118 chemical elements with name, symbol, atomic number, and mass numbers. Elements with more than one possible mass number have separate rows for each isotope.

Usage

data(element_set, package = "formatdown")

Format

Classes data.table and data.frame with 354 observations of 4 variables:

element

Character, element name, hydrogen (atomic number 1) through oganesson (atomic number 118).

symbol

Character, element symbol.

atomic_number

Character, 1-118.

mass_number

Character, 1-294.

Details

In "AZE" or "AZX" notation, "A" is the mass number, "Z" is the atomic number, and "E" or "X" is the element symbol.

Format numbers in decimal notation

Description

Convert a numeric vector to a character vector in which the numbers are formatted in decimal form and delimited for rendering as inline equations in an R markdown document.

Usage

format_dcml(
  x,
  digits = 4,
  ...,
  delim = formatdown_options("delim"),
  size = formatdown_options("size"),
  decimal_mark = formatdown_options("decimal_mark"),
  big_mark = formatdown_options("big_mark"),
  big_interval = formatdown_options("big_interval"),
  small_mark = formatdown_options("small_mark"),
  small_interval = formatdown_options("small_interval"),
  whitespace = formatdown_options("whitespace")
)

Arguments

Details

format_dcml() is a wrapper for the more general function format_numbers(). Where defaults are defined by formatdown_options(), users may reassign the arguments locally in the function call or globally using formatdown_options().

Arguments after the dots (...) must be referred to by name.

Value

A character vector in which numbers are formatted in decimal form and delimited for rendering as inline equations in an R markdown document.

See Also

Other format_*: format_engr(), format_nucl(), format_numbers(), format_sci(), format_text()

Examples

# input: single number
x <- 103400
format_dcml(x)

# input: units class
x <- 103400
units(x) <- "N m2 C-2"
format_dcml(x)

# input: vector
data("metals", package = "formatdown")
x <- metals$thrm_cond
format_dcml(x)

# significant digits
x <- 155.77
format_dcml(x, 2)
format_dcml(x, 3)
format_dcml(x, 4)

# input: data frame
x <- metals[, c("dens", "thrm_cond")]
as.data.frame(apply(x, 2, format_dcml, digits = 3))

# format_dcml() same as format_numbers(..., format = "dcml")
x <- 103400
format_dcml(x)
format_numbers(x, format = "dcml")

Format engineering notation

Description

Convert a numeric vector to a character vector in which the numbers are formatted in power-of-ten notation in engineering form and delimited for rendering as inline equations in an R markdown document.

Usage

format_engr(
  x,
  digits = 4,
  ...,
  omit_power = c(-1, 2),
  set_power = NULL,
  delim = formatdown_options("delim"),
  size = formatdown_options("size"),
  decimal_mark = formatdown_options("decimal_mark"),
  small_mark = formatdown_options("small_mark"),
  small_interval = formatdown_options("small_interval"),
  whitespace = formatdown_options("whitespace"),
  multiply_mark = formatdown_options("multiply_mark")
)

Arguments

Details

In engineering notation, all exponents are multiples of three. format_engr() is a wrapper for the more general function format_numbers(). Where defaults are defined by formatdown_options(), users may reassign the arguments locally in the function call or globally using formatdown_options().

Arguments after the dots (...) must be referred to by name.

Value

A character vector in which numbers are formatted in power-of-ten notation in engineering form and delimited for rendering as inline equations in an R markdown document.

See Also

Other format_*: format_dcml(), format_nucl(), format_numbers(), format_sci(), format_text()

Examples

# input: single number
x <- 6.0221E+23
format_engr(x)

# input: units class
x <- 103400
units(x) <- "N m2 C-2"
format_engr(x)

# input: vector
data("metals", package = "formatdown")
x <- metals$dens
format_engr(x)

# significant digits
x <- 9.75358e+5
format_engr(x, 2)
format_engr(x, 3)
format_engr(x, 4)

# input: data frame
x <- metals[, c("thrm_exp", "thrm_cond")]
as.data.frame(apply(x, 2, format_engr, digits = 3))

# format_engr() same as format_numbers(..., format = "engr")
x <- 6.0221E+23
format_engr(x)
format_numbers(x, format = "engr")

# omit_power
x <- 103400
format_engr(x, omit_power = c(-1, 2)) # default
format_engr(x, omit_power = c(-1, 5))
format_engr(x, omit_power = 5) # equivalent to omit_power = c(5, 5)

# omit_power = NULL, power-of-ten notation for all elements
x <- c(1.2, 103400)
format_engr(x)
format_engr(x, omit_power = NULL)

# omit_power applies to native exponent (before engr formatting)
x <- 103400
format_sci(x) # native exponent is 5
format_engr(x, omit_power = 5)

# omit_power applies to exponent after engr formatting
x <- 103400
format_engr(x) # engr exponent is 3
format_engr(x, omit_power = 3)

# set_power overrides default engineering exponent
x <- 103400
format_engr(x)
format_engr(x, set_power = 4)

# set_power overrides omit_power
x <- 103400
format_engr(x)
format_engr(x, omit_power = 3)
format_engr(x, omit_power = 3, set_power = 3)

Format isotopes in nuclear notation

Description

Convert chemical element or isotope from from hyphenated notation to nuclear notation.

Usage

format_nucl(
  x,
  face = "plain",
  ...,
  Z = formatdown_options("Z"),
  warn = formatdown_options("warn"),
  delim = formatdown_options("delim")
)

Arguments

Details

We start with a character string in hyphenated form X-A where X is the chemical symbol of an element and A is its mass number. For example, carbon 12 would be written as the string "C-12".

Given a character scalar, vector, or data frame column of isotopes in this form, format_nucl() constructs the form "$\\mathxx{^{A}X}$" where ⁠\\mathxx⁠ determines the font face: plain type is set by ⁠\\mathrm⁠; italic by ⁠\\mathit⁠; bold by ⁠\\mathbf⁠; sans serif by ⁠\\mathsf⁠; and monospace (typewriter text) by ⁠\\mathtt⁠. The result includes markup delimiters ⁠$...$⁠ for rendering (in an R markdown or Quarto markdown document) as an inline code chunk.

Unlike other functions in formatdown, format_nucl() does not support a size argument.

Value

A character vector of isotopes in nuclear notation with elements delimited as inline math markup in plain, italic, sans serif, bold, or monospace font face.

See Also

Other format_*: format_dcml(), format_engr(), format_numbers(), format_sci(), format_text()

Examples

# default arguments
x <- "C-12"
format_nucl(x)

# add atomic number
format_nucl(x, Z = TRUE)

# vector of isotopes
x <- c("C-12", "Fe-54", "U-238")
format_nucl(x, Z = TRUE)

# turn off the warning when using symbols
x <- "X-A"
format_nucl(x, Z = TRUE, warn = FALSE)

# change the typeface
x <- "C-12"
format_nucl(x, face = "bold")

# obtain all possible mass numbers for an element
element_set[symbol == "Ca"]

Format numbers

Description

Convert a numeric vector to a character vector in which the numbers are formatted in power-of-ten notation in scientific or engineering form and delimited for rendering as inline equations in an R markdown document. Decimal numbers can be similarly formatted, without the power-of-ten notation.

Usage

format_numbers(
  x,
  digits = 4,
  format = "engr",
  ...,
  omit_power = c(-1, 2),
  set_power = NULL,
  delim = formatdown_options("delim"),
  size = formatdown_options("size"),
  decimal_mark = formatdown_options("decimal_mark"),
  big_mark = formatdown_options("big_mark"),
  big_interval = formatdown_options("big_interval"),
  small_mark = formatdown_options("small_mark"),
  small_interval = formatdown_options("small_interval"),
  whitespace = formatdown_options("whitespace"),
  multiply_mark = formatdown_options("multiply_mark")
)

Arguments

Details

Given a number, a numerical vector, or a numerical column from a data frame, format_numbers() converts the numbers to character strings of the form, "$a \\times 10^{n}$", where a is the coefficient to a specified number of significant digits and n is the exponent. When used for decimal notation, format_numbers() converts numbers to character strings of the form "$a$".

Powers-of-ten notation is omitted over a range of exponents via omit_power such that numbers so specified are converted to decimal notation. For example, the default omit_power = c(-1, 2) formats numbers such as 0.123, 1.23, 12.3, and 123 in decimal form. To cancel these exceptions and convert all numbers to powers-of-ten notation, set the omit_power argument to NULL or NA.

Delimiters for inline math markup can be edited if necessary. If the default argument fails, try using "\\(" as an alternative. If using a custom delimiter to suit the markup environment, be sure to escape all special symbols.

When inputs are of class "units" (created with the units package), a math-text macro of the form ⁠\\mathrm{<units_string>}⁠ is appended to the formatted numerical value inside the math delimiters.

Arguments after the dots (...) must be referred to by name.

Value

A character vector in which numbers are formatted in power-of-ten or decimal notation and delimited for rendering as inline equations in an R markdown document.

See Also

Other format_*: format_dcml(), format_engr(), format_nucl(), format_sci(), format_text()

Examples

# input: single number
x <- 6.0221E+23
format_numbers(x)

# input: units class
x <- 103400
units(x) <- "N m2 C-2"
format_numbers(x)

# input: vector
data("metals", package = "formatdown")
x <- metals$dens
format_numbers(x)

# significant digits
x <- 9.75358e+5
format_numbers(x, 2)
format_numbers(x, 3)
format_numbers(x, 4)

# input: data frame
x <- metals[, c("thrm_exp", "thrm_cond")]
as.data.frame(apply(x, 2, format_sci, digits = 3))

# omit_power
x <- 103400
format_numbers(x, format = "sci", omit_power = c(-1, 2)) # default
format_numbers(x, format = "sci", omit_power = c(-1, 5))
format_numbers(x, format = "sci", omit_power = 5) # equivalent to omit_power = c(5, 5)

# omit_power = NULL, power-of-ten notation for all elements
x <- c(1.2, 103400)
format_numbers(x, format = "sci")
format_numbers(x, format = "sci", omit_power = NULL)

# set_power overrides default scientific exponent
x <- 103400
format_numbers(x, format = "sci")
format_numbers(x, format = "sci", set_power = 4)

# set_power overrides omit_power
x <- 103400
format_numbers(x, format = "sci")
format_numbers(x, format = "sci", omit_power = 5)
format_numbers(x, format = "sci", omit_power = 5, set_power = 4)

# decimal format overrides set_power
x <- 103400
format_numbers(x, format = "dcml")
format_numbers(x, format = "dcml", set_power = 3)

Format numbers in scientific notation

Description

Convert a numeric vector to a character vector in which the numbers are formatted in power-of-ten notation in scientific form and delimited for rendering as inline equations in an R markdown document.

Usage

format_sci(
  x,
  digits = 4,
  ...,
  omit_power = c(-1, 2),
  set_power = NULL,
  delim = formatdown_options("delim"),
  size = formatdown_options("size"),
  decimal_mark = formatdown_options("decimal_mark"),
  small_mark = formatdown_options("small_mark"),
  small_interval = formatdown_options("small_interval"),
  whitespace = formatdown_options("whitespace"),
  multiply_mark = formatdown_options("multiply_mark")
)

Arguments

Details

format_sci() is a wrapper for the more general function format_numbers(). Where defaults are defined by formatdown_options(), users may reassign the arguments locally in the function call or globally using formatdown_options().

Arguments after the dots (...) must be referred to by name.

Value

A character vector in which numbers are formatted in power-of-ten notation in scientific form and delimited for rendering as inline equations in an R markdown document.

See Also

Other format_*: format_dcml(), format_engr(), format_nucl(), format_numbers(), format_text()

Examples

# input: single number
x <- 6.0221E+23
format_sci(x)

# input: units class
x <- 103400
units(x) <- "N m2 C-2"
format_sci(x)

# input: vector
data("metals", package = "formatdown")
x <- metals$dens
format_sci(x)

# significant digits
x <- 9.75358e+5
format_sci(x, 2)
format_sci(x, 3)
format_sci(x, 4)

# input: data frame
x <- metals[, c("thrm_exp", "thrm_cond")]
as.data.frame(apply(x, 2, format_sci, digits = 3))

# format_sci() same as format_numbers(..., format = "sci")
x <- 6.0221E+23
format_sci(x)
format_numbers(x, format = "sci")

# omit_power
x <- 103400
format_sci(x, omit_power = c(-1, 2)) # default
format_sci(x, omit_power = c(-1, 5))
format_sci(x, omit_power = 5) # equivalent to omit_power = c(5, 5)

# omit_power = NULL, power-of-ten notation for all elements
x <- c(1.2, 103400)
format_sci(x)
format_sci(x, omit_power = NULL)

# set_power overrides default scientific exponent
x <- 103400
format_sci(x)
format_sci(x, set_power = 4)

# set_power overrides omit_power
x <- 103400
format_sci(x)
format_sci(x, omit_power = 5)
format_sci(x, omit_power = 5, set_power = 4)

Format text

Description

Convert a character vector to "math text" delimited for rendering as inline equations in an R markdown document. Particularly useful for matching the font face of character columns to that of numerical columns in a table.

Usage

format_text(
  x,
  face = "plain",
  ...,
  size = formatdown_options("size"),
  delim = formatdown_options("delim"),
  whitespace = formatdown_options("whitespace")
)

Arguments

Details

Given a scalar, vector, or data frame column, format_text() converts its argument to a character string of the form "$\\mathxx{a}$" where a is the element to be formatted and ⁠\\mathxx⁠ determines the font face: plain type is set by ⁠\\mathrm⁠; italic by ⁠\\mathit⁠; bold by ⁠\\mathbf⁠; sans serif by ⁠\\mathsf⁠; and monospace (typewriter text) by ⁠\\mathtt⁠. All strings include markup delimiters ⁠$...$⁠ for rendering (in an R markdown or Quarto markdown document) as an inline equation.

Value

A character vector with elements delimited as inline math markup in plain, italic, sans serif, bold, or monospace font face.

See Also

Other format_*: format_dcml(), format_engr(), format_nucl(), format_numbers(), format_sci()

Examples

# Text vector

# default face = "plain"
x <- air_meas$humid
format_text(x)

# equivalently
format_text(x, face = "plain")

# input vector
x <- c("Hello world!", "Goodbye blues!")
format_text(x)

# argument coerced to character string if possible
format_text(c(1.2, 2.3, 3.4))
format_text(x = NA)
format_text(x = c(TRUE, FALSE, TRUE))

# numbers as strings are rendered as-is
format_text(x = c("1.2E-3", "3.4E+0", "5.6E+3"))

# other font faces
format_text(x, face = "italic")
format_text(x, face = "bold")
format_text(x, face = "sans")
format_text(x, face = "mono")

Get and set function arguments via options

Description

Changes the default values of function arguments which affect the markup and appearance of formatdown results.

Usage

formatdown_options(..., reset = FALSE)

Arguments

Details

Global options are provided for arguments that users would 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.

The arguments that can be set with this function are as follows:

• delim: Character, length 1 or 2, to define the left and right math markup delimiters. The default setting, delim = "$", produces left and right delimiters ⁠$...$⁠. The alternate built-in setting, delim = "\\(", produces left and right delimiters ⁠\\( ... \\)⁠. Custom delimiters can be assigned in a vector of length 2 with left and right delimiter symbols, e.g., ⁠c("\\[", "\\]")⁠. Special characters typically must be escaped.

• size: Character, length 1, to assign a font size. If not empty, adds a font size macro to the markup inside the math delimiters. Possible values are "scriptsize", "small", "normalsize", "large", and "huge". One may also assign the equivalent LaTeX-style markup itself, e.g., "\\scriptsize", "\\small", etc. Default is NULL.

• decimal_mark: Character, length 1, to assign the decimal marker. Possible values are a period "." (default) or a comma ",". Passed to formatC(decimal.mark).

• big_mark: Character, length 1, used as the mark between every big_interval number of digits to the left of the decimal marker to improve readability. Possible values are empty "" (default) or "thin" to produce a LaTeX-style thin, horizontal space. One may also assign the thin-space markup itself "\\\\,". Passed to formatC(big.mark).

• big_interval: Integer, length 1, that defines the number of digits (default 3) in groups separated by big_mark. Passed to formatC(big.interval).

• small_mark: Character, length 1, used as the mark between every small_interval number of digits to the right of the decimal marker to improve readability. Possible values are empty "" (default) or "thin" to produce a LaTeX-style thin, horizontal space. One may also assign the thin-space markup itself "\\\\,". Passed to formatC(small.mark).

• small_interval: Integer, length 1, that defines the number of digits (default 5) in groups separated by small_mark. Passed to formatC(small.interval).

• whitespace: Character, length 1, to define the LaTeX-style math-mode macro to preserve a horizontal space between words of text or between physical-unit abbreviations when formatting numbers of class "units". Default is "\\\\ ". Alternatives include "\\\\:" or "⁠\\\\>⁠".

• multiply_mark: Character, length 1, to define the multiplication symbol in power of ten notation. Possible values are "\\times" (default) or a half-high dot "\\cdot" which is often used when the decimal mark is a comma.

• Z: Logical, length 1, default FALSE, used to determine whether or not the atomic number subscript is used in formatting nuclear notation of isotopes.

• warn: Logical, length 1, default TRUE, used to determine whether or not a warning is issued when an input for a chemical element in hyphenated notation contains an error in the element symbol or the mass number of the isotope.

Value

Nothing; used for its side-effect.

Examples

# Show all options
formatdown_options()

# Store existing settings, including any changes made by the user
old_settings <- formatdown_options()

# View one option
formatdown_options()$delim

# View multiple options
formatdown_options("size", "delim")

# Change options
formatdown_options(size = "small", delim = "\\(")
formatdown_options("size", "delim")

# Reset to default values
formatdown_options(reset = TRUE)
formatdown_options("size", "delim")

# Reset options to those before this example was run
do.call(formatdown_options, old_settings)

# Option effects

# delim
x <- 101300
format_dcml(x)
# equivalent to
format_dcml(x, delim = c("$", "$"))
# built-in alternate
format_dcml(x, delim = "\\(")
# equivalent to
format_dcml(x, delim = c("\\(", "\\)"))

# size
format_dcml(x, size = "small")
# equivalent to
format_dcml(x, size = "\\small")
# other possible values
format_dcml(x, size = "scriptsize")
format_dcml(x, size = "large")
format_dcml(x, size = "huge")
# default NULL
format_dcml(x, size = NULL)
# renders equivalent to
format_dcml(x, size = "normalsize")

# decimal_mark
y <- 6.02214076E+10
format_sci(y, 5, decimal_mark = ".")
format_sci(y, 5, decimal_mark = ",")

# big_mark
format_dcml(y, 9)
format_dcml(y, 9, big_mark = "thin")
# equivalent to
format_dcml(y, 9, big_mark = "\\\\,")

# big_interval
format_dcml(y, 9, big_mark = "thin", big_interval = 3)
format_dcml(y, 9, big_mark = "thin", big_interval = 5)

# small_mark
z <- 1.602176634e-8
format_sci(z, 10)
format_sci(z, 10, small_mark = "thin")
format_sci(z, 10, small_mark = "\\\\,")
format_engr(z, 10, small_mark = "thin")

# small_interval
format_sci(z, 10, small_mark = "thin", small_interval = 3)
format_sci(z, 10, small_mark = "thin", small_interval = 5)
format_engr(z, 10, small_mark = "thin", small_interval = 5)

# whitespace in text
p <- "Hello world!"
format_text(p)
# equivalent to
format_text(p, whitespace = "\\\\ ")
# alternates
format_text(p, whitespace = "\\\\:")
format_text(p, whitespace = "\\\\>")

# whitespace in physical units expression
x <- pi
units(x) <- "m/s"
format_dcml(x)
# equivalent to
format_dcml(x, whitespace = "\\\\ ")

# multiply_mark
x <- 101300
format_engr(x, decimal_mark = ".", multiply_mark = "\\times")
format_engr(x, decimal_mark = ",", multiply_mark = "\\cdot")

Properties of metals

Description

Table of mechanical and thermal properties of selected metals.

Usage

data(metals, package = "formatdown")

Format

Classes data.table and data.frame with 6 observations of 5 variables:

metal

Character, name of material

dens

Numeric, density (kg m^{-3})

thrm_exp

Numeric, coefficient of thermal expansion (m m^{-1}K^{-1})

thrm_cond

Numeric, thermal conductivity (W m^{-1}K^{-1})

elast_mod

Numeric, modulus of elasticity (Pa)

Source

Marks' Standard Handbook for Mechanical Engineers 9/e (1987) E.A. Avallone and T. Baumeister (ed.), "Basic Properties of Several Metals", pp. 6-11, McGraw-Hill, NY.

Properties of water

Description

Table of water properties at atmospheric pressure as a function of temperature.

Usage

data(water, package = "formatdown")

Format

Classes data.table and data.frame with 11 observations of 5 variables:

temp

Numeric, temperature (K)

dens

Numeric, density (kg m^{-3})

sp_wt

Numeric, specific weight (N m^{-3})

visc

Numeric, dynamic viscosity (Pa s)

bulk_mod

Numeric, bulk modulus (Pa)

Source

E. Maurer E and I. Embry (2022) hydraulics: Basic Pipe and Open Channel Hydraulics, R package ver. 0.6.0, https://edm44.github.io/hydraulics/.