The fmt_units() method lets you better format measurement units in the table body. These must conform to the Great Tablesunits notation; as an example of this, "J Hz^-1 mol^-1" can be used to generate units for the molar Planck constant. The notation here provides several conveniences for defining units, so as long as the values to be formatted conform to this syntax, you’ll obtain nicely-formatted inline units. Details pertaining to units notation can be found in the section entitled How to use units notation.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
How To Use Units Notation
The Great Tables 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 "**"
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s use the illness dataset and create a new table. The units column happens to contain string values in units notation (e.g., "x10^9 / L"). Using the fmt_units() method here will improve the formatting of those measurement units.
The constants dataset contains values for hundreds of fundamental physical constants. We’ll take a subset of values that have some molar basis and generate a new display table from that. Like the illness dataset, this one has a units column so, again, the fmt_units() method will be used to format those units. Here, the preference for typesetting measurement units is to have positive and negative exponents (e.g., not "<unit_1> / <unit_2>" but rather "<unit_1> <unit_2>^-1").
from great_tables.data import constantsimport polars as plimport polars.selectors as csconstants_mini = ( pl.from_pandas(constants) .filter(pl.col("name").str.contains("molar")).sort("value") .with_columns( name=pl.col("name") .str.to_titlecase() .str.replace("Kpa", "kpa") .str.replace("Of", "of") ))( GT(constants_mini) .cols_hide(columns=["uncert", "sf_value", "sf_uncert"]) .fmt_units(columns="units") .fmt_scientific(columns="value", decimals=3) .tab_header(title="Physical Constants Having a Molar Basis") .tab_options(column_labels_hidden=True))
Physical Constants Having a Molar Basis
Molar Planck Constant
3.990 × 10−10
J Hz−1 mol−1
Electron Molar Mass
5.486 × 10−7
kg mol−1
Molar Volume of Silicon
1.206 × 10−5
m3 mol−1
Muon Molar Mass
1.134 × 10−4
kg mol−1
Molar Mass Constant
1.000 × 10−3
kg mol−1
Proton Molar Mass
1.007 × 10−3
kg mol−1
Neutron Molar Mass
1.009 × 10−3
kg mol−1
Tau Molar Mass
1.908 × 10−3
kg mol−1
Deuteron Molar Mass
2.014 × 10−3
kg mol−1
Helion Molar Mass
3.015 × 10−3
kg mol−1
Triton Molar Mass
3.016 × 10−3
kg mol−1
Alpha Particle Molar Mass
4.002 × 10−3
kg mol−1
Molar Mass of Carbon-12
1.200 × 10−2
kg mol−1
Molar Volume of Ideal Gas (273.15 K, 101.325 kpa)
2.241 × 10−2
m3 mol−1
Molar Volume of Ideal Gas (273.15 K, 100 kpa)
2.271 × 10−2
m3 mol−1
Molar Gas Constant
8.314
J mol−1 K−1
See Also
The define_units() function can be used as a standalone utility for working with units notation. It can parses strings in units notation and can emit formatted units with its .to_html() method.