define_units

define_units(units_notation)

With define_units() you can work with a specially-crafted units notation string and emit the units as HTML (with the .to_html() method). This function is useful as a standalone utility and it powers the fmt_units() method in Great Tables.

Parameters

Name	Type	Description	Default
`units_notation`	`str`	A string of units notation.	required

Returns

Type	Description
`UnitDefinitionList`	A list of unit definitions.

Specification Of Units Notation

The following table demonstrates the various ways in which units can be specified in the units_notation string and how the input is processed by the define_units() function. The concluding step for display of the units in HTML is to use the to_html() method.

rule	input	output
'^' creates a superscript	m^2	m²
'_' creates a subscript	h_0	h₀
subscripts and superscripts can be combined	h_0^3	h₀³
use '[_subscript^superscript]' to create an overstrike	h[_0^3]	h3 0
a '/' at the beginning adds the superscript '-1'	/s	s⁻¹
hyphen is transformed to minus sign when preceding a unit	-h^2	−h²
'x' at the beginning is transformed to '×'	x10^3 kg^2 m^-1	×10³ kg² m⁻¹
ASCII terms from biology/chemistry turned into terminology forms	ug	µg
can create italics with '' or '_'; create bold text with '*' or '__'	m^2	m²
special symbol set surrounded by colons	:permille:C	‰C
chemistry notation: '%C6H6%'	g/L %C6H12O6%	g/L C₆H₁₂O₆

Examples

Let’s demonstrate a use case where we utilize define_units() to render an equation as the subtitle in the table header, which currently doesn’t accept unit notation as input.

We’ll start by creating a Polars DataFrame representing the calculations of the equation \(y= a_2x^2 + a_1x + a_0\).

Code

import polars as pl
from great_tables import GT, html, define_units

df = pl.DataFrame(
    {"x": [1, 2, 3], "a2": [2, 3, 4], "a1": [3, 4, 5], "a0": [4, 5, 6]}
).with_columns(
    y=(
        pl.col("a2").mul(pl.col("x").pow(2))
        + pl.col("a1").mul(pl.col("x"))
        + pl.col("a0")
    )
)

df

shape: (3, 5)

x	a2	a1	a0	y
i64	i64	i64	i64	i64
1	2	3	4	9
2	3	4	5	25
3	4	5	6	57

If we try to use unit annotations to format the equation as the subtitle in the header, it won’t work as expected:

(
    GT(df)
    .cols_label(a2="{{a_2}}", a1="{{a_1}}", a0="{{a_0}}")
    .tab_header(title="Linear Algebra", subtitle="y={{a_2}}{{x^2}}+{{a_1}}x+{{a_0}}")
)

x	a₂	a₁	a₀	y
Linear Algebra
y={{a_2}}{{x^2}}+{{a_1}}x+{{a_0}}
1	2	3	4	9
2	3	4	5	25
3	4	5	6	57

To address this, we can create a small helper function, u2html(), which wraps a given string in define_units() and emits the units to HTML. Next, we can build the subtitle by applying u2html() to the string with unit annotations. Finally, we pass the assembled subtitle string through html() to ensure it renders correctly.

def u2html(x: str) -> str:
    return define_units(x).to_html()


subtitle = (
    "y"
    + "="
    + u2html("{{a_2}}")
    + u2html("{{x^2}}")
    + "+"
    + u2html("{{a_1}}")
    + "x"
    + "+"
    + u2html("{{a_0}}")
)

(
    GT(df)
    .cols_label(a2="{{a_2}}", a1="{{a_1}}", a0="{{a_0}}")
    .tab_header(title="Linear Algebra", subtitle=html(subtitle))
)

x	a₂	a₁	a₀	y
Linear Algebra
y=a₂x²+a₁x+a₀
1	2	3	4	9
2	3	4	5	25
3	4	5	6	57