p2s_mapper 1.2.2 → 1.3.0

package/README.md

@@ -1,16 +1,28 @@
 # p2s_mapper
 
-Map a transcript's translation onto a protein structure: the pairwise alignment
-between them, the coordinate maps that alignment implies, which chain of the
-structure is the gene's product, SIFTS residue numbering, and the AlphaFold,
-PDBe and UniProt lookups that find a structure to map in the first place.
+Map a transcript's translation onto a protein structure.
+
+- **Align** the transcript to the structure's sequence (Smith-Waterman or
+  Needleman-Wunsch, BLOSUM62)
+- **Convert coordinates** both ways between transcript, alignment, structure,
+  Mol\* and UniProt numbering
+- **Choose the chain** that best matches the gene's protein
+- **Use SIFTS** to place UniProt annotations and drop fusion-partner residues
+- **Find structures** through AlphaFold, 3D-Beacons, PDBe and UniProt
+
+## Works with g2p_mapper
+
+p2s_mapper covers **protein ↔ structure**. The other half, **genome ↔ protein**,
+is [g2p_mapper](https://github.com/GMOD/g2p_mapper): it turns a transcript's CDS
+into per-codon genome positions, on either strand and across exon boundaries. It
+is p2s_mapper's only runtime dependency, and chaining the two takes you from a
+genome coordinate to a residue in 3D and back.
 
 Extracted from
 [jbrowse-plugin-protein3d](https://github.com/GMOD/jbrowse-plugin-protein3d),
 where we made the measurements behind the scoring rules. The package has no
-React, no JBrowse and no Mol\* dependency: a loaded Mol\* model reaches it
-through narrow structural interfaces, and `g2p_mapper` is the only runtime
-dependency.
+React, JBrowse or Mol\* dependency: a loaded Mol\* model reaches it through
+narrow structural interfaces.
 
 ## Install
 
@@ -18,133 +30,28 @@ dependency.
 npm install p2s_mapper
 ```
 
-## Coordinate conventions
-
-One residue has up to four numbers, and mixing them causes the off-by-one bugs
-this package's types prevent. **Every stored or computed coordinate is a 0-based
-position**: an index into the ungapped structure sequence or the ungapped
-transcript sequence, the one numbering that is dense and zero-based whatever the
-file. `coordinates.ts` brands the three internal spaces — structure position,
-transcript position, alignment column — so the compiler rejects mixing them. Two
-conversions leave that space, and each has exactly one correct route. **Mol\* is
-addressed by `label_seq_id`**, which is `position + 1` only for a file carrying
-`entity_poly_seq` or SEQRES; a SEQRES-less PDB numbers its observed residues by
-author numbering and leaves holes at unobserved loops, so `Entity.seqIds`
-carries the real ids and every crossing goes through `toLabelSeqIds`,
-`rangeToLabelSeqIds` or `makeLabelSeqIdIndex`. **The user sees `auth_seq_id`**,
-the depositors' numbering that papers and UniProt cite (1TUP position 154
-reads 248) and that Mol\*'s own hover shows; `Entity.authSeqIds` carries it, and
-it is display-only. UniProt positions are 1-based, and `pdbUniProtMapping`
-converts them with SIFTS rather than assuming any offset.
-
-## Exports
-
-### Alignment
-
-`runLocalAlignment`, `scoredAlignment`, `needlemanWunsch`, `smithWaterman`,
-`selfScore`, `alignmentTooLarge`, `MAX_ALIGNMENT_CELLS` — Smith-Waterman and
-Needleman-Wunsch over BLOSUM62, with affine gaps and a packed traceback.
-
-`PairwiseAlignment`, `transcriptAlignedSeq`, `structureAlignedSeq`,
-`alignmentLength`, `pairwiseAlignmentProblem`,
-`pairwiseAlignmentSequenceProblem`, `mappedStructureIdentity`,
-`unmapStructurePositions` — the two-row alignment, whose **row order is a
-contract**: row 0 is the transcript, row 1 is the structure. Read it through the
-accessors, not by index.
-
-`alignmentQuality`, `isLowSimilarity`, `describeAlignmentQuality`,
-`describeTranscriptCoverage`, `describeCoveredRange` — identity over the shorter
-sequence separates a real match from a chance local alignment; local identity
-alone does not.
-
-`AlignmentAlgorithm`, `coerceAlignmentAlgorithm`, `ALIGNMENT_ALGORITHM_LABELS`.
-
-### Coordinates
-
-`makeCoordinateMapper`, `CoordinateMapper`, `transcriptRangeToStructureRange`,
-`structurePos`, `transcriptPos`, `alignmentCol` — every conversion built once
-from an alignment, branded by space.
-
-`structureSeqVsTranscriptSeqMap`, `structurePositionToAlignmentMap`,
-`transcriptPositionToAlignmentMap`, `invertMap`, `codonGenomeSpan`,
-`stripStopCodon`, `stripAllStopCodons`.
-
-### Chain choice
-
-`chooseMappedEntity`, `alignTranscriptToEntity`, `explainedFraction`,
-`interactionMatchesMappedEntity` — which polymer entity is the transcript's
-product, ranked by identical residues over the **shorter** of the two sequences.
-A raw match count picks the large partner of every bound peptide, and the
-alignment score does not separate them either.
-
-`extractEntities`, `extractStructureSequences`, `entityLabel`, `residueNumber`,
-`residueRangeToPositions`, `fillAuthSeqIds`, `oneLetterSequence`,
-`toLabelSeqIds`, `rangeToLabelSeqIds`, `makeLabelSeqIdIndex` — read a loaded
-Mol\* model through a structural interface. Read `sequence.code`, never
-`sequence.label`: `label` spells MSE, TPO and ACE by component id, so the string
-outgrows `seqId` and every later position addresses the wrong residue.
-
-`extractPerResidueConfidence`, `looksLikePlddt` — AlphaFold's pLDDT out of the
-B-factor column, keyed by `label_seq_id` because the hierarchy holds only
-observed residues.
-
-`classifyIsoforms`, `selectBestTranscript`, `pickStructureSequence` — rank plain
-`{ id, seq }` isoform records against a chain.
-
-### SIFTS
-
-`fetchUniProtStructureMappings`, `parseUniProtStructureMappings`,
-`pdbeSiftsUrl`, `chooseUniProtMappingForEntity`, `makeUniProtPositionMap`,
-`identityUniProtPositionMap`, `fusionPartnerPositions` — the authoritative
-UniProt ↔ structure alignment. `fusionPartnerPositions` unmaps the residues
-SIFTS gives another protein on a fusion construct, which local alignment
-otherwise bridges (2RH1 scatters 33 receptor residues onto T4 lysozyme).
-
-`toAuthorRange`, `segmentsForAccession` — the author-numbered range a UniProt
-range is cited by. Haemoglobin numbers from the mature protein, so author
-residue 1 is UniProt residue 2.
-
-### Structure sources
-
-`fetchAlphaFoldModels`, `parseAlphaFoldModels`, `pickAlphaFoldModel` — asked
-rather than derived: a protein past AlphaFold's length cap has no F1 model at
-all, and the model version moves.
-
-`fetchExperimentalStructures`, `parseExperimentalStructures` — 3D-Beacons'
-experimental entries, PDBe only, because SASBDB's scattering fits file under the
-same category with near-full coverage and no residue mapping.
-
-`pdbeBestStructuresUrl`, `parseBestStructures`, `isPdbId`,
-`pdbeEntryMoleculesUrl`, `parseEntryMolecules`, `searchUniProtEntries`,
-`buildGeneNameQuery`, `isRecognizedDatabaseId`, `buildUniProtXrefQuery`,
-`getDbIdLabel`, `stripTrailingVersion`.
-
-Every request takes its `fetch` from the call —
-`{ fetch?: typeof fetch, signal? }`, defaulting to `globalThis.fetch` — so a
-host can hand in an instrumented one and a test can hand in a double.
+## How it fits together
 
-### Urls and formats
+![From a gene on the genome to a residue in 3D, and back](docs/img/pipeline.svg)
 
-`getPdbStructureUrl`, `getAlphaFoldStructureUrl`, `resolveStructureUrl`,
-`getPdbIdFromUrl`, `getUniprotIdFromAlphaFoldTarget`,
-`getStructureUrlFromTarget`, `getConfidenceUrlFromTarget`,
-`structureDisplayLabel`, `uniprotGffUrl`, `uniprotFastaUrl`, `uniprotEntryUrl`,
-`rcsbEntryUrl`.
+## Docs
 
-`structureFormatFromContent`, `structureFormatFromName`,
-`structureFileExtension`, `isBinaryStructureUrl` — which parser a structure
-needs, sniffed from **content** rather than a filename. PDB read as mmCIF
-throws, while mmCIF read as PDB succeeds and yields a model with thousands of
-misread atoms and zero polymer entities.
+- [faq.md](docs/faq.md) — can I trust the mapping? What the package checks, and
+  what it leaves to you
+- [pipeline.md](docs/pipeline.md) — the flow above, step by step, and why chain
+  choice divides by the shorter sequence
+- [coordinates.md](docs/coordinates.md) — the four numberings of a residue and
+  the one route between each
+- [api.md](docs/api.md) — every export, grouped by job
 
-`caCoordsToPdb`, `hasValidCaCoords` — a PDB file from Foldseek Cα coordinates.
+## Things to know first
 
-`rawfetch`, `myfetch`, `jsonfetch`, `httpError`, `HttpError`,
-`isDefinitiveFailure`, `networkError`, `abortError`, `timeout`, `FetchOptions`.
-A failed response throws an `HttpError` carrying its `status`, and
-`isDefinitiveFailure` is true for a 4xx — the server understood and declined, so
-retrying repeats the answer. `fetchUniProtStructureMappings` uses it: PDBe
-answers 404 for an entry it has no UniProt mapping for at all.
+- Every coordinate in the API is **0-based**, branded by space so the compiler
+  rejects mixing them. See [coordinates.md](docs/coordinates.md).
+- A `PairwiseAlignment` has **row 0 = transcript, row 1 = structure**. Use the
+  accessors, not indexes.
+- Network functions take `{ fetch?, signal? }` and default to
+  `globalThis.fetch`.
 
 ## License
 

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './types.ts';
 export * from './mappings.ts';
 export * from './pairwiseAlignment.ts';
 export * from './alignmentQuality.ts';
+export * from './sharedStretches.ts';
 export * from './coordinates.ts';
 export * from './invertMap.ts';
 export * from './stripStopCodon.ts';

package/dist/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./types.js"), exports);
 __exportStar(require("./mappings.js"), exports);
 __exportStar(require("./pairwiseAlignment.js"), exports);
 __exportStar(require("./alignmentQuality.js"), exports);
+__exportStar(require("./sharedStretches.js"), exports);
 // Coordinates
 __exportStar(require("./coordinates.js"), exports);
 __exportStar(require("./invertMap.js"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,YAAY;AACZ,6CAA0B;AAC1B,gDAA6B;AAC7B,yDAAsC;AACtC,wDAAqC;AAErC,cAAc;AACd,mDAAgC;AAChC,iDAA8B;AAC9B,sDAAmC;AAEnC,eAAe;AACf,0DAAuC;AACvC,iEAA8C;AAC9C,mEAAgD;AAChD,sDAAmC;AAEnC,QAAQ;AACR,yDAAsC;AACtC,sDAAmC;AAEnC,oBAAoB;AACpB,uDAAoC;AACpC,0DAAuC;AACvC,0DAAuC;AACvC,wDAAqC;AACrC,qDAAkC;AAClC,6CAA0B;AAE1B,mBAAmB;AACnB,qDAAkC;AAClC,uDAAoC;AACpC,qDAAkC;AAClC,kDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,YAAY;AACZ,6CAA0B;AAC1B,gDAA6B;AAC7B,yDAAsC;AACtC,wDAAqC;AACrC,uDAAoC;AAEpC,cAAc;AACd,mDAAgC;AAChC,iDAA8B;AAC9B,sDAAmC;AAEnC,eAAe;AACf,0DAAuC;AACvC,iEAA8C;AAC9C,mEAAgD;AAChD,sDAAmC;AAEnC,QAAQ;AACR,yDAAsC;AACtC,sDAAmC;AAEnC,oBAAoB;AACpB,uDAAoC;AACpC,0DAAuC;AACvC,0DAAuC;AACvC,wDAAqC;AACrC,qDAAkC;AAClC,6CAA0B;AAE1B,mBAAmB;AACnB,qDAAkC;AAClC,uDAAoC;AACpC,qDAAkC;AAClC,kDAA+B"}

package/dist/sharedStretches.d.ts

@@ -0,0 +1,17 @@
+import type { PairwiseAlignment } from './mappings.ts';
+/**
+ * Each residue of row `a` that row `b` shares, as 0-based index in `a` to
+ * 0-based index in `b`. A lone substitution between two kept stretches carries
+ * too: it is one codon two databases read differently, as MUC1's repeats are.
+ */
+export declare function sharedResidueMap(a: string, b: string): Map<number, number>;
+/** Each residue of isoform `from` that isoform `to` shares, through a global
+ * alignment of the two. */
+export declare function sharedIsoformResidues(from: string, to: string): Map<number, number>;
+/**
+ * The alignment of a transcript to another isoform of its protein, with every
+ * residue outside a shared stretch unmapped. For two isoforms, not for a
+ * structure: a mismatch against a structure's chain is usually a point
+ * mutation in the construct, at the right place in the fold.
+ */
+export declare function keepSharedStretches(pa: PairwiseAlignment): PairwiseAlignment;

package/dist/sharedStretches.js

@@ -0,0 +1,99 @@
+"use strict";
+// Which residues two isoforms of one protein share. An alignment column pairs
+// two residues whether or not one codon encodes both: a mutually exclusive exon
+// sits opposite its partner (PKM's exons 9 and 10, FGFR2's IIIb and IIIc), and
+// its residues align, mismatches and chance identities included. A residue
+// carries across only inside a stretch the two spell letter for letter: a long
+// one, or a short one bounded on both sides by a gap or a sequence end, the
+// shape a short shared exon takes (VEGFA's six-residue exon 8a).
+//
+// Measured 2026-09-25 against codon identity on the genome, over every isoform
+// of 13 genes (TP53, PKM, CDKN2A, FGFR2, TPM1, BRAF, EGFR, SCN8A, MAPT, BIN1,
+// VEGFA, TPM3, CD44; 89,927 truly shared residues), on global alignments: 335
+// placed wrongly and 28 missed, against 1,885 and 28 for every identical
+// residue and 328 and 64 for long stretches alone. The misses are single
+// residues at exon junctions, where the gap fits either side.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sharedResidueMap = sharedResidueMap;
+exports.sharedIsoformResidues = sharedIsoformResidues;
+exports.keepSharedStretches = keepSharedStretches;
+const mappings_ts_1 = require("./mappings.js");
+const pairwiseAlignment_ts_1 = require("./pairwiseAlignment.js");
+const LONG_STRETCH = 10;
+const SHORT_EXON = 3;
+/**
+ * Each residue of row `a` that row `b` shares, as 0-based index in `a` to
+ * 0-based index in `b`. A lone substitution between two kept stretches carries
+ * too: it is one codon two databases read differently, as MUC1's repeats are.
+ */
+function sharedResidueMap(a, b) {
+    const cols = [];
+    for (let c = 0, x = 0, y = 0; c < a.length; c++) {
+        const inA = a[c] !== '-';
+        const inB = b[c] !== '-';
+        cols.push({
+            x,
+            y,
+            kind: !inA || !inB
+                ? 'gap'
+                : a[c].toUpperCase() === b[c].toUpperCase()
+                    ? 'same'
+                    : 'mismatch',
+        });
+        if (inA) {
+            x++;
+        }
+        if (inB) {
+            y++;
+        }
+    }
+    const bounded = (c) => cols[c]?.kind !== 'mismatch';
+    const kept = cols.map(() => false);
+    for (let start = 0; start < cols.length;) {
+        let end = start;
+        while (cols[end]?.kind === 'same') {
+            end++;
+        }
+        const length = end - start;
+        if (length >= LONG_STRETCH ||
+            (length >= SHORT_EXON && bounded(start - 1) && bounded(end))) {
+            kept.fill(true, start, end);
+        }
+        start = Math.max(end, start + 1);
+    }
+    const shared = new Map();
+    cols.forEach((col, c) => {
+        if (kept[c] || (col.kind === 'mismatch' && kept[c - 1] && kept[c + 1])) {
+            shared.set(col.x, col.y);
+        }
+    });
+    return shared;
+}
+/** Each residue of isoform `from` that isoform `to` shares, through a global
+ * alignment of the two. */
+function sharedIsoformResidues(from, to) {
+    const { alignedSeq1, alignedSeq2 } = (0, pairwiseAlignment_ts_1.needlemanWunsch)(from, to);
+    return sharedResidueMap(alignedSeq1, alignedSeq2);
+}
+/**
+ * The alignment of a transcript to another isoform of its protein, with every
+ * residue outside a shared stretch unmapped. For two isoforms, not for a
+ * structure: a mismatch against a structure's chain is usually a point
+ * mutation in the construct, at the right place in the fold.
+ */
+function keepSharedStretches(pa) {
+    const structure = (0, mappings_ts_1.structureAlignedSeq)(pa);
+    const transcript = (0, mappings_ts_1.transcriptAlignedSeq)(pa);
+    const shared = sharedResidueMap(structure, transcript);
+    const unshared = new Set();
+    for (let i = 0, j = 0; i < structure.length; i++) {
+        if (structure[i] !== '-') {
+            if (transcript[i] !== '-' && !shared.has(j)) {
+                unshared.add(j);
+            }
+            j++;
+        }
+    }
+    return (0, mappings_ts_1.unmapStructurePositions)(pa, unshared);
+}
+//# sourceMappingURL=sharedStretches.js.map

package/dist/sharedStretches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedStretches.js","sourceRoot":"","sources":["../src/sharedStretches.ts"],"names":[],"mappings":"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"}

package/dist/structureSources.js

@@ -10,8 +10,11 @@ exports.beaconsSummaryUrl = beaconsSummaryUrl;
 exports.parseExperimentalStructures = parseExperimentalStructures;
 exports.fetchExperimentalStructures = fetchExperimentalStructures;
 const fetchUtils_ts_1 = require("./fetchUtils.js");
+// Unfiltered: the `?provider=pdbe` form answered BRAF, HBB and BRCA2 with a 404
+// about one time in three (2026-10-09), and the parser keeps PDBe's entries
+// anyway.
 function beaconsSummaryUrl(uniprotId) {
-    return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json?provider=pdbe`;
+    return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json`;
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -70,7 +73,15 @@ function parseExperimentalStructures(json) {
 /** Best-effort: an unreachable API reads as "no entries", which costs a
  * structure suggestion and nothing else. */
 async function fetchExperimentalStructures(uniprotId, opts) {
-    const res = await (0, fetchUtils_ts_1.rawfetch)(beaconsSummaryUrl(uniprotId), opts).catch(() => undefined);
-    return res?.ok ? parseExperimentalStructures(await res.json()) : [];
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const res = await (0, fetchUtils_ts_1.rawfetch)(beaconsSummaryUrl(uniprotId), opts).catch(() => undefined);
+        if (res?.ok) {
+            return parseExperimentalStructures(await res.json());
+        }
+        if (res?.status === 404 || opts?.signal?.aborted) {
+            return [];
+        }
+    }
+    return [];
 }
 //# sourceMappingURL=structureSources.js.map

package/dist/structureSources.js.map

@@ -1 +1 @@
-{"version":3,"file":"structureSources.js","sourceRoot":"","sources":["../src/structureSources.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"structureSources.js","sourceRoot":"","sources":["../src/structureSources.ts"],"names":[],"mappings":"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"}

package/esm/index.d.ts

@@ -2,6 +2,7 @@ export * from './types.ts';
 export * from './mappings.ts';
 export * from './pairwiseAlignment.ts';
 export * from './alignmentQuality.ts';
+export * from './sharedStretches.ts';
 export * from './coordinates.ts';
 export * from './invertMap.ts';
 export * from './stripStopCodon.ts';

package/esm/index.js

@@ -3,6 +3,7 @@ export * from "./types.js";
 export * from "./mappings.js";
 export * from "./pairwiseAlignment.js";
 export * from "./alignmentQuality.js";
+export * from "./sharedStretches.js";
 // Coordinates
 export * from "./coordinates.js";
 export * from "./invertMap.js";

package/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,wBAAwB,CAAA;AACtC,cAAc,uBAAuB,CAAA;AAErC,cAAc;AACd,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,qBAAqB,CAAA;AAEnC,eAAe;AACf,cAAc,yBAAyB,CAAA;AACvC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,kCAAkC,CAAA;AAChD,cAAc,qBAAqB,CAAA;AAEnC,QAAQ;AACR,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AAEnC,oBAAoB;AACpB,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAE1B,mBAAmB;AACnB,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,wBAAwB,CAAA;AACtC,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AAEpC,cAAc;AACd,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,qBAAqB,CAAA;AAEnC,eAAe;AACf,cAAc,yBAAyB,CAAA;AACvC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,kCAAkC,CAAA;AAChD,cAAc,qBAAqB,CAAA;AAEnC,QAAQ;AACR,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AAEnC,oBAAoB;AACpB,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAE1B,mBAAmB;AACnB,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA"}

package/esm/sharedStretches.d.ts

@@ -0,0 +1,17 @@
+import type { PairwiseAlignment } from './mappings.ts';
+/**
+ * Each residue of row `a` that row `b` shares, as 0-based index in `a` to
+ * 0-based index in `b`. A lone substitution between two kept stretches carries
+ * too: it is one codon two databases read differently, as MUC1's repeats are.
+ */
+export declare function sharedResidueMap(a: string, b: string): Map<number, number>;
+/** Each residue of isoform `from` that isoform `to` shares, through a global
+ * alignment of the two. */
+export declare function sharedIsoformResidues(from: string, to: string): Map<number, number>;
+/**
+ * The alignment of a transcript to another isoform of its protein, with every
+ * residue outside a shared stretch unmapped. For two isoforms, not for a
+ * structure: a mismatch against a structure's chain is usually a point
+ * mutation in the construct, at the right place in the fold.
+ */
+export declare function keepSharedStretches(pa: PairwiseAlignment): PairwiseAlignment;

package/esm/sharedStretches.js

@@ -0,0 +1,94 @@
+// Which residues two isoforms of one protein share. An alignment column pairs
+// two residues whether or not one codon encodes both: a mutually exclusive exon
+// sits opposite its partner (PKM's exons 9 and 10, FGFR2's IIIb and IIIc), and
+// its residues align, mismatches and chance identities included. A residue
+// carries across only inside a stretch the two spell letter for letter: a long
+// one, or a short one bounded on both sides by a gap or a sequence end, the
+// shape a short shared exon takes (VEGFA's six-residue exon 8a).
+//
+// Measured 2026-09-25 against codon identity on the genome, over every isoform
+// of 13 genes (TP53, PKM, CDKN2A, FGFR2, TPM1, BRAF, EGFR, SCN8A, MAPT, BIN1,
+// VEGFA, TPM3, CD44; 89,927 truly shared residues), on global alignments: 335
+// placed wrongly and 28 missed, against 1,885 and 28 for every identical
+// residue and 328 and 64 for long stretches alone. The misses are single
+// residues at exon junctions, where the gap fits either side.
+import { structureAlignedSeq, transcriptAlignedSeq, unmapStructurePositions, } from "./mappings.js";
+import { needlemanWunsch } from "./pairwiseAlignment.js";
+const LONG_STRETCH = 10;
+const SHORT_EXON = 3;
+/**
+ * Each residue of row `a` that row `b` shares, as 0-based index in `a` to
+ * 0-based index in `b`. A lone substitution between two kept stretches carries
+ * too: it is one codon two databases read differently, as MUC1's repeats are.
+ */
+export function sharedResidueMap(a, b) {
+    const cols = [];
+    for (let c = 0, x = 0, y = 0; c < a.length; c++) {
+        const inA = a[c] !== '-';
+        const inB = b[c] !== '-';
+        cols.push({
+            x,
+            y,
+            kind: !inA || !inB
+                ? 'gap'
+                : a[c].toUpperCase() === b[c].toUpperCase()
+                    ? 'same'
+                    : 'mismatch',
+        });
+        if (inA) {
+            x++;
+        }
+        if (inB) {
+            y++;
+        }
+    }
+    const bounded = (c) => cols[c]?.kind !== 'mismatch';
+    const kept = cols.map(() => false);
+    for (let start = 0; start < cols.length;) {
+        let end = start;
+        while (cols[end]?.kind === 'same') {
+            end++;
+        }
+        const length = end - start;
+        if (length >= LONG_STRETCH ||
+            (length >= SHORT_EXON && bounded(start - 1) && bounded(end))) {
+            kept.fill(true, start, end);
+        }
+        start = Math.max(end, start + 1);
+    }
+    const shared = new Map();
+    cols.forEach((col, c) => {
+        if (kept[c] || (col.kind === 'mismatch' && kept[c - 1] && kept[c + 1])) {
+            shared.set(col.x, col.y);
+        }
+    });
+    return shared;
+}
+/** Each residue of isoform `from` that isoform `to` shares, through a global
+ * alignment of the two. */
+export function sharedIsoformResidues(from, to) {
+    const { alignedSeq1, alignedSeq2 } = needlemanWunsch(from, to);
+    return sharedResidueMap(alignedSeq1, alignedSeq2);
+}
+/**
+ * The alignment of a transcript to another isoform of its protein, with every
+ * residue outside a shared stretch unmapped. For two isoforms, not for a
+ * structure: a mismatch against a structure's chain is usually a point
+ * mutation in the construct, at the right place in the fold.
+ */
+export function keepSharedStretches(pa) {
+    const structure = structureAlignedSeq(pa);
+    const transcript = transcriptAlignedSeq(pa);
+    const shared = sharedResidueMap(structure, transcript);
+    const unshared = new Set();
+    for (let i = 0, j = 0; i < structure.length; i++) {
+        if (structure[i] !== '-') {
+            if (transcript[i] !== '-' && !shared.has(j)) {
+                unshared.add(j);
+            }
+            j++;
+        }
+    }
+    return unmapStructurePositions(pa, unshared);
+}
+//# sourceMappingURL=sharedStretches.js.map

package/esm/sharedStretches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedStretches.js","sourceRoot":"","sources":["../src/sharedStretches.ts"],"names":[],"mappings":"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"}

package/esm/structureSources.js

@@ -5,8 +5,11 @@
 // the entry id from here and ask `fetchUniProtStructureMappings` for its
 // residue mapping.
 import { rawfetch } from "./fetchUtils.js";
+// Unfiltered: the `?provider=pdbe` form answered BRAF, HBB and BRCA2 with a 404
+// about one time in three (2026-10-09), and the parser keeps PDBe's entries
+// anyway.
 export function beaconsSummaryUrl(uniprotId) {
-    return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json?provider=pdbe`;
+    return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json`;
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -65,7 +68,15 @@ export function parseExperimentalStructures(json) {
 /** Best-effort: an unreachable API reads as "no entries", which costs a
  * structure suggestion and nothing else. */
 export async function fetchExperimentalStructures(uniprotId, opts) {
-    const res = await rawfetch(beaconsSummaryUrl(uniprotId), opts).catch(() => undefined);
-    return res?.ok ? parseExperimentalStructures(await res.json()) : [];
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const res = await rawfetch(beaconsSummaryUrl(uniprotId), opts).catch(() => undefined);
+        if (res?.ok) {
+            return parseExperimentalStructures(await res.json());
+        }
+        if (res?.status === 404 || opts?.signal?.aborted) {
+            return [];
+        }
+    }
+    return [];
 }
 //# sourceMappingURL=structureSources.js.map

package/esm/structureSources.js.map

@@ -1 +1 @@
-{"version":3,"file":"structureSources.js","sourceRoot":"","sources":["../src/structureSources.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"structureSources.js","sourceRoot":"","sources":["../src/structureSources.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "p2s_mapper",
   "description": "Map a transcript's translation onto a protein structure: alignment, coordinates, chain choice, SIFTS, and the AlphaFold and PDBe lookups that find the structure",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "packageManager": "pnpm@11.15.1",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './types.ts'
 export * from './mappings.ts'
 export * from './pairwiseAlignment.ts'
 export * from './alignmentQuality.ts'
+export * from './sharedStretches.ts'
 
 // Coordinates
 export * from './coordinates.ts'

package/src/sharedStretches.ts

@@ -0,0 +1,109 @@
+// Which residues two isoforms of one protein share. An alignment column pairs
+// two residues whether or not one codon encodes both: a mutually exclusive exon
+// sits opposite its partner (PKM's exons 9 and 10, FGFR2's IIIb and IIIc), and
+// its residues align, mismatches and chance identities included. A residue
+// carries across only inside a stretch the two spell letter for letter: a long
+// one, or a short one bounded on both sides by a gap or a sequence end, the
+// shape a short shared exon takes (VEGFA's six-residue exon 8a).
+//
+// Measured 2026-09-25 against codon identity on the genome, over every isoform
+// of 13 genes (TP53, PKM, CDKN2A, FGFR2, TPM1, BRAF, EGFR, SCN8A, MAPT, BIN1,
+// VEGFA, TPM3, CD44; 89,927 truly shared residues), on global alignments: 335
+// placed wrongly and 28 missed, against 1,885 and 28 for every identical
+// residue and 328 and 64 for long stretches alone. The misses are single
+// residues at exon junctions, where the gap fits either side.
+
+import {
+  structureAlignedSeq,
+  transcriptAlignedSeq,
+  unmapStructurePositions,
+} from './mappings.ts'
+import { needlemanWunsch } from './pairwiseAlignment.ts'
+
+import type { PairwiseAlignment } from './mappings.ts'
+
+const LONG_STRETCH = 10
+const SHORT_EXON = 3
+
+type ColumnKind = 'same' | 'mismatch' | 'gap'
+
+/**
+ * Each residue of row `a` that row `b` shares, as 0-based index in `a` to
+ * 0-based index in `b`. A lone substitution between two kept stretches carries
+ * too: it is one codon two databases read differently, as MUC1's repeats are.
+ */
+export function sharedResidueMap(a: string, b: string) {
+  const cols: { x: number; y: number; kind: ColumnKind }[] = []
+  for (let c = 0, x = 0, y = 0; c < a.length; c++) {
+    const inA = a[c] !== '-'
+    const inB = b[c] !== '-'
+    cols.push({
+      x,
+      y,
+      kind:
+        !inA || !inB
+          ? 'gap'
+          : a[c]!.toUpperCase() === b[c]!.toUpperCase()
+            ? 'same'
+            : 'mismatch',
+    })
+    if (inA) {
+      x++
+    }
+    if (inB) {
+      y++
+    }
+  }
+  const bounded = (c: number) => cols[c]?.kind !== 'mismatch'
+  const kept = cols.map(() => false)
+  for (let start = 0; start < cols.length;) {
+    let end = start
+    while (cols[end]?.kind === 'same') {
+      end++
+    }
+    const length = end - start
+    if (
+      length >= LONG_STRETCH ||
+      (length >= SHORT_EXON && bounded(start - 1) && bounded(end))
+    ) {
+      kept.fill(true, start, end)
+    }
+    start = Math.max(end, start + 1)
+  }
+  const shared = new Map<number, number>()
+  cols.forEach((col, c) => {
+    if (kept[c] || (col.kind === 'mismatch' && kept[c - 1] && kept[c + 1])) {
+      shared.set(col.x, col.y)
+    }
+  })
+  return shared
+}
+
+/** Each residue of isoform `from` that isoform `to` shares, through a global
+ * alignment of the two. */
+export function sharedIsoformResidues(from: string, to: string) {
+  const { alignedSeq1, alignedSeq2 } = needlemanWunsch(from, to)
+  return sharedResidueMap(alignedSeq1, alignedSeq2)
+}
+
+/**
+ * The alignment of a transcript to another isoform of its protein, with every
+ * residue outside a shared stretch unmapped. For two isoforms, not for a
+ * structure: a mismatch against a structure's chain is usually a point
+ * mutation in the construct, at the right place in the fold.
+ */
+export function keepSharedStretches(pa: PairwiseAlignment) {
+  const structure = structureAlignedSeq(pa)
+  const transcript = transcriptAlignedSeq(pa)
+  const shared = sharedResidueMap(structure, transcript)
+  const unshared = new Set<number>()
+  for (let i = 0, j = 0; i < structure.length; i++) {
+    if (structure[i] !== '-') {
+      if (transcript[i] !== '-' && !shared.has(j)) {
+        unshared.add(j)
+      }
+      j++
+    }
+  }
+  return unmapStructurePositions(pa, unshared)
+}

package/src/structureSources.ts

@@ -21,8 +21,11 @@ export interface ExperimentalStructure {
   coverage: number
 }
 
+// Unfiltered: the `?provider=pdbe` form answered BRAF, HBB and BRCA2 with a 404
+// about one time in three (2026-10-09), and the parser keeps PDBe's entries
+// anyway.
 export function beaconsSummaryUrl(uniprotId: string) {
-  return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json?provider=pdbe`
+  return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json`
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -94,8 +97,16 @@ export async function fetchExperimentalStructures(
   uniprotId: string,
   opts?: FetchOptions,
 ): Promise<ExperimentalStructure[]> {
-  const res = await rawfetch(beaconsSummaryUrl(uniprotId), opts).catch(
-    () => undefined,
-  )
-  return res?.ok ? parseExperimentalStructures(await res.json()) : []
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const res = await rawfetch(beaconsSummaryUrl(uniprotId), opts).catch(
+      () => undefined,
+    )
+    if (res?.ok) {
+      return parseExperimentalStructures(await res.json())
+    }
+    if (res?.status === 404 || opts?.signal?.aborted) {
+      return []
+    }
+  }
+  return []
 }