Source code for aerosoltools.loaders.support.units
"""Shared unit resolution for the loaders' *extra* (housekeeping) columns.
Instrument exports carry many non-core columns — temperatures, humidities,
flows, pressures, diagnostics — whose units, when present at all, are embedded
in the header in a jumble of conventions (``Sample temp (C)``, ``Pressure
[mBar]``, ``Temperature.C``). This helper gives every loader one place to turn
that raw frame into a clean ``extra_data`` frame plus a ``{column: unit}`` map:
* a recognised trailing unit is stripped from the header (so the column is named
``"Sample temp"`` and its unit ``"°C"`` is recorded separately), and
* the unit is canonicalised via the shared registry (``(C)`` → ``°C``,
``(ug/m3)`` → ``µg/m³``), so the same quantity from two instruments compares
equal.
Columns with no recognisable unit keep their header verbatim and simply get no
entry in the map — callers then show the header text alone rather than borrow
the primary series' unit. Only genuine units are ever attached (see
:func:`aerosoltools._core.metrics.parse_header_unit`), so an index ``[1] Conc``,
a coordinate format ``(ddmm.mmmmm)`` or a note ``(with RI)`` is never mistaken
for one.
"""
from __future__ import annotations
import pandas as pd
from ..._core.metrics import canonical_unit, parse_header_unit
[docs]
def resolve_extra_columns(
df: pd.DataFrame, curated: dict[str, str] | None = None
) -> tuple[pd.DataFrame, dict[str, str]]:
"""Clean an ``extra_data`` frame's headers and resolve their units.
Args:
df: The non-core columns to keep as ``extra_data`` (index already set).
curated: Optional ``{header: unit}`` overrides for columns whose unit is
known from the instrument spec but not written in the header (e.g. a
DiSCmini diffusion current). Curated units are canonicalised too and
win over header parsing; the column keeps its original name.
Returns:
``(clean_df, column_units)`` where ``clean_df`` is ``df`` with recognised
trailing units stripped from the column names, and ``column_units`` maps
each resolved column (by its final name) to a canonical unit string.
"""
curated = curated or {}
rename: dict[str, str] = {}
units: dict[str, str] = {}
taken = {str(c) for c in df.columns}
for col in df.columns:
raw = str(col)
if raw in curated:
units[raw] = canonical_unit(curated[raw])
continue
name, unit = parse_header_unit(raw)
if unit is None:
continue
# Strip the unit from the header when the cleaned name is usable and does
# not clash with another column; otherwise keep the raw header as-is.
if name and name != raw and name not in taken:
rename[raw] = name
taken.add(name)
units[name] = unit
else:
units[raw] = unit
clean = df.rename(columns=rename) if rename else df
return clean, units