salmopredict 0.1.0__py3-none-any.whl

salmopredict/core/modelinfo.py

@@ -0,0 +1,71 @@
+"""Read a model directory's recorded versions and compare with the runtime.
+
+AutoGluon serialises its version and training Python version into the model
+directory (``version.txt`` and ``metadata.json``). Reading those files is far
+cheaper and more robust than loading the predictor, so ``check`` and
+``build-model`` use this module to warn about version mismatches before an
+unpickle is attempted.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class ModelInfo:
+    path: Path
+    exists: bool
+    version_txt: Optional[str] = None       # contents of version.txt
+    meta_version: Optional[str] = None      # metadata.json "version"
+    py_version: Optional[str] = None        # training-time Python version
+    model_best: Optional[str] = None
+
+
+def installed_autogluon_version() -> Optional[str]:
+    """Return the installed ``autogluon.tabular`` version, or ``None``.
+
+    The top-level ``autogluon`` namespace package has no ``__version__``; the
+    version lives on the ``autogluon.tabular`` sub-package.
+    """
+    try:
+        import autogluon.tabular as agt
+
+        return getattr(agt, "__version__", None)
+    except Exception:
+        return None
+
+
+def read_model_info(model_path: Path) -> ModelInfo:
+    """Read version metadata recorded inside a model directory."""
+    model_path = Path(model_path)
+    if not model_path.is_dir():
+        return ModelInfo(path=model_path, exists=False)
+
+    info = ModelInfo(path=model_path, exists=True)
+
+    vtxt = model_path / "version.txt"
+    if vtxt.is_file():
+        info.version_txt = vtxt.read_text(encoding="utf-8").strip()
+
+    meta = model_path / "metadata.json"
+    if meta.is_file():
+        try:
+            data = json.loads(meta.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            data = {}
+        info.meta_version = data.get("version")
+        info.py_version = data.get("py_version")
+        info.model_best = data.get("model_best")
+
+    return info
+
+
+def runtime_py_version() -> str:
+    """Return the running interpreter's ``major.minor.micro`` version."""
+    v = sys.version_info
+    return f"{v.major}.{v.minor}.{v.micro}"

salmopredict/core/predict.py

@@ -0,0 +1,102 @@
+"""Model loading and prediction helpers.
+
+AutoGluon is imported lazily inside these functions so that ``salmopredict
+check`` / ``gui`` keep working even before the heavy dependency is importable.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Union
+
+import pandas as pd
+
+# AutoGluon logs benign "Found N mismatches ..." notices from this logger when a
+# model is loaded on a slightly different Python micro version / OS than it was
+# trained on (e.g. Linux -> macOS).
+_METADATA_LOGGER = "autogluon.common.utils.utils"
+
+
+@contextmanager
+def _quiet_load_warnings():
+    """Silence benign UserWarnings emitted while loading/predicting.
+
+    * fastai's ``load_learner`` "insecure pickle" notice -- AutoGluon's neural-net
+      sub-model is a fastai learner loaded (at load, or lazily during predict)
+      via pickle; the bundled model is trusted.
+    * setuptools' ``pkg_resources is deprecated`` notice -- raised while AutoGluon
+      collects package versions during load.
+
+    Only these specific messages are hidden; every other warning is left intact.
+    """
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore", message=r".*load_learner.*", category=UserWarning
+        )
+        warnings.filterwarnings(
+            "ignore", message=r".*insecure pickle.*", category=UserWarning
+        )
+        warnings.filterwarnings(
+            "ignore", message=r".*pkg_resources is deprecated.*", category=UserWarning
+        )
+        yield
+
+
+@contextmanager
+def _quiet_metadata_mismatch():
+    """Hide AutoGluon's load-time Python-micro-version / OS mismatch notices.
+
+    They are logged at WARNING level by the ``autogluon.common.utils.utils``
+    logger and are harmless for inference, so we raise that one logger's
+    threshold for the duration of the load and restore it afterwards.
+    """
+    lg = logging.getLogger(_METADATA_LOGGER)
+    prev = lg.level
+    lg.setLevel(logging.ERROR)
+    try:
+        yield
+    finally:
+        lg.setLevel(prev)
+
+
+def load_predictor(model_path: Union[str, Path]):
+    """Load an AutoGluon ``TabularPredictor`` from ``model_path``.
+
+    The path is passed as a plain string, never through a shell, so a literal
+    ``*`` in a directory name is safe.
+    """
+    from autogluon.tabular import TabularPredictor
+
+    model_path = Path(model_path)
+    if not model_path.is_dir():
+        raise FileNotFoundError(f"Model directory does not exist: {model_path}")
+    with _quiet_load_warnings(), _quiet_metadata_mismatch():
+        return TabularPredictor.load(str(model_path))
+
+
+def choose_model(predictor, preferred: str) -> str:
+    """Return ``preferred`` if the predictor has it, else its best model."""
+    names = predictor.model_names()
+    return preferred if preferred in names else predictor.model_best
+
+
+def predict_incidence(predictor, X: pd.DataFrame, model: str) -> pd.Series:
+    """Run prediction with the chosen model, returning a pandas Series."""
+    with _quiet_load_warnings():
+        return predictor.predict(X, as_pandas=True, model=model)
+
+
+def clamp_predictions(preds: pd.Series, low: float, high: float):
+    """Clamp ``preds`` into ``[low, high]``.
+
+    Incidence is a percentage, so predictions must stay within a valid range;
+    the regression model can occasionally emit values just outside it. Returns
+    ``(clamped, n_below, n_above)`` where the counts are how many values were
+    raised to ``low`` and lowered to ``high`` respectively (NaNs are ignored).
+    """
+    n_below = int((preds < low).sum())
+    n_above = int((preds > high).sum())
+    return preds.clip(lower=low, upper=high), n_below, n_above

salmopredict/gui/__init__.py

@@ -0,0 +1 @@
+"""Streamlit graphical interface for salmopredict."""

salmopredict/gui/app.py

@@ -0,0 +1,242 @@
+"""salmopredict Streamlit GUI.
+
+Launch with ``salmopredict gui`` (or ``streamlit run salmopredict/gui/app.py``).
+
+The interface lets the user point at an AutoGluon model directory, upload one
+feature CSV, run prediction with live progress, then view and download the
+prediction table. The predictor is cached so the (slow) model load happens only
+once.
+
+Output follows the two-type contract:
+  * input without a ``Sample`` column -> a single ``Incidence(%)`` column;
+  * input with a ``Sample`` column     -> ``Sample`` + ``Incidence(%)``, and,
+    if a metadata CSV is attached (joined on ``Sample``), its other columns too.
+"""
+
+from __future__ import annotations
+
+import io
+import tempfile
+from pathlib import Path
+
+import pandas as pd
+import streamlit as st
+
+from salmopredict import DESCRIPTION, __version__
+from salmopredict.config import (
+    DEFAULT_ENSEMBLE_MODEL,
+    PREDICTION_MAX,
+    PREDICTION_MIN,
+    SAMPLE_COLUMN,
+    PredictConfig,
+    default_model_path,
+)
+from salmopredict.pipeline import run_pipeline
+
+# Branding images, shipped inside the package so they show after a plain install.
+_ASSETS = Path(__file__).resolve().parent / "assets"
+_ICON_PATH = _ASSETS / "salmopredict_icon.png"   # salmopredict app icon (square)
+_LOGO_PATH = _ASSETS / "vphs_logo.png"           # VPHS lab logo (banner)
+
+_STAGE_LABELS = {
+    "load": "Loading model",
+    "predict": "Predicting",
+    "done": "Complete",
+}
+
+
+@st.cache_resource(show_spinner="Loading model (first time is slow)...")
+def get_predictor(model_path: str):
+    """Load and cache the predictor, keyed by model directory path."""
+    from salmopredict.core.predict import load_predictor
+
+    return load_predictor(model_path)
+
+
+def _input_columns(uploaded):
+    """Peek the header of the uploaded CSV; None if nothing chosen or unreadable."""
+    if uploaded is None:
+        return None
+    try:
+        return list(pd.read_csv(io.BytesIO(uploaded.getvalue()), nrows=0).columns)
+    except Exception:
+        return None
+
+
+def _has_sample(columns) -> bool:
+    return bool(columns) and any(
+        str(c).strip().lower() == SAMPLE_COLUMN.lower() for c in columns
+    )
+
+
+st.set_page_config(
+    page_title="salmopredict",
+    page_icon=str(_ICON_PATH) if _ICON_PATH.exists() else None,
+    layout="wide",
+)
+
+# Header: salmopredict app icon + title on the left, VPHS lab logo top-right.
+_icon_col, _title_col, _logo_col = st.columns([1, 4, 2])
+with _icon_col:
+    if _ICON_PATH.exists():
+        st.image(str(_ICON_PATH))
+with _title_col:
+    st.title("salmopredict")
+    st.caption(
+        f"Salmonella incidence prediction from virulence-factor gene features (v{__version__})"
+    )
+with _logo_col:
+    if _LOGO_PATH.exists():
+        st.image(str(_LOGO_PATH))
+
+st.markdown(DESCRIPTION)
+
+# --------------------------------------------------------------------------- #
+# Parameters
+# --------------------------------------------------------------------------- #
+_default_model = default_model_path()
+with st.sidebar:
+    st.header("Model")
+    model_path = st.text_input(
+        "AutoGluon model directory",
+        value=str(_default_model) if _default_model else "",
+        key="model_path",
+        help="Directory produced by TabularPredictor.save (or the slim deploy clone).",
+    )
+    model_name = st.text_input(
+        "Ensemble model", value=DEFAULT_ENSEMBLE_MODEL, key="model_name",
+        help="Falls back to the model's best if this name is absent.",
+    )
+
+    st.header("Input")
+    uploaded = st.file_uploader(
+        "Feature CSV", type=["csv"], accept_multiple_files=False, key="input",
+    )
+    output_dir = st.text_input("Output folder", value="", key="output_dir")
+
+    columns = _input_columns(uploaded)
+    has_input = uploaded is not None
+    input_has_sample = _has_sample(columns)
+    if has_input:
+        if input_has_sample:
+            st.caption(f"Input has a '{SAMPLE_COLUMN}' column, so the output is "
+                       f"{SAMPLE_COLUMN} plus Incidence(%).")
+        elif columns is not None:
+            st.caption("No 'Sample' column, so the output is Incidence(%) only "
+                       "(metadata cannot be attached).")
+
+    # Metadata attach is only available when the input carries a Sample column.
+    attach_file = None
+    if input_has_sample:
+        st.header("Attach metadata (needs a Sample column)")
+        st.caption(
+            "Joined on the 'Sample' key. The metadata CSV must also have a "
+            "'Sample' column; its other columns are appended to the output. "
+            "Example: examples/example_meta.csv."
+        )
+        attach_file = st.file_uploader(
+            "Metadata CSV (joined on Sample)", type=["csv"], key="attach",
+        )
+
+    run_clicked = st.button("Run prediction", type="primary", width="stretch", key="run_btn")
+
+
+# --------------------------------------------------------------------------- #
+# Run
+# --------------------------------------------------------------------------- #
+def _run() -> None:
+    if not model_path:
+        st.error("Please provide the AutoGluon model directory.")
+        return
+    if not has_input:
+        st.error("Please upload a feature CSV.")
+        return
+    if not output_dir:
+        st.error("Please provide an output folder.")
+        return
+
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    bar = st.progress(0.0, text="Starting...")
+
+    def cb(stage: str, done: int, total: int, message: str) -> None:
+        label = _STAGE_LABELS.get(stage, stage)
+        if total and total > 0:
+            bar.progress(min(1.0, done / total), text=f"{label}: {message}")
+        else:
+            bar.progress(0.0, text=f"{label}: {message}")
+
+    try:
+        # The uploaded file is materialised into a throwaway temp dir (never the
+        # output folder), so only pred_<stem>.csv is left behind. The temp dir is
+        # removed as soon as the run finishes.
+        with tempfile.TemporaryDirectory(prefix="salmopredict_") as tmp:
+            tmpd = Path(tmp)
+            input_path = tmpd / uploaded.name
+            input_path.write_bytes(uploaded.getvalue())
+
+            attach_path = None
+            if input_has_sample and attach_file is not None:
+                attach_path = tmpd / attach_file.name
+                attach_path.write_bytes(attach_file.getvalue())
+
+            config = PredictConfig(
+                input_path=input_path,
+                output_dir=out,
+                model_path=Path(model_path),
+                ensemble_model=model_name or DEFAULT_ENSEMBLE_MODEL,
+                attach_metadata=attach_path,
+                force=True,
+            )
+            predictor = get_predictor(model_path)
+            with st.spinner("Running..."):
+                result = run_pipeline(config, progress=cb, predictor=predictor)
+    except Exception as exc:  # surface any pipeline error in the UI
+        st.error(f"Run failed: {exc}")
+        return
+
+    bar.progress(1.0, text="Complete")
+    st.session_state["result"] = result
+    st.success(
+        f"Done. {result.n_rows} rows, label={result.label}, model={result.model_used}."
+    )
+
+
+if run_clicked:
+    _run()
+
+# --------------------------------------------------------------------------- #
+# Results
+# --------------------------------------------------------------------------- #
+result = st.session_state.get("result")
+if result is not None:
+    st.subheader(result.input_path.name)
+    if result.warned:
+        st.warning(
+            f"{result.missing_fraction:.1%} of model features were missing and "
+            f"filled with the fill value; check the input matches this model."
+        )
+    if result.collisions:
+        st.warning(
+            f"{len(result.collisions)} normalised column-name collision(s): "
+            f"{', '.join(result.collisions)}"
+        )
+    st.dataframe(result.predictions, width="stretch", hide_index=True)
+    st.download_button(
+        f"Download pred_{result.input_path.stem}.csv",
+        result.predictions.to_csv(index=False).encode("utf-8"),
+        file_name=f"pred_{result.input_path.stem}.csv",
+        mime="text/csv",
+        key=f"dl_{result.input_path.stem}",
+    )
+    with st.expander(f"Imputed features ({len(result.imputed)}), filled with fill value"):
+        st.write(", ".join(result.imputed) if result.imputed else "None")
+    if result.capped or result.floored:
+        st.caption(
+            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}."
+        )
+    st.caption(f"Output columns: {', '.join(result.predictions.columns)}")
+    st.caption(f"Written to: {result.output_path}")