tooluniverse-protein-modification-analysis - Claude MCP Skill

# 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:

| Tool | Returns | When to use |
|------|---------|-------------|
| `EBIProteins_get_mutagenesis` | Experimentally characterized point-mutation effects (gain/loss of function, binding/structural impact), UniProtKB-curated with literature evidence | Corroborate a PTM-adjacent residue's functional importance with direct mutagenesis evidence, independent of iPTMnet |
| `EBIProteins_get_proteomics_ptm` | MS-evidence-backed PTM sites from PeptideAtlas/ProteomicsDB/MaxQB/EPD | Cross-check an iPTMnet PTM call against raw MS detection evidence — **this is detection evidence, not curated/annotated PTM biology**, so treat a hit here as "observed by MS" not "known to be functional" |
| `EBIProteins_get_features` | Consolidated UniProt features by category (`DOMAINS_AND_SITES`, `MOLECULE_PROCESSING`, `PTM`, `STRUCTURAL`, `TOPOLOGY`, `VARIANTS`, `MUTAGENESIS`; default `DOMAINS_AND_SITES`) | Get all UniProt-curated PTM annotations in one call via `category="PTM"` — a faster alternative to browsing full UniProt when only PTM feature rows are needed |
| `EBIProteins_get_antigen` | Predicted antigenic regions with match-confidence scores | PTM sites near/inside an antigenic region can affect antibody binding — relevant when a PTM study feeds into antibody or immunoassay design |
| `EBIProteins_get_coordinates` | UniProt protein -> Ensembl gene/transcript ID, chromosome, strand, exon count | Map a PTM residue position back to genomic coordinates for genome-browser cross-referencing |
| `EBIProteins_get_proteomics_peptides` | Generic MS peptide-level detection evidence (position, uniqueness, source DB) | Confirm a PTM-bearing region of the protein has actually been observed by mass spec at all, before trusting a PTM call there |
| `EBIProteins_get_hpp_peptides` | Human Proteome Project peptide evidence — a stringent, typically larger evidence set than `get_proteomics_peptides` for the same accession | Prefer this over `get_proteomics_peptides` when the strongest available MS confirmation is needed (human proteins only) |

**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*):**

| Tool | Returns | When to use |
|------|---------|-------------|
| `EBIProteins_get_variation` | All known variants for a UniProt accession, merged from COSMIC/ClinVar/gnomAD/ExAC/UniProt, with clinical significance and disease associations; filterable by `source_type` and `disease_only` | Want every reported variant on a protein with disease context in one call |
| `EBIProteins_get_variation_by_dbsnp` | Reverse lookup: given a dbSNP rsID, every UniProt entry (incl. isoforms) carrying that variant, with the mapped protein-level consequence | Have an rsID, need to know which protein(s)/isoform(s) it affects and how — `tooluniverse-variant-analysis`'s `NCBIVariation_*` tools convert rsID<->SPDI<->HGVS notation but do not resolve to a UniProt protein consequence the way this does |
| `EBIProteins_get_variation_by_hgvs` | Reverse lookup: given an HGVS genomic expression (`NC_...:g....`), every overlapping UniProt entry with the resulting protein-level consequence | Have a genomic HGVS change, need its amino-acid consequence across all affected isoforms in one call, rather than converting notation first and then looking up each protein separately |

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):**

| Tool | Direction | Returns |
|------|-----------|---------|
| `EBIProteins_get_coordinate_mapping` | protein → genome | Per-*exon* residue-to-genomic-coordinate mapping across all transcript isoforms (chromosome, strand, exon boundaries) — exon-level detail that `EBIProteins_get_coordinates` (chromosome/strand/exon *count* only) doesn't give you |
| `EBIProteins_get_proteins_by_genomic_loc` | genome → protein | Reverse lookup: given `taxonomy` + `location` (`"17:7676154"`, 1-based) or `chromosome`+`position`, every UniProt protein whose coding sequence overlaps that position, with the exact affected residue |

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

| Tier | Criteria |
|------|----------|
| T1 | PTM at validated active/binding site with functional data |
| T2 | PTM in structured domain with ProtVar annotation |
| T3 | Correlation data only (mass spec detection) |
| T4 | Predicted, no experimental validation |

---

## Tool Parameter Reference

| Tool | Key Params |
|------|-----------|
| `iPTMnet_search` | `operation="search"`, `search_term`, `role` |
| `iPTMnet_get_ptm_sites` | `operation="get_ptm_sites"`, `uniprot_id` |
| `iPTMnet_get_proteoforms` | `operation="get_proteoforms"`, `uniprot_id` |
| `iPTMnet_get_ptm_ppi` | `operation="get_ptm_ppi"`, `uniprot_id` |
| `ELM_get_instances` | `operation="get_instances"`, `uniprot_id`, `motif_type` |
| `ELM_list_classes` | `operation="list_classes"` |
| `MassIVE_search_datasets` | `page_size`, `species` |
| `EBIProteins_get_mutagenesis` / `_get_proteomics_ptm` / `_get_antigen` / `_get_coordinates` / `_get_proteomics_peptides` / `_get_hpp_peptides` / `_get_domains_sites` / `_get_molecule_processing` / `_get_structural_features` / `_get_epitopes` | `accession` (UniProt) |
| `EBIProteins_get_features` | `accession`, `category` (default `DOMAINS_AND_SITES`) |
| `EBIProteins_get_coordinate_mapping` | `accession` (UniProt) |
| `EBIProteins_get_proteins_by_genomic_loc` | `taxonomy` (default 9606), `location` ("chr:pos") or `chromosome`+`position` |
| `EBIProteins_get_variation` | `accession`, optional `source_type`, `disease_only` |
| `EBIProteins_get_variation_by_dbsnp` | `dbsnp_id` (rsID) |
| `EBIProteins_get_variation_by_hgvs` | `hgvs` (genomic, `NC_...:g....`) |

**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

| Situation | Fallback |
|-----------|----------|
| Not in iPTMnet | UniProt PTM/processing annotations |
| No PTM-PPI data | STRING general PPI |
| No ProtVar data | UniProt domain annotations |
| No ELM data | Proceed with iPTMnet/UniProt only |
| `EBIProteins_get_rna_editing` 404s | Verified broken as of this writing (EBI-side, not a request bug) — skip, do not retry-loop on it |

## 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