antigen-ml 1.0.0__tar.gz

antigen_ml-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Sah, SignorLab, North Dakota State University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

antigen_ml-1.0.0/PKG-INFO

@@ -0,0 +1,413 @@
+Metadata-Version: 2.4
+Name: antigen-ml
+Version: 1.0.0
+Summary: Sequence- and structure-based antigenicity prediction using classical and ESM-2 features
+Author-email: Amit Sah <amit.sah@ndsu.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/asah15/antigen-ml
+Project-URL: Repository, https://github.com/asah15/antigen-ml
+Project-URL: Bug Tracker, https://github.com/asah15/antigen-ml/issues
+Keywords: antigenicity,protein,machine learning,ESM-2,bioinformatics,immunoinformatics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: xgboost>=2.0
+Requires-Dist: biopython>=1.83
+Requires-Dist: matplotlib>=3.8
+Provides-Extra: esm
+Requires-Dist: torch>=2.1; extra == "esm"
+Requires-Dist: transformers>=4.40; extra == "esm"
+Provides-Extra: gui
+Requires-Dist: Pillow>=10.0; extra == "gui"
+Provides-Extra: all
+Requires-Dist: torch>=2.1; extra == "all"
+Requires-Dist: transformers>=4.40; extra == "all"
+Requires-Dist: Pillow>=10.0; extra == "all"
+Dynamic: license-file
+
+# antigen-ml
+
+A machine-learning pipeline for predicting protein antigenicity from sequence and structural features, with optional ESM-2 protein language model embeddings.
+
+**Author:** Amit Sah — SignorLab, North Dakota State University  
+**Language:** Python 3.10+  
+**License:** MIT
+
+---
+
+## Overview
+
+antigen-ml trains classifiers to discriminate antigenic proteins (recognized by the immune system) from non-antigenic proteins. It supports two complementary feature tracks:
+
+| Track | Features | Dimensionality | Notes |
+|---|---|---|---|
+| Classical | AAC, DPC, CTD, physicochemical, structural | 503-dim | No GPU needed |
+| ESM-2 | Pretrained protein language model embeddings | 480–1280-dim | Requires PyTorch + internet |
+
+Both tracks can be combined. The pipeline fetches labeled training data from [IEDB](https://www.iedb.org/) and [UniProt](https://www.uniprot.org/), performs redundancy-aware cross-validation (GroupKFold with MinHash clustering), and outputs a calibrated XGBoost or Random Forest classifier.
+
+### Results on the full IEDB + UniProt dataset (n = 3,763)
+
+| Model | Features | CV AUC | Test AUC | Test MCC | Best threshold |
+|---|---|---|---|---|---|
+| XGBoost | Classical (503-dim) | 0.858 | 0.858 | 0.571 | 0.40 |
+| XGBoost | ESM-2 35M + Classical | ≥0.95 | — | — | — |
+
+---
+
+## Repository layout
+
+```
+antigen-ml/
+├── train.py                  # Main training script
+├── predict.py                # Inference on new FASTA sequences
+├── requirements.txt          # Python dependencies
+├── LICENSE
+├── README.md
+│
+├── src/
+│   ├── download_data.py      # Fetch labeled data from IEDB + UniProt
+│   ├── data.py               # FASTA/CSV I/O, cleaning, train/test split
+│   ├── features.py           # AAC, DPC, CTD, physicochemical features
+│   ├── struct_features.py    # Structural propensity features (28-dim)
+│   ├── models_classical.py   # Logistic regression, SVM, RF, XGBoost
+│   ├── models_deep.py        # ESM-2 embedding extractor + ProteinCNN
+│   └── evaluate.py           # AUC, MCC, PR, threshold search, plots
+│
+├── data/
+│   ├── raw/                  # Downloaded IEDB CSVs and UniProt FASTAs (not tracked)
+│   └── processed/            # dataset.csv built by download_data.py (not tracked)
+│
+└── results/                  # Model weights, plots, summary (best_model.pkl not tracked)
+```
+
+---
+
+## Installation
+
+**1. Clone the repository**
+
+```bash
+git clone https://github.com/asah15/antigen-ml.git
+cd antigen-ml
+```
+
+**2. Create a virtual environment (recommended)**
+
+```bash
+python -m venv .venv
+# Windows
+.venv\Scripts\activate
+# macOS / Linux
+source .venv/bin/activate
+```
+
+**3. Install core dependencies**
+
+```bash
+pip install -r requirements.txt
+```
+
+**4. (Optional) Install ESM-2 dependencies**
+
+Required only if you use `--features esm` during training.
+
+```bash
+# CPU-only PyTorch (smaller download):
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install transformers>=4.40
+
+# GPU (CUDA 12.x):
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+pip install transformers>=4.40
+```
+
+---
+
+## Quickstart
+
+### Step 1 — Download labeled training data
+
+The pipeline supports three data modes. **Mode A** (IEDB bulk export) gives the most sequences and is recommended.
+
+#### Mode A: IEDB bulk export (recommended, ~1,900 antigens)
+
+1. Go to [https://www.iedb.org/database_export_v3.php](https://www.iedb.org/database_export_v3.php)
+2. Download **B Cell Assays** → `bcell_full_v3.zip`
+3. Extract so that `bcell_full_v3_single_file/bcell_full_v3.csv` is accessible
+
+```bash
+python src/download_data.py \
+    --mode A \
+    --iedb_csv path/to/bcell_full_v3_single_file/bcell_full_v3.csv \
+    --out_csv data/processed/dataset.csv
+```
+
+#### Mode B: UniProt KW-0045 keyword query (~600 antigens, internet only)
+
+```bash
+python src/download_data.py \
+    --mode B \
+    --out_csv data/processed/dataset.csv
+```
+
+#### Mode C: Synthetic demo (no data needed, for testing the pipeline)
+
+```bash
+python src/download_data.py \
+    --mode C \
+    --out_csv data/processed/dataset.csv
+```
+
+---
+
+### Step 2 — Train a classifier
+
+#### Classical features (fast, no GPU required)
+
+```bash
+python train.py \
+    --csv data/processed/dataset.csv \
+    --features aac,dpc,ctd,phys,struct \
+    --models rf,xgb \
+    --cv 5
+```
+
+#### ESM-2 embeddings only
+
+```bash
+python train.py \
+    --csv data/processed/dataset.csv \
+    --features esm \
+    --esm_model facebook/esm2_t12_35M_UR50D \
+    --models xgb
+```
+
+Embeddings are automatically cached to `results/esm_cache.npy` after the first run. Subsequent training runs load from cache and skip the slow embedding step.
+
+#### Combined: ESM-2 + classical features (highest accuracy)
+
+```bash
+python train.py \
+    --csv data/processed/dataset.csv \
+    --features aac,dpc,ctd,phys,struct,esm \
+    --esm_model facebook/esm2_t12_35M_UR50D \
+    --models xgb
+```
+
+#### All options
+
+```
+--csv PATH          Labeled CSV with 'sequence' and 'label' columns
+--pos PATH          FASTA of antigen proteins (use with --neg)
+--neg PATH          FASTA of non-antigen proteins (use with --pos)
+--demo              Use 300 synthetic sequences per class (no files needed)
+
+--features STR      Comma-separated: aac,dpc,ctd,phys,struct,esm
+                    Default: aac,dpc,ctd,phys,struct
+--esm_model STR     ESM-2 HuggingFace model ID (default: facebook/esm2_t12_35M_UR50D)
+                    Options:
+                      facebook/esm2_t6_8M_UR50D    320-dim  (fastest)
+                      facebook/esm2_t12_35M_UR50D  480-dim  (default)
+                      facebook/esm2_t30_150M_UR50D 640-dim
+                      facebook/esm2_t33_650M_UR50D 1280-dim (best quality)
+--esm_cache PATH    Path to save/load ESM embeddings (default: results/esm_cache.npy)
+--models STR        Comma-separated: logreg,svm,rf,xgb  (default: rf,xgb)
+--cv INT            Cross-validation folds (default: 5)
+--out DIR           Output directory (default: results/)
+--seed INT          Random seed (default: 42)
+```
+
+**Outputs** written to `results/`:
+
+| File | Description |
+|---|---|
+| `best_model.pkl` | Trained classifier (best CV AUC) |
+| `summary.csv` | Per-model CV and test metrics |
+| `roc_pr.png` | ROC and Precision-Recall curves |
+| `metric_bars.png` | AUC bar chart across models |
+| `feature_importance.png` | Top-30 feature importances (RF/XGB) |
+| `esm_cache.npy` | Cached ESM-2 embeddings (if applicable) |
+
+---
+
+### Step 3 — Predict antigenicity for new proteins
+
+```bash
+python predict.py \
+    --fasta my_proteins.fasta \
+    --model results/best_model.pkl \
+    --threshold 0.40 \
+    --out predictions.tsv
+```
+
+#### Threshold guidance
+
+The default threshold is 0.50. For the XGBoost + classical model, threshold **0.40** maximizes MCC on the held-out test set. Use the value printed during training (`best-thr=X.XX`) for the model you saved.
+
+#### Output columns
+
+| Column | Description |
+|---|---|
+| `protein_id` | Sequence ID from FASTA header (first word) |
+| `length` | Amino-acid length after cleaning |
+| `antigenicity_score` | Model probability (0–1); higher = more likely antigen |
+| `prediction` | `antigen` or `non-antigen` at the given threshold |
+| `flag` | `low_confidence` if score is between 0.40 and 0.60 |
+
+#### All options
+
+```
+--fasta PATH        Input FASTA file (required)
+--model PATH        Trained model pickle (default: results/best_model.pkl)
+--threshold FLOAT   Decision threshold (default: 0.5)
+--out PATH          Output TSV path (default: stdout)
+--min_len INT       Skip sequences shorter than N aa (default: 30)
+--max_len INT       Truncate sequences longer than N aa (default: 6000)
+```
+
+---
+
+## Feature sets
+
+| Set | Flag | Dim | Description |
+|---|---|---|---|
+| Amino acid composition | `aac` | 20 | Fraction of each of the 20 standard amino acids |
+| Dipeptide composition | `dpc` | 400 | Fraction of each of the 400 dipeptide pairs |
+| CTD | `ctd` | 42 | Composition, transition, distribution descriptors (Dubchak 1995) |
+| Physicochemical | `phys` | 13 | MW, charge, pI, GRAVY, aromaticity, instability index, etc. |
+| Structural propensity | `struct` | 28 | Chou-Fasman, Eisenberg hydrophobicity, Vihinen flexibility, Janin surface exposure |
+| ESM-2 embeddings | `esm` | 320–1280 | Mean-pooled last-hidden-state from ESM-2 (Meta AI) |
+
+---
+
+## Data sources
+
+- **IEDB** (Immune Epitope Database): B-cell assay bulk export v3. Positive labels are proteins with experimentally confirmed B-cell epitopes. [https://www.iedb.org](https://www.iedb.org)
+- **UniProt/Swiss-Prot**: Reviewed entries. Positives are annotated with keyword KW-0045 (Antigen) in viral and bacterial organisms. Negatives are human, yeast, and plant entries without that keyword. [https://www.uniprot.org](https://www.uniprot.org)
+
+---
+
+## Reproducing the benchmark
+
+```bash
+# 1. Download IEDB bulk export manually (see Step 1 above), then:
+python src/download_data.py \
+    --mode A \
+    --iedb_csv path/to/bcell_full_v3.csv \
+    --out_csv data/processed/dataset.csv
+
+# 2. Train
+python train.py \
+    --csv data/processed/dataset.csv \
+    --features aac,dpc,ctd,phys,struct \
+    --models rf,xgb \
+    --seed 42
+
+# 3. Inspect results
+cat results/summary.csv
+```
+
+---
+
+## Windows GUI
+
+A point-and-click interface is included for running predictions and viewing training results without touching the command line.
+
+---
+
+### Option A — pip install (cleanest, no install wizard needed)
+
+Works on Windows, macOS, and Linux. No `.exe`, no `.bat`, no security warnings.
+
+```bash
+pip install antigen-ml          # core dependencies
+pip install antigen-ml[gui]     # + Pillow for plot display in the GUI
+```
+
+Then launch from any terminal:
+
+```bash
+antigenml-gui                   # opens the GUI window
+antigenml-train  --csv ...      # training pipeline
+antigenml-predict --fasta ...   # inference
+```
+
+> PyPI page: [pypi.org/project/antigen-ml](https://pypi.org/project/antigen-ml)
+
+---
+
+### Option B — Python installer script (Windows, no security warnings)
+
+Windows Smart App Control blocks unsigned `.bat` and `.exe` files, but
+`.py` files run through Python are never blocked.
+
+**Requirements:** Python 3.10+ in PATH ([python.org/downloads](https://www.python.org/downloads/)).
+
+```
+python windows\install.py
+```
+
+This creates a `.venv`, installs dependencies, and places an **antigen-ml GUI** shortcut on your Desktop.
+
+---
+
+### Option C — Standalone .exe (no Python required)
+
+Build a fully self-contained executable using PyInstaller and optionally wrap it into a one-click Setup wizard with Inno Setup.
+
+**Step 1 — Install build tools** (once):
+
+```
+pip install pyinstaller
+```
+
+Inno Setup (optional, for the Setup wizard): [jrsoftware.org/isinfo.php](https://jrsoftware.org/isinfo.php)
+
+**Step 2 — Build:**
+
+```
+windows\build_exe.bat
+```
+
+If Inno Setup is installed this produces `windows\Output\antigenml-setup.exe`, a standard Windows installer wizard. Without Inno Setup it produces the bundle at `dist\antigenml-gui\antigenml-gui.exe`; distribute the entire `antigenml-gui\` folder.
+
+> **Note:** The standalone .exe excludes ESM-2 (PyTorch) because it would add ~2 GB. Use `train.py` with `--features aac,dpc,ctd,phys,struct` (classical features only) when distributing models that run with the standalone build.
+
+---
+
+### GUI features
+
+**Predict tab** — Select a FASTA file and a trained model (`.pkl`), adjust the threshold and sequence-length filters, then click **Run**. Progress streams into the log panel in real time. Results appear in a table when the run completes: antigenic proteins are highlighted in orange, non-antigenic in green, and low-confidence calls (score 0.40–0.60) in yellow.
+
+**Results tab** — Browse the plots saved by `train.py` (ROC & PR curves, AUC comparison, feature importances) and the per-model metrics from `results/summary.csv`. Click **Refresh** after a new training run to reload everything.
+
+---
+
+## Citation
+
+If you use this tool in published work, please cite:
+
+```
+Sah, A. (2026). antigen-ml: sequence- and structure-based antigenicity prediction
+using classical and protein language model features. GitHub.
+https://github.com/ash15/antigen-ml
+```
+
+---
+
+## References
+
+- Dubchak, I. et al. (1995). Prediction of protein folding class using global description of amino acid sequence. *PNAS* 92(19), 8700–8704.
+- Lin, Z. et al. (2023). Evolutionary-scale prediction of atomic-level protein structure with a language model. *Science* 379(6637), 1123–1130. (ESM-2)
+- Vita, R. et al. (2019). The Immune Epitope Database (IEDB): 2018 update. *Nucleic Acids Research* 47(D1), D339–D343.