p2s_mapper 1.0.0

package/esm/structureUrls.js

@@ -0,0 +1,134 @@
+// Pure structure-URL builders and target parsers. Kept dependency-free so both
+// the launch flow and the ProteinView model (e.g. resolving a `uniprotId`/`pdbId`
+// shorthand at hydration) can import them without pulling in heavy launch code.
+const ALPHAFOLD_VERSION = 'v6';
+// UniProt endpoints. rest.* is the machine API (the GFF the feature tracks and
+// the alignment's annotation rows both read, the FASTA the temporary protein
+// assembly is built from); www.*/entry is the human-facing entry page the UI
+// links to. Centralized so a path change is one edit rather than a grep.
+export function uniprotGffUrl(uniprotId) {
+    return `https://rest.uniprot.org/uniprotkb/${uniprotId}.gff`;
+}
+export function uniprotFastaUrl(uniprotId) {
+    return `https://rest.uniprot.org/uniprotkb/${uniprotId}.fasta`;
+}
+export function uniprotEntryUrl(uniprotId) {
+    return `https://www.uniprot.org/uniprotkb/${uniprotId}/entry`;
+}
+/**
+ * The guessed filename of an accession's canonical AlphaFold model. A guess:
+ * the F1 fragment does not exist past the length cap and the version moves, so
+ * this is the last resort when the prediction API cannot be reached. Ask
+ * `fetchAlphaFoldModels` for the real files.
+ */
+export function getAlphaFoldStructureUrl(uniprotId, version = ALPHAFOLD_VERSION) {
+    return `https://alphafold.ebi.ac.uk/files/AF-${uniprotId}-F1-model_${version}.cif`;
+}
+export function getPdbStructureUrl(pdbId) {
+    return `https://files.rcsb.org/download/${pdbId}.cif`;
+}
+/**
+ * Resolve the `{ pdbId }` shorthand to a concrete structure URL, so a
+ * hand-authored snapshot or a short launch URL doesn't have to know RCSB's
+ * filename format. An explicit `url` (or inline `data`) always wins.
+ * Idempotent: re-resolving an already-resolved spec returns the same url.
+ *
+ * `uniprotId` deliberately resolves to no url here, and still outranks a
+ * `pdbId`. An accession's files are whatever AlphaFold DB currently holds — an
+ * isoform model, several fragments, a new model version — so the structure
+ * keeps the accession and the structure loader asks the prediction API which
+ * file to open.
+ *
+ * Shared by the Structure model's snapshot preprocessor and the
+ * LaunchView-ProteinView extension point, which would otherwise each carry
+ * their own copy of the same precedence rule.
+ */
+export function resolveStructureUrl({ url, data, uniprotId, pdbId, }) {
+    if (url !== undefined || data !== undefined) {
+        return url;
+    }
+    return uniprotId !== undefined || pdbId === undefined
+        ? undefined
+        : getPdbStructureUrl(pdbId);
+}
+// Hosts that serve the PDB archive, so a 4-character filename there really is
+// that PDB entry. Restricted deliberately: a user-uploaded model happening to be
+// named 1abc.cif must not pick up 1ABC's UniProt annotations.
+const PDB_ARCHIVE_HOSTS = ['files.rcsb.org', 'www.ebi.ac.uk', 'ftp.ebi.ac.uk'];
+/**
+ * The PDB id of a structure URL from the PDB archive, lowercased, or undefined
+ * for any other URL. Accepts the filename forms those hosts serve, e.g.
+ * `1TUP.cif`, `pdb1tup.ent.gz`, `1tup_updated.cif`.
+ */
+export function getPdbIdFromUrl(url) {
+    const { host, file } = (() => {
+        try {
+            const parsed = new URL(url);
+            return { host: parsed.hostname, file: parsed.pathname.split('/').pop() };
+        }
+        catch {
+            return { host: undefined, file: undefined };
+        }
+    })();
+    if (host === undefined || !PDB_ARCHIVE_HOSTS.includes(host)) {
+        return undefined;
+    }
+    const match = /^(?:pdb)?([1-9][a-z0-9]{3})(?:_updated)?\.(?:cif|bcif|pdb|ent)(?:\.gz)?$/i.exec(file ?? '');
+    return match?.[1]?.toLowerCase();
+}
+// Foldseek targets may contain a description after the ID separated by a
+// space, e.g. "AF-P16442-F1-model_v6 Histo-blood group ABO transferase".
+function extractTargetId(target) {
+    return target.split(' ')[0];
+}
+/** The accession of an AlphaFold model id or url, with its isoform suffix:
+ * `AF-P16442-F1-model_v6` gives P16442, `AF-P04637-2-F1-model_v6` P04637-2. */
+export function getUniprotIdFromAlphaFoldTarget(target) {
+    const match = /AF-([A-Z0-9]+(?:-\d+)?)-F\d+/.exec(extractTargetId(target));
+    return match?.[1];
+}
+// Foldseek names a pdb100 hit by the assembly file and chain it searched,
+// `8f2h-assembly1.cif.gz_A`; the entry id is the first four characters.
+export function getStructureUrlFromTarget(target, db) {
+    const targetId = extractTargetId(target);
+    if (targetId.startsWith('AF-')) {
+        return `https://alphafold.ebi.ac.uk/files/${targetId}.cif`;
+    }
+    const pdbId = db === 'pdb100'
+        ? /^([1-9][a-z0-9]{3})(?:[-_.]|$)/i.exec(targetId)?.[1]
+        : undefined;
+    return pdbId ? getPdbStructureUrl(pdbId) : undefined;
+}
+export function getConfidenceUrlFromTarget(target) {
+    const targetId = extractTargetId(target);
+    if (targetId.startsWith('AF-')) {
+        const confidenceId = targetId.replace('-model_', '-confidence_');
+        return `https://alphafold.ebi.ac.uk/files/${confidenceId}.json`;
+    }
+    return undefined;
+}
+/**
+ * What a structure is called in the UI: its PDB id, its AlphaFold accession,
+ * else the file's name. Shared by the view title, the alignment panel heading
+ * and the hover readout, so one structure reads the same everywhere.
+ */
+export function structureDisplayLabel({ url, data, uniprotId, }) {
+    if (url === undefined) {
+        return data !== undefined
+            ? 'Uploaded structure'
+            : uniprotId
+                ? `AlphaFold ${uniprotId}`
+                : '';
+    }
+    const pdbId = getPdbIdFromUrl(url);
+    if (pdbId) {
+        return pdbId.toUpperCase();
+    }
+    const urlAccession = getUniprotIdFromAlphaFoldTarget(url);
+    if (urlAccession) {
+        return `AlphaFold ${urlAccession}`;
+    }
+    const name = url.split('/').pop()?.split('?')[0];
+    return name === undefined || name === '' ? url : name;
+}
+//# sourceMappingURL=structureUrls.js.map

package/esm/structureUrls.js.map

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

package/esm/types.d.ts

@@ -0,0 +1,14 @@
+export type AlignmentAlgorithm = 'needleman_wunsch' | 'smith_waterman';
+export declare const ALIGNMENT_ALGORITHMS: {
+    readonly NEEDLEMAN_WUNSCH: "needleman_wunsch";
+    readonly SMITH_WATERMAN: "smith_waterman";
+};
+export declare const DEFAULT_ALIGNMENT_ALGORITHM: AlignmentAlgorithm;
+export declare const ALIGNMENT_ALGORITHM_VALUES: AlignmentAlgorithm[];
+/**
+ * Parses an untrusted algorithm name (a URL session-spec param) into the union.
+ * The only place a coercion is needed: the model property is an enumeration, so
+ * everything downstream of hydration is already typed.
+ */
+export declare function coerceAlignmentAlgorithm(value: string): AlignmentAlgorithm;
+export declare const ALIGNMENT_ALGORITHM_LABELS: Record<AlignmentAlgorithm, string>;

package/esm/types.js

@@ -0,0 +1,23 @@
+export const ALIGNMENT_ALGORITHMS = {
+    NEEDLEMAN_WUNSCH: 'needleman_wunsch',
+    SMITH_WATERMAN: 'smith_waterman',
+};
+export const DEFAULT_ALIGNMENT_ALGORITHM = 'smith_waterman';
+export const ALIGNMENT_ALGORITHM_VALUES = [
+    'needleman_wunsch',
+    'smith_waterman',
+];
+/**
+ * Parses an untrusted algorithm name (a URL session-spec param) into the union.
+ * The only place a coercion is needed: the model property is an enumeration, so
+ * everything downstream of hydration is already typed.
+ */
+export function coerceAlignmentAlgorithm(value) {
+    return (ALIGNMENT_ALGORITHM_VALUES.find(v => v === value) ??
+        DEFAULT_ALIGNMENT_ALGORITHM);
+}
+export const ALIGNMENT_ALGORITHM_LABELS = {
+    needleman_wunsch: 'Needleman-Wunsch',
+    smith_waterman: 'Smith-Waterman',
+};
+//# sourceMappingURL=types.js.map

package/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,gBAAgB,EAAE,kBAAkB;IACpC,cAAc,EAAE,gBAAgB;CACxB,CAAA;AAEV,MAAM,CAAC,MAAM,2BAA2B,GAAuB,gBAAgB,CAAA;AAE/E,MAAM,CAAC,MAAM,0BAA0B,GAAyB;IAC9D,kBAAkB;IAClB,gBAAgB;CACjB,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,OAAO,CACL,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC;QACjD,2BAA2B,CAC5B,CAAA;AACH,CAAC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAuC;IAC5E,gBAAgB,EAAE,kBAAkB;IACpC,cAAc,EAAE,gBAAgB;CACjC,CAAA"}

package/esm/uniProtSearch.d.ts

@@ -0,0 +1,32 @@
+import type { FetchOptions } from './fetchUtils.ts';
+export interface UniProtEntry {
+    accession: string;
+    id?: string;
+    geneName?: string;
+    organismName?: string;
+    proteinName?: string;
+    isReviewed: boolean;
+}
+/**
+ * `gene_exact` rather than `gene`, which also matches synonyms and returns
+ * paralogs. Without a taxon the query runs across every species, so a mouse
+ * assembly whose tracks carry no taxId lists mouse beside human instead of
+ * silently answering with the human entry.
+ *
+ * The symbol is quoted because a bare one containing `:` — an HLA allele, a
+ * name straight out of an annotation file — reads as another field to
+ * UniProt's parser, which answers 400.
+ */
+export declare function buildGeneNameQuery(geneName: string, organismId?: number): string;
+export interface UniProtSearchResult {
+    entries: UniProtEntry[];
+    attemptedCount: number;
+    failedCount: number;
+}
+export declare function searchUniProtEntries({ recognizedIds, geneId, geneName, organismId, }: {
+    recognizedIds?: string[];
+    geneId?: string;
+    geneName?: string;
+    /** NCBI taxon id; undefined searches every species */
+    organismId?: number;
+}, opts?: FetchOptions): Promise<UniProtSearchResult>;

package/esm/uniProtSearch.js

@@ -0,0 +1,110 @@
+import { jsonfetch } from "./fetchUtils.js";
+import { buildUniProtXrefQuery, isRecognizedDatabaseId, stripTrailingVersion, } from "./dbIds.js";
+const UNIPROT_FIELDS = 'accession,id,gene_names,organism_name,protein_name,reviewed';
+function mapApiResultToEntry(result) {
+    return {
+        accession: result.primaryAccession,
+        id: result.uniProtkbId,
+        geneName: result.genes?.[0]?.geneName?.value,
+        organismName: result.organism?.commonName ?? result.organism?.scientificName,
+        proteinName: result.proteinDescription?.recommendedName?.fullName?.value,
+        isReviewed: result.entryType === 'UniProtKB reviewed (Swiss-Prot)',
+    };
+}
+async function searchUniProt(query, size, opts) {
+    const url = `https://rest.uniprot.org/uniprotkb/search?query=${encodeURIComponent(query)}&fields=${UNIPROT_FIELDS}&size=${size}`;
+    const data = await jsonfetch(url, opts);
+    return data.results.map(mapApiResultToEntry);
+}
+/**
+ * `gene_exact` rather than `gene`, which also matches synonyms and returns
+ * paralogs. Without a taxon the query runs across every species, so a mouse
+ * assembly whose tracks carry no taxId lists mouse beside human instead of
+ * silently answering with the human entry.
+ *
+ * The symbol is quoted because a bare one containing `:` — an HLA allele, a
+ * name straight out of an annotation file — reads as another field to
+ * UniProt's parser, which answers 400.
+ */
+export function buildGeneNameQuery(geneName, organismId) {
+    return [
+        `gene_exact:"${geneName.replaceAll('"', '\\"')}"`,
+        organismId ? `organism_id:${organismId}` : undefined,
+        'reviewed:true',
+    ]
+        .filter(s => s !== undefined)
+        .join(' AND ');
+}
+async function searchByXref(id, opts) {
+    const query = buildUniProtXrefQuery(id);
+    if (!query) {
+        return { entries: [], error: undefined };
+    }
+    try {
+        return { entries: await searchUniProt(query, 10, opts), error: undefined };
+    }
+    catch (e) {
+        console.error(`xref search failed for ${id}:`, e);
+        return { entries: [], error: e };
+    }
+}
+async function searchByGeneName(geneName, organismId, opts) {
+    try {
+        const entries = await searchUniProt(buildGeneNameQuery(geneName, organismId), organismId ? 5 : 10, opts);
+        return { entries, error: undefined };
+    }
+    catch (e) {
+        console.error(`gene name search failed for ${geneName}:`, e);
+        return { entries: [], error: e };
+    }
+}
+function deduplicateEntries(entries) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of entries) {
+        if (!seen.has(entry.accession)) {
+            seen.add(entry.accession);
+            result.push(entry);
+        }
+    }
+    return result;
+}
+export async function searchUniProtEntries({ recognizedIds = [], geneId, geneName, organismId, }, opts) {
+    const idsToSearch = new Set(recognizedIds);
+    const strippedGeneId = geneId ? stripTrailingVersion(geneId) : undefined;
+    if (strippedGeneId && isRecognizedDatabaseId(strippedGeneId)) {
+        idsToSearch.add(strippedGeneId);
+    }
+    // The gene-name query runs alongside the xrefs rather than after them: it is
+    // only consulted when no xref found a reviewed entry, but waiting for that
+    // answer before starting it doubled the latency of the commonest case.
+    const [xrefResults, geneResult] = await Promise.all([
+        Promise.all([...idsToSearch].map(id => searchByXref(id, opts))),
+        geneName ? searchByGeneName(geneName, organismId, opts) : undefined,
+    ]);
+    let entries = deduplicateEntries(xrefResults.flatMap(r => r.entries));
+    // The gene-name answer is consulted only where no xref found a reviewed
+    // entry. Counting it otherwise reported "failed for 1 of 2 identifiers" over
+    // a gene that had in fact resolved, off a query nothing was waiting for.
+    const consultedGeneResult = geneResult && !entries.some(e => e.isReviewed) ? geneResult : undefined;
+    if (consultedGeneResult) {
+        entries = deduplicateEntries([...entries, ...consultedGeneResult.entries]);
+    }
+    const attemptedCount = idsToSearch.size + (consultedGeneResult ? 1 : 0);
+    const failedCount = xrefResults.filter(r => r.error !== undefined).length +
+        (consultedGeneResult?.error === undefined ? 0 : 1);
+    // Every attempt failing is a network problem, not an empty result. Throwing
+    // it stops consumers reporting "No UniProt ID found" over a dead connection.
+    if (entries.length === 0 &&
+        attemptedCount > 0 &&
+        attemptedCount === failedCount) {
+        throw (consultedGeneResult?.error ??
+            xrefResults.find(r => r.error !== undefined)?.error);
+    }
+    return {
+        entries: entries.toSorted((a, b) => Number(b.isReviewed) - Number(a.isReviewed)),
+        attemptedCount,
+        failedCount,
+    };
+}
+//# sourceMappingURL=uniProtSearch.js.map

package/esm/uniProtSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniProtSearch.js","sourceRoot":"","sources":["../src/uniProtSearch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,YAAY,CAAA;AAsCnB,MAAM,cAAc,GAClB,6DAA6D,CAAA;AAE/D,SAAS,mBAAmB,CAC1B,MAAsC;IAEtC,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,gBAAgB;QAClC,EAAE,EAAE,MAAM,CAAC,WAAW;QACtB,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK;QAC5C,YAAY,EACV,MAAM,CAAC,QAAQ,EAAE,UAAU,IAAI,MAAM,CAAC,QAAQ,EAAE,cAAc;QAChE,WAAW,EAAE,MAAM,CAAC,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,KAAK;QACxE,UAAU,EAAE,MAAM,CAAC,SAAS,KAAK,iCAAiC;KACnE,CAAA;AACH,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,KAAa,EACb,IAAY,EACZ,IAAmB;IAEnB,MAAM,GAAG,GAAG,mDAAmD,kBAAkB,CAAC,KAAK,CAAC,WAAW,cAAc,SAAS,IAAI,EAAE,CAAA;IAChI,MAAM,IAAI,GAAG,MAAM,SAAS,CAAmB,GAAG,EAAE,IAAI,CAAC,CAAA;IACzD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,UAAmB;IACtE,OAAO;QACL,eAAe,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG;QACjD,UAAU,CAAC,CAAC,CAAC,eAAe,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS;QACpD,eAAe;KAChB;SACE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;SAC5B,IAAI,CAAC,OAAO,CAAC,CAAA;AAClB,CAAC;AAOD,KAAK,UAAU,YAAY,CACzB,EAAU,EACV,IAAmB;IAEnB,MAAM,KAAK,GAAG,qBAAqB,CAAC,EAAE,CAAC,CAAA;IACvC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAA;IAC1C,CAAC;IACD,IAAI,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAA;IAC5E,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,GAAG,EAAE,CAAC,CAAC,CAAA;QACjD,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAA;IAClC,CAAC;AACH,CAAC;AAED,KAAK,UAAU,gBAAgB,CAC7B,QAAgB,EAChB,UAA8B,EAC9B,IAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,kBAAkB,CAAC,QAAQ,EAAE,UAAU,CAAC,EACxC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EACnB,IAAI,CACL,CAAA;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAA;IACtC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,+BAA+B,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAA;QAC5D,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAA;IAClC,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAuB;IACjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,MAAM,GAAmB,EAAE,CAAA;IACjC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;YACzB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EACE,aAAa,GAAG,EAAE,EAClB,MAAM,EACN,QAAQ,EACR,UAAU,GAOX,EACD,IAAmB;IAEnB,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAA;IAC1C,MAAM,cAAc,GAAG,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACxE,IAAI,cAAc,IAAI,sBAAsB,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7D,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IACjC,CAAC;IAED,6EAA6E;IAC7E,2EAA2E;IAC3E,uEAAuE;IACvE,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/D,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;KACpE,CAAC,CAAA;IAEF,IAAI,OAAO,GAAG,kBAAkB,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;IACrE,wEAAwE;IACxE,6EAA6E;IAC7E,yEAAyE;IACzE,MAAM,mBAAmB,GACvB,UAAU,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAA;IACzE,IAAI,mBAAmB,EAAE,CAAC;QACxB,OAAO,GAAG,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAA;IAC5E,CAAC;IAED,MAAM,cAAc,GAAG,WAAW,CAAC,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACvE,MAAM,WAAW,GACf,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,MAAM;QACrD,CAAC,mBAAmB,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEpD,4EAA4E;IAC5E,6EAA6E;IAC7E,IACE,OAAO,CAAC,MAAM,KAAK,CAAC;QACpB,cAAc,GAAG,CAAC;QAClB,cAAc,KAAK,WAAW,EAC9B,CAAC;QACD,MAAM,CACJ,mBAAmB,EAAE,KAAK;YAC1B,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,EAAE,KAAK,CACpD,CAAA;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,QAAQ,CACvB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CACtD;QACD,cAAc;QACd,WAAW;KACZ,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "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.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GMOD/p2s_mapper.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "exports": {
+    "import": "./esm/index.js",
+    "require": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "esm",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "g2p_mapper": "^2.1.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.9.5",
+    "eslint": "^10.8.0",
+    "eslint-plugin-import-x": "^4.17.1",
+    "git-cliff": "^2.13.1",
+    "prettier": "^3.9.6",
+    "rimraf": "^6.1.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^4.1.10"
+  },
+  "keywords": [
+    "bioinformatics"
+  ],
+  "author": {
+    "name": "Colin Diesh",
+    "email": "colin.diesh@gmail.com"
+  },
+  "scripts": {
+    "test": "vitest",
+    "clean": "rimraf dist esm",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint --report-unused-disable-directives --max-warnings 0",
+    "typecheck": "tsc --noEmit -p tsconfig.lint.json",
+    "prebuild": "pnpm clean",
+    "build:esm": "tsc --outDir esm",
+    "build:es5": "tsc --module commonjs --moduleResolution bundler --outDir dist",
+    "postbuild:es5": "echo '{\"type\": \"commonjs\"}' > dist/package.json",
+    "preversion": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test --run && pnpm build",
+    "version": "git-cliff --tag v$npm_package_version --unreleased --prepend CHANGELOG.md && git add CHANGELOG.md",
+    "postversion": "git push --follow-tags",
+    "build": "pnpm build:esm && pnpm build:es5"
+  }
+}

package/src/alignmentQuality.ts

@@ -0,0 +1,132 @@
+import {
+  alignmentLength,
+  structureAlignedSeq,
+  transcriptAlignedSeq,
+} from './mappings.ts'
+
+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 const LOW_IDENTITY_OVER_SHORTER = 0.3
+export const SHORT_ALIGNMENT_RESIDUES = 20
+export const SHORT_ALIGNMENT_IDENTITY = 0.8
+export const MIN_IDENTICAL_RESIDUES = 5
+
+export function alignmentQuality(pa: PairwiseAlignment): AlignmentQuality {
+  const t = transcriptAlignedSeq(pa)
+  const s = 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 < 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,
+  }
+}
+
+export function isLowSimilarity(q: AlignmentQuality) {
+  const floor =
+    q.identical < SHORT_ALIGNMENT_RESIDUES
+      ? SHORT_ALIGNMENT_IDENTITY
+      : LOW_IDENTITY_OVER_SHORTER
+  return q.identical < MIN_IDENTICAL_RESIDUES || q.identityOverShorter < floor
+}
+
+/** One line for the alignment header: "87% identity over 219 of 393
+ * structure residues". */
+export function describeAlignmentQuality(q: AlignmentQuality) {
+  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.
+ */
+export function describeTranscriptCoverage(q: AlignmentQuality) {
+  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. */
+export function describeCoveredRange(q: AlignmentQuality) {
+  return q.aligned === 0 || q.aligned === q.transcriptLength
+    ? undefined
+    : `covers transcript residues ${q.transcriptStart}–${q.transcriptEnd}`
+}

package/src/alphaFoldModels.ts

@@ -0,0 +1,91 @@
+import { httpError, rawfetch } from './fetchUtils.ts'
+
+import type { FetchOptions } from './fetchUtils.ts'
+import { stripStopCodon } from './stripStopCodon.ts'
+
+export interface AlphaFoldModel {
+  /** UniProt accession, with an isoform suffix on an isoform model */
+  accession: string
+  url: string
+  confidenceUrl?: string
+  sequence: string
+}
+
+interface PredictionEntry {
+  uniprotAccession?: unknown
+  cifUrl?: unknown
+  plddtDocUrl?: unknown
+  sequence?: unknown
+}
+
+function isPredictionEntry(value: unknown): value is PredictionEntry {
+  return typeof value === 'object' && value !== null
+}
+
+export function parseAlphaFoldModels(json: unknown): AlphaFoldModel[] {
+  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.
+ */
+export async function fetchAlphaFoldModels(
+  uniprotId: string,
+  opts?: FetchOptions,
+) {
+  const url = `https://alphafold.ebi.ac.uk/api/prediction/${encodeURIComponent(uniprotId)}`
+  const res = await rawfetch(url, opts)
+  if (res.status === 400 || res.status === 404) {
+    return []
+  }
+  if (!res.ok) {
+    throw await 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.
+ */
+export function pickAlphaFoldModel(
+  models: AlphaFoldModel[],
+  isoformSequences: Record<string, { seq: string }> | undefined,
+) {
+  const translations = new Set(
+    Object.values(isoformSequences ?? {}).map(v => 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]
+  )
+}