Create README.md

README.md

@@ -1,3 +1,113 @@
----
-license: cc0-1.0
----
+---
+license: cc0-1.0
+---
+
+## Winnow HeLa Single Shot Probability Calibrator
+
+**Winnow** recalibrates confidence scores and provides FDR control for *de novo* peptide sequencing (DNS) workflows.  
+This repository contains the calibrator trained on HeLa Single Shot data as referenced in our paper: TODO.
+
+- 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-helaqc-model",
+    allow_patterns=["*.pkl"]),
+    repo_type="model",
+    local_dir=helaqc_model,
+)
+
+# 2) Load calibrator
+calibrator = ProbabilityCalibrator.load(helaqc_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 the HeLa single-shot dataset (PXD044934)
+- 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:
+TODO