Protein Post-Translational Modification Analysis

Comprehensive PTM analysis using iPTMnet (primary), ProtVar (functional context), UniProt (baseline), STRING (interactions), ELM (linear motifs), and MassIVE/ProteomeXchange (experimental data).

iPTMnet is down (checked 2026-10-08). Its REST API has answered HTTP 503 to every request since at least 2026-09-20 while the website stays up, so every iPTMnet_* call below currently returns that error. Try one call; if it is a 503, use the fallbacks given in each phase -- UniProt_get_ptm_processing_by_accession for modified residues (with the modifying enzyme where curated), OmniPath_get_enzyme_substrate for enzyme-substrate pairs, EBIProteins_get_proteomics_ptm for mass-spectrometry evidence. Nothing replaces iPTMnet's proteoform and PTM-dependent-interaction data; say so in the report rather than filling the gap.

LOOK UP DON'T GUESS

• PTM sites/enzymes: iPTMnet_get_ptm_sites
• Functional consequence: ProtVar_get_function + iPTMnet_get_ptm_ppi
• Proteoforms: iPTMnet_get_proteoforms
• Linear motifs: ELM_get_instances

COMPUTE, DON'T DESCRIBE

When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

Domain Reasoning

PTMs are context-dependent: same phosphorylation site can activate or inhibit depending on kinase and effectors. Always check: which enzyme, what functional consequence, in what cell context.

KEY PRINCIPLES

1. Disambiguation first -- resolve to UniProt accession before iPTMnet calls
2. iPTMnet is SOAP-style -- every call requires operation parameter
3. Evidence-graded -- distinguish experimental (T1) from predicted (T4)
4. English-first queries

Workflow

Phase 0: Protein Disambiguation → UniProt accession
Phase 1: PTM Site Inventory → iPTMnet_get_ptm_sites
Phase 2: Proteoform Analysis → iPTMnet_get_proteoforms
Phase 3: PTM-Dependent Interactions → iPTMnet_get_ptm_ppi
Phase 4: Functional Context → ProtVar_get_function at key sites
Phase 4b: Linear Motif Context → ELM_get_instances for SLiM overlap
Phase 4c: Experimental Data → MassIVE/ProteomeXchange
Phase 5: Synthesis & Report

Phase 0: Disambiguation

• iPTMnet_search(operation="search", search_term="TP53", role="Substrate") -- find UniProt IDs
• If user provides UniProt accession directly, use it
• If iPTMnet is down: UniProt_search(query="gene_exact:TP53 AND reviewed:true", organism="human", limit=3) for the accession (a bare "TP53" ranks TP53TG5 and TP53BP1 above P04637)
• Select human entry if multiple hits

Phase 1: PTM Sites

iPTMnet_get_ptm_sites(operation="get_ptm_sites", uniprot_id="P04637") -- returns position, residue, modification type, enzyme, evidence. Group by modification type. Fallback: UniProt_get_ptm_processing_by_accession(accession="P04637") (modified residues, with the modifying enzyme in the description where curated, e.g. "Phosphoserine; by HIPK4"), OmniPath_get_enzyme_substrate(substrates="TP53") for enzyme-substrate pairs with residue and modification type, and EBIProteins_get_proteomics_ptm(accession="P04637") for MS-observed sites.

Phase 2: Proteoforms

iPTMnet_get_proteoforms(operation="get_proteoforms", uniprot_id=...) -- distinct PTM combinations. Focus on those with functional/disease annotations if >20.

Phase 3: PTM-Dependent Interactions

iPTMnet_get_ptm_ppi(operation="get_ptm_ppi", uniprot_id=...) -- interacting protein, PTM site, effect (enables/disrupts). Supplement with STRING_get_interaction_partners(identifiers=gene, species=9606, required_score=700). If iPTMnet is down, OmniPath_get_enzyme_substrate(enzymes=gene) and (substrates=gene) give the enzyme-substrate pairs behind many PTM-dependent interactions, but not whether a modification enables or disrupts a binding.

Phase 4: Functional Context

ProtVar_get_function(accession=..., position=N, variant_aa=AA) -- domain, active site, binding site, conservation. Grade: active-site PTM > domain-core > disordered region.

Phase 4b: Linear Motifs (ELM)

ELM_get_instances(operation="get_instances", uniprot_id=..., motif_type="MOD") -- MOD = modification sites, DEG = degradation signals. Cross-reference with Phase 1 PTM positions. ELM_list_classes(operation="list_classes") for motif details.

Phase 4c: Experimental Data

MassIVE_search_datasets(species="9606"), MassIVE_get_dataset(accession="MSV...") for public MS datasets.

Phase 4d: EBI Proteins Cross-Validation (Structural, Antigenic, MS-Peptide Evidence)

src/tooluniverse/data/ebi_proteins_ext_tools.json provides 11 UniProt-accession-keyed tools from the EBI Proteins API — a second, independent evidence source to corroborate or extend the iPTMnet/ProtVar findings above, not a replacement for them:

Known broken (verified live, not a guess): EBIProteins_get_rna_editing returns HTTP 404 directly from https://www.ebi.ac.uk/proteins/api/rna_editing/... for both of its own documented example accessions (P42262, P28335), while the sibling mutagenesis endpoint on the same API returns 200 for the same host. This looks like EBI deprecated/removed the endpoint rather than a transient outage — re-verify with a direct tu run EBIProteins_get_rna_editing '{"accession": "..."}' before relying on it, and do not present RNA-editing results from this tool as available without that check.

*Protein-level variant lookup (distinct from Phase 1-4 PTM tools, not duplicative of `tooluniverse-variant-analysis`'s SPDI/HGVS/rsID notation conversion):*

All 3 return multiple UniProt entries per query (isoforms, paralogs sharing the position) — always check total_entries/total_variants and report which specific entry/isoform a finding came from, don't assume the first entry is the canonical one.

Single-category shortcuts (verified identical data to `EBIProteins_get_features`): EBIProteins_get_domains_sites, EBIProteins_get_molecule_processing, and EBIProteins_get_structural_features each take a plain accession and return exactly the same feature list as EBIProteins_get_features(accession, category="DOMAINS_AND_SITES"|"MOLECULE_PROCESSING"|"STRUCTURAL") respectively — confirmed live on P04637, byte-for-byte the same 31 DOMAINS_AND_SITES features (minor field-naming difference only: the dedicated tool flattens evidences[].source/.id, the generic one nests source_name/source_id). Use the dedicated tool when you already know which single category you want (one fewer parameter); use EBIProteins_get_features when browsing multiple categories in a loop. EBIProteins_get_molecule_processing is the one to reach for on precursor proteins that get cleaved into a mature form — e.g. P01308 (insulin) returns signal peptide (1-24), B chain (25-54), C peptide (57-87), A chain (90-110).

Protein-to-genome coordinate mapping (two tools, more detail than the existing `EBIProteins_get_coordinates` summary above):

Real example (verified live): EBIProteins_get_coordinate_mapping(accession="P04637") → TP53 maps to 6 transcripts on chromosome 17 (reverse strand), 10 exons, positions 7669612-7676594. The reverse direction confirms it: EBIProteins_get_proteins_by_genomic_loc(taxonomy="9606", location="17:7676154") → TP53 (P04637) at protein residue 72 (Pro) on transcript ENST00000923569 — use this when you have a chromosomal variant position and need to know which protein(s)/residue it hits, before running any PTM/functional analysis on that residue.

*Epitopes (experimental, IEDB-sourced — distinct from `EBIProteins_get_antigen`'s predicted antigenic regions):* EBIProteins_get_epitopes(accession) returns experimentally-mapped immune epitope regions with sequence, PubMed evidence, and IEDB IDs — e.g. P04637 (TP53) has 62 mapped epitopes. Use this over EBIProteins_get_antigen when the question is "has this region actually been shown to trigger an immune response" rather than "does this region look antigenic by sequence pattern" — relevant for vaccine/antibody design questions that land in this skill via a PTM-and-antigenicity angle.

Evidence Grading

Tool Parameter Reference

Critical: All iPTMnet and ELM tools require operation as first parameter (SOAP-style). EBI Proteins tools take a plain accession/dbsnp_id/hgvs string, no operation wrapper.

Fallbacks

Limitations

• iPTMnet biased toward well-studied proteins
• Proteoform data covers observed combinations only
• PTM-PPI: only PTM-specific evidence; more PPIs exist in STRING
• EBIProteins_get_proteomics_ptm/_get_proteomics_peptides/_get_hpp_peptides are MS detection evidence, not curated PTM biology — a hit means "seen by mass spec," not "known functional PTM"
• EBIProteins_get_rna_editing is currently non-functional (HTTP 404 from EBI on both of its own documented example accessions, confirmed live) — do not rely on it until re-verified