msdt 1.0.0__tar.gz

msdt-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-exclude models *
+exclude msdt_models_v1.zip

msdt-1.0.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: msdt
+Version: 1.0.0
+Summary: Multi-medium DT50 persistence prediction: DreaMS 1024-d embedding -> logDT50 interval, p(P)/p(vP) and P/vP decision across soil/sediment/water_ph7/water_ph9
+Author: DT50 project
+License: MIT
+Project-URL: Homepage, https://pypi.org/project/msdt/
+Keywords: DT50,half-life,DreaMS,mass-spectrometry,persistence,uncertainty
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.13
+Requires-Dist: torch>=2.0
+
+# msdt — Multi-medium DT50 Persistence Predictor
+
+Predict chemical biotransformation persistence from a DreaMS mass-spectrometry
+embedding (1024-d) with four pre-trained heteroscedastic neural networks:
+
+| medium | NLL (val) | R² | model |
+|---|---|---|---|
+| soil | -0.619 | 0.777 | two-stage, STAGE2 pure-NLL |
+| sediment | -0.560 | 0.358 | bagging 0.8, 20-member ensemble |
+| water_ph7 | 0.636 | 0.103 | 10-member ensemble, VAR_SCALE 1.16 |
+| water_ph9 | -0.396 | 0.545 | single, β-NLL (β=0.70) |
+
+For each medium and scenario (`prec` = precision-oriented 0.7, `rec` =
+recall-oriented 0.7) it returns the predictive interval, persistence
+probabilities `p(P)` (≥120 d) / `p(vP)` (≥180 d), and the P/vP decision made
+with the corresponding best threshold (from 5-fold CV on the training set).
+
+## Installation
+
+```bash
+pip install msdt
+```
+
+> Note: `torch` is declared as a dependency; pip installs the PyPI build
+> (CPU on Windows). For GPU inference, install the CUDA build first, e.g.
+> `pip install torch --index-url https://download.pytorch.org/whl/cu126`.
+
+### Model weights (required)
+
+Weights (~210 MB zip) are **not** bundled in the wheel. Download
+`msdt_models_v1.zip`, extract it, and point `MSDT_MODELS_DIR` at the extracted
+`models` directory:
+
+```bash
+set MSDT_MODELS_DIR=D:\path\to\extracted\models   # Windows
+export MSDT_MODELS_DIR=/path/to/extracted/models  # Linux
+```
+
+Layout expected:
+
+```
+models/
+  soil/model_final.pth
+  sediment/model_final.pth
+  water_ph7/model_final.pth
+  water_ph9/model_final.pth
+```
+
+## Usage
+
+```python
+import msdt
+
+# Single compound
+r = msdt.predict(medium="soil", scenario="prec", dreams=dreams_1024d)
+print(r["interval_days"], r["p_P"], r["p_vP"], r["is_P"], r["is_vP"])
+
+# Batch (N, 1024)
+b = msdt.predict_batch(medium="water_ph7", scenario="rec", dreams=dreams_Nx1024)
+```
+
+Parameters:
+
+| parameter | values |
+|---|---|
+| `medium` | `"soil"` `"sediment"` `"water_ph7"` `"water_ph9"` |
+| `scenario` | `"prec"` (precision ≥ 0.7, max recall) / `"rec"` (recall ≥ 0.7, max precision) |
+| `dreams` | `(1024,)` or `(N, 1024)` float — raw DreaMS embedding, standardised internally |
+
+## Output
+
+Single (`predict`) returns a dict; batch (`predict_batch`) returns the same
+keys as arrays of length N (`interval_*` as `(N, 2)`):
+
+| field | meaning |
+|---|---|
+| `mu_log10` / `sigma_latent_log10` | predictive mean / deployable σ (log10 days) |
+| `interval_log10` / `interval_days` | 95% interval μ ± 1.96·σ_latent, log10 and days |
+| `p_P` / `p_vP` | P(logDT50 ≥ 120 d) / P(logDT50 ≥ 180 d) |
+| `threshold_P` / `threshold_vP` | best threshold for the chosen scenario |
+| `is_P` / `is_vP` | `p ≥ threshold` → `True` (classified as P / vP) |
+
+## Thresholds (5-fold CV, training set)
+
+| medium | P·prec | P·rec | vP·prec | vP·rec |
+|---|---|---|---|---|
+| soil | 0.118 | 0.132 | 0.020 | 0.006 |
+| sediment | 0.237 | 0.048 | 0.055 | 0.014 |
+| water_ph7 | 0.285 | 0.591 | 0.281 | 0.534 |
+| water_ph9 | 0.429 | 0.381 | 0.414 | 0.321 |
+
+## References
+
+- Salz et al., *Environ. Sci. Technol.* 2026 — DT50 with known label noise α
+- Seitzer et al., ICLR 2022 — β-NLL
+- Lakshminarayanan et al., NeurIPS 2017 — deep ensembles
+- Cator et al., 2022 — bootstrapped deep ensembles

msdt-1.0.0/README.md

@@ -0,0 +1,97 @@
+# msdt — Multi-medium DT50 Persistence Predictor
+
+Predict chemical biotransformation persistence from a DreaMS mass-spectrometry
+embedding (1024-d) with four pre-trained heteroscedastic neural networks:
+
+| medium | NLL (val) | R² | model |
+|---|---|---|---|
+| soil | -0.619 | 0.777 | two-stage, STAGE2 pure-NLL |
+| sediment | -0.560 | 0.358 | bagging 0.8, 20-member ensemble |
+| water_ph7 | 0.636 | 0.103 | 10-member ensemble, VAR_SCALE 1.16 |
+| water_ph9 | -0.396 | 0.545 | single, β-NLL (β=0.70) |
+
+For each medium and scenario (`prec` = precision-oriented 0.7, `rec` =
+recall-oriented 0.7) it returns the predictive interval, persistence
+probabilities `p(P)` (≥120 d) / `p(vP)` (≥180 d), and the P/vP decision made
+with the corresponding best threshold (from 5-fold CV on the training set).
+
+## Installation
+
+```bash
+pip install msdt
+```
+
+> Note: `torch` is declared as a dependency; pip installs the PyPI build
+> (CPU on Windows). For GPU inference, install the CUDA build first, e.g.
+> `pip install torch --index-url https://download.pytorch.org/whl/cu126`.
+
+### Model weights (required)
+
+Weights (~210 MB zip) are **not** bundled in the wheel. Download
+`msdt_models_v1.zip`, extract it, and point `MSDT_MODELS_DIR` at the extracted
+`models` directory:
+
+```bash
+set MSDT_MODELS_DIR=D:\path\to\extracted\models   # Windows
+export MSDT_MODELS_DIR=/path/to/extracted/models  # Linux
+```
+
+Layout expected:
+
+```
+models/
+  soil/model_final.pth
+  sediment/model_final.pth
+  water_ph7/model_final.pth
+  water_ph9/model_final.pth
+```
+
+## Usage
+
+```python
+import msdt
+
+# Single compound
+r = msdt.predict(medium="soil", scenario="prec", dreams=dreams_1024d)
+print(r["interval_days"], r["p_P"], r["p_vP"], r["is_P"], r["is_vP"])
+
+# Batch (N, 1024)
+b = msdt.predict_batch(medium="water_ph7", scenario="rec", dreams=dreams_Nx1024)
+```
+
+Parameters:
+
+| parameter | values |
+|---|---|
+| `medium` | `"soil"` `"sediment"` `"water_ph7"` `"water_ph9"` |
+| `scenario` | `"prec"` (precision ≥ 0.7, max recall) / `"rec"` (recall ≥ 0.7, max precision) |
+| `dreams` | `(1024,)` or `(N, 1024)` float — raw DreaMS embedding, standardised internally |
+
+## Output
+
+Single (`predict`) returns a dict; batch (`predict_batch`) returns the same
+keys as arrays of length N (`interval_*` as `(N, 2)`):
+
+| field | meaning |
+|---|---|
+| `mu_log10` / `sigma_latent_log10` | predictive mean / deployable σ (log10 days) |
+| `interval_log10` / `interval_days` | 95% interval μ ± 1.96·σ_latent, log10 and days |
+| `p_P` / `p_vP` | P(logDT50 ≥ 120 d) / P(logDT50 ≥ 180 d) |
+| `threshold_P` / `threshold_vP` | best threshold for the chosen scenario |
+| `is_P` / `is_vP` | `p ≥ threshold` → `True` (classified as P / vP) |
+
+## Thresholds (5-fold CV, training set)
+
+| medium | P·prec | P·rec | vP·prec | vP·rec |
+|---|---|---|---|---|
+| soil | 0.118 | 0.132 | 0.020 | 0.006 |
+| sediment | 0.237 | 0.048 | 0.055 | 0.014 |
+| water_ph7 | 0.285 | 0.591 | 0.281 | 0.534 |
+| water_ph9 | 0.429 | 0.381 | 0.414 | 0.321 |
+
+## References
+
+- Salz et al., *Environ. Sci. Technol.* 2026 — DT50 with known label noise α
+- Seitzer et al., ICLR 2022 — β-NLL
+- Lakshminarayanan et al., NeurIPS 2017 — deep ensembles
+- Cator et al., 2022 — bootstrapped deep ensembles

msdt-1.0.0/msdt/__init__.py

@@ -0,0 +1,112 @@
+"""msdt - multi-medium DT50 persistence prediction library.
+
+Combines the four medium-optimal heteroscedastic models
+(soil / sediment / water_ph7 / water_ph9). Given a DreaMS mass-spectrometry
+embedding (1024-d) it returns:
+  - predictive interval (mu +/- 1.96*sigma_latent, log10-days and days)
+  - persistence probabilities p(P) / p(vP) (120 d / 180 d thresholds)
+  - P / vP decisions made with the best threshold of the chosen scenario
+    (``prec`` = precision-oriented 0.7, ``rec`` = recall-oriented 0.7)
+
+Usage:
+    import msdt
+    out = msdt.predict("soil", "prec", dreams_1024d, models_dir="D:/models")
+    outs = msdt.predict_batch("water_ph7", "rec", dreams_Nx1024, models_dir="D:/models")
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+import numpy as np
+
+from .engine import (
+    MEDIUM_CFG,
+    MEDIUMS,
+    SCENARIOS,
+    get_engine,
+    validate_scenario,
+    _validate_vector,
+)
+
+__all__ = ["predict", "predict_batch", "MEDIUMS", "SCENARIOS"]
+__version__ = "1.0.0"
+
+
+def _single_result(medium: str, scenario: str, r: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "medium": medium,
+        "scenario": scenario,
+        "mu_log10": float(r["mu_log10"][0]),
+        "sigma_latent_log10": float(r["sigma_latent_log10"][0]),
+        "interval_log10": [float(r["interval_log10"][0, 0]), float(r["interval_log10"][0, 1])],
+        "interval_days": [float(r["interval_days"][0, 0]), float(r["interval_days"][0, 1])],
+        "p_P": float(r["p_P"][0]),
+        "p_vP": float(r["p_vP"][0]),
+        "threshold_P": float(r["threshold_P"]),
+        "threshold_vP": float(r["threshold_vP"]),
+        "is_P": bool(r["is_P"][0]),
+        "is_vP": bool(r["is_vP"][0]),
+    }
+
+
+def predict(
+    medium: str,
+    scenario: str,
+    dreams: Union[np.ndarray, List[float]],
+    models_dir: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Predict for a single compound.
+
+    Args:
+        medium: "soil" | "sediment" | "water_ph7" | "water_ph9"
+        scenario: "prec" (precision >= 0.7, max recall) | "rec" (recall >= 0.7, max precision)
+        dreams: DreaMS embedding, shape (1024,)
+        models_dir: optional directory containing {medium}/model_final.pth;
+            overrides MSDT_MODELS_DIR
+
+    Returns:
+        dict with predictive interval, p(P)/p(vP), thresholds and P/vP decisions
+    """
+    medium = str(medium).lower().strip()
+    scenario = validate_scenario(scenario)
+    x = _validate_vector(dreams, batch=False)
+    r = get_engine(medium, models_dir).run(x, scenario)
+    return _single_result(medium, scenario, r)
+
+
+def predict_batch(
+    medium: str,
+    scenario: str,
+    dreams: Union[np.ndarray, List[List[float]]],
+    models_dir: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Predict for a batch of compounds.
+
+    Args:
+        medium: "soil" | "sediment" | "water_ph7" | "water_ph9"
+        scenario: "prec" | "rec"
+        dreams: DreaMS embedding matrix, shape (N, 1024)
+        models_dir: optional directory containing {medium}/model_final.pth
+
+    Returns:
+        dict; scalar fields become arrays of length N (interval_* are (N, 2))
+    """
+    medium = str(medium).lower().strip()
+    scenario = validate_scenario(scenario)
+    x = _validate_vector(dreams, batch=True)
+    r = get_engine(medium, models_dir).run(x, scenario)
+    return {
+        "medium": medium,
+        "scenario": scenario,
+        "n": int(len(x)),
+        "mu_log10": r["mu_log10"],
+        "sigma_latent_log10": r["sigma_latent_log10"],
+        "interval_log10": r["interval_log10"],
+        "interval_days": r["interval_days"],
+        "p_P": r["p_P"],
+        "p_vP": r["p_vP"],
+        "threshold_P": float(r["threshold_P"]),
+        "threshold_vP": float(r["threshold_vP"]),
+        "is_P": r["is_P"],
+        "is_vP": r["is_vP"],
+    }