-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
235 lines (164 loc) · 7.42 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
---
output: github_document
---
<!-- Edit README.Rmd (not README.md) -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library("formatdown")
library("data.table")
# data.table printout
options(
datatable.print.nrows = 15,
datatable.print.topn = 3,
datatable.print.class = TRUE
)
```
<!-- Correcting for problems with LaTeX math in the README file only -->
# formatdown <img src="man/figures/logo.png" align="right">
Formatting Numbers in R Markdown Documents
<!-- badges: start -->
[](https://cran.r-project.org/package=formatdown)
[](https://github.com/graphdr/formatdown/actions/workflows/check-standard.yaml)
[](https://app.codecov.io/gh/graphdr/formatdown?branch=main)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->
Provides a small set of tools for formatting numbers in R markdown documents (file type `.Rmd` or `.qmd`). Converts a numerical vector to *character strings* in power-of-ten form, decimal form, or measurement-units form; all are math-delimited within quotation marks for rendering as inline equations. Useful for rendering numerical scalars using inline R code chunks or for rendering numerical columns in tables.
## Introduction
In professional technical prose, large and small numbers are generally typeset using powers of ten notation. For example, Planck's constant would be typeset as $6.63 \times 10^{-34}$ J/Hz rather than the familiar forms we use in communicating with computers, such as `6.63*10^-34` or `6.63E-34`.
The functions in this package help an author of an R markdown document convert large and small numbers to character strings, formatted using powers-of-ten notation. In addition, decimal numbers and text can be formatted with the same font face and size as the power-of-ten numbers for a consistent typeface across all columns of a data table.
Formatting tools include:
**`format_numbers()`**
: Convert a numeric vector to a math-delimited character vector in which the numbers can be formatted in scientific or engineering power-of-ten notation or in decimal form. Three convenience functions that wrap `format_numbers()` are provided as well: `format_sci()` for scientific notation, `format_engr()` for engineering notation, and `format_dcml()` for decimal notation.
**`format_text()`**
: Convert a character vector to math-delimited character vector. Useful for creating a consistent typeface across all columns of a table.
**`formatdown_options()`**
: 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.
## Usage
```{r}
# Packages
library("formatdown")
library("data.table")
library("knitr")
```
*Scalar values.* Typically rendered inline:
```{r}
x <- 101300
# Scientific notation
format_numbers(x, digits = 4, format = "sci")
# Engineering notation
format_numbers(x, digits = 4, format = "engr")
# Decimal notation
format_numbers(x, digits = 4, format = "dcml")
# With measurement units
units(x) <- "Pa"
units(x) <- "hPa"
format_dcml(x)
```
which, in an `.Rmd` or `.qmd` output document, are rendered using inline R code as
```{r}
#| echo: false
x <- 101300
sci <- format_sci(x)
engr <- format_engr(x)
dcml <- format_dcml(x)
units(x) <- "Pa"
units(x) <- "hPa"
hPa <- format_dcml(x)
DT <- wrapr::build_frame(
"Format", "Rendered as" |
"scientific", sci |
"engineering", engr |
"decimal", dcml |
"units", hPa
)
setDT(DT)
knitr::kable(DT, align = "r")
```
<br>
*Data frame*. Typically rendered in a table. We independently format columns from the `metals` data frame included with formatdown.
```{r}
# View the data set
metals
# First column in text format
DT <- copy(metals)
DT$metal <- format_text(DT$metal)
# Density and thermal conductivity in decimal form
cols_we_want <- c("dens", "thrm_cond")
DT[, cols_we_want] <- lapply(DT[, ..cols_we_want], function(x) format_dcml(x, 3))
# Thermal expansion in engineering format
DT$thrm_exp <- format_engr(DT$thrm_exp, 3)
# Elastic modulus in units form
units(DT$elast_mod) <- "Pa"
units(DT$elast_mod) <- "GPa"
DT$elast_mod <- format_dcml(DT$elast_mod, 3)
# Render in document
knitr::kable(DT,
align = "r",
caption = "Table 1: Properties of metals.",
col.names = c("Metal", "Density [kg/m$^3$]", "Therm. expan. [m/m K$^{-1}$]", "Therm. cond. [W/m K$^{-1}$]", "Elastic modulus")
)
```
<br>
*Options*. For users who prefer a comma as the decimal mark, the argument can be set once using `formatdown_options()`. If desired, we can also change the multiplication symbol to a half-high dot.
```{r}
formatdown_options(decimal_mark = ",", multiply_mark = "\\cdot")
```
Using the same code as above to format the metals data yields,
```{r}
#| echo: false
# First column in text format
DT <- copy(metals)
DT$metal <- format_text(DT$metal)
# Density and thermal conductivity in decimal form
cols_we_want <- c("dens", "thrm_cond")
DT[, cols_we_want] <- lapply(DT[, ..cols_we_want], function(x) format_dcml(x, 3))
# Thermal expansion in engineering format
DT$thrm_exp <- format_engr(DT$thrm_exp, 3)
# Elastic modulus in units form
units(DT$elast_mod) <- "Pa"
units(DT$elast_mod) <- "GPa"
DT$elast_mod <- format_dcml(DT$elast_mod, 3)
# Render in document
knitr::kable(DT,
align = "r",
caption = "Table 2: Changing the decimal mark",
col.names = c("Metal", "Density [kg/m$^3$]", "Therm. expan. [m/m K$^{-1}$]", "Therm. cond. [W/m K$^{-1}$]", "Elastic modulus")
)
```
<br>
To return to the default values,
```{r}
formatdown_options(reset = TRUE)
```
## Installation
Install from CRAN.
```r
install.packages("formatdown")
```
The development version can be installed from GitHub. I suggest using the "pak" package:
```r
pak::pkg_install("graphdr/formatdown")
```
## Requirements
- [`R`](https://www.r-project.org/) (\>= 3.5.0)
- [`data.table`](https://rdatatable.gitlab.io/data.table/) (\>= 1.9.8)
## Contributing
To provide feedback or report a bug,
- Use the GitHub <a href="https://github.com/graphdr/formatdown/issues">
Issues</a> page.
To contribute to formatdown,
- Please clone this repo locally.
- Commit your contribution on a separate branch.
- Submit a pull request
Participation in this open source project is subject to a [Code of
Conduct](https://graphdr.github.io/formatdown/CONDUCT.html).
## Software credits
- [`R`](https://www.r-project.org/) and [`RStudio`](https://posit.co/) for the working environment
- [`rmarkdown`](https://CRAN.R-project.org/package=rmarkdown) and [`knitr`](https://CRAN.R-project.org/package=knitr) for authoring tools
- [`data.table`](https://CRAN.R-project.org/package=data.table) for its programmable syntax
- [`units`](https://CRAN.R-project.org/package=units) for handling physical units
- [`wrapr`](https://CRAN.R-project.org/package=wrapr), [`checkmate`](https://CRAN.R-project.org/package=checkmate), and [`tinytest`](https://CRAN.R-project.org/package=tinytest) for programming tools
- [`devtools`](https://CRAN.R-project.org/package=devtools) and [`pkgdown`](https://CRAN.R-project.org/package=pkgdown) for package building