proteomics-ptm

name	proteomics-ptm
description	Load when summarising PTM sites (phosphorylation, acetylation, ubiquitination, etc.) from a per-site CSV — site-class assignment (Olsen et al. Class I/II/III by `localization_probability`), per-PTM-type counts, amino-acid distribution, sites-per-protein. Skip when raw spectra are the input or when you only need protein-level abundance (use `proteomics-quantification`).
version	0.5.0
author	OmicsClaw
license	MIT
tags	["proteomics","ptm","phosphorylation","acetylation","ubiquitination","site-localization"]
requires	["pandas","numpy"]

proteomics-ptm

When to use

The user has a PTM-site CSV (columns include protein and ptm_type, optionally localization_probability, amino_acid) and wants per-PTM summary: site-class assignment using Olsen et al. (2006) thresholds (Class I ≥ --loc-threshold, Class II ≥ 0.50, Class III < 0.50, Unknown if no probability), per-PTM-type counts, amino-acid distribution, sites-per-protein.

--loc-threshold controls the Class I cutoff (default 0.75).

For protein-level abundance (no PTM split) use proteomics-quantification. For DE between conditions use proteomics-de.

Inputs & Outputs

Input	Format	Required
PTM sites	.csv with required columns protein, ptm_type; optional localization_probability, amino_acid	yes (unless --demo)
Class I cutoff	--loc-threshold <float> (default 0.75)	no

Output	Path	Notes
All PTM sites	tables/ptm_sites.csv	input copy with added site_class column (Class I / Class II / Class III / Unknown)
Class I subset	tables/ptm_class_I_sites.csv	sites with localization_probability ≥ --loc-threshold
Report	report.md + result.json	per-PTM-type counts, AA distribution, sites-per-protein stats

Flow

1. Load CSV (--input <ptm_sites.csv>) or generate a demo (--demo).
2. Validate required columns protein, ptm_type (proteomics_ptm.py:148-152 raises ValueError("Missing required column: '{col}'")).
3. If localization_probability column exists, classify each site (proteomics_ptm.py:154-161):
   • Class I: prob ≥ --loc-threshold (default 0.75)
   • Class II: prob ≥ 0.50
   • Class III: < 0.50 (default branch)
   • If column missing → Unknown
4. Aggregate per-PTM-type counts (:166), amino-acid distribution (:171, optional), sites-per-protein (:177).
5. Write tables/ptm_sites.csv (proteomics_ptm.py:292) + tables/ptm_class_I_sites.csv (:297) + report.md + result.json.

Gotchas

• Required CSV columns are LOWERCASE: protein, ptm_type. proteomics_ptm.py:149-152 raises ValueError("Missing required column: '{col}'") on first missing column. MaxQuant Phospho (STY)Sites.txt uses Proteins / Modification; rename to lowercase protein / ptm_type first.
• Without localization_probability, EVERY site is Unknown. proteomics_ptm.py:163 falls back to df["site_class"] = "Unknown". The tables/ptm_class_I_sites.csv output will then be empty (no Class I sites). For unprocessed search-engine output that lacks the localization-probability column, run a localization tool (e.g. PhosphoRS / Andromeda) upstream.
• --input REQUIRED unless --demo. proteomics_ptm.py:284 raises ValueError("--input required when not using --demo").
• Class II cutoff is HARD-CODED at 0.50. Only --loc-threshold (Class I cutoff) is configurable. The 0.50 boundary at proteomics_ptm.py:158 cannot be tuned via CLI.
• amino_acid distribution is optional and key-absent when empty. Without the amino_acid column, the script omits summary["amino_acid_distribution"] entirely (the if aa_counts: guard at proteomics_ptm.py:204 skips the assignment). Downstream consumers should check key presence ("amino_acid_distribution" in summary), not just length. Note the actual key name is amino_acid_distribution — NOT aa_counts.
• ptm_type values are case-sensitive. Phospho and phospho are counted as distinct PTM types. Pre-normalise casing if your search engine emits mixed values.

Key CLI

# Demo
python omicsclaw.py run proteomics-ptm --demo --output /tmp/ptm_demo

# Real PTM sites with default Class I threshold
python omicsclaw.py run proteomics-ptm \
  --input phospho_sites.csv --output results/

# Stricter Class I threshold (0.95)
python omicsclaw.py run proteomics-ptm \
  --input phospho_sites.csv --output results/ --loc-threshold 0.95

See also

• references/parameters.md — every CLI flag
• references/methodology.md — Olsen et al. site-class definition, per-PTM caveats
• references/output_contract.md — tables/ptm_sites.csv + Class I subset schemas
• Adjacent skills: proteomics-data-import (upstream — protein-level table normalisation), proteomics-quantification (parallel — protein-level abundance, no PTM split), proteomics-de (downstream — differential PTM site abundance via two-group test), proteomics-enrichment (downstream — pathway enrichment on PTM-target proteins)