nomogram 0.1.0__py3-none-any.whl

nomogram/plot.py

@@ -0,0 +1,176 @@
+# SPDX-FileCopyrightText: 2026 Miki
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Plots of comparisons, with matplotlib (extra ``viz``).
+
+matplotlib is imported inside the functions only, so that the package
+works without it; a missing extra gives an explicit message
+(``pip install nomogram[viz]``).
+
+Values outside a formulation's validity domain are NaN (see
+:meth:`nomogram.model.Formulation.evaluate`), so they show as gaps in the
+curves: the domains are visible on the plot.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from nomogram.comparison import Comparison
+from nomogram.expression import to_latex
+from nomogram.model import Notation
+from nomogram.semantics import semantic_catalog
+
+__all__ = ["plot_deviations", "plot_values"]
+
+
+def _pyplot() -> Any:
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError as exc:
+        msg = "nomogram.plot needs matplotlib: install the extra, nomogram[viz]"
+        raise ImportError(msg) from exc
+    return plt
+
+
+def _axes(ax: Any) -> Any:
+    if ax is not None:
+        return ax
+    _, created = _pyplot().subplots()
+    return created
+
+
+def _abscissa(comparison: Comparison, kind: str | None) -> tuple[str, Any]:
+    """The input plotted along x: its label and its values."""
+    if kind is None:
+        varying = [k for k, q in comparison.inputs.items() if np.ndim(q.magnitude) == 1]
+        if len(varying) != 1:
+            msg = (
+                "choose the input to plot along x with input_kind; "
+                f"one-dimensional inputs: {', '.join(sorted(varying)) or 'none'}"
+            )
+            raise ValueError(msg)
+        kind = varying[0]
+    if kind not in comparison.inputs:
+        msg = f"no input of kind {kind!r} in the comparison"
+        raise ValueError(msg)
+    quantity = comparison.inputs[kind]
+    kinds = semantic_catalog().quantity_kinds
+    name = kinds[kind].label if kind in kinds else kind
+    return f"{name} [{quantity.units:~P}]", np.asarray(quantity.magnitude, dtype=float)
+
+
+#: Line styles taken in turn once the colour cycle (10 colours) is used up.
+_LINESTYLES = ("-", "-.", ":")
+
+
+def _style(index: int) -> dict[str, str]:
+    """Distinct styles beyond ten curves: the colour cycle repeats."""
+    return {"linestyle": _LINESTYLES[(index // 10) % len(_LINESTYLES)]}
+
+
+def _label(comparison: Comparison, key: str) -> str:
+    formulation = comparison.formulations.get(key)
+    label = getattr(formulation, "label", None)
+    return str(label) if label else key
+
+
+def plot_deviations(
+    comparison: Comparison, *, input_kind: str | None = None, ax: Any = None
+) -> Any:
+    """Plot the relative deviation of each formulation from the reference, in %.
+
+    Parameters
+    ----------
+    comparison : Comparison
+        The result of :func:`nomogram.comparison.compare`.
+    input_kind : str, optional
+        Quantity kind of the input plotted along x; needed only when
+        several inputs are one-dimensional arrays.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; new ones are created otherwise.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The axes, for further customisation.
+
+    Raises
+    ------
+    ImportError
+        If matplotlib is not installed (extra ``viz``).
+    ValueError
+        If the input to plot along x cannot be determined.
+    """
+    x_label, x = _abscissa(comparison, input_kind)
+    ax = _axes(ax)
+    others = [k for k in comparison.relative_deviations if k != comparison.reference]
+    for index, key in enumerate(others):
+        deviation = comparison.relative_deviations[key]
+        values = np.broadcast_to(np.asarray(deviation, dtype=float), x.shape)
+        ax.plot(x, 100 * values, label=_label(comparison, key), **_style(index))
+    ax.axhline(0.0, color="0.4", linewidth=0.8, linestyle="--")
+    ax.set_xlabel(x_label)
+    ax.set_ylabel(f"Deviation from {_label(comparison, comparison.reference)} [%]")
+    ax.legend(fontsize="small")
+    return ax
+
+
+def plot_values(
+    comparison: Comparison,
+    *,
+    input_kind: str | None = None,
+    notation: Notation | None = None,
+    ax: Any = None,
+) -> Any:
+    """Plot the values of each formulation, the reference included.
+
+    Parameters
+    ----------
+    comparison : Comparison
+        The result of :func:`nomogram.comparison.compare`.
+    input_kind : str, optional
+        Quantity kind of the input plotted along x.
+    notation : Notation, optional
+        Notation of the y-axis symbol (for example the WMO one); the
+        identifier's default rendering otherwise.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; new ones are created otherwise.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The axes, for further customisation.
+
+    Raises
+    ------
+    ImportError
+        If matplotlib is not installed (extra ``viz``).
+    ValueError
+        If the input to plot along x cannot be determined.
+    """
+    import sympy
+
+    x_label, x = _abscissa(comparison, input_kind)
+    ax = _axes(ax)
+    for index, (key, quantity) in enumerate(comparison.values.items()):
+        values = np.broadcast_to(np.asarray(quantity.magnitude, dtype=float), x.shape)
+        style = (
+            {"color": "black", "linestyle": "--"}
+            if key == comparison.reference
+            else _style(index)
+        )
+        ax.plot(x, values, label=_label(comparison, key), **style)
+    reference = comparison.formulations.get(comparison.reference)
+    unit = comparison.values[comparison.reference].units
+    if reference is not None:
+        symbols = dict(notation.symbols) if notation else {}
+        symbol = to_latex(sympy.Symbol(reference.output.identifier), symbols)
+        ax.set_ylabel(f"${symbol}$ [{unit:~P}]")
+    else:
+        ax.set_ylabel(f"[{unit:~P}]")
+    ax.set_xlabel(x_label)
+    ax.legend(fontsize="small")
+    return ax

nomogram/semantics.py

@@ -0,0 +1,333 @@
+# SPDX-FileCopyrightText: 2026 Miki
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Quantity kinds, units and CF standard names, from bundled QUDT and CF subsets.
+
+nomogram does not build its own ontology. It bundles a frozen subset of
+`QUDT <https://qudt.org/>`_ (quantity kinds and unit definitions, CC BY
+4.0) and of the `CF standard name table <https://cfconventions.org/>`_
+(CC0 1.0), extracted at development time by
+``scripts/extract_semantics.py``. Nothing is fetched at run time.
+
+On top of QUDT, nomogram states the scale type of each kind and whether
+it is a difference (QUDT's *delta quantity*, OM's ``Measure``) or a point;
+the scale type decides which units apply (offset units only for
+interval-scale kinds). Links to external vocabularies (Wikidata...) are
+:class:`ExternalMatch` objects carrying a SKOS relation and the date they
+were last verified. ``docs/rosetta.md`` maps this vocabulary.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+from functools import lru_cache
+from importlib.resources import files
+from types import MappingProxyType
+from typing import Any
+
+from nomogram.units import ScaleType
+
+__all__ = [
+    "CFStandardName",
+    "ExternalMatch",
+    "MatchRelation",
+    "QuantityKind",
+    "SemanticCatalog",
+    "UnitDefinition",
+    "semantic_catalog",
+]
+
+_DIMENSION_VECTOR = re.compile(
+    r"^A(-?\d+)E(-?\d+)L(-?\d+)I(-?\d+)M(-?\d+)H(-?\d+)T(-?\d+)D([01])$"
+)
+
+#: Base dimensions of a QUDT dimension vector, in order.
+_BASE_DIMENSIONS = (
+    "amount_of_substance",
+    "electric_current",
+    "length",
+    "luminous_intensity",
+    "mass",
+    "temperature",
+    "time",
+)
+
+
+class MatchRelation(Enum):
+    """SKOS mapping relation between a nomogram object and an external one."""
+
+    EXACT = "exact"
+    CLOSE = "close"
+    BROAD = "broad"
+    NARROW = "narrow"
+
+    @property
+    def skos(self) -> str:
+        """IRI of the corresponding SKOS property."""
+        return f"http://www.w3.org/2004/02/skos/core#{self.value}Match"
+
+
+@dataclass(frozen=True)
+class ExternalMatch:
+    """Link from a nomogram object to an object of an external vocabulary.
+
+    Attributes
+    ----------
+    target : str
+        IRI of the external object, for example a Wikidata entity.
+    relation : MatchRelation
+        How close the two objects are. Links imported from QUDT's
+        ``wikidataMatch``, a plain annotation, are close matches.
+    verified : datetime.date
+        Date the link was last verified against its source.
+    """
+
+    target: str
+    relation: MatchRelation
+    verified: datetime.date
+
+
+def _dimensions(vector: str) -> Mapping[str, int]:
+    match = _DIMENSION_VECTOR.match(vector)
+    if match is None:
+        msg = f"invalid QUDT dimension vector: {vector!r}"
+        raise ValueError(msg)
+    exponents = (int(e) for e in match.groups()[:7])
+    return MappingProxyType(
+        {d: e for d, e in zip(_BASE_DIMENSIONS, exponents, strict=True) if e}
+    )
+
+
+@dataclass(frozen=True)
+class QuantityKind:
+    """A quantity kind, from QUDT or defined by nomogram, with its scale typing.
+
+    Kinds defined by nomogram (absent from QUDT) specialize a QUDT kind
+    and have no IRI yet: their local name is stable and will become the
+    end of a persistent IRI once nomogram has one.
+
+    Attributes
+    ----------
+    name : str
+        Local name, for example ``"CelsiusTemperature"``.
+    origin : str
+        ``"qudt"`` or ``"nomogram"``.
+    iri : str or None
+        QUDT IRI; ``None`` for a kind defined by nomogram.
+    label : str
+        English label.
+    dimension_vector : str
+        QUDT dimension vector, for example ``"A0E0L0I0M0H1T0D0"``.
+    specialization_of : str or None
+        QUDT local name of the kind this one specializes.
+    scale_type : ScaleType
+        Scale of the kind's values (nomogram's addition).
+    delta : bool
+        Whether values are differences rather than points (nomogram's
+        addition; QUDT's ``isDeltaQuantity`` is set on no kind).
+    cf_standard_names : tuple of str
+        CF standard names for this kind.
+    applicable_units : tuple of str
+        QUDT local names of the units that apply.
+    added_units : tuple of str
+        The applicable units QUDT does not declare, added by nomogram.
+    matches : tuple of ExternalMatch
+        Links to external vocabularies.
+    """
+
+    name: str
+    origin: str
+    iri: str | None
+    label: str
+    dimension_vector: str
+    specialization_of: str | None
+    scale_type: ScaleType
+    delta: bool
+    cf_standard_names: tuple[str, ...]
+    applicable_units: tuple[str, ...]
+    added_units: tuple[str, ...]
+    matches: tuple[ExternalMatch, ...]
+
+    @property
+    def dimensions(self) -> Mapping[str, int]:
+        """Non-zero exponents of the base dimensions, by dimension name."""
+        return _dimensions(self.dimension_vector)
+
+
+@dataclass(frozen=True)
+class UnitDefinition:
+    """A QUDT unit definition, with its pint expression.
+
+    A value v in this unit is ``(v + offset) * multiplier`` in the coherent
+    SI unit of the same dimension (QUDT's conversion rule).
+
+    Attributes
+    ----------
+    name : str
+        QUDT local name, for example ``"DEG_C"``.
+    iri : str
+        QUDT IRI.
+    label : str
+        QUDT English label.
+    symbol : str or None
+        QUDT symbol (the glyph).
+    dimension_vector : str
+        QUDT dimension vector.
+    multiplier : float
+        QUDT ``conversionMultiplier``.
+    offset : float
+        QUDT ``conversionOffset``; non-zero for offset units such as
+        ``DEG_C``.
+    ucum : str or None
+        UCUM code.
+    udunits : str or None
+        UDUNITS code.
+    pint : str
+        Expression of the unit in pint, for example ``"degC"``.
+    matches : tuple of ExternalMatch
+        Links to external vocabularies.
+    """
+
+    name: str
+    iri: str
+    label: str
+    symbol: str | None
+    dimension_vector: str
+    multiplier: float
+    offset: float
+    ucum: str | None
+    udunits: str | None
+    pint: str
+    matches: tuple[ExternalMatch, ...]
+
+    @property
+    def dimensions(self) -> Mapping[str, int]:
+        """Non-zero exponents of the base dimensions, by dimension name."""
+        return _dimensions(self.dimension_vector)
+
+
+@dataclass(frozen=True)
+class CFStandardName:
+    """A CF standard name and its canonical unit.
+
+    Attributes
+    ----------
+    name : str
+        The standard name, for example ``"relative_humidity"``.
+    canonical_units : str
+        CF canonical unit, in UDUNITS syntax (``"kg m-3"``).
+    pint : str
+        The same unit as a pint expression (``"kg * m ** -3"``).
+    """
+
+    name: str
+    canonical_units: str
+    pint: str
+
+
+@dataclass(frozen=True)
+class SemanticCatalog:
+    """The bundled subsets, read-only.
+
+    Attributes
+    ----------
+    quantity_kinds : mapping of str to QuantityKind
+        By QUDT local name.
+    units : mapping of str to UnitDefinition
+        By QUDT local name.
+    cf_standard_names : mapping of str to CFStandardName
+        By standard name.
+    qudt_version : str
+        QUDT release the subset was extracted from.
+    cf_version : str
+        CF standard name table version.
+    extracted : datetime.date
+        Extraction date.
+    """
+
+    quantity_kinds: Mapping[str, QuantityKind]
+    units: Mapping[str, UnitDefinition]
+    cf_standard_names: Mapping[str, CFStandardName]
+    qudt_version: str
+    cf_version: str
+    extracted: datetime.date
+
+
+def _matches(items: list[dict[str, str]]) -> tuple[ExternalMatch, ...]:
+    return tuple(
+        ExternalMatch(
+            target=item["target"],
+            relation=MatchRelation(item["relation"]),
+            verified=datetime.date.fromisoformat(item["verified"]),
+        )
+        for item in items
+    )
+
+
+def _kind(name: str, data: dict[str, Any]) -> QuantityKind:
+    return QuantityKind(
+        name=name,
+        origin="qudt",
+        iri=data["iri"],
+        label=data["label"],
+        dimension_vector=data["dimension_vector"],
+        specialization_of=data["specialization_of"],
+        scale_type=ScaleType(data["scale_type"]),
+        delta=data["delta"],
+        cf_standard_names=tuple(data["cf_standard_names"]),
+        applicable_units=tuple(data["applicable_units"]),
+        added_units=tuple(data["added_units"]),
+        matches=_matches(data["matches"]),
+    )
+
+
+def _unit(name: str, data: dict[str, Any]) -> UnitDefinition:
+    return UnitDefinition(
+        name=name,
+        iri=data["iri"],
+        label=data["label"],
+        symbol=data["symbol"],
+        dimension_vector=data["dimension_vector"],
+        multiplier=data["multiplier"],
+        offset=data["offset"],
+        ucum=data["ucum"],
+        udunits=data["udunits"],
+        pint=data["pint"],
+        matches=_matches(data["matches"]),
+    )
+
+
+@lru_cache(maxsize=1)
+def semantic_catalog() -> SemanticCatalog:
+    """Return the bundled QUDT and CF subsets.
+
+    The file is read once; the catalog is immutable and shared.
+
+    Returns
+    -------
+    SemanticCatalog
+        Quantity kinds, unit definitions and CF standard names.
+    """
+    resource = files("nomogram") / "data" / "semantics.json"
+    data = json.loads(resource.read_text(encoding="utf-8"))
+    sources = data["sources"]
+    return SemanticCatalog(
+        quantity_kinds=MappingProxyType(
+            {n: _kind(n, d) for n, d in data["quantity_kinds"].items()}
+        ),
+        units=MappingProxyType({n: _unit(n, d) for n, d in data["units"].items()}),
+        cf_standard_names=MappingProxyType(
+            {
+                n: CFStandardName(n, d["canonical_units"], d["pint"])
+                for n, d in data["cf_standard_names"].items()
+            }
+        ),
+        qudt_version=sources["qudt"]["version"],
+        cf_version=sources["cf_standard_names"]["version"],
+        extracted=datetime.date.fromisoformat(sources["extracted"]),
+    )

nomogram/units.py

@@ -0,0 +1,118 @@
+# SPDX-FileCopyrightText: 2026 Miki
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Units: a private pint registry and the scale rules nomogram relies on.
+
+nomogram uses `pint <https://pint.readthedocs.io/>`_ as its unit engine,
+so that quantity values coming from MetPy or xarray (pint-xarray) are
+accepted as they are. A pint ``Quantity`` (magnitude and unit) is what
+QUDT calls a ``QuantityValue`` and the VIM a *quantity value* (1.19).
+nomogram's own registry is created once, here, and never modified
+afterwards: nomogram never touches pint's global application registry.
+
+Scale semantics follow the SI Brochure (9th edition, section 2.3.1): the
+degree Celsius is equal in magnitude to the kelvin; what is offset is the
+quantity *Celsius temperature*, t = T - T0 with T0 = 273.15 K. pint, like
+QUDT (``qudt:conversionOffset``), carries that offset in the unit. In
+pint terms, a Celsius temperature is a *point* expressed in ``degC`` and
+a temperature difference is expressed in ``delta_degC`` or ``K`` (OM's
+``Point`` and ``Measure``; QUDT's *delta quantity*). pint refuses
+ambiguous operations such as adding two temperature points
+(:class:`pint.errors.OffsetUnitCalculusError`).
+
+Quantity kinds (thermodynamic temperature, Celsius temperature,
+temperature difference...) come with the bundled QUDT and CF subsets.
+``docs/rosetta.md`` maps this vocabulary across QUDT, the SI, pint, SymPy,
+CF and OM.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+import pint
+
+__all__ = ["Q_", "ScaleType", "convert", "is_offset_unit", "ureg"]
+
+#: The registry used by nomogram. Created once; never modified afterwards.
+ureg: pint.UnitRegistry = pint.UnitRegistry()
+
+#: Shortcut for building quantities in nomogram's registry.
+Q_ = ureg.Quantity
+
+
+class ScaleType(Enum):
+    """Type of quantity-value scale (VIM 1.27; QUDT ``qudt:ScaleType``).
+
+    A ratio scale has a natural zero (kelvin, pascal): ratios of values are
+    meaningful. An interval scale has a conventional origin (Celsius
+    temperature): only differences are meaningful, and its values are
+    points relative to that origin. QUDT also has ordinal and nominal
+    scales; formulas do not need them, so they are left out.
+    """
+
+    RATIO = "ratio"
+    INTERVAL = "interval"
+
+
+def is_offset_unit(unit: object) -> bool:
+    """Tell whether a unit carries an offset, i.e. expresses points of an interval scale.
+
+    A unit carries an offset (QUDT ``conversionOffset``; pint's
+    non-multiplicative units) when its zero is not the zero of the
+    corresponding base unit: 0 degC is 273.15 K, whereas 0 delta_degC is
+    0 K. The test relies on pint's public conversion only.
+
+    Parameters
+    ----------
+    unit : str or pint.Unit
+        Unit name or unit object; it is read by name in nomogram's
+        registry.
+
+    Returns
+    -------
+    bool
+        ``True`` for units such as ``degC`` or ``degF``; ``False`` for
+        multiplicative units such as ``K``, ``Pa`` or ``delta_degC``.
+    """
+    zero = Q_(0.0, str(unit)).to_base_units().magnitude
+    return bool(zero != 0.0)
+
+
+def convert(quantity: Any, unit: str) -> Any:
+    """Convert a quantity value to ``unit``, accepting other pint registries.
+
+    Values built with another pint registry (MetPy's, for instance) are
+    first rebuilt in nomogram's registry from their magnitude and unit
+    name, so that pint does not reject the mix of registries.
+
+    Parameters
+    ----------
+    quantity : pint.Quantity
+        The quantity value to convert (pint's name for it is kept); its
+        magnitude may be a number or a numpy array.
+    unit : str
+        Target unit, for example ``"K"``, ``"hPa"`` or ``"delta_degC"``.
+
+    Returns
+    -------
+    pint.Quantity
+        The converted quantity value, in nomogram's registry.
+
+    Raises
+    ------
+    pint.errors.DimensionalityError
+        If the target unit does not have the dimension of the value.
+    TypeError
+        If ``quantity`` is not a pint quantity.
+    """
+    if not isinstance(quantity, pint.Quantity):
+        msg = f"expected a pint quantity, got {type(quantity).__name__}"
+        raise TypeError(msg)
+    native = (
+        quantity
+        if quantity._REGISTRY is ureg
+        else Q_(quantity.magnitude, str(quantity.units))
+    )
+    return native.to(unit)