Background

My first attempt to provide powers-of-ten formatting was in my 2016 package, docxtools. That implementation has several shortcomings.

I wrote its formatting function to accept a data frame as input, which entailed a lot of programming overhead to separate numerical from non-numerical variable classes and to reassemble them after the numerical columns were formatted. This could have been simplified with judicious use of lapply(), with which I was not sufficiently experienced at the time. I also failed to take advantage of formatC() in constructing the output.

With formatdown, my goal is to provide similar functionality but with more concise code, greater flexibility, and a more balanced approach to package dependencies.

Improvements

The primary design change is that the format_power() function operates on a numerical vector instead of a data frame. The benefits of this change are: 1) simpler code that should be easier to revise and maintain; 2) scalar values can be formatted for rendering inline; and 3) data frames can still be formatted, by column, using lapply().

To illustrate formatting a scalar value inline, the markup for Avogadro’s number (x = 6.0221E+23) in engineering format is given by,

    $N_A =$ `r format_power(x, digits = 5, format = "engr")`

which is rendered (in this output document) as .

The second improvement is the addition of an option for scientific notation. For example, the markup for Avogadro’s number in scientific notation is given by,

    $N_A =$ `r format_power(x, digits = 5, format = "sci")`

which renders as .

The third improvement is the addition of an option for omitting powers-of-ten notation over a range of exponents. For example, the markup for x = 1.23E-4 in decimal notation is given by,

    $x =$ `r format_power(x = 1.234E-4, omit_power = c(-4, 0))`

which renders as .

A final (internal) improvement is a more balanced approach to package dependencies. With a tighter focus on what formatdown is to accomplish compared to docxtools, I have reduced the dependencies to checkmate, wrapr, and data.table.

The package vignette illustrates package usage in detail.

However, having successfully submitted the package to CRAN, I started working on this post and immediately (!) uncovered an issue that had not appeared while working on the package vignettes.

Delimiter issue

I wrote the package vignette using the rmarkdown::html_vignette output style per usual. All the formatted output rendered as expected in that document. I write this blog using quarto. As seen in the examples above, inline math is rendered as expected.

The issue arises when using knitr::kable() and kableExtra::kbl() to display data tables in this blog post. To illustrate, consider this data frame, included with formatdown (ideal gas properties of air at room temperature).

density

         date  trial humidity    T_K   p_Pa     R  density
       <Date> <char>   <fctr>  <num>  <num> <int>    <num>
1: 2018-06-12      a      low 294.05 101100   287 1.197976
2: 2018-06-13      b     high 294.15 101000   287 1.196384
3: 2018-06-14      c   medium 294.65 101100   287 1.195536
4: 2018-06-15      d      low 293.35 101000   287 1.199647
5: 2018-06-16      e     high 293.85 101100   287 1.198791

Formatting the pressure column, the markup looks OK.

DT <- copy(density)
DT$p_Pa <- format_power(DT$p_Pa, 4)
DT

         date  trial humidity    T_K                   p_Pa     R  density
       <Date> <char>   <fctr>  <num>                 <char> <int>    <num>
1: 2018-06-12      a      low 294.05 $101.1\\times{10}^{3}$   287 1.197976
2: 2018-06-13      b     high 294.15 $101.0\\times{10}^{3}$   287 1.196384
3: 2018-06-14      c   medium 294.65 $101.1\\times{10}^{3}$   287 1.195536
4: 2018-06-15      d      low 293.35 $101.0\\times{10}^{3}$   287 1.199647
5: 2018-06-16      e     high 293.85 $101.1\\times{10}^{3}$   287 1.198791

knitr::kable() yields the expected output with pressure formatted in engineering notation.

R code

knitr::kable(DT, align = "r")

date	trial	humidity	T_K	p_Pa	R	density
2018-06-12	a	low	294.05		287	1.197976
2018-06-13	b	high	294.15		287	1.196384
2018-06-14	c	medium	294.65		287	1.195536
2018-06-15	d	low	293.35		287	1.199647
2018-06-16	e	high	293.85		287	1.198791

kableExtra::kbl(DT, align = "r")

knitr::kable(DT, align = "r")

# Substitute math delimiters
sub_delim <- function(x) {
  x <- sub("\\$", "\\\\(", x) # first $
  x <- sub("\\$", "\\\\)", x) # second $
}

DT$p_Pa <- sub_delim(DT$p_Pa)
DT

         date  trial humidity    T_K                       p_Pa     R  density
       <Date> <char>   <fctr>  <num>                     <char> <int>    <num>
1: 2018-06-12      a      low 294.05 \\(101.1\\times{10}^{3}\\)   287 1.197976
2: 2018-06-13      b     high 294.15 \\(101.0\\times{10}^{3}\\)   287 1.196384
3: 2018-06-14      c   medium 294.65 \\(101.1\\times{10}^{3}\\)   287 1.195536
4: 2018-06-15      d      low 293.35 \\(101.0\\times{10}^{3}\\)   287 1.199647
5: 2018-06-16      e     high 293.85 \\(101.1\\times{10}^{3}\\)   287 1.198791

knitr::kable(DT, align = "c")

kableExtra::kbl(DT, align = "c")

library("kableExtra")

var_names <- c("Date", "Trial", "Humidity", "Temperature", "Pressure", "Gas constant", "Density" )
var_units <- c("", "", "", "[K]", "[Pa]", "[J/(kg K)]", "[kg/m\\(^3\\)]")
var_align <- "r"

DT |> 
  kbl(align = var_align, col.names = var_units) |>
  column_spec(1:6, color = "black", background = "white") |>
  add_header_above(header = var_names, align = var_align, background = "#c7eae5", line_sep = 0) |>
  kable_paper(lightable_options = "basic", full_width = TRUE)

    format_power(x, digits, format, omit_power, delim)

Fixed exponents

Preparing this post, I adapted a table of water properties from the hydraulics package to use as an example and discovered another, more subtle issue. First, I’ll construct the data frame.

# Construct a table of water properties
temperature     <- seq(0, 45, 10) + 273.15
density         <- c(1000, 1000, 998, 996, 992)
specific_weight <- c(9809, 9807, 9793, 9768, 9734)
viscosity       <- c(173, 131, 102, 81.7, 67.0) * 1E-8
bulk_modulus    <- c(202, 210, 218, 225, 228) * 1E+7

water <- data.table(temperature, density, specific_weight, viscosity,  bulk_modulus)

water

   temperature density specific_weight viscosity bulk_modulus
         <num>   <num>           <num>     <num>        <num>
1:      273.15    1000            9809  1.73e-06     2.02e+09
2:      283.15    1000            9807  1.31e-06     2.10e+09
3:      293.15     998            9793  1.02e-06     2.18e+09
4:      303.15     996            9768  8.17e-07     2.25e+09
5:      313.15     992            9734  6.70e-07     2.28e+09

DT <- copy(water)

# 5 signif digits
cols_to_format <- c("temperature")
DT[, (cols_to_format) := lapply(.SD, function(x) format_power(x, 5)), .SDcols = cols_to_format]

# 4 signif digits
cols_to_format <- c("specific_weight")
DT[, (cols_to_format) := lapply(.SD, function(x) format_power(x, 4)), .SDcols = cols_to_format]

# 3 signif digits
cols_to_format <- c("viscosity", "bulk_modulus")
DT[, (cols_to_format) := lapply(.SD, function(x) format_power(x)), .SDcols = cols_to_format]

# 3 signif digits omit powers
cols_to_format <- c("density")
DT[, (cols_to_format) := lapply(.SD, function(x) format_power(x, omit_power = c(0, 3))), .SDcols = cols_to_format]

# change the delimiters
DT <- DT[, lapply(.SD, function(x) sub_delim(x))]

# Table 
DT |> 
  kbl(align = "cclrrrr") |>
  kable_paper(lightable_options = "basic", full_width = TRUE) |>
  row_spec(0, background = "#c7eae5") |>
  column_spec(1:5, color = "black", background = "white")

# Manually edit strings to illustrate
DT$viscosity[4] <- "\\(0.82\\times{10}^{-6}\\)"
DT$viscosity[5] <- "\\(0.67\\times{10}^{-6}\\)"

# Table 
DT |> 
  kbl(align = "cclrrrr") |>
  kable_paper(lightable_options = "basic", full_width = TRUE) |>
  row_spec(0, background = "#c7eae5") |>
  column_spec(1:5, color = "black", background = "white")

Units

And now for something completely different!

Thinking about measurement units, I looked for relevant R packages and found units. With appropriate units, powers-of-ten notation can be practically eliminated. For example, a pressure reading of Pa can be reported as GPa.

To illustrate, I start with the basic water data,

water

   temperature density specific_weight viscosity bulk_modulus
         <num>   <num>           <num>     <num>        <num>
1:      273.15    1000            9809  1.73e-06     2.02e+09
2:      283.15    1000            9807  1.31e-06     2.10e+09
3:      293.15     998            9793  1.02e-06     2.18e+09
4:      303.15     996            9768  8.17e-07     2.25e+09
5:      313.15     992            9734  6.70e-07     2.28e+09

With tools from the units package, I can define a symbol uP to represent micropoise (a non-SI viscosity unit equal to 10 Pa-s). And I can write a short function to convert the numbers from basic units to displayed units, for example, converting Pa to GPa (gigapascal) or Pa-s to P (micropoise).

library("units")

# Define the uP units
install_unit("uP", "micropoise", "micropoise")

# Function to assign and convert units 
assign_units <- function(x, base_unit, display_unit) {
  
  # convert x to "Units" class in base units
  units(x) <- base_unit
  
  # convert from basic to display units
  units(x) <- as_units(display_unit)
  
  # return value
  x
}

Convert each column and output the results.

# Apply to one variable at a time
DT <- copy(water)
DT$temperature     <- assign_units(DT$temperature, "K", "degree_C")
DT$density         <- assign_units(DT$density, "kg/m^3", "kg/m^3")
DT$specific_weight <- assign_units(DT$specific_weight, "N/m^3", "kN/m^3")
DT$viscosity       <- assign_units(DT$viscosity, "Pa*s", "uP")
DT$bulk_modulus    <- assign_units(DT$bulk_modulus, "Pa", "GPa")

# Output
DT |> 
  kbl(align = "r") |>
  kable_paper(lightable_options = "basic", full_width = TRUE) |>
  row_spec(0, background = "#c7eae5") |>
  column_spec(1:5, color = "black", background = "white") 

The entries in the data frame are still numeric but are of the “Units” class, enabling math operations among values with compatible units. See the units website for details.

str(DT)

Classes 'data.table' and 'data.frame':  5 obs. of  5 variables:
 $ temperature    : Units: [°C] num  0 10 20 30 40
 $ density        : Units: [kg/m^3] num  1000 1000 998 996 992
 $ specific_weight: Units: [kN/m^3] num  9.81 9.81 9.79 9.77 9.73
 $ viscosity      : Units: [uP] num  17.3 13.1 10.2 8.17 6.7
 $ bulk_modulus   : Units: [GPa] num  2.02 2.1 2.18 2.25 2.28
 - attr(*, ".internal.selfref")=<externalptr> 

If I were to refine this table further, I would report the numerical values without labels in each cell, moving the unit labels to a sub-header row. Possible future work.

Closing

The new formatdown package formats numbers in powers-of-ten notation for inline math markup. A new argument is already in the works for managing the math delimiters. Potential new features include a fixed power-of-tens option as well as replacing powers-of-ten notation with deliberate manipulation of physical units.