p2s_mapper 1.0.0

package/src/caCoordsToPdb.ts

@@ -0,0 +1,111 @@
+// 3-letter amino acid codes
+const AA_3LETTER: Record<string, string> = {
+  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: string, len: number) {
+  return str.padStart(len, ' ')
+}
+
+function padRight(str: string, len: number) {
+  return str.padEnd(len, ' ')
+}
+
+function formatCoord(val: number) {
+  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
+ */
+export function caCoordsToPdb(
+  tCa: string,
+  tSeq: string,
+  chainId = 'A',
+  title?: string,
+) {
+  const coords = tCa.split(',').map(Number)
+  const lines: string[] = []
+
+  // 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.
+ */
+export function hasValidCaCoords<T extends { tCa?: string; tSeq?: string }>(
+  hit: T,
+): hit is T & { tCa: string; tSeq: string } {
+  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
+}

package/src/chooseMappedEntity.ts

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

package/src/coordinates.ts

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

package/src/dbIds.ts

@@ -0,0 +1,46 @@
+// Single source of truth for database IDs that UniProt can cross-reference.
+// Each entry carries everything downstream needs: the UniProt xref database
+// 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'
+
+const DB_ID_PATTERNS: { db: DbType; pattern: RegExp; label: string }[] = [
+  { db: 'ensembl', pattern: /^ENS[A-Z]*G\d+/i, label: 'Ensembl gene' },
+  { db: 'ensembl', pattern: /^ENS[A-Z]*T\d+/i, label: 'Ensembl transcript' },
+  { db: 'ensembl', pattern: /^ENS[A-Z]*P\d+/i, label: 'Ensembl protein' },
+  { db: 'refseq', pattern: /^[NX]M_\d+/i, label: 'RefSeq mRNA' },
+  { db: 'refseq', pattern: /^[NX]R_\d+/i, label: 'RefSeq ncRNA' },
+  { db: 'refseq', pattern: /^[NX]P_\d+/i, label: 'RefSeq protein' },
+  { db: 'ccds', pattern: /^CCDS\d+/i, label: 'CCDS' },
+  { db: 'hgnc', pattern: /^HGNC:\d+/i, label: 'HGNC' },
+]
+
+export function matchDbIdPattern(id: string) {
+  return DB_ID_PATTERNS.find(p => p.pattern.test(id))
+}
+
+/** Whether an ID is a database identifier UniProt can map. */
+export function isRecognizedDatabaseId(id: string) {
+  return matchDbIdPattern(id) !== undefined
+}
+
+/** Human-readable label for an ID, e.g. "ENST00000123 (Ensembl transcript)".
+ * Unrecognized IDs are returned unadorned. */
+export function getDbIdLabel(id: string) {
+  const match = matchDbIdPattern(id)
+  return match ? `${id} (${match.label})` : id
+}
+
+/** The UniProt xref query fragment for a recognized ID, e.g.
+ * "xref:ensembl-ENST00000123". HGNC strips its redundant "HGNC:" prefix. */
+export function buildUniProtXrefQuery(id: string) {
+  const match = matchDbIdPattern(id)
+  return match
+    ? `xref:${match.db}-${match.db === 'hgnc' ? id.replace('HGNC:', '') : id}`
+    : undefined
+}
+
+export function stripTrailingVersion(s?: string) {
+  return s?.replace(/\.[^./]+$/, '')
+}

package/src/extractPerResidueConfidence.ts

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