define_units: Define measurement units with *gt*'s units notation

View source: R/helpers.R

define_unitsR Documentation

Define measurement units with gt's units notation


The define_units() function is available for working with text in gt's units notation.





Text in specialized units notation

⁠scalar<character>⁠ // required

A single string that defines the units (e.g., "m/s") to be used.


An object of class units_definition.

How to use gt's units notation

The units notation involves a shorthand of writing units that feels familiar and is fine-tuned for the task at hand. Each unit is treated as a separate entity (parentheses and other symbols included) and the addition of subscript text and exponents is flexible and relatively easy to formulate. This is all best shown with examples:

  • "m/s" and "m / s" both render as "m/s"

  • "m s^-1" will appear with the "-1" exponent intact

  • "m /s" gives the the same result, as "/<unit>" is equivalent to "<unit>^-1"

  • "E_h" will render an "E" with the "h" subscript

  • "t_i^2.5" provides a t with an "i" subscript and a "2.5" exponent

  • "m[_0^2]" will use overstriking to set both scripts vertically

  • "g/L %C6H12O6%" uses a chemical formula (enclosed in a pair of "%" characters) as a unit partial, and the formula will render correctly with subscripted numbers

  • Common units that are difficult to write using ASCII text may be implicitly converted to the correct characters (e.g., the "u" in "ug", "um", "uL", and "umol" will be converted to the Greek mu symbol; "degC" and "degF" will render a degree sign before the temperature unit)

  • We can transform shorthand symbol/unit names enclosed in ":" (e.g., ":angstrom:", ":ohm:", etc.) into proper symbols

  • Greek letters can added by enclosing the letter name in ":"; you can use lowercase letters (e.g., ":beta:", ":sigma:", etc.) and uppercase letters too (e.g., ":Alpha:", ":Zeta:", etc.)

  • The components of a unit (unit name, subscript, and exponent) can be fully or partially italicized/emboldened by surrounding text with "*" or "**"

Function ID


Function Introduced

In Development

See Also

Other helper functions: adjust_luminance(), cell_borders(), cell_fill(), cell_text(), cells_body(), cells_column_labels(), cells_column_spanners(), cells_footnotes(), cells_grand_summary(), cells_row_groups(), cells_source_notes(), cells_stub_grand_summary(), cells_stub_summary(), cells_stubhead(), cells_stub(), cells_summary(), cells_title(), currency(), default_fonts(), escape_latex(), from_column(), google_font(), gt_latex_dependencies(), html(), md(), nanoplot_options(), pct(), px(), random_id(), stub(), system_fonts()

gt documentation built on Oct. 7, 2023, 9:07 a.m.