Skip to content

fix(ptm): map each UniProt site through a transcript encoding its isoform; classify on the codon's three bases - #489

Merged
enriquea merged 2 commits into
devfrom
fix/ptm-isoform-codons
Nov 18, 2026
Merged

enriquea merged 2 commits into
devfrom
fix/ptm-isoform-codons

Conversation

@enriquea

@enriquea enriquea commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Fixes #486 and #487. Both proposals are trimmed to what changes results; the sections below say what was left out and why.

#486: a UniProt site maps through a transcript encoding its isoform

map_ptm_sites placed every UniProt position on one transcript per protein (the MANE Select one when UniProt cross-references it) whatever isoform that transcript encodes, and read MOD_RES features numbered on a non-canonical isoform as canonical positions. Those sites landed on the wrong codon with no error.

  • Download: also fetches cc_alternative_products (which isoform is canonical) and adds an isoform column: empty for a site on the canonical sequence, the isoform's id (P98175-5) otherwise. A row's ensembl_xrefs keeps only the transcripts whose cross-reference isoformId is that sequence. amino_acid comes from the canonical sequence, so it is left empty for a non-canonical site.
  • Mapping: such a site resolves through those transcripts only (MANE among them first). It never falls back to the gene's MANE Select transcript; with no matching transcript it fails as unresolved. A non-canonical site is written with its isoform as uniprot_id, so (uniprot_id, residue_pos) stays unique (the per-source overlap in plot.py keys on it).
  • Reporting: PTMBuildResult.failure_counts and a Failed: line in ptm build's summary give the failed sites per reason (unresolved, beyond_cds).
  • Old inputs: a UniProt TSV without isoform is refused with a message to download it again, since some of its sites would land on another isoform's codon.
  • Unchanged: PeptideAtlas and CPTAC rows carry no cross-references and keep the gene_mane path; the docs now say when that is right.

Left out: the protein-FASTA download, sequence alignment and residue check. UniProt already says which transcript encodes which isoform, and using that fixes both causes, including the 8 sites in the issue's sample that encode the same residue on the wrong codon, which no residue check can catch. Sites whose isoform has no transcript are dropped rather than rescued by alignment.

#487: classify on the codon's three bases

The mapper computed a codon's three bases and kept only their min and max, and each consumer reconstructed the codon differently:

Consumer Before, for a codon split by an intron
annotate_variants_with_ptm (annotate, landscape, population) codon_start..+2: took in the splice-donor base, missed the base in the next exon
annotate_variants_by_symbol codon_start..codon_end: the whole intron was site
training-set codon join (codon_sites) the two ends: missed one codon base

The sites table now carries codon_pos1..codon_pos3 (transcript order), and all three read them. The window is every position within the flank of one of the bases: identical to before for a contiguous codon, and no longer spanning the intron for a split one. A sites table without these fields is refused with a message to rebuild it.

Left out: counting --flanking-codons along the CDS. It needs transcript structure at annotate time; the docs keep saying the window is counted in genomic bases.

Verification

  • Live UniProt + Ensembl 113 GTF (ETS1, CDK9, RBM10, GATA4), ptm build: a site maps to the wrong codon without error when its sequence differs from the transcript's protein #486's acceptance:
    • ETS1 Thr38 and Ser251 land on the codons of residues 82 and 295 of ENST00000392668's protein.
    • CDK9 Ser35 (P50750-2) is dropped as unresolved.
    • RBM10's two P98175-5 sites map through ENST00000329236, which encodes P98175-5.
    • GATA4 Lys300 moves from the MANE codon (11750222) to the canonical one (11750225).
  • GLI1 Ser130 (ptm annotate: split codons and junction-crossing windows are classified on genomic bases #487's acceptance), both classifiers: chr12:57465111 is site, the splice-donor base chr12:57464869 is proximal, the middle of the intron is non-PTM. A contiguous codon keeps the same site and window positions.
  • Tests:
    • test_ptm.py: the round-trip test now covers a split codon (TP53 residue 25). One new regression test runs the UniProt parser and mapper on an entry whose MANE transcript encodes another isoform; it fails when cross-references are left unfiltered.
    • Hail tests: the uniprot-ptm snapshot (regenerated, +3 fields), conformance and export-strata tests pass.
    • pytest --require-round-trips locally: everything passes except 4 tests in pqtl (caplog comes back empty after earlier tests), which fail identically on dev and pass alone; CI on dev is green.
  • Drift baseline: the uniprot-ptm probe fingerprints the TSV columns and the response keys, which this changes, so the baseline is regenerated here. The rebuild-ledger row also records the release move from 2026_03 to 2026_04.

After merge

Rebuild uniprot-ptm:sites, any ptm build table, and training sets with a ptm_site column (the ClinVar x heart example).

…form; classify on the codon's three bases

#486: map_ptm_sites placed every UniProt position on one transcript per protein,
the MANE Select one when cross-referenced, whatever isoform it encodes, and read
MOD_RES features numbered on a non-canonical isoform as canonical positions.
Such sites landed on the wrong codon with no error (95 of 1,098 sites in a
123-gene sample). The UniProt download now also fetches cc_alternative_products,
records the isoform a site is numbered on (`isoform`, empty for the canonical
sequence) and keeps in `ensembl_xrefs` only the transcripts whose isoformId is
that sequence. Those sites never fall back to the gene's MANE Select transcript;
with no matching transcript they fail as `unresolved`. A site on a non-canonical
isoform is written with that isoform as `uniprot_id` and no `amino_acid`.
PTMBuildResult.failure_counts and `ptm build`'s summary give the failed sites per
reason. A UniProt TSV without the `isoform` column is refused. PeptideAtlas and
CPTAC rows keep the gene_mane path.

#487: the mapper computed a codon's three bases but kept only their min and max,
and the three consumers each guessed the rest: annotate_variants_with_ptm took
codon_start..+2 (the splice-donor base, never the base in the next exon),
annotate_variants_by_symbol took codon_start..codon_end (the whole intron), and
the training-set codon join took the two ends. The sites table now carries
codon_pos1..3 (transcript order); all three classify on them, with the window
measured from the nearest base, which is unchanged for a contiguous codon. A
sites table without them is refused with a message to rebuild it.

Verified on live UniProt and Ensembl 113: ETS1 Thr38 and Ser251 land on the
codons of residues 82 and 295 of the MANE protein, CDK9 Ser35 (P50750-2) is
dropped, RBM10's P98175-5 sites map through the transcript encoding P98175-5,
and GATA4 Lys300 moves off the MANE codon. For GLI1 Ser130 both classifiers
call chr12:57465111 a site and the splice-donor base chr12:57464869 proximal.
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 1745853a-9034-4698-92d9-1d43855ef332

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@qodo-code-review

Copy link
Copy Markdown
Contributor

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

…d release 2026_04

The probe fingerprints the download's TSV columns and the response's entry
keys; this PR adds the isoform column and the comments key
(cc_alternative_products). UniProt also moved from 2026_03 to 2026_04, so the
rebuild-ledger row records the dataset as needing a rebuild.
@codacy-production

Copy link
Copy Markdown

Not up to standards ⛔

🔴 Issues 7 minor

Alerts:
⚠ 7 issues (≤ 0 issues of at least minor severity)

Results:
7 new issues

Category Results
Documentation 7 minor

View in Codacy

🟢 Metrics 33 complexity

Metric Results
Complexity 33

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

@enriquea
enriquea merged commit 532c054 into dev Nov 18, 2026
10 of 11 checks passed
@enriquea
enriquea deleted the fix/ptm-isoform-codons branch November 18, 2026 20:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant