Metadata-Version: 2.4
Name: msdt
Version: 1.0.3
Summary: Mass-spectrometry (MS) 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: Skylark0069
License: MIT
Project-URL: Homepage, https://pypi.org/project/msdt/
Keywords: DT50,half-life,DreaMS,mass-spectrometry,MS/MS,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
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.13
Requires-Dist: torch>=2.0
Dynamic: license-file

# MSDT — Mass-Spectrometry-Based DT50 Persistence Prediction

**MSDT**: **MS** = mass spectrometry (质谱), **DT** = DT50 (biodegradation
half-life). The input is a **DreaMS embedding** — a 1024-dimensional vector
computed by the DreaMS neural network from a chemical's tandem mass spectrum
(MS/MS). Four pre-trained heteroscedastic models (soil / sediment /
water_ph7 / water_ph9) predict the half-life interval, the persistence
probabilities `p(P)` (≥120 d) / `p(vP)` (≥180 d), and the P/vP decision for
the chosen scenario (`prec` = precision-oriented 0.7, `rec` = recall-oriented
0.7).

| 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) |

## How it works

```
MS/MS spectrum of a compound
        │  DreaMS (deep representation learning, transformer)
        ▼
1024-d DreaMS embedding
        │  msdt.predict / predict_batch (this package)
        ▼
logDT50 interval · p(P) · p(vP) · P/vP decision
```

## Installation

```bash
pip install msdt        # this package
pip install dreams      # DreaMS encoder (spectrum -> 1024-d embedding)
```

> 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`.

## 1. Obtain the DreaMS embedding

The input of MSDT is the DreaMS embedding of a spectrum, not the raw spectrum.
DreaMS is a transformer-based, self-supervised model pre-trained on millions
of MS/MS spectra (Bushuiev et al., *Nature Biotechnology* 2025):

- Repository: <https://github.com/pluskal-lab/DreaMS>
- Paper: <https://www.nature.com/articles/s41587-025-02663-3>
- Documentation: <https://dreams-docs.readthedocs.io/>
- Pre-trained weights: <https://zenodo.org/records/10997887>

```python
from dreams.api import dreams_embeddings

embs = dreams_embeddings("spectra.mgf")   # (N, 1024) float matrix
print(embs.shape)                          # e.g. (5, 1024)
```

Supported input formats: `.mgf`, `.mzML`, `.msp`, HDF5.

## 2. Model weights (required)

Weights (~210 MB zip) are **not** bundled in the wheel. Download
[`msdt_models_v1.zip`](https://github.com/Skylark0069/MSDT/releases/download/v1.0.2/msdt_models_v1.zip)
(Release `v1.0.2`), extract it, and point the library at the extracted
`models` directory — per call:

```python
r = msdt.predict("soil", "prec", dreams, models_dir=r"D:\path\to\models")
```

or via the environment variable:

```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
```

## 3. Predict

```python
import msdt

# Single compound: one DreaMS embedding (1024,)
r = msdt.predict(medium="soil", scenario="prec", dreams=embs[0])
print(r["interval_days"], r["p_P"], r["p_vP"], r["is_P"], r["is_vP"])

# Batch: matrix of embeddings (N, 1024)
b = msdt.predict_batch(medium="water_ph7", scenario="rec", dreams=embs)
```

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 — DreaMS embedding, standardised internally |
| `models_dir` | optional dir containing `{medium}/model_final.pth`; overrides `MSDT_MODELS_DIR` |

## 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

- Bushuiev et al., *Nat. Biotechnol.* 2025 — DreaMS (input encoder)
- 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
