Source code for lair

"""
lair: tools for land-air interactions research.

lair is a toolkit, one module per topic: import the module you need, as in
``from lair.meteorology import poisson`` (the API reference lists them). The
package itself holds what the modules share: the unit registry
:data:`units` with its :data:`mass_flux` context, and
:func:`setup_ccg_filter`, which ``import lair`` calls. It also re-exports
:mod:`lair.config`, :func:`~lair.records.ftp_download` and
:func:`~lair.records.unzip`, and ``__version__``.

Importing lair changes pint for the whole process: it adds the
:data:`mass_flux` context to the registry and makes pint write a unit's parts
in the order of their dimensions (``kg/km**2/d``).
"""

import logging
import os
from importlib.metadata import PackageNotFoundError
from importlib.metadata import version as _version

import cf_xarray.units  # must be imported before pint_xarray
import pint
import pint_xarray

# sort_by_dimensionality prints a unit's parts in dimension order (kg/km**2/d,
# where pint's default gives kg/d/km**2). pint >= 0.26 exports it; pint 0.24 and
# 0.25, the newest pint on Python 3.11, have it only in a private module. When
# neither has it (pint older than 0.24, or a pint that moves it again) the import
# fails here, on purpose: without it Inventory.get_units mislabels a flux unit.
# pyrefly checks against the installed pint, so it reports whichever import that
# pint lacks: each suppression below is for one pint version.
try:
    # pyrefly: ignore[missing-module-attribute]
    from pint.delegates.formatter import sort_by_dimensionality
except ImportError:
    from pint.delegates.formatter._compound_unit_helpers import (
        # pyrefly: ignore[missing-module-attribute]
        sort_by_dimensionality,
    )

from . import config
from .records import ftp_download, unzip

#: The pint unit registry lair uses, which is pint-xarray's, so a quantified
#: xarray object and a plain quantity share it. It has the :data:`mass_flux`
#: context.
#: :doc:`/examples/units` converts a methane flux with it.
#:
#: See Also
#: --------
#: mass_flux : The context that converts between moles and mass.
#: lair.inventories.convert_units : Converts an array's ``units`` attribute for a pollutant.
#:
#: Examples
#: --------
#: A quantity is a number with a unit, and the registry reads the unit from
#: text, CF spellings such as ``m-2 s-1`` included. ``to`` converts within one
#: dimension; a flux in moles needs the ``mass_flux`` context to become a flux
#: in mass.
#:
#: .. ipython:: python
#:
#:    from lair import units
#:
#:    flux = 10 * units("nmol m-2 s-1")
#:    print(f"{flux:~P}")
#:    print(f"{flux.to('mol km-2 d-1'):~P.3f}")
#:
#: :meta hide-value:
units = pint_xarray.unit_registry

logger = logging.getLogger(__name__)

try:
    __version__ = _version("lair")  # set by setuptools-scm from git tags
except PackageNotFoundError:  # running from a source tree that isn't installed
    __version__ = "0+unknown"


def _molar_mass(mw):
    """Return ``mw`` if it is a molar mass, else raise a TypeError that names it."""
    if not isinstance(mw, pint.Quantity) or not mw.check("[mass] / [substance]"):
        raise TypeError(
            "The mass_flux context needs mw, the molar mass as a quantity, "
            "e.g. units.context('mass_flux', mw=16.04 * units('g/mol')); "
            f"got mw={mw!r}"
        )
    return mw


#: The pint context that converts a flux between moles and mass, given ``mw``.
#:
#: It converts ``[substance]/[area]/[time]`` to ``[mass]/[area]/[time]`` and
#: back, multiplying or dividing by ``mw``, the molar mass as a quantity in
#: g/mol: ``units.context("mass_flux", mw=16.04 * units("g/mol"))``. Without
#: ``mw``, or with a plain number, the conversion raises a ``TypeError`` that
#: names ``mw``. Importing lair adds it to :data:`units`; :doc:`/examples/units`
#: shows it on a methane flux.
#:
#: See Also
#: --------
#: units : The registry that has the context.
#: lair.inventories.molecular_weight : The molar mass of a pollutant, for ``mw``.
#: lair.inventories.convert_units : Does this conversion for a pollutant's name.
#:
#: Examples
#: --------
#: 10 nmol m-2 s-1 of methane (16.04 g/mol) is 13.86 kg km-2 d-1, and back:
#:
#: .. ipython:: python
#:
#:    from lair import units
#:
#:    mw = 16.04 * units("g/mol")
#:    flux = 10 * units("nmol m-2 s-1")
#:    with units.context("mass_flux", mw=mw):
#:        kg = flux.to("kg km-2 d-1")
#:        mol = kg.to("nmol m-2 s-1")
#:    print(f"{kg:~P.2f}")
#:    print(f"{mol:~P.2f}")
#:
#: :meta hide-value:
mass_flux = pint.Context("mass_flux")
mass_flux.add_transformation(
    "[substance] / [area] / [time]",
    "[mass] / [area] / [time]",
    # pint types the callback narrowly; (units, value, mw) is what it calls
    # pyrefly: ignore[bad-argument-type]
    lambda units, substance, mw=None: substance * _molar_mass(mw),
)
mass_flux.add_transformation(
    "[mass] / [area] / [time]",
    "[substance] / [area] / [time]",
    # pyrefly: ignore[bad-argument-type]
    lambda units, mass, mw=None: mass / _molar_mass(mw),
)
units.add_context(mass_flux)

# Set default pint sorting function to sort by dimensionality.
# Not cosmetic: inventories.Inventory.get_units splits a flux unit on "/"
# and reads its parts in this order.
units.formatter.default_sort_func = sort_by_dimensionality


[docs] def setup_ccg_filter(lair_dir: str | None = None) -> None: """ Set up the CCG filter module from NOAA GML. Installs ``_ccg_filter.py`` into ``lair_dir``, from NOAA's ``ccg_filter.zip``, unless the file is already there. ``import lair`` calls this function: :ref:`first-import-download` says what is downloaded and why, what happens without a network, and how to skip the download or place the file yourself. Called on its own, it raises when the download fails or the zip holds no ``ccg_filter.py``, and leaves no partial file behind. The file is moved into place atomically, so concurrent first imports (a Slurm array, for example) are safe: one that finds the file already installed uses it. Parameters ---------- lair_dir : str, optional Directory to install ``_ccg_filter.py`` into. Defaults to the lair package directory. See Also -------- lair.background.thoning : Fits NOAA's curve, which needs the filter. Examples -------- >>> import lair >>> lair.setup_ccg_filter() # doctest: +SKIP """ import tempfile import zipfile if lair_dir is None: lair_dir = os.path.dirname(__file__) ccg_filter_file = os.path.join(lair_dir, "_ccg_filter.py") if os.path.exists(ccg_filter_file): return if os.getenv("LAIR_SKIP_CCG_DOWNLOAD"): # Offline/CI/read-only: skip the FTP download (see docstring) return # The temporary directory sits next to the target so os.replace stays on one # filesystem (atomic); it is removed on exit, whether or not we succeed. with tempfile.TemporaryDirectory(prefix=".ccg_filter-", dir=lair_dir) as tmp: ftp_download("ftp.gml.noaa.gov", "user/thoning/ccgcrv/ccg_filter.zip", tmp) zf = os.path.join(tmp, "ccg_filter.zip") with zipfile.ZipFile(zf) as z: members = [ m for m in z.namelist() if os.path.basename(m) == "ccg_filter.py" ] if not members: raise FileNotFoundError( f"No ccg_filter.py in NOAA's {os.path.basename(zf)}" ) source = z.read(members[0]) staged = os.path.join(tmp, "_ccg_filter.py") with open(staged, "wb") as f: f.write(source) if os.path.exists(ccg_filter_file): # Another process installed it while we were downloading return os.replace(staged, ccg_filter_file)
def _setup_ccg_filter_or_warn() -> None: """ Install the CCG filter at import; a failure warns instead of raising. Only ``lair.background`` needs the filter, so a NOAA outage or a node without outbound FTP shouldn't break ``import lair``. """ try: setup_ccg_filter() except Exception as e: logger.warning( "Could not install NOAA's CCG filter (%s: %s). lair.background is " "unavailable until lair.setup_ccg_filter() succeeds.", type(e).__name__, e, ) _setup_ccg_filter_or_warn()