p2s_mapper 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colin Diesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# 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.
+
+Extracted from
+[jbrowse-plugin-protein3d](https://github.com/GMOD/jbrowse-plugin-protein3d),
+which is where the measurements behind the scoring rules were made. 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.
+
+## Install
+
+```
+npm install p2s_mapper
+```
+
+## Coordinate conventions
+
+One residue has up to four numbers, and mixing them is the off-by-one class of
+bug this package exists to prevent. **Every stored or computed coordinate is a
+0-based position**: an index into the ungapped structure sequence or the
+ungapped transcript sequence, which is 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 one door.
+**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 is
+shown `auth_seq_id`**, the depositors' numbering, which is what papers and
+UniProt cite (1TUP position 154 reads 248) and what 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 is what 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.
+
+### Urls and formats
+
+`getPdbStructureUrl`, `getAlphaFoldStructureUrl`, `resolveStructureUrl`,
+`getPdbIdFromUrl`, `getUniprotIdFromAlphaFoldTarget`,
+`getStructureUrlFromTarget`, `getConfidenceUrlFromTarget`,
+`structureDisplayLabel`, `uniprotGffUrl`, `uniprotFastaUrl`, `uniprotEntryUrl`,
+`rcsbEntryUrl`.
+
+`structureFormatFromContent`, `structureFormatFromName`,
+`structureFileExtension`, `isBinaryStructureUrl` — which parser a structure
+needs, sniffed from **content** rather than a filename. Getting it wrong fails
+asymmetrically: PDB read as mmCIF throws, while mmCIF read as PDB succeeds and
+yields a model with thousands of misread atoms and zero polymer entities.
+
+`caCoordsToPdb`, `hasValidCaCoords` — a PDB file from Foldseek Cα coordinates.
+
+`rawfetch`, `myfetch`, `jsonfetch`, `httpError`, `networkError`, `abortError`,
+`timeout`, `FetchOptions`.
+
+## License
+
+MIT

package/dist/alignmentQuality.d.ts

@@ -0,0 +1,58 @@
+import type { PairwiseAlignment } from './mappings.ts';
+export interface AlignmentQuality {
+    /** columns carrying a residue on both rows, i.e. mapped positions */
+    aligned: number;
+    identical: number;
+    transcriptLength: number;
+    structureLength: number;
+    /** identical over aligned; 0 when nothing aligned */
+    identity: number;
+    /** identical over the shorter of the two sequences: the statistic that
+     * separates a real match from a chance local alignment, see below */
+    identityOverShorter: number;
+    /** aligned over the structure's length */
+    structureCoverage: number;
+    /** first and last transcript residue the alignment covers, 1-based
+     * inclusive; 0 when nothing aligned. A structure is usually a fragment, and
+     * which part of the protein it holds is the reader's first question. */
+    transcriptStart: number;
+    transcriptEnd: number;
+}
+/**
+ * Below either floor the mapped positions are as likely to be chance as
+ * homology. Local alignment picks the best-scoring stretch of two sequences,
+ * so identity over the aligned columns is inflated whatever the inputs:
+ * measured 2026-09-11 on random sequences, Smith-Waterman with BLOSUM62 gave
+ * 37% identity over 27 columns at 300 × 300 and 30% over 100 columns at
+ * 500 × 150, two thirds of the shorter chain, and p53 against a ribosomal
+ * protein (7K00 RPS11) gives 31 identities at a third identity. Neither local
+ * identity nor coverage alone separates those from a real match. Identical
+ * residues over the shorter sequence does: 0.03, 0.20 and 0.24 for the chance
+ * cases against 0.9 or better for any structure of the transcript's protein
+ * and about 0.6 for an ortholog.
+ *
+ * A short alignment has to be nearly perfect instead: a 10-residue decoy with
+ * 3 identities sits at the ratio floor, while a real bound peptide (1YCR's 15
+ * p53 residues, 4ZZJ's 7) is identical or one off. So under
+ * SHORT_ALIGNMENT_RESIDUES identical residues the ratio floor rises to
+ * SHORT_ALIGNMENT_IDENTITY, and under MIN_IDENTICAL_RESIDUES nothing passes,
+ * since a tetrapeptide is never the gene's product.
+ */
+export declare const LOW_IDENTITY_OVER_SHORTER = 0.3;
+export declare const SHORT_ALIGNMENT_RESIDUES = 20;
+export declare const SHORT_ALIGNMENT_IDENTITY = 0.8;
+export declare const MIN_IDENTICAL_RESIDUES = 5;
+export declare function alignmentQuality(pa: PairwiseAlignment): AlignmentQuality;
+export declare function isLowSimilarity(q: AlignmentQuality): boolean;
+/** One line for the alignment header: "87% identity over 219 of 393
+ * structure residues". */
+export declare function describeAlignmentQuality(q: AlignmentQuality): string;
+/**
+ * The same counted from the transcript's side, for the always-visible header:
+ * how much of the gene's protein this structure speaks for is what decides
+ * whether a codon has a residue at all.
+ */
+export declare function describeTranscriptCoverage(q: AlignmentQuality): string;
+/** Which residues of the transcript a fragment holds, or undefined when it
+ * covers the whole translation. */
+export declare function describeCoveredRange(q: AlignmentQuality): string | undefined;

package/dist/alignmentQuality.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_IDENTICAL_RESIDUES = exports.SHORT_ALIGNMENT_IDENTITY = exports.SHORT_ALIGNMENT_RESIDUES = exports.LOW_IDENTITY_OVER_SHORTER = void 0;
+exports.alignmentQuality = alignmentQuality;
+exports.isLowSimilarity = isLowSimilarity;
+exports.describeAlignmentQuality = describeAlignmentQuality;
+exports.describeTranscriptCoverage = describeTranscriptCoverage;
+exports.describeCoveredRange = describeCoveredRange;
+const mappings_ts_1 = require("./mappings.js");
+/**
+ * Below either floor the mapped positions are as likely to be chance as
+ * homology. Local alignment picks the best-scoring stretch of two sequences,
+ * so identity over the aligned columns is inflated whatever the inputs:
+ * measured 2026-09-11 on random sequences, Smith-Waterman with BLOSUM62 gave
+ * 37% identity over 27 columns at 300 × 300 and 30% over 100 columns at
+ * 500 × 150, two thirds of the shorter chain, and p53 against a ribosomal
+ * protein (7K00 RPS11) gives 31 identities at a third identity. Neither local
+ * identity nor coverage alone separates those from a real match. Identical
+ * residues over the shorter sequence does: 0.03, 0.20 and 0.24 for the chance
+ * cases against 0.9 or better for any structure of the transcript's protein
+ * and about 0.6 for an ortholog.
+ *
+ * A short alignment has to be nearly perfect instead: a 10-residue decoy with
+ * 3 identities sits at the ratio floor, while a real bound peptide (1YCR's 15
+ * p53 residues, 4ZZJ's 7) is identical or one off. So under
+ * SHORT_ALIGNMENT_RESIDUES identical residues the ratio floor rises to
+ * SHORT_ALIGNMENT_IDENTITY, and under MIN_IDENTICAL_RESIDUES nothing passes,
+ * since a tetrapeptide is never the gene's product.
+ */
+exports.LOW_IDENTITY_OVER_SHORTER = 0.3;
+exports.SHORT_ALIGNMENT_RESIDUES = 20;
+exports.SHORT_ALIGNMENT_IDENTITY = 0.8;
+exports.MIN_IDENTICAL_RESIDUES = 5;
+function alignmentQuality(pa) {
+    const t = (0, mappings_ts_1.transcriptAlignedSeq)(pa);
+    const s = (0, mappings_ts_1.structureAlignedSeq)(pa);
+    let aligned = 0;
+    let identical = 0;
+    let transcriptLength = 0;
+    let structureLength = 0;
+    let transcriptStart = 0;
+    let transcriptEnd = 0;
+    for (let i = 0; i < (0, mappings_ts_1.alignmentLength)(pa); i++) {
+        const a = t[i];
+        const b = s[i];
+        const ta = a !== '-';
+        const sb = b !== '-';
+        if (ta) {
+            transcriptLength++;
+        }
+        if (sb) {
+            structureLength++;
+        }
+        if (ta && sb) {
+            aligned++;
+            transcriptStart = transcriptStart || transcriptLength;
+            transcriptEnd = transcriptLength;
+            if (a.toUpperCase() === b.toUpperCase()) {
+                identical++;
+            }
+        }
+    }
+    const shorter = Math.min(transcriptLength, structureLength);
+    return {
+        aligned,
+        identical,
+        transcriptLength,
+        structureLength,
+        identity: aligned ? identical / aligned : 0,
+        identityOverShorter: shorter ? identical / shorter : 0,
+        structureCoverage: structureLength ? aligned / structureLength : 0,
+        transcriptStart,
+        transcriptEnd,
+    };
+}
+function isLowSimilarity(q) {
+    const floor = q.identical < exports.SHORT_ALIGNMENT_RESIDUES
+        ? exports.SHORT_ALIGNMENT_IDENTITY
+        : exports.LOW_IDENTITY_OVER_SHORTER;
+    return q.identical < exports.MIN_IDENTICAL_RESIDUES || q.identityOverShorter < floor;
+}
+/** One line for the alignment header: "87% identity over 219 of 393
+ * structure residues". */
+function describeAlignmentQuality(q) {
+    if (q.aligned === 0) {
+        return 'no residues aligned';
+    }
+    return `${Math.round(q.identity * 100)}% identity over ${q.aligned} of ${q.structureLength} structure residues`;
+}
+/**
+ * The same counted from the transcript's side, for the always-visible header:
+ * how much of the gene's protein this structure speaks for is what decides
+ * whether a codon has a residue at all.
+ */
+function describeTranscriptCoverage(q) {
+    if (q.aligned === 0) {
+        return 'no residues aligned';
+    }
+    return `${Math.round(q.identity * 100)}% identity, ${q.aligned} of ${q.transcriptLength} transcript residues covered`;
+}
+/** Which residues of the transcript a fragment holds, or undefined when it
+ * covers the whole translation. */
+function describeCoveredRange(q) {
+    return q.aligned === 0 || q.aligned === q.transcriptLength
+        ? undefined
+        : `covers transcript residues ${q.transcriptStart}–${q.transcriptEnd}`;
+}
+//# sourceMappingURL=alignmentQuality.js.map

package/dist/alignmentQuality.js.map

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

package/dist/alphaFoldModels.d.ts

@@ -0,0 +1,29 @@
+import type { FetchOptions } from './fetchUtils.ts';
+export interface AlphaFoldModel {
+    /** UniProt accession, with an isoform suffix on an isoform model */
+    accession: string;
+    url: string;
+    confidenceUrl?: string;
+    sequence: string;
+}
+export declare function parseAlphaFoldModels(json: unknown): AlphaFoldModel[];
+/**
+ * Every model AlphaFold DB has for an accession: the canonical one and any
+ * isoform models, each with its file url and sequence. Asked rather than
+ * derived from the accession, because a derived `AF-<acc>-F1-model_v6` does
+ * not exist past the length cap (dystrophin has fourteen isoform models and no
+ * F1) and moves with every model version. An accession AlphaFold has never
+ * folded answers 400 or 404, which is no models rather than an error.
+ */
+export declare function fetchAlphaFoldModels(uniprotId: string, opts?: FetchOptions): Promise<AlphaFoldModel[]>;
+/**
+ * The model to open for a gene's transcripts: one folded from exactly a
+ * transcript's translation, canonical first, so the view maps it as an
+ * identity; else the canonical model; else the longest isoform model.
+ *
+ * Takes any record of sequences, since the structure loader knows one
+ * translation rather than a gene's isoforms.
+ */
+export declare function pickAlphaFoldModel(models: AlphaFoldModel[], isoformSequences: Record<string, {
+    seq: string;
+}> | undefined): AlphaFoldModel | undefined;

package/dist/alphaFoldModels.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAlphaFoldModels = parseAlphaFoldModels;
+exports.fetchAlphaFoldModels = fetchAlphaFoldModels;
+exports.pickAlphaFoldModel = pickAlphaFoldModel;
+const fetchUtils_ts_1 = require("./fetchUtils.js");
+const stripStopCodon_ts_1 = require("./stripStopCodon.js");
+function isPredictionEntry(value) {
+    return typeof value === 'object' && value !== null;
+}
+function parseAlphaFoldModels(json) {
+    return (Array.isArray(json) ? json : []).flatMap(e => isPredictionEntry(e) &&
+        typeof e.uniprotAccession === 'string' &&
+        typeof e.cifUrl === 'string' &&
+        typeof e.sequence === 'string'
+        ? [
+            {
+                accession: e.uniprotAccession,
+                url: e.cifUrl,
+                confidenceUrl: typeof e.plddtDocUrl === 'string' ? e.plddtDocUrl : undefined,
+                sequence: e.sequence,
+            },
+        ]
+        : []);
+}
+/**
+ * Every model AlphaFold DB has for an accession: the canonical one and any
+ * isoform models, each with its file url and sequence. Asked rather than
+ * derived from the accession, because a derived `AF-<acc>-F1-model_v6` does
+ * not exist past the length cap (dystrophin has fourteen isoform models and no
+ * F1) and moves with every model version. An accession AlphaFold has never
+ * folded answers 400 or 404, which is no models rather than an error.
+ */
+async function fetchAlphaFoldModels(uniprotId, opts) {
+    const url = `https://alphafold.ebi.ac.uk/api/prediction/${encodeURIComponent(uniprotId)}`;
+    const res = await (0, fetchUtils_ts_1.rawfetch)(url, opts);
+    if (res.status === 400 || res.status === 404) {
+        return [];
+    }
+    if (!res.ok) {
+        throw await (0, fetchUtils_ts_1.httpError)(res, url);
+    }
+    return parseAlphaFoldModels(await res.json());
+}
+/**
+ * The model to open for a gene's transcripts: one folded from exactly a
+ * transcript's translation, canonical first, so the view maps it as an
+ * identity; else the canonical model; else the longest isoform model.
+ *
+ * Takes any record of sequences, since the structure loader knows one
+ * translation rather than a gene's isoforms.
+ */
+function pickAlphaFoldModel(models, isoformSequences) {
+    const translations = new Set(Object.values(isoformSequences ?? {}).map(v => (0, stripStopCodon_ts_1.stripStopCodon)(v.seq)));
+    const canonicalFirst = [...models].sort((a, b) => Number(a.accession.includes('-')) - Number(b.accession.includes('-')));
+    return (canonicalFirst.find(m => translations.has(m.sequence)) ??
+        canonicalFirst.find(m => !m.accession.includes('-')) ??
+        [...models].sort((a, b) => b.sequence.length - a.sequence.length)[0]);
+}
+//# sourceMappingURL=alphaFoldModels.js.map

package/dist/alphaFoldModels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alphaFoldModels.js","sourceRoot":"","sources":["../src/alphaFoldModels.ts"],"names":[],"mappings":";;AAwBA,oDAiBC;AAUD,oDAaC;AAUD,gDAgBC;AA1FD,mDAAqD;AAGrD,2DAAoD;AAiBpD,SAAS,iBAAiB,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAA;AACpD,CAAC;AAED,SAAgB,oBAAoB,CAAC,IAAa;IAChD,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CACnD,iBAAiB,CAAC,CAAC,CAAC;QACpB,OAAO,CAAC,CAAC,gBAAgB,KAAK,QAAQ;QACtC,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAC5B,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC5B,CAAC,CAAC;YACE;gBACE,SAAS,EAAE,CAAC,CAAC,gBAAgB;gBAC7B,GAAG,EAAE,CAAC,CAAC,MAAM;gBACb,aAAa,EACX,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;gBAC/D,QAAQ,EAAE,CAAC,CAAC,QAAQ;aACrB;SACF;QACH,CAAC,CAAC,EAAE,CACP,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,oBAAoB,CACxC,SAAiB,EACjB,IAAmB;IAEnB,MAAM,GAAG,GAAG,8CAA8C,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAA;IACzF,MAAM,GAAG,GAAG,MAAM,IAAA,wBAAQ,EAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IACrC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC7C,OAAO,EAAE,CAAA;IACX,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,MAAM,IAAA,yBAAS,EAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACjC,CAAC;IACD,OAAO,oBAAoB,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAChC,MAAwB,EACxB,gBAA6D;IAE7D,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,MAAM,CAAC,MAAM,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAA,kCAAc,EAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CACtE,CAAA;IACD,MAAM,cAAc,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CACrC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CACxE,CAAA;IACD,OAAO,CACL,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QACtD,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACpD,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CACrE,CAAA;AACH,CAAC"}

package/dist/caCoordsToPdb.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Convert Foldseek tCa coordinates and tSeq to PDB format
+ * tCa is a comma-separated string of x,y,z triplets
+ * tSeq is the amino acid sequence
+ */
+export declare function caCoordsToPdb(tCa: string, tSeq: string, chainId?: string, title?: string): string;
+/**
+ * Whether a Foldseek hit carries tCa data that can be converted to PDB. A type
+ * predicate rather than a boolean so a guarded caller can pass `hit.tCa`/
+ * `hit.tSeq` straight to caCoordsToPdb without re-asserting they're defined.
+ */
+export declare function hasValidCaCoords<T extends {
+    tCa?: string;
+    tSeq?: string;
+}>(hit: T): hit is T & {
+    tCa: string;
+    tSeq: string;
+};

package/dist/caCoordsToPdb.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.caCoordsToPdb = caCoordsToPdb;
+exports.hasValidCaCoords = hasValidCaCoords;
+// 3-letter amino acid codes
+const AA_3LETTER = {
+    A: 'ALA',
+    C: 'CYS',
+    D: 'ASP',
+    E: 'GLU',
+    F: 'PHE',
+    G: 'GLY',
+    H: 'HIS',
+    I: 'ILE',
+    K: 'LYS',
+    L: 'LEU',
+    M: 'MET',
+    N: 'ASN',
+    P: 'PRO',
+    Q: 'GLN',
+    R: 'ARG',
+    S: 'SER',
+    T: 'THR',
+    V: 'VAL',
+    W: 'TRP',
+    Y: 'TYR',
+    X: 'UNK', // Unknown
+};
+function padLeft(str, len) {
+    return str.padStart(len, ' ');
+}
+function padRight(str, len) {
+    return str.padEnd(len, ' ');
+}
+function formatCoord(val) {
+    return val.toFixed(3).padStart(8, ' ');
+}
+/**
+ * Convert Foldseek tCa coordinates and tSeq to PDB format
+ * tCa is a comma-separated string of x,y,z triplets
+ * tSeq is the amino acid sequence
+ */
+function caCoordsToPdb(tCa, tSeq, chainId = 'A', title) {
+    const coords = tCa.split(',').map(Number);
+    const lines = [];
+    // Add header
+    if (title) {
+        lines.push(`TITLE     ${title}`);
+    }
+    lines.push('REMARK   1 Generated from Foldseek Cα coordinates');
+    let atomNum = 1;
+    let resNum = 1;
+    for (let i = 0; i < coords.length - 2; i += 3) {
+        const x = coords[i];
+        const y = coords[i + 1];
+        const z = coords[i + 2];
+        const aa = tSeq[resNum - 1] ?? 'X';
+        const resName = AA_3LETTER[aa] ?? 'UNK';
+        if (x === undefined || y === undefined || z === undefined) {
+            break;
+        }
+        // PDB ATOM record format
+        // Columns: 1-6 "ATOM  ", 7-11 serial, 13-16 name, 17 altLoc, 18-20 resName,
+        // 22 chainID, 23-26 resSeq, 27 iCode, 31-38 x, 39-46 y, 47-54 z,
+        // 55-60 occupancy, 61-66 tempFactor, 77-78 element
+        const line = 'ATOM  ' +
+            padLeft(String(atomNum), 5) +
+            '  CA  ' +
+            padRight(resName, 3) +
+            ' ' +
+            chainId +
+            padLeft(String(resNum), 4) +
+            '    ' +
+            formatCoord(x) +
+            formatCoord(y) +
+            formatCoord(z) +
+            '  1.00  0.00           C';
+        lines.push(line);
+        atomNum++;
+        resNum++;
+    }
+    lines.push('END');
+    return lines.join('\n');
+}
+/**
+ * Whether a Foldseek hit carries tCa data that can be converted to PDB. A type
+ * predicate rather than a boolean so a guarded caller can pass `hit.tCa`/
+ * `hit.tSeq` straight to caCoordsToPdb without re-asserting they're defined.
+ */
+function hasValidCaCoords(hit) {
+    const { tCa, tSeq } = hit;
+    // Need at least 3 coordinates (x,y,z for one residue) and a sequence
+    return !!tCa && !!tSeq && tCa.split(',').length >= 3;
+}
+//# sourceMappingURL=caCoordsToPdb.js.map

package/dist/caCoordsToPdb.js.map

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

package/dist/chooseMappedEntity.d.ts

@@ -0,0 +1,55 @@
+import type { PairwiseAlignment } from './mappings.ts';
+import type { AlignmentAlgorithm } from './types.ts';
+/**
+ * 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.
+ */
+export declare function interactionMatchesMappedEntity(entityId: string, mappedEntityId: string | undefined): boolean;
+export interface EntitySelection extends ScoredAlignment {
+    /** index into the candidate array of the entity that is the transcript's */
+    index: number;
+}
+export interface ScoredAlignment {
+    /** alignment of the transcript against the entity (stop codons stripped on
+     * both sides, matching the rest of the mapping pipeline) */
+    alignment: PairwiseAlignment;
+    /** identical aligned residues */
+    matches: number;
+    /** identical residues over the shorter sequence, the score that picks the
+     * entity; see `explainedFraction` */
+    explained: number;
+    /** the alignment's BLOSUM62 score, gap penalties included */
+    score: number;
+}
+/** A candidate entity: its sequence, and whether it is DNA/RNA, which is never
+ * the transcript's product however its letters happen to align. */
+export interface EntityCandidate {
+    seq: string;
+    nucleicAcid?: boolean;
+}
+export declare function explainedFraction(matches: number, transcriptLength: number, entityLength: number): number;
+/**
+ * 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.
+ */
+export declare function alignTranscriptToEntity(transcript: string, entitySeq: string, algorithm: AlignmentAlgorithm): ScoredAlignment | undefined;
+/**
+ * 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.
+ */
+export declare function chooseMappedEntity(transcript: string, entities: readonly (string | EntityCandidate)[], algorithm: AlignmentAlgorithm): EntitySelection | undefined;