formatting: Text and Number Formatting

In ratlas: ATLAS Formatting Functions and Templates

Text and Number Formatting

Description

These formatting functions are used to format numerical values in a consistent manner. This is useful for printing numbers inline with text, as well as for formatting tables. Many of the included formatting functions were adapted from TJ Mahr's printy package.

Usage

fmt_count(x, big_interval = 3L, big_mark = ",")

fmt_digits(
  x,
  digits = 3,
  fmt_small = FALSE,
  max_value = NULL,
  keep_zero = FALSE
)

fmt_leading_zero(x)

fmt_minus(x, output = NULL)

fmt_replace_na(x, replacement = "—")

fmt_corr(x, digits, output = NULL)

fmt_prop(x, digits, fmt_small = TRUE, keep_zero = FALSE)

fmt_prop_pct(x, digits = 0, fmt_small = TRUE)

Arguments

x	Number or number string to be formatted
big_interval	Interval indicating where to place numeric dividers
big_mark	Character used as mark between big interval before the decimal
digits	Number of decimal places to retain
fmt_small	Indicator for replacing zero with < (e.g., .000 becomes ⁠<.001⁠). Default is TRUE.
max_value	If fmt_small is TRUE and a ⁠max_value is supplied⁠, any value greater than the max_value is replaced with > (e.g., if max_value = 50, then 60 becomes ⁠>49.9⁠). The number of digits depends on digits.
keep_zero	If fmt_small is TRUE, whether to preserve true 0s (e.g., 0.0000001 becomes ⁠<.001⁠, but 0.0000000 stays .000).
output	The output type for the rendered document. One of "latex" or "html".
replacement	The value to use when replacing missing values

Details

fmt_count() is a wrapper for base::prettyNum(). Prints a number with a big_mark between every big_interval.

fmt_digits() is a wrapper for base::sprintf(). Prints a number with digits number of decimal places, without losing trailing zeros, as happens with base::round().

fmt_leading_zero() removes the leading zero for decimal values.

fmt_minus() replaces hyphens with the HTML minus sign (⁠−⁠).

fmt_replace_na() replaces NA values with a specified replacement. This is useful for formatting tables, when blanks are not desired. The default behavior is to replace missing values with an em-dash (⁠—⁠).

fmt_prop_pct() formats proportions as percentages. This takes a number bounded between 0 and 1, multiplies it by 100, and then rounds to the specified number of digits using fmt_digits().

Two additional formatters are provided to format numbers according to the American Psychological Association (APA) style guide. The 7th edition of the APA style guide specifies that numbers bounded between [-1, 1] should not include the leading zero (section 6.36; APA, 2020). This is the case for many types of numbers commonly used by ATLAS including correlations, proportions, probabilities, and p-values. The fmt_corr() function is used to format values bounded between [-1, 1]. Digits are first rounded to the specified number of digits using fmt_digits(), and then leading zeros are removed using fmt_leading_zero() and negative signs are replaced with fmt_minus(). The fmt_prop is very similar, but is intended for values between [0, 1]. This function also wraps fmt_digits() and fmt_leading_zero(). However, fmt_prop() also replaces small values to avoid values of 0 (e.g., .00 is replaced with ⁠< .01⁠).

Value

The updated character object of the same size as x.

References

American Psychological Association. (2020). Publication manual of the American Psychological Association (7th ed.). \Sexpr[results=rd]{tools:::Rd_expr_doi("doi:10.1037/0000165-000")}

See Also

Other formatters: fmt_table(), padding

Examples

test_cor <- cor(mtcars[, 1:4])
as.character(round(test_cor[1:4, 3], 2))
fmt_digits(test_cor[1:4, 3], 2)

fmt_digits(test_cor[1:4, 3], 2) %>%
  fmt_leading_zero()

fmt_digits(test_cor[1:4, 3], 2) %>%
  fmt_minus()

fmt_digits(c(test_cor[1:4, 3], NA_real_), 2) %>%
  fmt_replace_na(replacement = "&mdash;")

fmt_corr(test_cor[1:4, 3], 2)

fmt_prop(c(0.001, 0.035, 0.683), digits = 2)

ratlas documentation built on April 4, 2025, 12:22 a.m.