Formatting Tools for R Markdown Documents
Provides a small set of tools for formatting tasks when creating documents in R Markdown or Quarto Markdown. Convert the elements of a numerical vector to character strings in one of several forms: powers-of-ten notation in engineering or scientific form delimited for rendering as inline equations; integer or decimal notation delimited for equation rendering; numbers with measurement units (non-delimited) where units are selected to eliminate the need for powers-of-ten or scientific notation. Useful for rendering a numerical scalar in an inline R code chunk as well as formatting columns of data frames displayed in a table.
Introduction
In professional technical prose, large and small numbers are generally typeset using powers of ten notation. For example, Plank’s constant would be typeset as 6.626 × 10−34 J/Hz rather than the familiar forms we use in communicating with computers, such as 6.626*10^34 or 6.626E-34.
The functions in this package help an author convert large and small numbers to character strings, formatted using powers-of-ten notation (and other formats) suitable for use in technical writing or presentations.
Formatting tools include:
format_power()
Convert the elements of a numerical vector to character strings in which the numbers are formatted using powers-of-ten notation in scientific or engineering form and delimited for rendering as inline equations in .Rmd or .qmd markdown files.
format_decimal()
Similar to above, but as integers or decimals
format_units()
Format a vector of numbers as character strings with measurement units appended via the ‘units’ package.
Usage
# Packages
library("formatdown")
library("data.table")
library("knitr")Scalar values. Typically rendered inline:
x <- 101300
# Scientific notation, math delimited
format_power(x, digits = 4, format = "sci")
#> [1] "$1.013 \\times 10^{5}$"
# Engineering notation, math-delimited
format_power(x, digits = 4, format = "engr")
#> [1] "$101.3 \\times 10^{3}$"
# Decimal notation, math-delimited
format_decimal(x, digits = 0, big_mark = ",")
#> [1] "$101,300$"
# Unit notation, non-delimited
units(x) <- "Pa"
format_units(x, unit = "hPa")
#> [1] "1013 [hPa]"which, in an .Rmd or .qmd output document, are rendered using inline R code as
| Notation | Rendered as |
|---|---|
| scientific | 1.013 × 105 |
| engineering | 101.3 × 103 |
| integer or decimal | 101, 300 |
| units | 1013 [hPa] |
Data frame. Typically rendered as a table. We independently format columns from the water data frame included with formatdown.
# Extract three columns
properties <- water[, .(temp, visc, bulk_mod)]
# Decimal notation
properties[, temp := format_decimal(temp, 1)]
# Power-of-ten notation with fixed exponent
properties[, visc := format_power(visc, set_power = -3)]
# Power-of-ten notation with 3 significant figures
properties[, bulk_mod := format_power(bulk_mod, 3)]
# Unit notation
properties$bulk_mod_GPa <- water$bulk_mod
units(properties$bulk_mod_GPa) <- "Pa"
properties[, bulk_mod_GPa := format_units(bulk_mod_GPa, 3, unit = "GPa")]
# Render in document
knitr::kable(properties,
align = "r",
caption = "Table 1: Properties of water as a function of temperature.",
col.names = c("Temperature [K]", "Viscosity [Pa-s]", "Bulk modulus [Pa]", "Bulk modulus [GPa]")
)| Temperature [K] | Viscosity [Pa-s] | Bulk modulus [Pa] | Bulk modulus [GPa] |
|---|---|---|---|
| 273.1 | 1.734 × 10−3 | 2.02 × 109 | 2.02 [GPa] |
| 283.1 | 1.310 × 10−3 | 2.10 × 109 | 2.10 [GPa] |
| 293.1 | 1.021 × 10−3 | 2.18 × 109 | 2.18 [GPa] |
| 303.1 | 0.8174 × 10−3 | 2.25 × 109 | 2.25 [GPa] |
| 313.1 | 0.6699 × 10−3 | 2.28 × 109 | 2.28 [GPa] |
| 323.1 | 0.5605 × 10−3 | 2.29 × 109 | 2.29 [GPa] |
| 333.1 | 0.4776 × 10−3 | 2.28 × 109 | 2.28 [GPa] |
| 343.1 | 0.4135 × 10−3 | 2.25 × 109 | 2.25 [GPa] |
| 353.1 | 0.3631 × 10−3 | 2.20 × 109 | 2.20 [GPa] |
| 363.1 | 0.3229 × 10−3 | 2.14 × 109 | 2.14 [GPa] |
| 373.1 | 0.2902 × 10−3 | 2.07 × 109 | 2.07 [GPa] |
Table 1: Properties of water as a function of temperature.
Installation
Install from CRAN.
install.packages("formatdown")The development version can be installed from GitHub.
install.packages("pak")
pak::pkg_install("graphdr/formatdown")Requirements
-
R(>= 3.5.0) -
data.table(>= 1.9.8)
Contributing
To contribute to formatdown,
- Please clone this repo locally.
- Commit your contribution on a separate branch.
- If you submit a function, please use the checkmate package to include runtime argument checks.
To provide feedback or report a bug,
- Use the GitHub Issues page.
- Please run the package unit tests and report the results with your bug report. Any user can run the package tests by installing the tinytest package and running:
# Detailed test results
test_results <- tinytest::test_package("formatdown")
as.data.frame(test_results)Participation in this open source project is subject to a Code of Conduct.