p2s_mapper 1.0.0

package/dist/chooseMappedEntity.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interactionMatchesMappedEntity = interactionMatchesMappedEntity;
+exports.explainedFraction = explainedFraction;
+exports.alignTranscriptToEntity = alignTranscriptToEntity;
+exports.chooseMappedEntity = chooseMappedEntity;
+const pairwiseAlignment_ts_1 = require("./pairwiseAlignment.js");
+const stripStopCodon_ts_1 = require("./stripStopCodon.js");
+const mappings_ts_1 = require("./mappings.js");
+/**
+ * Whether a structure interaction (hover/click) should drive genome navigation.
+ * Only the transcript's mapped entity may — a hover on any other chain carries
+ * that chain's own label_seq_id and would mis-map through the wrong alignment.
+ * A structure with no resolved mapping (`mappedEntityId` undefined, e.g. a
+ * standalone viewer with no transcript) stays fully interactive.
+ */
+function interactionMatchesMappedEntity(entityId, mappedEntityId) {
+    return mappedEntityId === undefined || entityId === mappedEntityId;
+}
+/**
+ * Identical residues over the shorter of the two sequences: how much of
+ * whichever is smaller, transcript or entity, the other reproduces.
+ *
+ * A raw match count favours whatever chain is longest, and a complex's partner
+ * usually is: on 1H26 the 11-residue p53 peptide matches 11 while CDK2 accrues
+ * 58 scattered identities, and on 4ZZJ SIRT1 beats the 7-residue p53 peptide
+ * 63 to 6. The Smith-Waterman score is no better there (56 vs 58). Dividing
+ * by length asks the question the picker actually has, which chain *is* this
+ * gene's product: the peptide scores 0.69 and 0.50, the partners 0.19 and
+ * 0.17, and across a ribosome's 55 chains no decoy passes 0.29.
+ *
+ * Dividing by the *entity's* length alone penalised a fusion construct: a
+ * 60-residue target fused to a 370-residue carrier scored 0.14, and a random
+ * 10-mer decoy chain with 3 identities beat it a third of the time (measured
+ * 2026-09-11). Dividing by the shorter sequence leaves every chain shorter
+ * than the transcript scored as before and lets a chain that contains the
+ * whole transcript score near 1 however long its tag is. The pseudocount
+ * keeps a two-residue fragment that happens to match (a tRNA end in 7K00)
+ * from scoring 1.0.
+ */
+const EXPLAINED_PSEUDOCOUNT = 5;
+function explainedFraction(matches, transcriptLength, entityLength) {
+    return (matches / (Math.min(transcriptLength, entityLength) + EXPLAINED_PSEUDOCOUNT));
+}
+function countMatches(pa) {
+    const a = (0, mappings_ts_1.transcriptAlignedSeq)(pa);
+    const b = (0, mappings_ts_1.structureAlignedSeq)(pa);
+    let matches = 0;
+    for (let i = 0; i < a.length; i++) {
+        const ca = a[i];
+        const cb = b[i];
+        if (ca !== '-' && cb !== '-' && ca?.toUpperCase() === cb?.toUpperCase()) {
+            matches++;
+        }
+    }
+    return matches;
+}
+/**
+ * Align one transcript to one entity, stop codons stripped on both sides. An
+ * exact match skips the DP entirely; an oversized pair returns undefined rather
+ * than locking up the tab. Used both to score every entity of a structure and
+ * to honour a user's explicit chain choice.
+ */
+function alignTranscriptToEntity(transcript, entitySeq, algorithm) {
+    const t = (0, stripStopCodon_ts_1.stripStopCodon)(transcript);
+    const s = (0, stripStopCodon_ts_1.stripStopCodon)(entitySeq);
+    if (!t || !s || (0, pairwiseAlignment_ts_1.alignmentTooLarge)(t.length, s.length)) {
+        return undefined;
+    }
+    if (s === t) {
+        return {
+            alignment: {
+                consensus: '|'.repeat(t.length),
+                alns: [
+                    { id: 'seq1', seq: t },
+                    { id: 'seq2', seq: s },
+                ],
+            },
+            matches: t.length,
+            explained: explainedFraction(t.length, t.length, s.length),
+            score: (0, pairwiseAlignment_ts_1.selfScore)(t),
+        };
+    }
+    const { alignment, score } = (0, pairwiseAlignment_ts_1.scoredAlignment)(t, s, algorithm);
+    const matches = countMatches(alignment);
+    return {
+        alignment,
+        matches,
+        explained: explainedFraction(matches, t.length, s.length),
+        score,
+    };
+}
+/**
+ * Pick which polymer entity of a structure corresponds to the transcript.
+ *
+ * The plugin historically hardcoded entity `[0]`, which silently mis-maps every
+ * heteromeric / protein-DNA / processed-peptide structure where the protein of
+ * interest is some other chain. Selecting by alignment makes the structure self-
+ * describe which entity is the gene's protein: an exact sequence match wins
+ * outright, otherwise the entity with the highest identity over the shorter
+ * sequence (see `explainedFraction`). Nucleic-acid entities are never
+ * candidates.
+ *
+ * Returns `undefined` only when there is nothing to map (no transcript or no
+ * protein entities) — never a silent fallback to the wrong entity.
+ */
+function chooseMappedEntity(transcript, entities, algorithm) {
+    const t = (0, stripStopCodon_ts_1.stripStopCodon)(transcript);
+    if (!t) {
+        return undefined;
+    }
+    const candidates = entities.map(e => typeof e === 'string'
+        ? { seq: (0, stripStopCodon_ts_1.stripStopCodon)(e) }
+        : { ...e, seq: (0, stripStopCodon_ts_1.stripStopCodon)(e.seq) });
+    const exactIndex = candidates.findIndex(c => !c.nucleicAcid && c.seq.length > 0 && c.seq === t);
+    if (exactIndex !== -1) {
+        const exact = alignTranscriptToEntity(t, candidates[exactIndex].seq, algorithm);
+        return { index: exactIndex, ...exact };
+    }
+    // Each alignment is an O(len(t) * len(s)) main-thread DP, so a complex with
+    // many chains pays it once per chain. Homomers and repeated chains share a
+    // sequence, so align each distinct one once and reuse the result.
+    const bySeq = new Map();
+    let best;
+    for (let index = 0; index < candidates.length; index++) {
+        const { seq, nucleicAcid } = candidates[index];
+        if (nucleicAcid) {
+            continue;
+        }
+        if (!bySeq.has(seq)) {
+            bySeq.set(seq, alignTranscriptToEntity(t, seq, algorithm));
+        }
+        const scored = bySeq.get(seq);
+        if (scored && (!best || scored.explained > best.explained)) {
+            best = { index, ...scored };
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=chooseMappedEntity.js.map

package/dist/chooseMappedEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chooseMappedEntity.js","sourceRoot":"","sources":["../src/chooseMappedEntity.ts"],"names":[],"mappings":";;AAkBA,wEAKC;AAkDD,8CAQC;AAsBD,0DAgCC;AAgBD,gDA8CC;AArMD,iEAI+B;AAC/B,2DAAoD;AACpD,+CAAyE;AAKzE;;;;;;GAMG;AACH,SAAgB,8BAA8B,CAC5C,QAAgB,EAChB,cAAkC;IAElC,OAAO,cAAc,KAAK,SAAS,IAAI,QAAQ,KAAK,cAAc,CAAA;AACpE,CAAC;AA2BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,qBAAqB,GAAG,CAAC,CAAA;AAE/B,SAAgB,iBAAiB,CAC/B,OAAe,EACf,gBAAwB,EACxB,YAAoB;IAEpB,OAAO,CACL,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,YAAY,CAAC,GAAG,qBAAqB,CAAC,CAC7E,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CAAC,EAAqB;IACzC,MAAM,CAAC,GAAG,IAAA,kCAAoB,EAAC,EAAE,CAAC,CAAA;IAClC,MAAM,CAAC,GAAG,IAAA,iCAAmB,EAAC,EAAE,CAAC,CAAA;IACjC,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACf,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACf,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,CAAC;YACxE,OAAO,EAAE,CAAA;QACX,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,uBAAuB,CACrC,UAAkB,EAClB,SAAiB,EACjB,SAA6B;IAE7B,MAAM,CAAC,GAAG,IAAA,kCAAc,EAAC,UAAU,CAAC,CAAA;IACpC,MAAM,CAAC,GAAG,IAAA,kCAAc,EAAC,SAAS,CAAC,CAAA;IACnC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,IAAA,wCAAiB,EAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACZ,OAAO;YACL,SAAS,EAAE;gBACT,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;gBAC/B,IAAI,EAAE;oBACJ,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE;oBACtB,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE;iBACvB;aACF;YACD,OAAO,EAAE,CAAC,CAAC,MAAM;YACjB,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;YAC1D,KAAK,EAAE,IAAA,gCAAS,EAAC,CAAC,CAAC;SACpB,CAAA;IACH,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAA,sCAAe,EAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAA;IAC7D,MAAM,OAAO,GAAG,YAAY,CAAC,SAAS,CAAC,CAAA;IACvC,OAAO;QACL,SAAS;QACT,OAAO;QACP,SAAS,EAAE,iBAAiB,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACzD,KAAK;KACN,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,kBAAkB,CAChC,UAAkB,EAClB,QAA+C,EAC/C,SAA6B;IAE7B,MAAM,CAAC,GAAG,IAAA,kCAAc,EAAC,UAAU,CAAC,CAAA;IACpC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAClC,OAAO,CAAC,KAAK,QAAQ;QACnB,CAAC,CAAC,EAAE,GAAG,EAAE,IAAA,kCAAc,EAAC,CAAC,CAAC,EAAE;QAC5B,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,IAAA,kCAAc,EAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CACzC,CAAA;IACD,MAAM,UAAU,GAAG,UAAU,CAAC,SAAS,CACrC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CACvD,CAAA;IACD,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,uBAAuB,CACnC,CAAC,EACD,UAAU,CAAC,UAAU,CAAE,CAAC,GAAG,EAC3B,SAAS,CACT,CAAA;QACF,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,KAAK,EAAE,CAAA;IACxC,CAAC;IAED,4EAA4E;IAC5E,2EAA2E;IAC3E,kEAAkE;IAClE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuC,CAAA;IAC5D,IAAI,IAAiC,CAAA;IACrC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACvD,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,KAAK,CAAE,CAAA;QAC/C,IAAI,WAAW,EAAE,CAAC;YAChB,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,CAAA;QAC5D,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3D,IAAI,GAAG,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,CAAA;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/coordinates.d.ts

@@ -0,0 +1,66 @@
+import type { PairwiseAlignment } from './mappings.ts';
+/**
+ * Branded coordinate spaces. Every position in this plugin is a bare `number`,
+ * but the *meaning* differs: a structure residue index is not interchangeable
+ * with a transcript residue index or an alignment column, and mixing them is
+ * the root cause of the off-by-one class of bugs. Branding makes the compiler
+ * reject cross-space mixing; construct values with the helpers below at the
+ * boundaries where raw numbers enter (molstar picks, hover events, features).
+ *
+ * Conventions: all are 0-based. StructurePos indexes the ungapped structure
+ * sequence; TranscriptPos the ungapped transcript sequence; AlignmentCol a
+ * column of the pairwise alignment (gaps included).
+ */
+type Branded<B extends string> = number & {
+    readonly __brand: B;
+};
+export type StructurePos = Branded<'StructurePos'>;
+export type TranscriptPos = Branded<'TranscriptPos'>;
+export type AlignmentCol = Branded<'AlignmentCol'>;
+export declare const structurePos: (n: number) => StructurePos;
+export declare const transcriptPos: (n: number) => TranscriptPos;
+export declare const alignmentCol: (n: number) => AlignmentCol;
+export interface CoordinateMaps {
+    structureSeqToTranscriptSeqPosition: Record<number, number>;
+    transcriptSeqToStructureSeqPosition: Record<number, number>;
+    structurePositionToAlignmentMap: Record<number, number>;
+    transcriptPositionToAlignmentMap: Record<number, number>;
+    alignmentToStructurePosition: Record<number, number>;
+    alignmentToTranscriptPosition: Record<number, number>;
+}
+export interface CoordinateMapper {
+    structureToTranscript: (p: StructurePos) => TranscriptPos | undefined;
+    transcriptToStructure: (p: TranscriptPos) => StructurePos | undefined;
+    structureToAlignment: (p: StructurePos) => AlignmentCol | undefined;
+    alignmentToStructure: (c: AlignmentCol) => StructurePos | undefined;
+    transcriptToAlignment: (p: TranscriptPos) => AlignmentCol | undefined;
+    alignmentToTranscript: (c: AlignmentCol) => TranscriptPos | undefined;
+    /**
+     * Raw lookup tables, for consumers that iterate the whole map rather than
+     * convert a single position (e.g. per-residue track rendering, selection of
+     * all aligned residues). Plain numbers — prefer the typed methods above for
+     * point conversions.
+     */
+    readonly maps: CoordinateMaps;
+}
+/**
+ * Builds every coordinate conversion once from a pairwise alignment, replacing
+ * the scatter of per-getter map builds + repeated invertMap calls. The branded
+ * methods are the preferred API; `maps` stays unbranded for whole-map consumers.
+ */
+export declare function makeCoordinateMapper(pairwiseAlignment: PairwiseAlignment): CoordinateMapper;
+/**
+ * The 0-based half-open structure-position range covering an inclusive range
+ * of 1-based transcript residues, the numbering a UniProt feature or a domain
+ * map uses. Residues the structure lacks are skipped, so a range that runs
+ * past a fragment's end clamps to the last modeled residue; undefined when none
+ * of the range aligns to the structure.
+ */
+export declare function transcriptRangeToStructureRange(mapper: CoordinateMapper, range: {
+    start: number;
+    end: number;
+}): {
+    start: number;
+    end: number;
+} | undefined;
+export {};

package/dist/coordinates.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alignmentCol = exports.transcriptPos = exports.structurePos = void 0;
+exports.makeCoordinateMapper = makeCoordinateMapper;
+exports.transcriptRangeToStructureRange = transcriptRangeToStructureRange;
+const mappings_ts_1 = require("./mappings.js");
+const invertMap_ts_1 = require("./invertMap.js");
+const structurePos = (n) => n;
+exports.structurePos = structurePos;
+const transcriptPos = (n) => n;
+exports.transcriptPos = transcriptPos;
+const alignmentCol = (n) => n;
+exports.alignmentCol = alignmentCol;
+/**
+ * Builds every coordinate conversion once from a pairwise alignment, replacing
+ * the scatter of per-getter map builds + repeated invertMap calls. The branded
+ * methods are the preferred API; `maps` stays unbranded for whole-map consumers.
+ */
+function makeCoordinateMapper(pairwiseAlignment) {
+    const { structureSeqToTranscriptSeqPosition, transcriptSeqToStructureSeqPosition, } = (0, mappings_ts_1.structureSeqVsTranscriptSeqMap)(pairwiseAlignment);
+    const s2aln = (0, mappings_ts_1.structurePositionToAlignmentMap)(pairwiseAlignment);
+    const t2aln = (0, mappings_ts_1.transcriptPositionToAlignmentMap)(pairwiseAlignment);
+    const aln2s = (0, invertMap_ts_1.invertMap)(s2aln);
+    const aln2t = (0, invertMap_ts_1.invertMap)(t2aln);
+    // The `as` casts below are the single brand-crossing point: indexing a
+    // Record<number,number> yields a plain number that we re-brand to its output
+    // space. Isolated here so the rest of the codebase stays brand-clean.
+    return {
+        structureToTranscript: p => structureSeqToTranscriptSeqPosition[p],
+        transcriptToStructure: p => transcriptSeqToStructureSeqPosition[p],
+        structureToAlignment: p => s2aln[p],
+        alignmentToStructure: c => aln2s[c],
+        transcriptToAlignment: p => t2aln[p],
+        alignmentToTranscript: c => aln2t[c],
+        maps: {
+            structureSeqToTranscriptSeqPosition,
+            transcriptSeqToStructureSeqPosition,
+            structurePositionToAlignmentMap: s2aln,
+            transcriptPositionToAlignmentMap: t2aln,
+            alignmentToStructurePosition: aln2s,
+            alignmentToTranscriptPosition: aln2t,
+        },
+    };
+}
+/**
+ * The 0-based half-open structure-position range covering an inclusive range
+ * of 1-based transcript residues, the numbering a UniProt feature or a domain
+ * map uses. Residues the structure lacks are skipped, so a range that runs
+ * past a fragment's end clamps to the last modeled residue; undefined when none
+ * of the range aligns to the structure.
+ */
+function transcriptRangeToStructureRange(mapper, range) {
+    let first;
+    let last;
+    for (let residue = range.start; residue <= range.end; residue++) {
+        const pos = mapper.transcriptToStructure((0, exports.transcriptPos)(residue - 1));
+        if (pos !== undefined) {
+            first = first === undefined ? pos : Math.min(first, pos);
+            last = last === undefined ? pos : Math.max(last, pos);
+        }
+    }
+    return first === undefined || last === undefined
+        ? undefined
+        : { start: first, end: last + 1 };
+}
+//# sourceMappingURL=coordinates.js.map

package/dist/coordinates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinates.js","sourceRoot":"","sources":["../src/coordinates.ts"],"names":[],"mappings":";;;AA4DA,oDAiCC;AASD,0EAgBC;AAtHD,+CAIsB;AACtB,iDAA0C;AAqBnC,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAiB,CAAA;AAA/C,QAAA,YAAY,gBAAmC;AACrD,MAAM,aAAa,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAkB,CAAA;AAAjD,QAAA,aAAa,iBAAoC;AACvD,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAiB,CAAA;AAA/C,QAAA,YAAY,gBAAmC;AA2B5D;;;;GAIG;AACH,SAAgB,oBAAoB,CAClC,iBAAoC;IAEpC,MAAM,EACJ,mCAAmC,EACnC,mCAAmC,GACpC,GAAG,IAAA,4CAA8B,EAAC,iBAAiB,CAAC,CAAA;IACrD,MAAM,KAAK,GAAG,IAAA,6CAA+B,EAAC,iBAAiB,CAAC,CAAA;IAChE,MAAM,KAAK,GAAG,IAAA,8CAAgC,EAAC,iBAAiB,CAAC,CAAA;IACjE,MAAM,KAAK,GAAG,IAAA,wBAAS,EAAC,KAAK,CAAC,CAAA;IAC9B,MAAM,KAAK,GAAG,IAAA,wBAAS,EAAC,KAAK,CAAC,CAAA;IAE9B,uEAAuE;IACvE,6EAA6E;IAC7E,sEAAsE;IACtE,OAAO;QACL,qBAAqB,EAAE,CAAC,CAAC,EAAE,CACzB,mCAAmC,CAAC,CAAC,CAA8B;QACrE,qBAAqB,EAAE,CAAC,CAAC,EAAE,CACzB,mCAAmC,CAAC,CAAC,CAA6B;QACpE,oBAAoB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAC/D,oBAAoB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAC/D,qBAAqB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAChE,qBAAqB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA8B;QACjE,IAAI,EAAE;YACJ,mCAAmC;YACnC,mCAAmC;YACnC,+BAA+B,EAAE,KAAK;YACtC,gCAAgC,EAAE,KAAK;YACvC,4BAA4B,EAAE,KAAK;YACnC,6BAA6B,EAAE,KAAK;SACrC;KACF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,+BAA+B,CAC7C,MAAwB,EACxB,KAAqC;IAErC,IAAI,KAAyB,CAAA;IAC7B,IAAI,IAAwB,CAAA;IAC5B,KAAK,IAAI,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;QAChE,MAAM,GAAG,GAAG,MAAM,CAAC,qBAAqB,CAAC,IAAA,qBAAa,EAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;QACpE,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YACxD,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QACvD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS;QAC9C,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,GAAG,CAAC,EAAE,CAAA;AACrC,CAAC"}

package/dist/dbIds.d.ts

@@ -0,0 +1,16 @@
+type DbType = 'ensembl' | 'refseq' | 'ccds' | 'hgnc';
+export declare function matchDbIdPattern(id: string): {
+    db: DbType;
+    pattern: RegExp;
+    label: string;
+} | undefined;
+/** Whether an ID is a database identifier UniProt can map. */
+export declare function isRecognizedDatabaseId(id: string): boolean;
+/** Human-readable label for an ID, e.g. "ENST00000123 (Ensembl transcript)".
+ * Unrecognized IDs are returned unadorned. */
+export declare function getDbIdLabel(id: string): string;
+/** The UniProt xref query fragment for a recognized ID, e.g.
+ * "xref:ensembl-ENST00000123". HGNC strips its redundant "HGNC:" prefix. */
+export declare function buildUniProtXrefQuery(id: string): string | undefined;
+export declare function stripTrailingVersion(s?: string): string | undefined;
+export {};

package/dist/dbIds.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchDbIdPattern = matchDbIdPattern;
+exports.isRecognizedDatabaseId = isRecognizedDatabaseId;
+exports.getDbIdLabel = getDbIdLabel;
+exports.buildUniProtXrefQuery = buildUniProtXrefQuery;
+exports.stripTrailingVersion = stripTrailingVersion;
+const DB_ID_PATTERNS = [
+    { db: 'ensembl', pattern: /^ENS[A-Z]*G\d+/i, label: 'Ensembl gene' },
+    { db: 'ensembl', pattern: /^ENS[A-Z]*T\d+/i, label: 'Ensembl transcript' },
+    { db: 'ensembl', pattern: /^ENS[A-Z]*P\d+/i, label: 'Ensembl protein' },
+    { db: 'refseq', pattern: /^[NX]M_\d+/i, label: 'RefSeq mRNA' },
+    { db: 'refseq', pattern: /^[NX]R_\d+/i, label: 'RefSeq ncRNA' },
+    { db: 'refseq', pattern: /^[NX]P_\d+/i, label: 'RefSeq protein' },
+    { db: 'ccds', pattern: /^CCDS\d+/i, label: 'CCDS' },
+    { db: 'hgnc', pattern: /^HGNC:\d+/i, label: 'HGNC' },
+];
+function matchDbIdPattern(id) {
+    return DB_ID_PATTERNS.find(p => p.pattern.test(id));
+}
+/** Whether an ID is a database identifier UniProt can map. */
+function isRecognizedDatabaseId(id) {
+    return matchDbIdPattern(id) !== undefined;
+}
+/** Human-readable label for an ID, e.g. "ENST00000123 (Ensembl transcript)".
+ * Unrecognized IDs are returned unadorned. */
+function getDbIdLabel(id) {
+    const match = matchDbIdPattern(id);
+    return match ? `${id} (${match.label})` : id;
+}
+/** The UniProt xref query fragment for a recognized ID, e.g.
+ * "xref:ensembl-ENST00000123". HGNC strips its redundant "HGNC:" prefix. */
+function buildUniProtXrefQuery(id) {
+    const match = matchDbIdPattern(id);
+    return match
+        ? `xref:${match.db}-${match.db === 'hgnc' ? id.replace('HGNC:', '') : id}`
+        : undefined;
+}
+function stripTrailingVersion(s) {
+    return s?.replace(/\.[^./]+$/, '');
+}
+//# sourceMappingURL=dbIds.js.map

package/dist/dbIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dbIds.js","sourceRoot":"","sources":["../src/dbIds.ts"],"names":[],"mappings":";;AAkBA,4CAEC;AAGD,wDAEC;AAID,oCAGC;AAID,sDAKC;AAED,oDAEC;AAtCD,MAAM,cAAc,GAAqD;IACvE,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,cAAc,EAAE;IACpE,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,oBAAoB,EAAE;IAC1E,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,EAAE;IACvE,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,EAAE;IAC/D,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,gBAAgB,EAAE;IACjE,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE;IACnD,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE;CACrD,CAAA;AAED,SAAgB,gBAAgB,CAAC,EAAU;IACzC,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;AACrD,CAAC;AAED,8DAA8D;AAC9D,SAAgB,sBAAsB,CAAC,EAAU;IAC/C,OAAO,gBAAgB,CAAC,EAAE,CAAC,KAAK,SAAS,CAAA;AAC3C,CAAC;AAED;8CAC8C;AAC9C,SAAgB,YAAY,CAAC,EAAU;IACrC,MAAM,KAAK,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAA;IAClC,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;AAC9C,CAAC;AAED;4EAC4E;AAC5E,SAAgB,qBAAqB,CAAC,EAAU;IAC9C,MAAM,KAAK,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAA;IAClC,OAAO,KAAK;QACV,CAAC,CAAC,QAAQ,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE;QAC1E,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED,SAAgB,oBAAoB,CAAC,CAAU;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;AACpC,CAAC"}

package/dist/extractPerResidueConfidence.d.ts

@@ -0,0 +1,49 @@
+interface ConfidenceModel {
+    obj?: {
+        data: {
+            atomicConformation: {
+                B_iso_or_equiv: {
+                    value: (row: number) => number;
+                };
+            };
+            atomicHierarchy: {
+                residueAtomSegments: {
+                    offsets: ArrayLike<number>;
+                    count: number;
+                };
+                chainAtomSegments: {
+                    index: ArrayLike<number>;
+                };
+                chains: {
+                    label_entity_id: {
+                        value: (row: number) => string;
+                    };
+                };
+                residues: {
+                    label_seq_id: {
+                        value: (row: number) => number;
+                    };
+                };
+            };
+        };
+    };
+}
+/**
+ * Per-residue B-factor / pLDDT of one polymer entity, keyed by molstar's
+ * `label_seq_id`. Keyed by id rather than by residue order because the atomic
+ * hierarchy only holds *observed* residues: a chain with an unmodeled loop, or
+ * a chain that is not the first in the file, would otherwise plot every value
+ * against the wrong SEQRES position. Convert through `Entity.seqIds`.
+ */
+export interface EntityConfidence {
+    entityId: string;
+    byLabelSeqId: Map<number, number>;
+}
+export declare function extractPerResidueConfidence(model: ConfidenceModel): EntityConfidence[] | undefined;
+/**
+ * AlphaFold-style pLDDT lives in [0, 100] and varies across residues. A
+ * constant column (common when a PDB has no B-factors) or out-of-range values
+ * indicate the track wouldn't be meaningful as confidence.
+ */
+export declare function looksLikePlddt(values: number[] | undefined): values is number[];
+export {};

package/dist/extractPerResidueConfidence.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPerResidueConfidence = extractPerResidueConfidence;
+exports.looksLikePlddt = looksLikePlddt;
+function extractPerResidueConfidence(model) {
+    const data = model.obj?.data;
+    if (!data) {
+        return undefined;
+    }
+    const { B_iso_or_equiv } = data.atomicConformation;
+    const { residueAtomSegments, chainAtomSegments, chains, residues } = data.atomicHierarchy;
+    const byEntity = new Map();
+    for (let residue = 0; residue < residueAtomSegments.count; residue++) {
+        const atom = residueAtomSegments.offsets[residue];
+        const entityId = chains.label_entity_id.value(chainAtomSegments.index[atom]);
+        let values = byEntity.get(entityId);
+        if (!values) {
+            values = new Map();
+            byEntity.set(entityId, values);
+        }
+        const seqId = residues.label_seq_id.value(residue);
+        if (!values.has(seqId)) {
+            values.set(seqId, B_iso_or_equiv.value(atom));
+        }
+    }
+    return [...byEntity].map(([entityId, byLabelSeqId]) => ({
+        entityId,
+        byLabelSeqId,
+    }));
+}
+/**
+ * AlphaFold-style pLDDT lives in [0, 100] and varies across residues. A
+ * constant column (common when a PDB has no B-factors) or out-of-range values
+ * indicate the track wouldn't be meaningful as confidence.
+ */
+function looksLikePlddt(values) {
+    return (!!values &&
+        values.length > 1 &&
+        values.every(v => v >= 0 && v <= 100) &&
+        new Set(values).size > 1);
+}
+//# sourceMappingURL=extractPerResidueConfidence.js.map

package/dist/extractPerResidueConfidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractPerResidueConfidence.js","sourceRoot":"","sources":["../src/extractPerResidueConfidence.ts"],"names":[],"mappings":";;AAyCA,kEA8BC;AAOD,wCASC;AA9CD,SAAgB,2BAA2B,CACzC,KAAsB;IAEtB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,CAAA;IAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC,kBAAkB,CAAA;IAClD,MAAM,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,EAAE,QAAQ,EAAE,GAChE,IAAI,CAAC,eAAe,CAAA;IACtB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA+B,CAAA;IACvD,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC;QACrE,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,OAAO,CAAE,CAAA;QAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,eAAe,CAAC,KAAK,CAC3C,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAE,CAC/B,CAAA;QACD,IAAI,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QACnC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,GAAG,EAAE,CAAA;YAClB,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QAChC,CAAC;QACD,MAAM,KAAK,GAAG,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAClD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,QAAQ;QACR,YAAY;KACb,CAAC,CAAC,CAAA;AACL,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAC5B,MAA4B;IAE5B,OAAO,CACL,CAAC,CAAC,MAAM;QACR,MAAM,CAAC,MAAM,GAAG,CAAC;QACjB,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;QACrC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CACzB,CAAA;AACH,CAAC"}

package/dist/extractStructureSequences.d.ts

@@ -0,0 +1,142 @@
+/** A polymer entity of a loaded structure: its mmCIF entity id, its one-letter
+ * sequence, and the molstar `label_seq_id` of each of those residues.
+ *
+ * The entity id is what lets every downstream step talk about "the gene's
+ * protein" by identity instead of by the fragile entity-[0] position.
+ *
+ * `seqIds` is what lets it talk about a *residue* by identity. Structure
+ * positions in this plugin are 0-based indices into `seq`; molstar addresses
+ * residues by `label_seq_id`. Those are related by `+1` only when the entity's
+ * sequence covers every residue from 1 — true for any mmCIF with an
+ * `entity_poly_seq` category (all of RCSB and AlphaFold) and for PDB files
+ * carrying SEQRES records, because molstar synthesizes the category from them.
+ *
+ * A PDB-format file with no SEQRES has no such category, so molstar falls back
+ * to `StructureSequence.fromHierarchy` and takes `label_seq_id` straight from
+ * the observed residues' author numbering: a chain whose coordinates start at
+ * residue 94 yields seqIds 94.., and an unobserved loop leaves a hole. Deriving
+ * the id arithmetically there is off by the whole offset, in both directions —
+ * every hover reads the wrong residue and every highlight paints the wrong one.
+ * So carry the real ids and convert through them.
+ */
+export interface Entity {
+    entityId: string;
+    seq: string;
+    seqIds: number[];
+    /** author chain ids carrying this entity, e.g. ['A', 'B'] for a homodimer;
+     * what a user recognises from the PDB entry page, where the entity id is
+     * molstar's own bookkeeping */
+    chains: string[];
+    /** DNA, RNA or a hybrid, by molstar's entity subtype. Its one-letter
+     * sequence spells amino acids too (A, C, G, T, U), so it has to be kept
+     * out of the transcript alignment rather than merely scoring low. */
+    nucleicAcid?: boolean;
+    /** `auth_seq_id` per position: the numbering the depositors chose, which
+     * for an RCSB entry is the one papers and UniProt cite (1TUP's position 154
+     * is R248) and what Mol*'s own hover label shows. Display only; every
+     * coordinate the plugin computes with stays a 0-based position, and molstar
+     * is addressed through `seqIds`. Absent when the model has no atomic
+     * hierarchy to read it from. See `residueNumber`. */
+    authSeqIds?: number[];
+}
+interface Column<T> {
+    rowCount: number;
+    value(row: number): T;
+}
+interface StructureModel {
+    obj?: {
+        data: {
+            entities?: {
+                subtype: Column<string>;
+                getEntityIndex(id: string): number;
+            };
+            sourceData?: {
+                data: unknown;
+            };
+            sequence: {
+                sequences: readonly {
+                    entityId: string;
+                    sequence: {
+                        code: {
+                            toArray(): ArrayLike<string>;
+                        };
+                        seqId: {
+                            toArray(): ArrayLike<number>;
+                        };
+                    };
+                }[];
+            };
+            atomicHierarchy?: {
+                chains: {
+                    label_entity_id: Column<string>;
+                    auth_asym_id: Column<string>;
+                };
+                residues?: {
+                    label_seq_id: Column<number>;
+                    auth_seq_id: Column<number>;
+                };
+                residueAtomSegments?: {
+                    offsets: ArrayLike<number>;
+                    count: number;
+                };
+                chainAtomSegments?: {
+                    index: ArrayLike<number>;
+                };
+            };
+        };
+    };
+}
+/**
+ * Author numbering for every SEQRES position, observed or not. A residue with
+ * no atoms has no auth_seq_id of its own, so it takes the offset of the nearest
+ * observed residue before it (after it, at an unobserved N-terminus): a
+ * disordered loop keeps counting the way the paper does. With nothing observed
+ * the label numbering stands.
+ */
+export declare function fillAuthSeqIds(seqIds: number[], observed: Map<number, number> | undefined): number[];
+/** The number a residue is called by: author numbering when the file carries
+ * it, else molstar's label_seq_id, which is the author numbering already for a
+ * SEQRES-less PDB and 1..N for everything else. */
+export declare function residueNumber(entity: Entity | undefined, pos: number): number;
+/**
+ * The 0-based half-open position range covering an inclusive range of author
+ * residue numbers, the form a paper or a spec names a site by ("R248",
+ * "residues 102-292"). Undefined when no residue of the entity carries a number
+ * in the range, so a typo selects nothing rather than something else.
+ */
+export declare function residueRangeToPositions(entity: Entity | undefined, range: {
+    start: number;
+    end: number;
+}): {
+    start: number;
+    end: number;
+} | undefined;
+/**
+ * One letter per position, so `seq[pos]` and `seqIds[pos]` name the same
+ * residue. Molstar's `label` column is not that: it spells a residue with no
+ * one-letter code by its component id (MSE, TPO, ACE) and an alternate site as
+ * "(S|P)", which shifted every later position. `code` writes X for those; the
+ * mmCIF canonical sequence then supplies the parent residue (MSE is M) when it
+ * has one letter per position, which a chromophore spelled "TYG" does not.
+ */
+export declare function oneLetterSequence(codes: ArrayLike<string>, canonical: string | undefined): string;
+export declare function extractEntities(model: StructureModel): Entity[] | undefined;
+/** A user-facing name for an entity: its chains when known, else its id. */
+export declare function entityLabel(entity: Entity): string;
+/** The protein chains' sequences, for the launch dialog's isoform matching,
+ * which has no use for a DNA strand that happens to align. */
+export declare function extractStructureSequences(model: StructureModel): string[] | undefined;
+/**
+ * The molstar `label_seq_id`s for a set of 0-based structure positions. Unknown
+ * positions are dropped rather than guessed, so an out-of-range position paints
+ * nothing instead of painting something wrong.
+ */
+export declare function toLabelSeqIds(entity: Entity | undefined, positions: Iterable<number>): number[];
+/** As toLabelSeqIds, for a half-open [start, end) structure-position range. */
+export declare function rangeToLabelSeqIds(entity: Entity | undefined, range: {
+    start: number;
+    end: number;
+} | undefined): number[];
+/** Reverse of `seqIds`: molstar's label_seq_id -> 0-based structure position. */
+export declare function makeLabelSeqIdIndex(entity: Entity | undefined): Map<number, number>;
+export {};