p2s_mapper 1.4.0 → 2.0.0

package/esm/structureSources.js

@@ -1,82 +1,166 @@
-// The experimental structures 3D-Beacons knows for a UniProt entry: every PDBe
-// entry mapped to the accession, with the UniProt range it covers and its
-// resolution, in one CORS-enabled call. That is what lets a page offer a
-// crystal structure beside a prediction without a PDB search of its own; take
-// the entry id from here and ask `fetchUniProtStructureMappings` for its
+// The experimental structures RCSB aligns to a UniProt entry: every PDB entity
+// carrying the accession, with the UniProt range it covers, then each entry's
+// method, resolution and chains. Two CORS-enabled calls, which is what lets a
+// page offer a crystal structure beside a prediction without a PDB search of
+// its own; take the entry id from here and ask `fetchPdbEntry` for its
 // residue mapping.
-import { rawfetch } from "./fetchUtils.js";
-// Unfiltered: the `?provider=pdbe` form answered BRAF, HBB and BRCA2 with a 404
-// about one time in three (2026-10-09), and the parser keeps PDBe's entries
-// anyway.
-export function beaconsSummaryUrl(uniprotId) {
-    return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json`;
+import { RCSB_DATA_GRAPHQL_URL, graphqlFetch } from "./pdbEntry.js";
+import { isPdbId } from "./structureUrls.js";
+export const RCSB_SEQUENCE_COORDINATES_URL = 'https://sequence-coordinates.rcsb.org/graphql';
+export function entityAlignmentsQuery(uniprotId) {
+    return `{ alignments(from: UNIPROT, to: PDB_ENTITY, queryId: "${uniprotId}") {
+  target_alignments {
+    target_id
+    coverage { query_coverage }
+    aligned_regions { query_begin query_end }
+  }
+} }`;
 }
+export const ENTITY_DETAILS_QUERY = `query($ids: [String!]!) { polymer_entities(entity_ids: $ids) {
+  rcsb_id
+  rcsb_polymer_entity_container_identifiers { auth_asym_ids }
+  entry { rcsb_entry_info { experimental_method resolution_combined } }
+} }`;
+// RCSB's cap on ids per batch request
+const DETAILS_BATCH = 1000;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function finiteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
+function strings(value) {
+    return Array.isArray(value)
+        ? value.filter((v) => typeof v === 'string')
+        : [];
+}
 /**
- * PDBe entries only, best-covering first and sharpest within a tie.
- *
- * Predicted entries (AlphaFold, SWISS-MODEL, AlphaFill) are left out because a
- * prediction comes from AlphaFold's own API, which answers per model. And
- * 3D-Beacons files SASBDB's small-angle-scattering fits under "experimentally
- * determined" too, with numeric ids and near-full coverage — dystrophin's best
- * "structure" by coverage was SASBDB 436 — which are not entries a residue
- * mapping exists for. Hence the `provider === 'PDBe'` gate rather than the
- * category alone.
+ * PDB entities only: the same list carries RCSB's computed models
+ * (`AF_AFP04637F1_1`), which a residue mapping does not exist for. The range
+ * spans every aligned region, as 3D-Beacons reported it.
  */
-export function parseExperimentalStructures(json) {
-    const structures = isRecord(json) ? json.structures : undefined;
-    if (!Array.isArray(structures)) {
+export function parseEntityAlignments(data) {
+    const alignments = isRecord(data) ? data.alignments : undefined;
+    const targets = isRecord(alignments)
+        ? alignments.target_alignments
+        : undefined;
+    if (!Array.isArray(targets)) {
         return [];
     }
-    return structures
-        .flatMap(entry => {
-        const s = isRecord(entry) ? entry.summary : undefined;
-        if (!isRecord(s)) {
+    return targets.flatMap(target => {
+        if (!isRecord(target) || typeof target.target_id !== 'string') {
             return [];
         }
-        const start = finiteNumber(s.uniprot_start);
-        const end = finiteNumber(s.uniprot_end);
-        const coverage = finiteNumber(s.coverage);
-        return typeof s.model_identifier === 'string' &&
-            s.provider === 'PDBe' &&
-            s.model_category === 'EXPERIMENTALLY DETERMINED' &&
-            start !== undefined &&
-            end !== undefined &&
-            coverage !== undefined
+        const [pdbId] = target.target_id.split('_');
+        const coverage = isRecord(target.coverage)
+            ? finiteNumber(target.coverage.query_coverage)
+            : undefined;
+        const regions = Array.isArray(target.aligned_regions)
+            ? target.aligned_regions.filter(isRecord)
+            : [];
+        const begins = regions.map(r => finiteNumber(r.query_begin));
+        const ends = regions.map(r => finiteNumber(r.query_end));
+        return pdbId !== undefined &&
+            isPdbId(pdbId) &&
+            coverage !== undefined &&
+            begins.length > 0 &&
+            begins.every(b => b !== undefined) &&
+            ends.every(e => e !== undefined)
             ? [
                 {
-                    pdbId: s.model_identifier.toLowerCase(),
-                    method: typeof s.experimental_method === 'string'
-                        ? s.experimental_method
-                        : 'experimental',
-                    resolution: finiteNumber(s.resolution),
-                    start,
-                    end,
+                    entityId: target.target_id,
+                    pdbId: pdbId.toLowerCase(),
+                    start: Math.min(...begins),
+                    end: Math.max(...ends),
                     coverage,
                 },
             ]
             : [];
-    })
-        .sort((a, b) => b.coverage - a.coverage ||
+    });
+}
+export function parseEntityDetails(data) {
+    const entities = isRecord(data) ? data.polymer_entities : undefined;
+    const details = new Map();
+    for (const entity of Array.isArray(entities) ? entities : []) {
+        if (!isRecord(entity) || typeof entity.rcsb_id !== 'string') {
+            continue;
+        }
+        const ids = entity.rcsb_polymer_entity_container_identifiers;
+        const info = isRecord(entity.entry)
+            ? entity.entry.rcsb_entry_info
+            : undefined;
+        const resolutions = isRecord(info) ? info.resolution_combined : undefined;
+        const resolution = Array.isArray(resolutions)
+            ? finiteNumber(resolutions[0])
+            : undefined;
+        details.set(entity.rcsb_id, {
+            method: isRecord(info) && typeof info.experimental_method === 'string'
+                ? info.experimental_method
+                : 'experimental',
+            ...(resolution === undefined ? {} : { resolution }),
+            chains: strings(isRecord(ids) ? ids.auth_asym_ids : undefined),
+        });
+    }
+    return details;
+}
+/**
+ * One row per entry, best coverage first and sharpest within a tie. An entry
+ * with several entities of the protein (a construct crystallised beside a
+ * different fragment of itself) takes the best-covering entity's range and
+ * every entity's chains.
+ */
+export function experimentalStructures(alignments, details) {
+    const byEntry = new Map();
+    for (const a of alignments) {
+        const d = details.get(a.entityId);
+        if (!d) {
+            continue;
+        }
+        const existing = byEntry.get(a.pdbId);
+        if (!existing) {
+            byEntry.set(a.pdbId, {
+                pdbId: a.pdbId,
+                method: d.method,
+                ...(d.resolution === undefined ? {} : { resolution: d.resolution }),
+                start: a.start,
+                end: a.end,
+                coverage: a.coverage,
+                chains: [...d.chains],
+            });
+            continue;
+        }
+        for (const chain of d.chains) {
+            if (!existing.chains.includes(chain)) {
+                existing.chains.push(chain);
+            }
+        }
+        if (a.coverage > existing.coverage) {
+            Object.assign(existing, {
+                start: a.start,
+                end: a.end,
+                coverage: a.coverage,
+            });
+        }
+    }
+    return [...byEntry.values()].sort((a, b) => b.coverage - a.coverage ||
         (a.resolution ?? Infinity) - (b.resolution ?? Infinity));
 }
-/** Best-effort: an unreachable API reads as "no entries", which costs a
- * structure suggestion and nothing else. */
+const ISOFORM_SUFFIX = /-\d+$/;
+/**
+ * Every PDB entry aligned to the accession. An accession with none, or one
+ * RCSB does not know, is `[]`; an isoform accession is asked as its entry,
+ * which is what the alignment is numbered on.
+ */
 export async function fetchExperimentalStructures(uniprotId, opts) {
-    for (let attempt = 0; attempt < 2; attempt++) {
-        const res = await rawfetch(beaconsSummaryUrl(uniprotId), opts).catch(() => undefined);
-        if (res?.ok) {
-            return parseExperimentalStructures(await res.json());
-        }
-        if (res?.status === 404 || opts?.signal?.aborted) {
-            return [];
+    const alignments = parseEntityAlignments(await graphqlFetch(RCSB_SEQUENCE_COORDINATES_URL, entityAlignmentsQuery(uniprotId.replace(ISOFORM_SUFFIX, '')), undefined, opts));
+    const ids = alignments.map(a => a.entityId);
+    const details = new Map();
+    for (let i = 0; i < ids.length; i += DETAILS_BATCH) {
+        const batch = parseEntityDetails(await graphqlFetch(RCSB_DATA_GRAPHQL_URL, ENTITY_DETAILS_QUERY, { ids: ids.slice(i, i + DETAILS_BATCH) }, opts));
+        for (const [id, d] of batch) {
+            details.set(id, d);
         }
     }
-    return [];
+    return experimentalStructures(alignments, details);
 }
 //# sourceMappingURL=structureSources.js.map

package/esm/structureSources.js.map

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

package/esm/structureUrls.d.ts

@@ -9,6 +9,8 @@ export declare function uniprotEntryUrl(uniprotId: string): string;
  */
 export declare function getAlphaFoldStructureUrl(uniprotId: string, version?: string): string;
 export declare function getPdbStructureUrl(pdbId: string): string;
+export declare function isPdbId(value: string): boolean;
+export declare function rcsbEntryUrl(pdbId: string): string;
 /**
  * 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

package/esm/structureUrls.js

@@ -27,6 +27,15 @@ export function getAlphaFoldStructureUrl(uniprotId, version = ALPHAFOLD_VERSION)
 export function getPdbStructureUrl(pdbId) {
     return `https://files.rcsb.org/download/${pdbId}.cif`;
 }
+// A PDB id is four characters, the first a digit: 1TUP, 6ZIO. Checked before
+// a typed one reaches a fetch, so three characters on the way to four are not
+// a 404 apiece.
+export function isPdbId(value) {
+    return /^[1-9][A-Za-z0-9]{3}$/.test(value);
+}
+export function rcsbEntryUrl(pdbId) {
+    return `https://www.rcsb.org/structure/${pdbId.toUpperCase()}`;
+}
 /**
  * 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

package/esm/structureUrls.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "p2s_mapper",
-  "description": "Map a transcript's translation onto a protein structure: alignment, coordinates, chain choice, SIFTS, and the AlphaFold and PDBe lookups that find the structure",
-  "version": "1.4.0",
+  "description": "Map a transcript's translation onto a protein structure: alignment, coordinates, chain choice, UniProt mapping, and the AlphaFold and RCSB lookups that find the structure",
+  "version": "2.0.0",
   "packageManager": "pnpm@11.15.1",
   "repository": {
     "type": "git",
@@ -25,6 +25,7 @@
     "clean": "rimraf dist esm",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "docs:api": "node scripts/api-doc.ts",
     "lint": "eslint --report-unused-disable-directives --max-warnings 0",
     "typecheck": "tsc --noEmit -p tsconfig.lint.json",
     "prebuild": "pnpm clean",

package/src/coordinates.ts

@@ -19,10 +19,9 @@ import type { PairwiseAlignment } from './mappings.ts'
  * 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 type StructurePos = number & { readonly __brand: 'StructurePos' }
+export type TranscriptPos = number & { readonly __brand: 'TranscriptPos' }
+export type AlignmentCol = number & { readonly __brand: 'AlignmentCol' }
 
 export const structurePos = (n: number) => n as StructurePos
 export const transcriptPos = (n: number) => n as TranscriptPos

package/src/dbIds.ts

@@ -3,7 +3,7 @@
 // keyword, the regex (Ensembl patterns cover human ENS, mouse ENSMUS, zebrafish
 // ENSDAR, etc.), and a human-readable label. Recognition, label rendering, and
 // xref-query building all derive from this list, so a new ID type is one entry.
-type DbType = 'ensembl' | 'refseq' | 'ccds' | 'hgnc' | 'geneid'
+export type DbType = 'ensembl' | 'refseq' | 'ccds' | 'hgnc' | 'geneid'
 
 const DB_ID_PATTERNS: { db: DbType; pattern: RegExp; label: string }[] = [
   { db: 'ensembl', pattern: /^ENS[A-Z]*G\d+/i, label: 'Ensembl gene' },

package/src/extractPerResidueConfidence.ts

@@ -2,7 +2,7 @@
 // store the per-residue pLDDT in the B-factor column (B_iso_or_equiv), so the
 // first atom of each residue yields pLDDT for a predicted model and the
 // crystallographic B-factor for an experimental one.
-interface ConfidenceModel {
+export interface ConfidenceModel {
   obj?: {
     data: {
       atomicConformation: {

package/src/extractStructureSequences.ts

@@ -20,32 +20,32 @@
  * So carry the real ids and convert through them.
  */
 export interface Entity {
+  /** mmCIF entity id, molstar's own bookkeeping */
   entityId: string
+  /** one letter per residue, observed or not */
   seq: string
+  /** molstar `label_seq_id` per position of `seq` */
   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 */
+  /** author chain ids carrying this entity, e.g. ['A', 'B'] for a homodimer:
+   * what a user recognises from the PDB entry page */
   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. */
+  /** DNA, RNA or a hybrid, by molstar's entity subtype. Its letters spell
+   * amino acids too (A, C, G, T, U), so it is kept out of the alignment
+   * rather than left to score 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`. */
+  /** `auth_seq_id` per position: the depositors' numbering, which papers cite
+   * (1TUP's position 154 is R248) and Mol*'s hover shows. Display only;
+   * address Mol* through `seqIds`. Absent when the model has no atomic
+   * hierarchy. See `residueNumber`. */
   authSeqIds?: number[]
 }
 
-interface Column<T> {
+export interface Column<T> {
   rowCount: number
   value(row: number): T
 }
 
-interface StructureModel {
+export interface StructureModel {
   obj?: {
     data: {
       entities?: {

package/src/fetchUtils.ts

@@ -75,10 +75,32 @@ export interface FetchOptions extends RequestInit {
   fetch?: typeof globalThis.fetch
 }
 
+const USER_AGENT = 'p2s_mapper (+https://github.com/GMOD/p2s_mapper)'
+
+/**
+ * AlphaFold's prediction API answers 403 to `node`, the user agent Node's fetch
+ * sends (measured 2026-10-11), so outside a browser every request names this
+ * package unless the caller named something else. A browser sends its own, and
+ * a script-set one would cost a CORS preflight on every call.
+ */
+function withUserAgent(init: RequestInit) {
+  if (
+    typeof navigator !== 'undefined' &&
+    navigator.userAgent.startsWith('Mozilla')
+  ) {
+    return init
+  }
+  const headers = new Headers(init.headers)
+  if (!headers.has('user-agent')) {
+    headers.set('user-agent', USER_AGENT)
+  }
+  return { ...init, headers }
+}
+
 export async function rawfetch(url: string, args?: FetchOptions) {
   const { fetch: f = globalThis.fetch, ...init } = args ?? {}
   try {
-    return await f(url, init)
+    return await f(url, withUserAgent(init))
   } catch (e) {
     throw networkError(url, e)
   }

package/src/index.ts

@@ -16,14 +16,12 @@ export * from './extractStructureSequences.ts'
 export * from './extractPerResidueConfidence.ts'
 export * from './isoformRanking.ts'
 
-// SIFTS
+// UniProt mapping
 export * from './pdbUniProtMapping.ts'
-export * from './siftsNumbering.ts'
+export * from './pdbEntry.ts'
 
 // Structure sources
 export * from './alphaFoldModels.ts'
-export * from './pdbeBestStructures.ts'
-export * from './pdbeEntryMolecules.ts'
 export * from './structureSources.ts'
 export * from './uniProtSearch.ts'
 export * from './dbIds.ts'

package/src/isoformRanking.ts

@@ -22,11 +22,11 @@ export interface RankedIsoform {
 }
 
 export interface ClassifiedIsoforms {
-  // protein matches the structure residues, longest first
+  /** translates to exactly the structure's sequence, longest first */
   matches: RankedIsoform[]
-  // has a protein sequence but doesn't match the structure, best-aligning first
+  /** translates to something else, best-aligning first */
   nonMatches: RankedIsoform[]
-  // ids of the isoforms no protein sequence could be computed for
+  /** ids of the isoforms with no translation */
   noData: string[]
 }
 

package/src/pairwiseAlignment.ts

@@ -68,7 +68,7 @@ function getScore(a: string, b: string) {
 const GAP_OPEN = -10
 const GAP_EXTEND = -0.5
 
-interface AlignmentResult {
+export interface AlignmentResult {
   alignedSeq1: string
   alignedSeq2: string
   score: number