235 lines
8.6 KiB
Markdown
235 lines
8.6 KiB
Markdown
# `units`: A Quarto Extension for Standardized Scientific Unit Notation
|
||
|
||
|
||
This extension provides a centralized, extensible mechanism for the consistent rendering of physical quantities across Quarto-based scientific websites and publications.
|
||
It is designed principally for use in computational chemistry, biochemistry, and computer-aided drug design (CADD), disciplines in which a single document routinely reports energies, distances, timescales, concentrations, electrostatic potentials, and temperatures spanning many orders of magnitude and multiple unit systems.
|
||
|
||
## Motivation
|
||
|
||
The correct typographic and semantic treatment of physical quantities is governed by well-established conventions.
|
||
Most notably those of the International Bureau of Weights and Measures (BIPM) as codified in the SI Brochure, and their discipline-specific elaborations in the IUPAC *Quantities, Units and Symbols in Physical Chemistry* ("Green Book") and NIST Special Publication 811.
|
||
These conventions specify, among other things: upright (non-italic) typesetting of unit symbols; a non-breaking space between a numerical value and its associated unit; the use of negative exponents rather than stacked solidi for compound units; and unambiguous conversion factors between coherent and non-coherent units within a given physical dimension.
|
||
|
||
In practice, manuscripts and websites authored under time constraints tend to depart from these conventions inconsistently: for example, a bond length may be rendered as `1.54 Å` in one section and `1.54Å` (with an ordinary, breakable space) in another or an energy value may be transcribed from kJ·mol⁻¹ to kcal·mol⁻¹ by hand.
|
||
|
||
## Installation
|
||
|
||
You can install this Quarto extension with the following command:
|
||
|
||
```bash
|
||
quarto add https://git.scient.ing/infra/units-quarto-extension/archive/main.tar.gz
|
||
```
|
||
|
||
Following installation, confirm the presence of the extension within the project:
|
||
|
||
```text
|
||
_extensions/
|
||
└── units/
|
||
├── _extension.yml
|
||
└── units.lua
|
||
```
|
||
|
||
A minimal document using the extension should render without error:
|
||
|
||
```markdown
|
||
---
|
||
title: "Installation Check"
|
||
---
|
||
|
||
The bond length is {{< distance 1.54 angstrom >}}.
|
||
```
|
||
|
||
## Reference: Shortcodes
|
||
|
||
| Shortcode | Signature | Description |
|
||
|---|---|---|
|
||
| `unit` | `{{< unit <unit-key> >}}` | Renders the typeset symbol for a single unit, with no numerical value or conversion. |
|
||
| `sci` | `{{< sci <value> >}}` | Renders a bare numerical value in scientific notation, independent of any unit. |
|
||
| `energy` | `{{< energy <value> <unit> [<target-unit>] >}}` | Bulk (non-molar) energy: J, kJ, cal, kcal. |
|
||
| `molarenergy` | `{{< molarenergy <value> <unit> [<target-unit>] >}}` | Molar energy: J/mol, kJ/mol, cal/mol, kcal/mol, eV, hartree, cm⁻¹. |
|
||
| `distance` | `{{< distance <value> <unit> [<target-unit>] >}}` | Distance: angstrom, nanometer, picometer, bohr, meter. |
|
||
| `time` | `{{< time <value> <unit> [<target-unit>] >}}` | Time: second and its SI-prefixed subdivisions, plus minute, hour, day. |
|
||
| `concentration` | `{{< concentration <value> <unit> [<target-unit>] >}}` | Molar concentration: M, mM, μM, nM, pM, fM. |
|
||
| `voltage` | `{{< voltage <value> <unit> [<target-unit>] >}}` | Electrical potential: kV, V, mV, μV. |
|
||
| `temperature` | `{{< temperature <value> <unit> [<target-unit>] >}}` | Temperature: kelvin, celsius, fahrenheit (affine conversion). |
|
||
| `massconc` | `{{< massconc <value> <mass-unit> <molar-mass> <target-unit> >}}` | Mass-per-volume concentration converted to molar concentration given an explicit molar mass. |
|
||
|
||
Each quantity shortcode accepts an optional keyword argument, `notation=sci` or `notation=plain`, which overrides the automatic determination of numerical formatting described below.
|
||
|
||
## Supported Unit Categories
|
||
|
||
### Bulk Energy (base unit: joule)
|
||
|
||
| Unit key | Symbol | Notes |
|
||
|---|---|---|
|
||
| `J` | J | SI base representation |
|
||
| `kJ` | kJ | |
|
||
| `cal` | cal | Thermochemical calorie (1 cal = 4.184 J) |
|
||
| `kcal` | kcal | |
|
||
|
||
### Molar Energy (base unit: kJ·mol⁻¹)
|
||
|
||
| Unit key | Symbol | Notes |
|
||
|---|---|---|
|
||
| `J/mol` | J·mol⁻¹ | |
|
||
| `kJ/mol` | kJ·mol⁻¹ | |
|
||
| `cal/mol` | cal·mol⁻¹ | |
|
||
| `kcal/mol` | kcal·mol⁻¹ | |
|
||
| `eV` | eV | 1 eV = 96.485 kJ·mol⁻¹ |
|
||
| `hartree` | *E*ₕ | Atomic unit of energy; 1 hartree = 2625.5 kJ·mol⁻¹ |
|
||
| `cm-1` | cm⁻¹ | Wavenumber, as conventionally reported in vibrational spectroscopy |
|
||
|
||
### Distance (base unit: ångström)
|
||
|
||
| Unit key | Symbol | Notes |
|
||
|---|---|---|
|
||
| `angstrom` | Å | Rendered using U+00C5, the canonical (NFKC-normalized) form |
|
||
| `nanometer` | nm | |
|
||
| `picometer` | pm | |
|
||
| `bohr` | *a*₀ | Atomic unit of length |
|
||
| `meter` | m | |
|
||
|
||
### Time (base unit: second)
|
||
|
||
| Unit key | Symbol |
|
||
|---|---|
|
||
| `second` | s |
|
||
| `millisecond` | ms |
|
||
| `microsecond` | μs |
|
||
| `nanosecond` | ns |
|
||
| `picosecond` | ps |
|
||
| `femtosecond` | fs |
|
||
| `minute` | min |
|
||
| `hour` | h |
|
||
| `day` | d |
|
||
|
||
### Molar Concentration (base unit: molar)
|
||
|
||
| Unit key | Symbol |
|
||
|---|---|
|
||
| `molar` | M |
|
||
| `millimolar` | mM |
|
||
| `micromolar` | μM |
|
||
| `nanomolar` | nM |
|
||
| `picomolar` | pM |
|
||
| `femtomolar` | fM |
|
||
|
||
### Mass Concentration (base unit: mg·mL⁻¹)
|
||
|
||
| Unit key | Symbol |
|
||
|---|---|
|
||
| `mg/mL` | mg·mL⁻¹ |
|
||
| `μg/mL` | μg·mL⁻¹ |
|
||
| `ng/mL` | ng·mL⁻¹ |
|
||
|
||
This category is consumed exclusively by the `massconc` shortcode, which additionally requires a molar mass argument to compute the corresponding molar concentration.
|
||
|
||
### Voltage (base unit: volt)
|
||
|
||
| Unit key | Symbol |
|
||
|---|---|
|
||
| `kilovolt` | kV |
|
||
| `volt` | V |
|
||
| `millivolt` | mV |
|
||
| `microvolt` | μV |
|
||
|
||
### Temperature
|
||
|
||
| Unit key | Symbol | Conversion basis |
|
||
|---|---|---|
|
||
| `kelvin` | K | Identity (SI base unit; no degree sign, per convention) |
|
||
| `celsius` | °C | *T*(K) = *T*(°C) + 273.15 |
|
||
| `fahrenheit` | °F | *T*(K) = [*T*(°F) + 459.67] × 5/9 |
|
||
|
||
## Numerical Formatting
|
||
|
||
The rendered representation of a numerical value is determined automatically unless overridden by the `notation` keyword argument.
|
||
|
||
By default, a value is formatted to three significant figures using fixed decimal notation.
|
||
Should this formatting internally require exponential notation, the extension instead renders the value in explicit scientific notation, with the mantissa and a true superscript exponent joined by a non-breaking multiplication sign:
|
||
|
||
```markdown
|
||
{{< sci 6.02214076e23 >}}
|
||
```
|
||
|
||
renders as 6.022 × 10²³, rather than the unprocessed string `6.02e+23`.
|
||
|
||
## Worked Examples
|
||
|
||
### Distance
|
||
|
||
```markdown
|
||
The O–H bond length is {{< distance 0.96 angstrom >}}.
|
||
Converted to nanometers: {{< distance 1.54 angstrom nanometer >}}.
|
||
```
|
||
> The O–H bond length is 0.96 Å.
|
||
> Converted to nanometers: 1.54 Å (0.154 nm).
|
||
|
||
### Bulk Energy
|
||
|
||
```markdown
|
||
Combustion releases {{< energy 4.18 J >}} of heat under these conditions.
|
||
```
|
||
> Combustion releases 4.18 J of heat under these conditions.
|
||
|
||
### Molar Energy
|
||
|
||
```markdown
|
||
The activation barrier was {{< molarenergy 45.2 kJ/mol kcal/mol >}}.
|
||
A single-point DFT energy of {{< molarenergy 0.0421 hartree kcal/mol >}} was obtained.
|
||
```
|
||
> The activation barrier was 45.2 kJ·mol⁻¹ (10.8 kcal·mol⁻¹).
|
||
> A single-point DFT energy of 0.0421 *E*ₕ (110 kcal·mol⁻¹) was obtained.
|
||
|
||
### Time
|
||
|
||
```markdown
|
||
The production molecular dynamics simulation was extended to
|
||
{{< time 500 nanosecond microsecond >}}, using an integration timestep of
|
||
{{< time 2e-15 second femtosecond >}}.
|
||
```
|
||
> The production molecular dynamics simulation was extended to 500 ns
|
||
> (0.5 μs), using an integration timestep of 2 × 10⁻¹⁵ s (2 fs).
|
||
|
||
### Molar Concentration
|
||
|
||
```markdown
|
||
The compound exhibited a Kᵢ of {{< concentration 12 nanomolar >}}
|
||
against the target enzyme.
|
||
```
|
||
> The compound exhibited a Kᵢ of 12 nM against the target enzyme.
|
||
|
||
### Voltage
|
||
|
||
```markdown
|
||
Resting membrane potential was recorded at {{< voltage -70 millivolt >}}.
|
||
```
|
||
> Resting membrane potential was recorded at -70 mV.
|
||
|
||
### Temperature
|
||
|
||
```markdown
|
||
Assays were conducted at {{< temperature 25 celsius kelvin >}}, approximating
|
||
physiological temperature of {{< temperature 310.15 kelvin celsius >}}.
|
||
```
|
||
> Assays were conducted at 25 °C (298 K), approximating physiological
|
||
> temperature of 310.15 K (37 °C).
|
||
|
||
### Scientific Notation and Rate Constants
|
||
|
||
```markdown
|
||
The observed second-order rate constant was
|
||
{{< concentration 2.1e6 molar notation=sci >}}⁻¹·{{< unit second >}}⁻¹.
|
||
```
|
||
> The observed second-order rate constant was 2.1 × 10⁶ M⁻¹·s⁻¹.
|
||
|
||
### Mass-to-Molar Concentration Conversion
|
||
|
||
```markdown
|
||
A stock solution prepared at {{< massconc 0.5 mg/mL 350.4 micromolar >}}
|
||
was used for the binding assay.
|
||
```
|
||
> A stock solution prepared at 0.5 mg·mL⁻¹ (1.43 μM, MW 350.4 g/mol) was
|
||
> used for the binding assay.
|
||
|