p2s_mapper 1.0.0

package/src/pdbUniProtMapping.ts

@@ -0,0 +1,320 @@
+// SIFTS UniProt <-> PDB residue mapping.
+//
+// UniProt feature coordinates are positions in the UniProt canonical sequence.
+// For an AlphaFold model that *is* the structure's own sequence, so a feature at
+// UniProt position p sits at structure position p - 1. For an experimental PDB
+// entry it is not: the deposited construct is usually a fragment, often with
+// tags or engineered residues, so the two numberings differ by a per-segment
+// offset (1TUP's p53 chain starts at UniProt 94; 6VXX's spike SEQRES 33 is
+// UniProt 14). SIFTS is the authoritative alignment between the two, published
+// per entity/chain by PDBe.
+//
+// `residue_number` in the PDBe response is the 1-based index into the entity's
+// SEQRES, i.e. label_seq_id, which is exactly this plugin's structure-sequence
+// position + 1 (see applyLociInteractivity.ts for the other place that boundary
+// is crossed).
+
+import { jsonfetch, timeout } from './fetchUtils.ts'
+
+import type { FetchOptions } from './fetchUtils.ts'
+
+/** One contiguous UniProt <-> structure correspondence for a single entity.
+ * `unp*` are 1-based UniProt positions; `struct*` are 0-based inclusive
+ * structure-sequence positions, this plugin's native coordinate. */
+export interface UniProtStructureSegment {
+  entityId: string
+  /** author chain id, when the response names it */
+  chainId?: string
+  unpStart: number
+  unpEnd: number
+  structStart: number
+  structEnd: number
+  /** the endpoints' author residue numbers, the numbering a paper cites and a
+   * Mol* hover shows; absent when the response omits them */
+  authorStart?: number
+  authorEnd?: number
+}
+
+export interface UniProtStructureMapping {
+  accession: string
+  /** UniProt entry name, e.g. "P53_HUMAN" */
+  name?: string
+  segments: UniProtStructureSegment[]
+}
+
+/**
+ * Maps a 1-based UniProt position to a 0-based structure-sequence position.
+ * Returns undefined for positions outside the modeled region, so callers drop
+ * the feature instead of drawing it somewhere misleading.
+ */
+export type MapUniProtPosition = (uniprotPos: number) => number | undefined
+
+export function pdbeSiftsUrl(pdbId: string) {
+  return `https://www.ebi.ac.uk/pdbe/api/mappings/uniprot/${pdbId.toLowerCase()}`
+}
+
+const SIFTS_RETRY_DELAYS_MS = [1000, 3000]
+// bounded, since a view reports itself loading until SIFTS answers
+const SIFTS_TIMEOUT_MS = 20_000
+
+/** SIFTS for an entry, retried twice: one failed request would otherwise
+ * leave a fusion construct mapped onto its partner for the whole session. */
+export async function fetchUniProtStructureMappings(
+  pdbId: string,
+  opts?: FetchOptions,
+) {
+  const { signal: caller, ...rest } = opts ?? {}
+  const signal = caller ?? undefined
+  const deadline = () =>
+    signal
+      ? AbortSignal.any([signal, AbortSignal.timeout(SIFTS_TIMEOUT_MS)])
+      : AbortSignal.timeout(SIFTS_TIMEOUT_MS)
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return parseUniProtStructureMappings(
+        await jsonfetch(pdbeSiftsUrl(pdbId), { ...rest, signal: deadline() }),
+      )
+    } catch (e) {
+      const delay = SIFTS_RETRY_DELAYS_MS[attempt]
+      if (delay === undefined) {
+        throw e
+      }
+      await timeout(delay, signal)
+    }
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function finiteNumber(value: unknown) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+function residueNumber(endpoint: unknown) {
+  return isRecord(endpoint) ? finiteNumber(endpoint.residue_number) : undefined
+}
+
+function authorResidueNumber(endpoint: unknown) {
+  return isRecord(endpoint)
+    ? finiteNumber(endpoint.author_residue_number)
+    : undefined
+}
+
+function parseSegment(mapping: unknown): UniProtStructureSegment | undefined {
+  if (!isRecord(mapping)) {
+    return undefined
+  }
+  const entityId = finiteNumber(mapping.entity_id)
+  const unpStart = finiteNumber(mapping.unp_start)
+  const unpEnd = finiteNumber(mapping.unp_end)
+  const structStart = residueNumber(mapping.start)
+  const structEnd = residueNumber(mapping.end)
+  const authorStart = authorResidueNumber(mapping.start)
+  const authorEnd = authorResidueNumber(mapping.end)
+  return entityId === undefined ||
+    unpStart === undefined ||
+    unpEnd === undefined ||
+    structStart === undefined ||
+    structEnd === undefined
+    ? undefined
+    : {
+        entityId: String(entityId),
+        ...(typeof mapping.chain_id === 'string'
+          ? { chainId: mapping.chain_id }
+          : {}),
+        unpStart,
+        unpEnd,
+        // SEQRES/label_seq_id is 1-based, structure positions are 0-based
+        structStart: structStart - 1,
+        structEnd: structEnd - 1,
+        ...(authorStart === undefined ? {} : { authorStart }),
+        ...(authorEnd === undefined ? {} : { authorEnd }),
+      }
+}
+
+/**
+ * Parses a PDBe `mappings/uniprot/{pdbId}` response into one entry per UniProt
+ * accession. Unparseable segments are skipped rather than failing the whole
+ * response — a chimera with one malformed segment still maps its other chains.
+ * The response is keyed by pdb id, so the single entry is taken whatever its key.
+ */
+export function parseUniProtStructureMappings(
+  json: unknown,
+): UniProtStructureMapping[] {
+  const entry = isRecord(json) ? Object.values(json)[0] : undefined
+  const uniprot = isRecord(entry) ? entry.UniProt : undefined
+  if (!isRecord(uniprot)) {
+    return []
+  }
+  const result: UniProtStructureMapping[] = []
+  for (const [accession, value] of Object.entries(uniprot)) {
+    const mappings = isRecord(value) ? value.mappings : undefined
+    const segments = Array.isArray(mappings)
+      ? mappings.map(parseSegment).filter(s => s !== undefined)
+      : []
+    if (segments.length > 0) {
+      result.push({
+        accession,
+        name:
+          isRecord(value) && typeof value.name === 'string'
+            ? value.name
+            : undefined,
+        segments,
+      })
+    }
+  }
+  return result
+}
+
+function coveredResidues(segments: UniProtStructureSegment[]) {
+  return segments.reduce((a, s) => a + (s.structEnd - s.structStart + 1), 0)
+}
+
+/** The entity a SIFTS segment is matched against: its mmCIF id and the author
+ * chains carrying it. */
+export interface SegmentEntity {
+  entityId: string
+  chains: readonly string[]
+}
+
+/**
+ * The segments of one accession that describe this entity. SIFTS numbers
+ * entities as the mmCIF does, and a PDB-format file loaded through Mol* numbers
+ * them per chain (1H26.pdb's chain C is entity 2, which in SIFTS is cyclin A),
+ * so a segment naming its chain is matched by chain.
+ */
+function segmentsForEntity(
+  mapping: UniProtStructureMapping,
+  entity: SegmentEntity,
+) {
+  return dedupeSegments(
+    mapping.segments.filter(s =>
+      s.chainId === undefined
+        ? s.entityId === entity.entityId
+        : entity.chains.includes(s.chainId),
+    ),
+  )
+}
+
+/**
+ * Picks the UniProt entry that describes a given entity, with its segments
+ * narrowed to that entity. Only the entity the plugin has mapped to the
+ * transcript is relevant — a heteromer maps each of its chains to a different
+ * accession, and using the wrong one would silently annotate the wrong protein.
+ * When several accessions cover the same entity (a chimeric construct) the one
+ * contributing the most residues wins.
+ */
+export function chooseUniProtMappingForEntity(
+  mappings: UniProtStructureMapping[],
+  entity: SegmentEntity | undefined,
+): UniProtStructureMapping | undefined {
+  if (entity === undefined) {
+    return undefined
+  }
+  let best: UniProtStructureMapping | undefined
+  for (const mapping of mappings) {
+    const segments = segmentsForEntity(mapping, entity)
+    if (
+      segments.length > 0 &&
+      (!best || coveredResidues(segments) > coveredResidues(best.segments))
+    ) {
+      best = { ...mapping, segments }
+    }
+  }
+  return best
+}
+
+const OWN_PSEUDOCOUNT = 5
+const MIN_OWN_IDENTITY = 0.5
+
+/**
+ * Mapped structure positions that SIFTS assigns to a protein other than the
+ * transcript's, on a chain that fuses two. Local alignment bridges a fusion
+ * boundary, and on every GPCR fusion construct checked it scattered receptor
+ * residues onto the partner, 33 of them onto T4 lysozyme in 2RH1.
+ *
+ * `mapped` is each mapped structure position and whether its pair is
+ * identical. The transcript's own accession is the one whose covered positions
+ * are most often identical, plus a pseudocount, as the chain picker scores
+ * chains. A count of covered positions would not do: TP53's 11-residue peptide
+ * fused to CDK2 covers 11 positions against 224 chance hits on the kinase, and
+ * counting unmapped the peptide. Unless that accession reaches half identity
+ * the transcript is taken to be neither protein, and nothing is unmapped.
+ * Residues SIFTS assigns to no accession, such as tags, stay mapped.
+ */
+export function fusionPartnerPositions(
+  mappings: UniProtStructureMapping[],
+  entity: SegmentEntity | undefined,
+  mapped: ReadonlyMap<number, boolean>,
+) {
+  const partners = new Set<number>()
+  const byAccession = entity
+    ? mappings
+        .map(m => segmentsForEntity(m, entity))
+        .filter(segments => segments.length > 0)
+    : []
+  if (byAccession.length < 2) {
+    return partners
+  }
+  const covers = (segments: UniProtStructureSegment[], pos: number) =>
+    segments.some(s => pos >= s.structStart && pos <= s.structEnd)
+  const identity = byAccession.map(segments => {
+    let covered = 0
+    let identical = 0
+    for (const [pos, same] of mapped) {
+      if (covers(segments, pos)) {
+        covered++
+        identical += same ? 1 : 0
+      }
+    }
+    return identical / (covered + OWN_PSEUDOCOUNT)
+  })
+  const ownIdentity = Math.max(...identity)
+  if (ownIdentity < MIN_OWN_IDENTITY) {
+    return partners
+  }
+  const own = byAccession[identity.indexOf(ownIdentity)]!
+  for (const pos of mapped.keys()) {
+    if (
+      !covers(own, pos) &&
+      byAccession.some(segments => segments !== own && covers(segments, pos))
+    ) {
+      partners.add(pos)
+    }
+  }
+  return partners
+}
+
+// SIFTS lists one mapping per *chain*, so the several chains of a homodimer
+// repeat the same entity-level correspondence. They collapse to one segment.
+function dedupeSegments(segments: UniProtStructureSegment[]) {
+  const seen = new Set<string>()
+  return segments.filter(s => {
+    const key = `${s.unpStart}-${s.unpEnd}-${s.structStart}-${s.structEnd}`
+    const isNew = !seen.has(key)
+    seen.add(key)
+    return isNew
+  })
+}
+
+/** 1-based UniProt position -> 0-based structure position, for an AlphaFold
+ * model whose sequence is the UniProt sequence. */
+export const identityUniProtPositionMap: MapUniProtPosition = uniprotPos =>
+  uniprotPos - 1
+
+export function makeUniProtPositionMap(
+  segments: UniProtStructureSegment[],
+): MapUniProtPosition {
+  return uniprotPos => {
+    const segment = segments.find(
+      s => uniprotPos >= s.unpStart && uniprotPos <= s.unpEnd,
+    )
+    if (!segment) {
+      return undefined
+    }
+    const pos = segment.structStart + (uniprotPos - segment.unpStart)
+    return pos <= segment.structEnd ? pos : undefined
+  }
+}

package/src/pdbeBestStructures.ts

@@ -0,0 +1,94 @@
+// PDBe's SIFTS-derived list of the experimental structures covering a UniProt
+// entry, one row per chain, ranked by PDBe (coverage, then resolution). The
+// dialog shows one row per entry, so the chains of a homomer collapse into it.
+
+export interface PdbStructureEntry {
+  pdbId: string
+  experimentalMethod: string
+  /** Å; absent for NMR and some EM entries */
+  resolution?: number
+  /** 1-based inclusive UniProt positions the entry covers */
+  unpStart: number
+  unpEnd: number
+  /** share of the UniProt sequence the entry covers, 0..1 */
+  coverage: number
+  chains: string[]
+}
+
+export function pdbeBestStructuresUrl(uniprotId: string) {
+  return `https://www.ebi.ac.uk/pdbe/api/mappings/best_structures/${uniprotId}`
+}
+
+// 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: string) {
+  return /^[1-9][A-Za-z0-9]{3}$/.test(value)
+}
+
+export function rcsbEntryUrl(pdbId: string) {
+  return `https://www.rcsb.org/structure/${pdbId.toUpperCase()}`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function finiteNumber(value: unknown) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+/**
+ * Groups the per-chain rows into one entry per PDB id, keeping PDBe's order.
+ * An entry whose chains cover different UniProt ranges (a construct
+ * crystallised beside a different fragment of itself) keeps its first row's
+ * range, which is the one PDBe ranked it by. The response is keyed by
+ * accession, so the single entry is taken whatever its key.
+ */
+export function parseBestStructures(json: unknown): PdbStructureEntry[] {
+  const rows = isRecord(json) ? Object.values(json)[0] : undefined
+  if (!Array.isArray(rows)) {
+    return []
+  }
+  const byId = new Map<string, PdbStructureEntry>()
+  for (const row of rows) {
+    if (!isRecord(row)) {
+      continue
+    }
+    const pdbId = typeof row.pdb_id === 'string' ? row.pdb_id : undefined
+    const chain = typeof row.chain_id === 'string' ? row.chain_id : undefined
+    const unpStart = finiteNumber(row.unp_start)
+    const unpEnd = finiteNumber(row.unp_end)
+    const coverage = finiteNumber(row.coverage)
+    if (
+      pdbId === undefined ||
+      chain === undefined ||
+      unpStart === undefined ||
+      unpEnd === undefined ||
+      coverage === undefined
+    ) {
+      continue
+    }
+    const existing = byId.get(pdbId)
+    if (existing) {
+      if (!existing.chains.includes(chain)) {
+        existing.chains.push(chain)
+      }
+      continue
+    }
+    const resolution = finiteNumber(row.resolution)
+    byId.set(pdbId, {
+      pdbId,
+      experimentalMethod:
+        typeof row.experimental_method === 'string'
+          ? row.experimental_method
+          : 'unknown',
+      ...(resolution === undefined ? {} : { resolution }),
+      unpStart,
+      unpEnd,
+      coverage,
+      chains: [chain],
+    })
+  }
+  return [...byId.values()]
+}

package/src/pdbeEntryMolecules.ts

@@ -0,0 +1,37 @@
+// The polymer entities of a PDB entry, as PDBe already knows them. The dialog
+// wants the entry's residues only to annotate the isoform list, and reading
+// them out of the structure file meant downloading and parsing the whole
+// mmCIF — minutes for a ribosome, for a label. This is a few kB of JSON, and
+// the view downloads the file itself when the user actually launches.
+
+export function pdbeEntryMoleculesUrl(pdbId: string) {
+  return `https://www.ebi.ac.uk/pdbe/api/pdb/entry/molecules/${pdbId.toLowerCase()}`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * One sequence per protein entity, in entity order. Nucleic-acid entities are
+ * left out: A, C, G, T and U are amino-acid letters too, so a DNA chain scores
+ * as a candidate rather than losing honestly.
+ */
+export function parseEntryMolecules(json: unknown): string[] {
+  const entities = isRecord(json) ? Object.values(json)[0] : undefined
+  if (!Array.isArray(entities)) {
+    return []
+  }
+  return entities.flatMap(entity => {
+    if (!isRecord(entity)) {
+      return []
+    }
+    const { molecule_type: type, sequence } = entity
+    return typeof type === 'string' &&
+      type.startsWith('polypeptide') &&
+      typeof sequence === 'string' &&
+      sequence.length > 0
+      ? [sequence]
+      : []
+  })
+}

package/src/siftsNumbering.ts

@@ -0,0 +1,61 @@
+// How a PDB entry numbers the residues of a UniProt sequence. Author numbering
+// is what a paper cites and what a viewer lights a named residue by, and it is
+// not the UniProt numbering for every entry: haemoglobin's chains number from
+// the mature protein, so author residue 1 is UniProt residue 2 (2HHB, measured
+// 2026-09-12). SIFTS records the correspondence per chain segment, and
+// `fetchUniProtStructureMappings` is what asks PDBe for it.
+
+import type { UniProtStructureSegment } from './pdbUniProtMapping.ts'
+
+export interface AuthorRange {
+  start: number
+  end: number
+  chain: string
+  /** author number minus UniProt number in the chosen segment */
+  shift: number
+}
+
+/** The segments SIFTS gives one accession, chain ids and author numbers
+ * included, out of a whole entry's mappings. */
+export function segmentsForAccession(
+  mappings: readonly {
+    accession: string
+    segments: UniProtStructureSegment[]
+  }[],
+  accession: string,
+) {
+  return mappings.find(m => m.accession === accession)?.segments ?? []
+}
+
+/**
+ * The author-numbered range a UniProt range is cited by in the entry: the
+ * segment overlapping most of the range decides the shift. Undefined when no
+ * chain of the entry covers any of it, or when SIFTS named no author numbers.
+ */
+export function toAuthorRange(
+  segments: readonly UniProtStructureSegment[],
+  range: { start: number; end: number },
+): AuthorRange | undefined {
+  const overlap = (s: UniProtStructureSegment) =>
+    Math.min(s.unpEnd, range.end) - Math.max(s.unpStart, range.start) + 1
+  const best = segments
+    .flatMap(s => {
+      const { chainId, authorStart, unpStart, unpEnd } = s
+      return chainId !== undefined &&
+        authorStart !== undefined &&
+        overlap(s) > 0
+        ? [{ chainId, authorStart, unpStart, unpEnd, overlap: overlap(s) }]
+        : []
+    })
+    .toSorted((a, b) => b.overlap - a.overlap)[0]
+  if (!best) {
+    return undefined
+  }
+  const shift = best.authorStart - best.unpStart
+  return {
+    start: Math.max(range.start, best.unpStart) + shift,
+    end: Math.min(range.end, best.unpEnd) + shift,
+    chain: best.chainId,
+    shift,
+  }
+}

package/src/stripStopCodon.ts

@@ -0,0 +1,20 @@
+/**
+ * Drop the terminal stop codon(s) from a translated protein sequence.
+ *
+ * Only trailing `*` go: an interior stop (mis-annotated CDS, selenoprotein
+ * read-through) occupies a real codon position, and deleting it would shift
+ * every later residue out of step with g2p's codon-indexed transcript
+ * coordinates — offsetting every genome↔structure hover past that point.
+ */
+export function stripStopCodon(seq: string) {
+  return seq.replace(/\*+$/, '')
+}
+
+/**
+ * Strip every stop codon, including interior ones. Only for sequences handed to
+ * an external similarity search (Foldseek, AlphaFold), where `*` is not a valid
+ * query character and no coordinate depends on the result's positions.
+ */
+export function stripAllStopCodons(seq: string) {
+  return seq.replaceAll('*', '')
+}

package/src/structureFormat.ts

@@ -0,0 +1,70 @@
+/**
+ * Which molstar trajectory parser a structure needs.
+ *
+ * Getting this wrong is not a graceful failure in either direction: parsing a
+ * PDB file as mmCIF throws ("Unexpected token. Expected data_, loop_, or data
+ * name"), and — worse — parsing an mmCIF as PDB *succeeds* and yields a model
+ * with zero polymer entities and thousands of misread atoms, so the view loads
+ * with no sequence, no alignment and no genome mapping, and nothing reports an
+ * error.
+ *
+ * So detection lives here and is applied as the default at every entry point,
+ * rather than at one of them.
+ *
+ * The two names are the subset of molstar's `BuiltInTrajectoryFormat` a
+ * structure loaded from a file or a url can be, spelled out rather than
+ * imported so nothing here depends on molstar.
+ */
+export type StructureFormat = 'pdb' | 'mmcif'
+
+// Only the PDB set is enumerated: mmCIF is the fallback (see below), so listing
+// its extensions would be a second source of truth that could disagree.
+const PDB_EXTENSIONS = new Set(['pdb', 'ent', 'pdb1', 'pdb2', 'pdb3'])
+
+/** Trailing extension of a filename or URL, lowercased, ignoring any query or
+ * fragment and any `.gz` wrapper (`…/pdb1tup.ent.gz` -> `ent`). */
+export function structureFileExtension(nameOrUrl: string) {
+  const path = nameOrUrl.split(/[?#]/)[0] ?? ''
+  const name = path.split('/').pop() ?? ''
+  const parts = name.toLowerCase().split('.')
+  if (parts.at(-1) === 'gz') {
+    parts.pop()
+  }
+  return parts.length > 1 ? (parts.at(-1) ?? '') : ''
+}
+
+/**
+ * Format for a filename or URL. Unknown extensions fall back to mmCIF, which is
+ * what every URL this plugin generates itself serves (AlphaFold and RCSB both
+ * hand out `.cif`).
+ */
+export function structureFormatFromName(nameOrUrl: string): StructureFormat {
+  return PDB_EXTENSIONS.has(structureFileExtension(nameOrUrl)) ? 'pdb' : 'mmcif'
+}
+
+/** Whether a URL points at a binary-encoded structure, which molstar must be
+ * told to download as bytes rather than text. */
+export function isBinaryStructureUrl(url: string) {
+  return structureFileExtension(url) === 'bcif'
+}
+
+/**
+ * Format for structure text that arrived without a filename — an inline `data`
+ * snapshot, a pasted file, or the PDB the plugin synthesizes from Foldseek Cα
+ * coordinates. Sniffs the content, which is strictly more reliable than a name
+ * and is the only signal available here.
+ *
+ * mmCIF is line-oriented and its first meaningful line is a `data_` block
+ * header (comments and blank lines may precede it); PDB has none.
+ */
+export function structureFormatFromContent(data: string): StructureFormat {
+  // a data_ header can only appear in the first few lines; don't scan a 30MB
+  // structure to find out
+  for (const line of data.slice(0, 4096).split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed !== '' && !trimmed.startsWith('#')) {
+      return trimmed.toLowerCase().startsWith('data_') ? 'mmcif' : 'pdb'
+    }
+  }
+  return 'pdb'
+}