Create model card

README.md

@@ -0,0 +1,128 @@
+---
+license: apache-2.0
+language:
+- en
+tags:
+- proteomics
+- mass-spectrometry
+- peptide-sequencing
+- de-novo
+- calibration
+- fdr
+---
+
+## Winnow General Probability Calibrator
+
+**Winnow** recalibrates confidence scores and provides FDR control for *de novo* peptide sequencing (DNS) workflows.  
+This repository hosts a pretrained, general-purpose calibrator that maps raw InstaNovo model confidences and complementary features (mass error, retention time, chimericity, beam features, Prosit features) to well-calibrated probabilities.
+
+- Intended inputs: spectrum input data and corresponding MS/MS PSM results produced by InstaNovo
+- Outputs: calibrated per-PSM probabilities in `calibrated_confidence`.
+
+### What’s inside
+- `calibrator.pkl`: trained classifier
+- `scaler.pkl`: feature standardiser
+- `irt_predictor.pkl`: Prosit iRT regressor used by RT features
+
+---
+
+## How to use
+
+### Python
+```python
+from pathlib import Path
+from huggingface_hub import snapshot_download
+from winnow.calibration.calibrator import ProbabilityCalibrator
+from winnow.datasets.data_loaders import InstaNovoDatasetLoader
+from winnow.scripts.main import filter_dataset
+from winnow.fdr.nonparametric import NonParametricFDRControl
+
+# 1) Download model files
+snapshot_download(
+    repo_id="InstaDeepAI/winnow-general-model",
+    allow_patterns=["*.pkl"]),
+    repo_type="model",
+    local_dir=general_model,
+)
+
+# 2) Load calibrator
+calibrator = ProbabilityCalibrator.load(general_model)
+
+# 3) Load your dataset (InstaNovo-style config)
+dataset = InstaNovoDatasetLoader().load(
+    "path_to_spectrum_data.parquet",
+    "path_to_instanovo_predictions.csv",
+)
+dataset = filter_dataset(dataset)  # standard Winnow filtering
+
+# 4) Predict calibrated confidences
+calibrator.predict(dataset)  # adds dataset.metadata["calibrated_confidence"]
+
+# 5) Optional: FDR control on calibrated confidence
+fdr = NonParametricFDRControl()
+fdr.fit(dataset.metadata["calibrated_confidence"])
+cutoff = fdr.get_confidence_cutoff(0.05)  # 5% FDR cutoff
+dataset.metadata["keep@5%"] = dataset.metadata["calibrated_confidence"] >= cutoff
+```
+
+### CLI
+```bash
+# After `pip install winnow`
+winnow predict \
+  --data-source instanovo \
+  --dataset-config-path config_with_dataset_paths.yaml \
+  --model-folder general_model_folder \
+  --method winnow \
+  --fdr-threshold 0.05 \
+  --confidence-column calibrated_confidence \
+  --output-path outputs/winnow_predictions.csv
+```
+
+---
+
+## Inputs and outputs
+**Required columns for calibration:**
+- Spectrum data (*.parquet)
+  - spectrum_id (string): unique spectrum identifier
+  - sequence (string): ground truth peptide sequence from database search (optional)
+  - retention_time (float): retention time (seconds)
+  - precursor_mass (float): mass of the precursor ion (from MS1)
+  - mz_array (list[float]): mass-to-charge values of the MS2 spectrum
+  - intensity_array (list[float]): intensity values of the MS2 spectrum
+  - precursor_charge (int): charge of the precursor (from MS1)
+
+- Beam predictions (*_beams.csv)
+  - spectrum_id (string)
+  - sequence (string): ground truth peptide sequence from database search (optional)
+  - preds (string): top prediction, untokenised sequence
+  - preds_tokenised (string): comma‐separated tokens for the top prediction
+  - log_probs (float): top prediction log probability
+  - preds_beam_k (string): untokenised sequence for beam k (k≥0)
+  - log_probs_beam_k (float)
+  - token_log_probs_k (string/list-encoded): per-token log probabilities for beam k
+
+**Output columns (added by Winnow's calibrator on `predict`):**
+  - `calibrated_confidence`: calibrated probability
+  - Optional (if requested): `psm_pep`, `psm_fdr`, `psm_qvalue`
+  - All input columns are retained in-place
+
+---
+
+## Training data
+
+- The general model was trained on a pooled, labelled set spanning multiple public datasets to encourage cross-dataset generalisation:
+  - HeLa single-shot (PXD044934)
+  - *Candidatus* Scalindua Brodae (PXD044934)
+  - Wound exudates (PXD025748)
+  - HepG2 (PXD019483)
+  - Immunopeptidomics (PXD006939)
+  - HeLa degradome (PXD044934)
+  - Snake venoms (PXD036161)
+- All default features were enabled for the training of this model.
+- Predictions were obtained using InstaNovo v1.1.1 with knapsack beam search set to 50 beams.
+
+---
+
+## Citation
+
+If you use Winnow or this model, please cite: