salmopredict 0.1.0__py3-none-any.whl

salmopredict/__init__.py

@@ -0,0 +1,30 @@
+"""salmopredict: predict Salmonella Incidence from virulence-factor gene features.
+
+Given a feature table of Salmonella virulence-factor gene presence/frequency,
+salmopredict:
+
+1. Aligns the input columns to the features expected by a pre-trained AutoGluon
+   TabularPredictor (normalising R-``make.names``-style column names and filling
+   genes the model expects but the input lacks with zero).
+2. Runs the ``WeightedEnsemble_L2`` model to predict the ``Incidence`` target.
+3. Writes one prediction file (``Incidence(%)``, plus a ``Sample`` column and any
+   attached metadata when the input carries a ``Sample`` column).
+
+The same core is shared by a command-line interface and a Streamlit GUI.
+"""
+
+__version__ = "0.1.0"
+
+# One-paragraph summary shown in both the CLI help and the GUI, so the two
+# interfaces describe the tool with identical wording.
+DESCRIPTION = (
+    "salmopredict predicts Salmonella incidence from virulence-factor "
+    "gene-frequency features and provides both command-line and graphical "
+    "interfaces. It standardizes the input feature table and outputs per-row "
+    "incidence predictions. salmopredict was developed at the State Key "
+    "Laboratory of Veterinary Public Health and Safety, China Agricultural "
+    "University, in collaboration with the China National Center for Food Safety "
+    "Risk Assessment (CFSA)."
+)
+
+__all__ = ["__version__", "DESCRIPTION"]

salmopredict/cli.py

@@ -0,0 +1,303 @@
+"""Command-line interface for salmopredict.
+
+Commands:
+    salmopredict run          -- predict Incidence for one or more feature CSVs
+    salmopredict gui          -- launch the Streamlit graphical interface
+    salmopredict check        -- verify dependencies and the model
+    salmopredict build-model  -- clone a full AutoGluon model into a slim deploy copy
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from . import DESCRIPTION, __version__
+from .config import (
+    DEFAULT_ENSEMBLE_MODEL,
+    DEFAULT_MISSING_WARN_FRACTION,
+    PREDICTION_MAX,
+    PREDICTION_MIN,
+    PredictConfig,
+    default_model_path,
+)
+
+# Colorised --help. rich-argparse handles column alignment, NO_COLOR, and
+# non-TTY detection for us; if it is not installed we fall back to plain help so
+# the CLI keeps working uncoloured.
+try:
+    from rich_argparse import RawDescriptionRichHelpFormatter as _HelpFormatter
+
+    # A tasteful, on-theme palette (salmon headings for a Salmonella tool).
+    _HelpFormatter.styles["argparse.prog"] = "bold #fa8072"
+    _HelpFormatter.styles["argparse.groups"] = "bold #fa8072"
+    _HelpFormatter.styles["argparse.args"] = "cyan"
+    _HelpFormatter.styles["argparse.metavar"] = "dim cyan"
+    _HelpFormatter.styles["argparse.help"] = "default"
+except ImportError:  # pragma: no cover - color is a nice-to-have, not required
+    from argparse import RawDescriptionHelpFormatter as _HelpFormatter
+
+
+class _CliProgress:
+    """Throttled, single-line progress reporter for the terminal."""
+
+    def __init__(self) -> None:
+        self._stage = None
+
+    def __call__(self, stage: str, done: int, total: int, message: str) -> None:
+        if stage != self._stage:
+            if self._stage is not None:
+                sys.stderr.write("\n")
+            self._stage = stage
+        if total and total > 0:
+            pct = 100.0 * done / total
+            sys.stderr.write(f"\r[{stage}] {done}/{total} ({pct:5.1f}%) {message:<40.40}")
+        else:
+            sys.stderr.write(f"\r[{stage}] {message:<60.60}")
+        sys.stderr.flush()
+        if stage == "done":
+            sys.stderr.write("\n")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="salmopredict",
+        description=DESCRIPTION,
+        formatter_class=_HelpFormatter,
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"salmopredict {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    default_model = default_model_path()
+
+    run = sub.add_parser("run", help="Predict Incidence for one feature CSV.",
+                         formatter_class=_HelpFormatter)
+    run.add_argument("-i", "--input", required=True,
+                     help="One feature CSV file. If it has a 'Sample' column, the "
+                          "output carries Sample + the prediction; otherwise it is "
+                          "the prediction column only.")
+    run.add_argument("-o", "--output", required=True,
+                     help="Output directory (created if missing); the result is "
+                          "written there as pred_<input-stem>.csv.")
+    run.add_argument("--model", default=str(default_model) if default_model else None,
+                     help="AutoGluon model directory. Defaults to $SALMOPREDICT_MODEL "
+                          "or the model bundled under the package.")
+    run.add_argument("--model-name", default=DEFAULT_ENSEMBLE_MODEL,
+                     help=f"Ensemble sub-model to predict with "
+                          f"(default {DEFAULT_ENSEMBLE_MODEL}; falls back to the "
+                          f"model's best if absent).")
+    run.add_argument("--missing-warn-frac", type=float, default=DEFAULT_MISSING_WARN_FRACTION,
+                     help=f"Warn if more than this fraction of model features are "
+                          f"missing from the input (default {DEFAULT_MISSING_WARN_FRACTION}).")
+    run.add_argument("--fill-value", type=float, default=0.0,
+                     help="Value for features the model expects but the input lacks "
+                          "(default 0.0 = gene absent).")
+    run.add_argument("--attach",
+                     help="Metadata CSV joined on the 'Sample' key. Requires the "
+                          "input to have a 'Sample' column; the metadata file must "
+                          "have one too. Its other columns are appended to the output.")
+    run.add_argument("-f", "--force", action="store_true",
+                     help="Allow writing into a non-empty output directory.")
+
+    gui = sub.add_parser("gui", help="Launch the Streamlit GUI.",
+                         formatter_class=_HelpFormatter)
+    gui.add_argument("--port", type=int, default=8501, help="Port (default 8501).")
+
+    check = sub.add_parser("check", help="Check dependencies and the model.",
+                           formatter_class=_HelpFormatter)
+    check.add_argument("--model", default=str(default_model) if default_model else None,
+                       help="Model directory to verify (default: bundled/env model).")
+
+    build = sub.add_parser("build-model",
+                           help="Clone a full AutoGluon model into a slim deploy copy.",
+                           formatter_class=_HelpFormatter)
+    build.add_argument("--source", required=True,
+                       help="Source AutoGluon model directory (may contain a literal '*').")
+    build.add_argument("-o", "--output", required=True,
+                       help="Destination directory for the slim clone (must not be "
+                            "inside --source).")
+    build.add_argument("--model-name", default=DEFAULT_ENSEMBLE_MODEL,
+                       help=f"Model to keep in the clone (default {DEFAULT_ENSEMBLE_MODEL}).")
+    build.add_argument("-f", "--force", action="store_true",
+                       help="Allow writing into an existing destination directory.")
+
+    return parser
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    config = PredictConfig(
+        input_path=Path(args.input),
+        output_dir=Path(args.output),
+        model_path=Path(args.model) if args.model else None,
+        ensemble_model=args.model_name,
+        fill_value=args.fill_value,
+        missing_warn_fraction=args.missing_warn_frac,
+        attach_metadata=Path(args.attach) if args.attach else None,
+        force=args.force,
+    )
+
+    # Imported here so 'check'/'gui' work even if autogluon is absent.
+    from .pipeline import run_pipeline
+
+    result = run_pipeline(config, progress=_CliProgress())
+
+    cols = ", ".join(result.predictions.columns)
+    print(f"\nDone. label={result.label}  model={result.model_used}")
+    print(f"  {result.input_path.name}: {result.n_rows} rows -> {result.output_path}")
+    print(f"    Sample column: {'yes' if result.has_sample else 'no'}"
+          + ("  (metadata attached)" if result.attached else ""))
+    print(f"    output columns: {cols}")
+    n_imp = len(result.imputed)
+    print(f"    imputed (filled {config.fill_value:g}): {n_imp} feature(s)"
+          + (f" [{', '.join(result.imputed)}]" if 0 < n_imp <= 12 else ""))
+    print(f"    missing fraction: {result.missing_fraction:.1%}")
+    if result.floored or result.capped:
+        print(f"    clamped to [{PREDICTION_MIN:g}, {PREDICTION_MAX:g}]: "
+              f"{result.capped} capped at {PREDICTION_MAX:g}, "
+              f"{result.floored} floored at {PREDICTION_MIN:g}")
+    if result.collisions:
+        print(f"    WARNING: {len(result.collisions)} normalised column name "
+              f"collision(s): {', '.join(result.collisions)}")
+    if result.warned:
+        print(f"    WARNING: {result.missing_fraction:.1%} of model features were "
+              f"missing and filled with {config.fill_value:g} -- check that this "
+              f"is the right input for this model.")
+    return 0
+
+
+def _silence_streamlit_onboarding() -> None:
+    """Skip Streamlit's first-run email prompt and telemetry.
+
+    Streamlit asks for an email on first launch unless a credentials file
+    exists; we create an anonymous one (empty email) so users never see that
+    prompt. Nothing is sent anywhere.
+    """
+    creds = Path.home() / ".streamlit" / "credentials.toml"
+    if not creds.exists():
+        try:
+            creds.parent.mkdir(parents=True, exist_ok=True)
+            creds.write_text('[general]\nemail = ""\n')
+        except OSError:
+            pass  # non-fatal; the user can still press Enter at the prompt
+
+
+def _cmd_gui(args: argparse.Namespace) -> int:
+    app = Path(__file__).resolve().parent / "gui" / "app.py"
+    _silence_streamlit_onboarding()
+    env = os.environ.copy()
+    env.setdefault("STREAMLIT_BROWSER_GATHER_USAGE_STATS", "false")
+    cmd = [sys.executable, "-m", "streamlit", "run", str(app),
+           "--server.port", str(args.port),
+           "--browser.gatherUsageStats", "false"]
+    try:
+        return subprocess.call(cmd, env=env)
+    except FileNotFoundError:
+        print("streamlit is not installed. Install it with: pip install streamlit",
+              file=sys.stderr)
+        return 1
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    from .core import modelinfo
+
+    ok = True
+
+    ag_version = modelinfo.installed_autogluon_version()
+    ag_ok = ag_version == "1.1.1"
+    print(f"  autogluon.tabular: {'OK ' + ag_version if ag_version else 'MISSING'}"
+          + ("" if ag_ok or not ag_version else "  (WARNING: model was trained with 1.1.1)"))
+    ok = ok and bool(ag_version)
+
+    for mod in ("torch", "streamlit", "pandas"):
+        try:
+            m = __import__(mod)
+            print(f"  {mod}: OK {getattr(m, '__version__', '')}")
+        except Exception:
+            print(f"  {mod}: MISSING")
+            if mod != "streamlit":  # streamlit only needed for the GUI
+                ok = False
+
+    model_path = Path(args.model) if args.model else None
+    if model_path is None:
+        print("  model: MISSING (no --model, $SALMOPREDICT_MODEL, or bundled model)")
+        ok = False
+    else:
+        info = modelinfo.read_model_info(model_path)
+        if not info.exists:
+            print(f"  model: MISSING ({model_path})")
+            ok = False
+        else:
+            print(f"  model: OK ({model_path})")
+            print(f"    version.txt: {info.version_txt}  metadata.version: {info.meta_version}"
+                  f"  best: {info.model_best}")
+            if ag_version and info.version_txt and info.version_txt != ag_version:
+                print(f"    WARNING: model autogluon {info.version_txt} != installed "
+                      f"{ag_version}; unpickling may fail.")
+            rt = modelinfo.runtime_py_version()
+            if info.py_version and not rt.startswith(info.py_version.rsplit(".", 1)[0]):
+                print(f"    WARNING: model trained on Python {info.py_version}, "
+                      f"running {rt}.")
+            # Confirm the predictor actually loads.
+            try:
+                from .core.predict import load_predictor
+                p = load_predictor(model_path)
+                has_l2 = DEFAULT_ENSEMBLE_MODEL in p.model_names()
+                print(f"    load: OK  label={p.label}  {DEFAULT_ENSEMBLE_MODEL}: "
+                      f"{'present' if has_l2 else 'absent (will fall back to best)'}")
+            except Exception as exc:
+                print(f"    load: FAILED -- {exc}")
+                ok = False
+
+    return 0 if ok else 1
+
+
+def _cmd_build_model(args: argparse.Namespace) -> int:
+    from .core.predict import load_predictor
+
+    source = Path(args.source)
+    dest = Path(args.output)
+    if dest.resolve() == source.resolve() or source.resolve() in dest.resolve().parents:
+        raise ValueError("--output must not be the source directory or inside it.")
+
+    print(f"Loading source model: {source}")
+    predictor = load_predictor(source)
+    if args.model_name not in predictor.model_names():
+        raise ValueError(
+            f"Model '{args.model_name}' not found in source. Available include: "
+            f"{', '.join(predictor.model_names()[:10])} ..."
+        )
+
+    print(f"Cloning for deployment (keeping {args.model_name}) -> {dest}")
+    predictor.clone_for_deployment(
+        path=str(dest),
+        model=args.model_name,
+        dirs_exist_ok=args.force,
+    )
+    print(f"Done. Slim model written to: {dest}")
+    print("Tip: point --model / $SALMOPREDICT_MODEL at this directory, or place it "
+          "under the package 'models/' folder.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "run":
+            return _cmd_run(args)
+        if args.command == "gui":
+            return _cmd_gui(args)
+        if args.command == "check":
+            return _cmd_check(args)
+        if args.command == "build-model":
+            return _cmd_build_model(args)
+    except (FileNotFoundError, ValueError, RuntimeError) as exc:
+        print(f"\nError: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

salmopredict/config.py

@@ -0,0 +1,103 @@
+"""Run configuration for salmopredict.
+
+A single :class:`PredictConfig` object carries every parameter through the
+pipeline so the CLI and the Streamlit GUI share exactly the same core.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+# Ensemble model used for prediction. The bundled model's overall best is
+# WeightedEnsemble_L3, but the established workflow uses L2, so we default to L2
+# for result parity. Falls back to predictor.model_best if L2 is absent.
+DEFAULT_ENSEMBLE_MODEL = "WeightedEnsemble_L2"
+
+# When more than this fraction of the model's features are missing from the
+# input (and therefore filled with ``fill_value``), a prominent warning is
+# emitted -- the prediction still runs.
+DEFAULT_MISSING_WARN_FRACTION = 0.30
+
+# Environment variable that can point at a default model directory.
+MODEL_ENV_VAR = "SALMOPREDICT_MODEL"
+
+# The one identifier column salmopredict recognises. When present in the input
+# it is carried into the output and used to join any attached metadata; when
+# absent the output holds the prediction column only.
+SAMPLE_COLUMN = "Sample"
+
+# Name of the single prediction column written to the output.
+PREDICTION_COLUMN = "Incidence(%)"
+
+# Incidence is a percentage, so predictions are clamped to this range. The
+# regression model can occasionally output values slightly outside [0, 100],
+# which are not physically meaningful; clamping keeps every output valid.
+PREDICTION_MIN = 0.0
+PREDICTION_MAX = 100.0
+
+# Directory inside the package where a slimmed deployment model may be shipped.
+_PKG_MODELS_DIR = Path(__file__).resolve().parent / "models"
+
+
+def default_model_path() -> Optional[Path]:
+    """Locate a default AutoGluon model directory.
+
+    Resolution order:
+      1. ``$SALMOPREDICT_MODEL`` if it points at an existing directory.
+      2. The single sub-directory of the package ``models/`` folder, if exactly
+         one exists (the slimmed model shipped via ``build-model``).
+    Returns ``None`` when neither is available, in which case ``--model`` must
+    be given explicitly.
+    """
+    env = os.environ.get(MODEL_ENV_VAR)
+    if env:
+        p = Path(env).expanduser()
+        if p.is_dir():
+            return p
+    if _PKG_MODELS_DIR.is_dir():
+        subdirs = [d for d in sorted(_PKG_MODELS_DIR.iterdir()) if d.is_dir()]
+        if len(subdirs) == 1:
+            return subdirs[0]
+    return None
+
+
+@dataclass
+class PredictConfig:
+    """All parameters for one salmopredict run.
+
+    One input feature CSV is aligned to the model and predicted, producing one
+    output file ``pred_<input-stem>.csv`` in ``output_dir``.
+
+    Output columns depend on the input:
+      * no ``Sample`` column  -> just the prediction (``Incidence(%)``);
+      * a ``Sample`` column    -> ``Sample`` + ``Incidence(%)``, and, if
+        ``attach_metadata`` is given, the metadata columns (joined on ``Sample``)
+        are appended. Attaching metadata requires a ``Sample`` column.
+    """
+
+    input_path: Path
+    output_dir: Path
+    model_path: Optional[Path] = field(default_factory=default_model_path)
+    ensemble_model: str = DEFAULT_ENSEMBLE_MODEL
+    fill_value: float = 0.0
+    missing_warn_fraction: float = DEFAULT_MISSING_WARN_FRACTION
+
+    # Optional external metadata CSV joined on the ``Sample`` key.
+    attach_metadata: Optional[Path] = None
+
+    force: bool = False
+
+    def __post_init__(self) -> None:
+        self.input_path = Path(self.input_path)
+        self.output_dir = Path(self.output_dir)
+        if self.model_path is not None:
+            self.model_path = Path(self.model_path)
+        if self.attach_metadata is not None:
+            self.attach_metadata = Path(self.attach_metadata)
+        if not 0.0 <= float(self.missing_warn_fraction) <= 1.0:
+            raise ValueError("missing_warn_fraction must be between 0 and 1")
+        self.missing_warn_fraction = float(self.missing_warn_fraction)
+        self.fill_value = float(self.fill_value)

salmopredict/core/__init__.py

@@ -0,0 +1 @@
+"""Computation core for salmopredict (interface-independent)."""

salmopredict/core/align.py

@@ -0,0 +1,104 @@
+"""Align an input feature table to an AutoGluon model's expected features.
+
+The bundled model was trained on USA data whose column names were normalised
+R-``make.names``-style (``/`` and ``-`` become ``.``), and the input feature
+tables carry many extra gene columns the model does not use plus a couple of
+genes the model expects but the panel lacks. This module reproduces the exact
+alignment used by the original ``predict_autogluon.py``:
+
+* normalise column names with :func:`san` (mimicking ``make.names``),
+* build ``X`` column-by-column in the model's feature order,
+* fill features the model expects but the input lacks with ``fill_value`` (a
+  missing gene means frequency 0, i.e. a weighted feature of 0),
+* ignore extra input columns.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import List
+
+import pandas as pd
+
+# Non-[0-9A-Za-z_] -> '.', matching R make.names and predict_autogluon.py's san().
+_SAN_RE = re.compile(r"[^0-9A-Za-z_]")
+
+
+def san(name: str) -> str:
+    """Normalise a column name the way R ``make.names`` does for our data."""
+    return _SAN_RE.sub(".", name)
+
+
+@dataclass
+class AlignmentResult:
+    """Outcome of aligning one input table to the model features."""
+
+    X: pd.DataFrame              # columns == model features, in model order
+    model_features: List[str]
+    imputed: List[str]          # model features absent from input -> filled
+    extra_ignored: List[str]    # input columns not used by any feature
+    collisions: List[str] = field(default_factory=list)  # san() name clashes
+    n_rows: int = 0
+
+    @property
+    def missing_fraction(self) -> float:
+        if not self.model_features:
+            return 0.0
+        return len(self.imputed) / len(self.model_features)
+
+
+def align_features(df: pd.DataFrame, predictor, *, fill_value: float = 0.0) -> AlignmentResult:
+    """Build the model input ``X`` from an arbitrary feature table.
+
+    Args:
+        df: Input feature table (rows = samples, columns = gene features).
+        predictor: A loaded AutoGluon ``TabularPredictor``.
+        fill_value: Value for features the model expects but the input lacks.
+
+    Returns:
+        An :class:`AlignmentResult`. Exact column-name matches take precedence
+        over ``san``-normalised matches; anything still unmatched is imputed.
+    """
+    feats = list(predictor.feature_metadata_in.get_features())
+    feat_san = {san(f) for f in feats}
+
+    exact = set(df.columns)
+    san_map: dict[str, str] = {}   # normalised input name -> original input name
+    collisions: List[str] = []
+    for col in df.columns:
+        s = san(col)
+        if s in san_map and s in feat_san:
+            # Two input columns normalise to the same model-relevant name.
+            collisions.append(s)
+        san_map[s] = col
+
+    # Build every column first, then construct X in one shot: assigning column
+    # by column into a growing DataFrame fragments it and is slow for 100+ cols.
+    data: dict = {}
+    imputed: List[str] = []
+    used_original: set = set()
+    for f in feats:
+        if f in exact:
+            data[f] = df[f].to_numpy()
+            used_original.add(f)
+        elif f in san_map:
+            src = san_map[f]
+            data[f] = df[src].to_numpy()
+            used_original.add(src)
+        else:
+            data[f] = fill_value  # scalar broadcasts across the index below
+            imputed.append(f)
+
+    X = pd.DataFrame(data, index=df.index, columns=feats)
+
+    extra_ignored = [c for c in df.columns if c not in used_original]
+
+    return AlignmentResult(
+        X=X,
+        model_features=feats,
+        imputed=imputed,
+        extra_ignored=extra_ignored,
+        collisions=sorted(set(collisions)),
+        n_rows=len(df),
+    )

salmopredict/core/io_tables.py

@@ -0,0 +1,76 @@
+"""Input reading and output-table assembly.
+
+Output contract (see :class:`~salmopredict.config.PredictConfig`):
+
+* If the input has **no** ``Sample`` column, the output is a single
+  ``Incidence(%)`` column -- features only, no metadata.
+* If the input **has** a ``Sample`` column, the output is
+  ``Sample`` + ``Incidence(%)``. When a metadata CSV is attached (it must also
+  have a ``Sample`` column), its remaining columns are joined on ``Sample`` and
+  appended: ``Sample`` + ``Incidence(%)`` + metadata columns.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import pandas as pd
+
+from ..config import PREDICTION_COLUMN, SAMPLE_COLUMN, PredictConfig
+
+
+def read_features(path: Path) -> pd.DataFrame:
+    """Read a feature CSV (UTF-8, header row of feature names)."""
+    return pd.read_csv(path)
+
+
+def find_sample_column(df: pd.DataFrame) -> Optional[str]:
+    """Return the input's ``Sample`` column name (case-insensitive), or None."""
+    for col in df.columns:
+        if str(col).strip().lower() == SAMPLE_COLUMN.lower():
+            return col
+    return None
+
+
+def build_output(
+    df: pd.DataFrame,
+    preds: pd.Series,
+    config: PredictConfig,
+) -> pd.DataFrame:
+    """Assemble the output table according to the two-type contract above."""
+    sample_col = find_sample_column(df)
+
+    out = pd.DataFrame(index=df.index)
+    if sample_col is not None:
+        out[SAMPLE_COLUMN] = df[sample_col].to_numpy()
+    out[PREDICTION_COLUMN] = preds.to_numpy()
+
+    if config.attach_metadata is not None:
+        if sample_col is None:
+            raise ValueError(
+                "Attaching metadata requires a 'Sample' column in the input; "
+                "this input has none."
+            )
+        meta = pd.read_csv(config.attach_metadata)
+        meta_sample = find_sample_column(meta)
+        if meta_sample is None:
+            raise ValueError(
+                "The metadata file must have a 'Sample' column to join on."
+            )
+        if meta[meta_sample].duplicated().any():
+            raise ValueError(
+                "The metadata file has duplicate 'Sample' values; cannot join "
+                "unambiguously."
+            )
+        # Normalise both keys to SAMPLE_COLUMN, then left-join so every input row
+        # is kept in order; unmatched samples get blank metadata.
+        meta = meta.rename(columns={meta_sample: SAMPLE_COLUMN})
+        out = out.merge(meta, on=SAMPLE_COLUMN, how="left")
+
+    return out
+
+
+def write_output(out_df: pd.DataFrame, path: Path) -> None:
+    """Write the output table as UTF-8 CSV without the row index."""
+    out_df.to_csv(path, index=False, encoding="utf-8")