opensmell 3.0.0__py3-none-any.whl

opensmell/__init__.py

@@ -0,0 +1,239 @@
+"""opensmell — digital olfaction SDK.
+
+v3 modular framework: sensor-agnostic interfaces at the top level
+(`io`, `csv`, `normalize`, `quality`, `features`) with sensor-specific
+implementations in `opensmell.mox` (and future `opensmell.miris`,
+`opensmell.electrochemical`). The MOX thermodynamic feasibility chain lives at
+`opensmell.mox.smellability`.
+
+Legacy v2 CSV-based API (`process`, `train`, `predict`, `extract_features`,
+`load_recording`, `SmellResult`) is preserved for backwards compatibility.
+
+The feasibility chain is re-exported at the top level as `opensmell.smellability`
+so `resolve_and_run`, `chemical_from_smiles`, and the verdicts are reachable
+without importing the internals.
+"""
+
+import numpy as np
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.ensemble import RandomForestClassifier
+
+from . import features as _features
+from .calibration import (
+    CalibrationError,
+    build_calibration_payload,
+    calibrate_precise,
+    calibrate_quick,
+    concentration_series,
+    fit_power_law,
+    invert_concentration,
+    loocv_power_law,
+    normed_to_rr,
+    two_point_calibration,
+)
+from .hardware import (
+    HardwareInsufficiencyWarning,
+    check_rig_sufficiency,
+    effective_dims,
+    implied_channels,
+    min_effective_dimensions,
+)
+from .mox.preprocessing import load_csv, rs_r0_normalize, segment
+from .result import SmellResult
+
+# --- MOX thermodynamic feasibility chain (Smellability) ---
+from .mox import smellability
+
+# Register the re-export as a real dotted path so `import opensmell.smellability`
+# (and `from opensmell.smellability import ...`) works, not just attribute access.
+import sys as _sys
+
+_sys.modules[__name__ + ".smellability"] = smellability
+del _sys
+
+# --- New v3 sensor-agnostic API ---
+from .csv import guess_sensor_type, parse_csv
+from .features import process_mox, run_processor
+from .ingest import (
+    IngestedCollection,
+    IngestedSession,
+    build_osmell_file,
+    ingest_file,
+    ingest_folder,
+)
+from .io import (
+    build_osmell,
+    csv_from_file,
+    default_file_name,
+    parse_osmell,
+    parse_osmell_file,
+    write_osmell,
+)
+from .quality import compute_quality
+from .types import (
+    OSMELL_FORMAT_VERSION,
+    CalibrationDescriptor,
+    ChannelDescriptor,
+    ChannelStats,
+    OsmellFile,
+    OsmellManifest,
+    ParsedSample,
+    QualityReport,
+    SensorDescriptor,
+    SessionDescriptor,
+    SessionEvent,
+)
+
+
+def _feature_vector(feature_dict: dict) -> tuple:
+    keys = sorted(feature_dict.keys())
+    values = [feature_dict[k] for k in keys]
+    return np.array(values, dtype=np.float32), keys
+
+
+def _features_from_normed(normed: np.ndarray, n_channels: int = None) -> tuple:
+    if n_channels is None:
+        n_channels = normed.shape[1] if normed.ndim == 2 else 1
+    segments = segment(normed)
+    all_features = []
+    for seg in segments:
+        feats = _features.extract_all_framework_features(seg)
+        vals, _ = _feature_vector(feats)
+        all_features.append(vals)
+    arr = np.array(all_features)
+    fnames = _features.feature_names(n_channels=n_channels)
+    return arr, fnames
+
+
+def load_recording(filepath: str) -> np.ndarray:
+    raw = load_csv(filepath)
+    return rs_r0_normalize(raw)
+
+
+def extract_features(filepath: str) -> tuple:
+    normed = load_recording(filepath)
+    return _features_from_normed(normed, n_channels=normed.shape[1])
+
+
+def feature_names(n_channels=None) -> list:
+    """Names of the MOX framework features (in extraction order).
+
+    Length is a function of channel count (``28·c + c(c−1)/2 + 4``); pass
+    ``n_channels`` to match a non-6 rig, or omit for the canonical 6.
+    """
+    return _features.feature_names(n_channels=n_channels)
+
+
+def process(filepath: str, model: Pipeline = None) -> SmellResult:
+    normed = load_recording(filepath)
+    if model is not None:
+        check_rig_sufficiency(normed.shape[1], model)
+    features_arr, fnames = _features_from_normed(normed)
+    if features_arr.shape[0] == 0:
+        return SmellResult(features=np.array([]), feature_names=fnames, n_windows=0)
+    avg_features = features_arr.mean(axis=0)
+    if model is not None:
+        pred = model.predict([avg_features])[0]
+        proba = model.predict_proba([avg_features]).max()
+        warning = ""
+        if proba < 0.5:
+            warning = "Low confidence"
+        elif proba < 0.7:
+            warning = "Moderate confidence"
+        return SmellResult(
+            substance=str(pred),
+            confidence=float(proba),
+            warning=warning,
+            features=avg_features,
+            feature_names=fnames,
+            n_windows=features_arr.shape[0],
+        )
+    return SmellResult(
+        features=avg_features,
+        feature_names=fnames,
+        n_windows=features_arr.shape[0],
+    )
+
+
+def train(X: np.ndarray, y: np.ndarray, n_estimators: int = 200) -> Pipeline:
+    model = Pipeline([
+        ("scaler", StandardScaler()),
+        ("clf", RandomForestClassifier(
+            n_estimators=n_estimators,
+            class_weight="balanced",
+            random_state=42,
+            n_jobs=-1,
+        )),
+    ])
+    model.fit(X, y)
+    n_ch = implied_channels(X.shape[1])
+    if n_ch is not None:
+        model.min_effective_dimensions = effective_dims(n_ch)
+    return model
+
+
+def predict(filepath: str, model: Pipeline) -> SmellResult:
+    return process(filepath, model=model)
+
+
+# Backwards-compat alias for the .osmell loader.
+load_osmell = parse_osmell_file
+
+__all__ = [
+    "extract_features",
+    "feature_names",
+    "process",
+    "train",
+    "predict",
+    "load_recording",
+    "SmellResult",
+    # Reference-point calibration (§4.6, §10.10)
+    "CalibrationError",
+    "two_point_calibration",
+    "fit_power_law",
+    "invert_concentration",
+    "loocv_power_law",
+    "build_calibration_payload",
+    "concentration_series",
+    "normed_to_rr",
+    "calibrate_quick",
+    "calibrate_precise",
+    # Hardware sufficiency gate (§10.10 N→M limit)
+    "HardwareInsufficiencyWarning",
+    "check_rig_sufficiency",
+    "effective_dims",
+    "min_effective_dimensions",
+    "implied_channels",
+    # v3 sensor-agnostic API
+    "parse_csv",
+    "guess_sensor_type",
+    "ingest_file",
+    "ingest_folder",
+    "build_osmell_file",
+    "IngestedSession",
+    "IngestedCollection",
+    "parse_osmell",
+    "parse_osmell_file",
+    "load_osmell",
+    "build_osmell",
+    "write_osmell",
+    "csv_from_file",
+    "default_file_name",
+    "compute_quality",
+    "run_processor",
+    "process_mox",
+    # MOX thermodynamic feasibility chain (Smellability)
+    "smellability",
+    "OSMELL_FORMAT_VERSION",
+    "OsmellFile",
+    "OsmellManifest",
+    "SensorDescriptor",
+    "SessionDescriptor",
+    "ChannelDescriptor",
+    "SessionEvent",
+    "ParsedSample",
+    "ChannelStats",
+    "QualityReport",
+    "CalibrationDescriptor",
+]

opensmell/calibration.py

@@ -0,0 +1,313 @@
+"""Reference-point calibration (§4.6, §10.10).
+
+The only sanctioned path to quantification: measured resistance ratio
+``rr = R/R0`` at KNOWN concentrations ``C`` on a specific rig, per channel.
+The sensor power law is
+
+    rr = a · C^b          (b < 0 for the classic reducing-gas response)
+
+so a channel's ``(a, b)`` are fitted in log-log space and concentration is
+inverted as
+
+    C = (rr / a) ^ (1 / b)
+
+These are per-rig, per-channel, per-substance quantities. They do not transfer
+across rigs (§4.6 proof), they are valid only for the reference substance they
+were measured with, and they must be re-measured as the rig drifts. The
+``sensor.calibration`` manifest contract (§10.10) stores them.
+
+Design principles:
+
+- *Warn, never silently interpolate.* Every fit reports R², residual spread,
+  coverage (ppm span) and a leave-one-out concentration error.
+- *Falsifiable.* ``loocv_power_law`` gives the held-out % error you should
+  expect at the fitted concentrations; extrapolation outside the calibrated
+  ppm range is explicitly penalized (see ``research/calibration-experiments/
+  reference-point-calibration/`` for the quantified numbers).
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import date
+from typing import Dict, Optional
+
+import numpy as np
+
+from .constants import UnknownSensorError, power_law
+
+
+class CalibrationError(ValueError):
+    """A calibration fit is impossible with the given data (e.g. < 2 points,
+    non-positive values, or a degenerate reference pair)."""
+
+
+def normed_to_rr(normed) -> np.ndarray:
+    """Convert normalized response ``(R - R0)/R0`` to the ratio ``R/R0``.
+
+    The calibration power law uses ``rr = R/R0``; ``load_recording`` returns the
+    normalized form, so ``rr = 1 + normed``.
+    """
+    arr = np.asarray(normed, dtype=np.float64)
+    return 1.0 + arr
+
+
+def invert_concentration(rr, a: float, b: float) -> np.ndarray:
+    """Invert ``rr = a·C^b`` to concentration ``C = (rr/a)^(1/b)``.
+
+    Returns NaN where ``rr``, ``a``, or ``b`` make the inversion undefined
+    (``rr <= 0``, ``a <= 0``, ``b == 0``).
+    """
+    arr = np.asarray(rr, dtype=np.float64)
+    scalar = arr.ndim == 0
+    arr = np.atleast_1d(arr)
+    a = float(a)
+    b = float(b)
+    if a <= 0 or b == 0:
+        out = np.full(arr.shape, np.nan)
+    else:
+        with np.errstate(invalid="ignore", divide="ignore", over="ignore"):
+            out = (arr / a) ** (1.0 / b)
+        out = np.where(arr > 0, out, np.nan)
+    return float(out[0]) if scalar else out
+
+
+def two_point_calibration(rr1: float, c1: float, rr2: float, c2: float):
+    """Exact (a, b) from two measured (rr, C) points (§4.6).
+
+    ``b = log(rr1/rr2) / log(C1/C2)``, ``a = rr1 / C1^b``. Raises
+    ``CalibrationError`` on degenerate inputs (equal concentrations, equal
+    responses, non-positive values).
+    """
+    if not (rr1 > 0 and rr2 > 0 and c1 > 0 and c2 > 0):
+        raise CalibrationError(
+            f"Reference points must be positive: (rr1, c1, rr2, c2) = "
+            f"({rr1}, {c1}, {rr2}, {c2}).")
+    if c1 == c2:
+        raise CalibrationError("Two-point calibration needs distinct concentrations.")
+    if rr1 == rr2:
+        raise CalibrationError("Two-point calibration needs distinct responses.")
+    b = math.log(rr1 / rr2) / math.log(c1 / c2)
+    a = rr1 / (c1 ** b)
+    return float(a), float(b)
+
+
+def _valid_mask(rr, c) -> np.ndarray:
+    rr = np.asarray(rr, dtype=np.float64)
+    c = np.asarray(c, dtype=np.float64)
+    return np.isfinite(rr) & np.isfinite(c) & (rr > 0) & (c > 0)
+
+
+def fit_power_law(rr, c) -> dict:
+    """Multi-point power-law fit in log-log space (recommended over two-point).
+
+    OLS of ``log(rr) = log(a) + b·log(C)``. Returns a dict with ``a``, ``b``,
+    ``r2``, ``rmse_log_rr`` (residual spread in log-response, a noise proxy),
+    ``n_points``, ppm coverage, and ``residuals`` (log domain).
+
+    Requires at least 2 valid (positive, finite) points; raises
+    ``CalibrationError`` otherwise.
+    """
+    rr = np.asarray(rr, dtype=np.float64)
+    c = np.asarray(c, dtype=np.float64)
+    if rr.ndim == 0:
+        rr = rr.reshape(1)
+        c = np.asarray(c, dtype=np.float64).reshape(1)
+    mask = _valid_mask(rr, c)
+    if mask.sum() < 2:
+        raise CalibrationError(
+            f"Need >= 2 valid (positive) reference points, got {int(mask.sum())}.")
+    log_rr = np.log(rr[mask])
+    log_c = np.log(c[mask])
+    b, loga = np.polyfit(log_c, log_rr, 1)
+    a = float(math.exp(loga))
+    resid = log_rr - (b * log_c + loga)
+    ss_res = float(np.sum(resid ** 2))
+    ss_tot = float(np.sum((log_rr - log_rr.mean()) ** 2))
+    r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
+    rmse = float(np.sqrt(np.mean(resid ** 2)))
+    return {
+        "a": float(a),
+        "b": float(b),
+        "r2": r2,
+        "rmse_log_rr": rmse,
+        "n_points": int(mask.sum()),
+        "min_ppm": float(np.min(c[mask])),
+        "max_ppm": float(np.max(c[mask])),
+        "decades": float(np.log10(np.max(c[mask]) / np.min(c[mask]))),
+        "residuals": resid.tolist(),
+        "method": "multi-point-loglog",
+    }
+
+
+def loocv_power_law(rr, c) -> Optional[dict]:
+    """Leave-one-concentration-out falsification of the power-law fit.
+
+    For each reference point, fit ``(a, b)`` on the other points and predict
+    the held-out concentration; report relative error. Returns ``None`` when
+    fewer than 3 valid points exist (a 2-point fit has no independent holdout).
+    """
+    rr = np.asarray(rr, dtype=np.float64)
+    c = np.asarray(c, dtype=np.float64)
+    mask = _valid_mask(rr, c)
+    rr_v, c_v = rr[mask], c[mask]
+    if len(rr_v) < 3:
+        return None
+
+    folds = []
+    for i in range(len(rr_v)):
+        tr_rr = np.concatenate([rr_v[:i], rr_v[i + 1:]])
+        tr_c = np.concatenate([c_v[:i], c_v[i + 1:]])
+        fit = fit_power_law(tr_rr, tr_c)
+        pred = invert_concentration(rr_v[i], fit["a"], fit["b"])
+        err = (float(pred) - float(c_v[i])) / float(c_v[i])
+        folds.append({
+            "heldout_ppm": float(c_v[i]),
+            "pred_ppm": float(pred),
+            "rel_error": float(err),
+            "abs_pct_error": abs(err) * 100.0,
+        })
+    abs_pct = np.array([f["abs_pct_error"] for f in folds])
+    rel = np.array([f["rel_error"] for f in folds])
+    return {
+        "n_folds": len(folds),
+        "mean_abs_pct_error": float(np.mean(abs_pct)),
+        "median_abs_pct_error": float(np.median(abs_pct)),
+        "max_abs_pct_error": float(np.max(abs_pct)),
+        "bias_pct": float(np.mean(rel) * 100.0),
+        "folds": folds,
+    }
+
+
+def build_calibration_payload(
+    fits: Dict[str, dict],
+    reference_substance: str,
+    calibration_date: Optional[str] = None,
+    method: str = "multi-point-loglog",
+) -> Dict[str, dict]:
+    """Build a ``sensor.calibration`` manifest payload (§10.10 contract).
+
+    ``fits`` maps channel id -> ``fit_power_law`` result. The returned dict is
+    directly consumable by ``CalibrationDescriptor.from_dict`` and round-trips
+    through ``.osmell``. ``reference_ppm`` is the geometric-mean concentration
+    of the calibration range (the contract stores a single scalar).
+    """
+    if calibration_date is None:
+        calibration_date = date.today().isoformat()
+    payload: Dict[str, dict] = {}
+    for ch, fit in fits.items():
+        a = fit.get("a")
+        b = fit.get("b")
+        if a is None or b is None:
+            continue
+        ref_ppm = math.sqrt(max(fit.get("min_ppm", 1.0), 1.0)
+                            * max(fit.get("max_ppm", 1.0), 1.0))
+        payload[ch] = {
+            "a": float(a),
+            "b": float(b),
+            "referenceSubstance": reference_substance,
+            "referencePpm": float(ref_ppm),
+            "date": calibration_date,
+            "method": method,
+        }
+    return payload
+
+
+def concentration_series(normed, params: Dict[int, tuple]) -> np.ndarray:
+    """Per-channel concentration time series from a normalized recording.
+
+    ``normed`` is ``(R - R0)/R0`` per channel (``load_recording`` output);
+    ``params`` maps channel index -> ``(a, b)``. Uncalibrated channels yield
+    NaN. Use with the ``sensor.calibration`` manifest contract via
+    ``extract_all_framework_features(calibration=...)`` for the scalar feature
+    path.
+    """
+    normed = np.asarray(normed, dtype=np.float64)
+    if normed.ndim == 1:
+        normed = normed.reshape(-1, 1)
+    rr = normed_to_rr(normed)
+    out = np.full_like(rr, np.nan)
+    for ch, (a, b) in params.items():
+        if 0 <= ch < rr.shape[1]:
+            out[:, ch] = invert_concentration(rr[:, ch], a, b)
+    return out
+
+
+def calibrate_quick(sensor: str, gas: str, channel: str = "ch0",
+                    reference_ppm: Optional[float] = None,
+                    override: Optional[Dict[str, float]] = None) -> dict:
+    """Datasheet-derived single-channel calibration (no measured points).
+
+    Looks up the converted ``(a, b)`` power-law constants for the given
+    ``sensor`` model responding to ``gas`` from the embedded ``sensors.json``
+    (§10.10). It is a *starting point* for quantification, not a substitute for
+    measured reference points: the constants are single-reference-substance
+    datasheet estimates that do not transfer across rigs (§4.6).
+
+    ``override`` may supply ``{"a": ..., "b": ...}`` to adjust the tabulated
+    values for a specific rig. Returns a one-channel ``sensor.calibration``
+    payload conforming to ``CalibrationDescriptor.from_dict``.
+    """
+    if override is None:
+        override = {}
+    try:
+        params = dict(power_law(sensor, gas))
+    except UnknownSensorError:
+        raise
+    params.update(override)
+    b = float(params["b"])
+    a = float(params["a"])
+    if a <= 0 or b == 0:
+        raise CalibrationError(
+            f"`calibrate_quick` requires a > 0 and b != 0 for a usable power law; "
+            f"got (a={a}, b={b}) sensor={sensor} gas={gas}.")
+    payload = {
+        "a": a,
+        "b": b,
+        "referenceSubstance": gas,
+        "date": date.today().isoformat(),
+        "method": "datasheet",
+    }
+    if reference_ppm is not None:
+        payload["referencePpm"] = float(reference_ppm)
+    return {channel: payload}
+
+
+def calibrate_precise(sensor: str, gas: str, rr, c,
+                      channel: str = "ch0",
+                      reference_ppm: Optional[float] = None) -> dict:
+    """Measured multi-point power-law calibration wrapper (§4.6).
+
+    Fits ``(a, b)`` in log-log space from measured ``(rr, C)`` reference points
+    (reusing ``fit_power_law``), reports LOOCV falsification (``loocv_power_law``),
+    and returns both a ``sensor.calibration`` payload (for ``CalibrationDescriptor``)
+    and the full fit + diagnostics under ``"diagnostics"``.
+
+    ``sensor``/``gas`` are descriptive metadata; the ``(a, b)`` come entirely
+    from the measured points, never from the datasheet table.
+    """
+    fit = fit_power_law(rr, c)
+    loocv = loocv_power_law(rr, c)
+    if reference_ppm is None:
+        reference_ppm = math.sqrt(max(fit.get("min_ppm", 1.0), 1.0)
+                                  * max(fit.get("max_ppm", 1.0), 1.0))
+    payload = {
+        channel: {
+            "a": fit["a"],
+            "b": fit["b"],
+            "referenceSubstance": gas,
+            "referencePpm": float(reference_ppm),
+            "date": date.today().isoformat(),
+            "method": "multi-point-loglog",
+        }
+    }
+    return {
+        "channel": channel,
+        "sensor": sensor,
+        "gas": gas,
+        "calibration": payload,
+        "diagnostics": {key: fit[key] for key in (
+            "a", "b", "r2", "rmse_log_rr", "n_points", "min_ppm",
+            "max_ppm", "decades", "method")},
+        "loocv": loocv,
+    }

opensmell/constants/__init__.py

@@ -0,0 +1,137 @@
+"""Offline sensor constants for MOX power-law response (§4.6, §10.10).
+
+Power-law channels. Every ``(a, b)`` pair satisfies the SDK power law
+
+    rr = a · C^b      (C in ppm, rr = R/R0)
+
+with concentration inverted as ``C = (rr / a) ^ (1 / b)``. Values are the
+**converted** datasheet-derived constants (source ``MQSensorsLib``, referenced
+by each sensor's ``sources``), so they are directly consumable by the
+reference-point calibration machinery. They are single-reference-substance
+estimates; real quantification still needs per-rig, per-channel measured
+reference points (§4.6).
+
+Relative-response channels. Some MEMS entries (``SGP30``, ``SGP40``,
+``TGS8100``, ``BME680``) carry no ``gases`` table and
+``power_law_calibratable = False``: there is no authoritative, publicly
+available power-law mapping to a target gas concentration for them, so the
+SDK deliberately refuses to fabricate one. They are usable as relative
+response/VOC-index channels, but ``power_law``/``clean_air_ratio``/etc. raise
+``UnknownSensorError`` for them. Use ``is_power_law_sensor`` to distinguish.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List, Optional
+
+_SENSORS_PATH = Path(__file__).with_name("sensors.json")
+
+_load = None
+
+
+def _load_sensors() -> dict:
+    global _load
+    if _load is None:
+        with _SENSORS_PATH.open("r", encoding="utf-8") as f:
+            _load = json.load(f)
+    return _load
+
+
+class UnknownSensorError(KeyError):
+    """The requested sensor model is not in the offline constants table."""
+
+
+def sensor_models() -> List[str]:
+    """Sorted list of sensor models present in the constants table."""
+    return sorted(_load_sensors()["sensors"].keys())
+
+
+def _gases_for(sensor: str) -> Dict[str, Dict[str, float]]:
+    """Gas-to-constants map for ``sensor`` ([] if none tabulated).
+
+    A ``KeyError`` here means either the sensor is unknown, or it is a known
+    non-power-law channel (e.g. relative-response MEMS like ``TGS8100`` /
+    ``SGP30`` / ``SGP40`` / ``BME680``) that has no ``gases`` table. Both cases
+    surface as ``UnknownSensorError`` so callers never see a raw ``KeyError``.
+    """
+    try:
+        gases = _load_sensors()["sensors"][sensor]["gases"]
+    except KeyError:
+        raise UnknownSensorError(sensor) from None
+    return gases
+
+
+def sensor_gases(sensor: str) -> List[str]:
+    """Gases (substances) a sensor model has response constants for."""
+    return list(_gases_for(sensor).keys())
+
+
+def clean_air_ratio(sensor: str) -> float:
+    """Clean-air resistance ratio ``Rs/R0`` reported for the sensor model."""
+    try:
+        return float(_load_sensors()["sensors"][sensor]["clean_air_ratio"])
+    except KeyError:
+        raise UnknownSensorError(sensor) from None
+
+
+def power_law(sensor: str, gas: str) -> Dict[str, float]:
+    """Return ``{"a": a, "b": b}`` for ``sensor`` responding to ``gas``.
+
+    Raises ``UnknownSensorError`` for an unknown sensor (or a known
+    non-power-law channel with no ``gases`` table) and ``KeyError`` for a gas
+    the sensor has no tabulated response for.
+    """
+    gases = _gases_for(sensor)
+    try:
+        return dict(gases[gas])
+    except KeyError:
+        raise KeyError(
+            f"'{sensor}' has no tabulated response for gas '{gas}'. "
+            f"Known gases: {sorted(gases)}") from None
+
+
+def all_power_laws(sensor: str) -> Dict[str, Dict[str, float]]:
+    """All ``{gas: {"a": a, "b": b}}`` responses for a sensor model."""
+    return {g: dict(v) for g, v in _gases_for(sensor).items()}
+
+
+def is_power_law_sensor(sensor: str) -> bool:
+    """Whether ``sensor`` has a tabulated power-law ``gases`` table.
+
+    Power-law channels (e.g. the MQ family) return True and can feed
+    ``power_law``/``clean_air_ratio``. Relative-response MEMS entries
+    (``TGS8100``, ``SGP30``, ``SGP40``, ``BME680``) and unknown sensors
+    return False -- they cannot be quantified from offline constants.
+    """
+    try:
+        return "gases" in _load_sensors()["sensors"][sensor]
+    except KeyError:
+        return False
+
+
+def sensor_sources(sensor: str) -> List[str]:
+    """Verification/reference URLs for ``sensor`` (datasheets, source code).
+
+    These are the provenance links backing the tabulated constants (or, for
+    non-power-law MEMS entries, the official documentation confirming no
+    authoritative power-law exists). Raises ``UnknownSensorError`` if the
+    sensor is not in the table.
+    """
+    try:
+        return list(_load_sensors()["sensors"][sensor].get("sources", []))
+    except KeyError:
+        raise UnknownSensorError(sensor) from None
+
+
+__all__ = [
+    "UnknownSensorError",
+    "sensor_models",
+    "sensor_gases",
+    "clean_air_ratio",
+    "power_law",
+    "all_power_laws",
+    "is_power_law_sensor",
+    "sensor_sources",
+]