Metadata-Version: 2.4
Name: msdt
Version: 2.0.0
Summary: Medium-specific biodegradation and hydrolysis half-life distributions and persistence probabilities from DreaMS mass spectral embeddings
Author: Skylark0069
License: MIT
Project-URL: Homepage, https://github.com/Skylark0069/MSDT
Project-URL: Repository, https://github.com/Skylark0069/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

**Predicting environmental half-life distributions from tandem mass spectra**

MSDT accompanies *Unknown chemicals hiding in plain sight: a global atlas of persistence risks* by Yunhao Ke, Xuebing Wang, Nanyang Yu and Si Wei. Four medium-specific models map 1,024-dimensional [DreaMS](https://github.com/pluskal-lab/DreaMS) embeddings to half-life estimates, predictive uncertainty and persistence probabilities.

Soil and sediment models predict biodegradation half-lives. Water models predict hydrolysis half-lives at pH 7 and pH 9, corresponding to the study's freshwater and seawater endpoints.

## Study highlights

- 442,725 consensus spectral features screened across 126 GNPS datasets spanning 23 countries and marine regions.
- 44,259 persistence candidates in the Persistence Spectral Atlas; 98.1% lacked spectral-library matches.
- 5,456 high-confidence aqueous candidates, including 1,011 with human-sample spectral matches.
- Structural and family annotations integrated through library matching, SIRIUS and molecular networking.

## Installation

Python 3.10 or later:

```bash
pip install msdt==2.0.0
```

To encode MS/MS spectra, install DreaMS:

```bash
pip install git+https://github.com/pluskal-lab/DreaMS.git
```

For a source installation, clone this repository and run `pip install .`.

## Model weights

Download the [model weights](https://github.com/Skylark0069/MSDT/releases/download/v1.0.2/msdt_models_v1.zip), extract the archive, and point `models_dir` at this directory:

```text
models/
  soil/model_final.pth
  sediment/model_final.pth
  water_ph7/model_final.pth
  water_ph9/model_final.pth
```

You can also configure the directory through `MSDT_MODELS_DIR`:

```powershell
# PowerShell
$env:MSDT_MODELS_DIR = "D:\path\to\models"
```

```bash
# Linux / macOS
export MSDT_MODELS_DIR=/path/to/models
```

The explicit `models_dir` takes priority, followed by the environment variable and package-local `msdt/models`.

## Quick start

```python
from dreams.api import dreams_embeddings
import msdt

embs = dreams_embeddings("spectra.mgf")  # (N, 1024)

# One spectrum
r = msdt.predict("soil", embs[0], models_dir="models")
print(r["half_life_days"], r["interval_days"])
print(r["p_P"], r["p_vP"], r["is_P"], r["is_vP"])

# Batch prediction and high-confidence selection
b = msdt.predict_batch("water_ph7", embs, models_dir="models")
high_confidence = b["p_P"] >= 0.9
```

MSDT accepts DreaMS embeddings and applies the standardization stored in each checkpoint. The study used positive-ion [M+H]+ spectra.

| Parameter | Values |
|---|---|
| `medium` | `soil`, `sediment`, `water_ph7`, `water_ph9` |
| `dreams` | `(1024,)` for `predict`; `(N, 1024)` for `predict_batch` |
| `models_dir` | Directory containing the model checkpoints |
| `analysis` | Keyword-only `global` (default) or `evaluation` |

## Persistence probabilities

| Model | P boundary (days) | vP boundary (days) | Global tails | Evaluation tails |
|---|---:|---:|---|---|
| `soil` | 120 | 180 | Gaussian | Gaussian |
| `sediment` | 120 | 180 | Student-t, df = 8 | Student-t, df = 8 |
| `water_ph7` | 40 | 60 | Gaussian | Student-t, df = 8 |
| `water_ph9` | 60 | 180 | Gaussian | Gaussian |

`p_P` and `p_vP` are the probabilities that DT50 exceeds the corresponding boundary. Binary classifications use **p >= 0.5**. The study also uses probability tiers of 0.7 and 0.9. The 180-day seawater vP boundary is a study-specific comparison threshold.

The default `analysis="global"` follows environmental deployment. Use `analysis="evaluation"` for the manuscript's OOF/development probability mapping:

```python
evaluation = msdt.predict_batch(
    "water_ph7", embs, models_dir="models", analysis="evaluation"
)
```

Student-t probabilities use the exported sigma as the scale parameter.

## Prediction outputs

Single predictions return Python scalars and lists. Batch numerical outputs are NumPy arrays of length N, with intervals shaped `(N, 2)`.

| Field | Description |
|---|---|
| `mu_log10` | Predicted location of log10(DT50 in days) |
| `sigma_latent_log10` | Latent predictive scale |
| `half_life_days` | Central half-life estimate, 10**mu |
| `interval_log10`, `interval_days` | Nominal 95% normal-approximation intervals, mu +/- 1.96 sigma, and their back-transform |
| `p_P`, `p_vP` | Persistence probabilities |
| `is_P`, `is_vP` | Binary classifications at p >= 0.5 |
| `half_life_threshold_P_days`, `half_life_threshold_vP_days` | Endpoint boundaries in days |
| `probability_cutoff` | Binary classification cutoff, 0.5 |
| `medium`, `process`, `analysis` | Endpoint and analysis metadata |
| `probability_distribution`, `student_t_df` | Tail distribution and degrees of freedom |
| `n` | Batch size |

## Model performance

| Medium | Fitting spectra | Development spectra | Development NLL | Development R² |
|---|---:|---:|---:|---:|
| Soil | 1,924 | 66 | -0.619 | 0.777 |
| Sediment | 1,242 | 178 | -0.560 | 0.358 |
| Freshwater, pH 7 | 2,897 | 287 | 0.636 | 0.103 |
| Seawater, pH 9 | 2,852 | 59 | -0.396 | 0.545 |

Development collections are separated by compound and used for model selection. Fivefold OOF evaluation partitions spectral samples with seed 42. NLL omits the additive Gaussian constant.

## Documentation and tests

- [Model and study methods](https://github.com/Skylark0069/MSDT/blob/main/docs/manuscript.md)
- [Study data records](https://github.com/Skylark0069/MSDT/blob/main/docs/data.md)
- [Model implementations](https://github.com/Skylark0069/MSDT/tree/main/msdt/_models)

The probability implementation reproduces the P/vP flags for all 442,725 global records in each medium. Run the regression suite with:

```bash
python -m unittest discover -s tests -v
```
