p2s_mapper 1.0.0

package/src/extractStructureSequences.ts

@@ -0,0 +1,342 @@
+/** A polymer entity of a loaded structure: its mmCIF entity id, its one-letter
+ * sequence, and the molstar `label_seq_id` of each of those residues.
+ *
+ * The entity id is what lets every downstream step talk about "the gene's
+ * protein" by identity instead of by the fragile entity-[0] position.
+ *
+ * `seqIds` is what lets it talk about a *residue* by identity. Structure
+ * positions in this plugin are 0-based indices into `seq`; molstar addresses
+ * residues by `label_seq_id`. Those are related by `+1` only when the entity's
+ * sequence covers every residue from 1 — true for any mmCIF with an
+ * `entity_poly_seq` category (all of RCSB and AlphaFold) and for PDB files
+ * carrying SEQRES records, because molstar synthesizes the category from them.
+ *
+ * A PDB-format file with no SEQRES has no such category, so molstar falls back
+ * to `StructureSequence.fromHierarchy` and takes `label_seq_id` straight from
+ * the observed residues' author numbering: a chain whose coordinates start at
+ * residue 94 yields seqIds 94.., and an unobserved loop leaves a hole. Deriving
+ * the id arithmetically there is off by the whole offset, in both directions —
+ * every hover reads the wrong residue and every highlight paints the wrong one.
+ * So carry the real ids and convert through them.
+ */
+export interface Entity {
+  entityId: string
+  seq: string
+  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 */
+  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. */
+  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`. */
+  authSeqIds?: number[]
+}
+
+interface Column<T> {
+  rowCount: number
+  value(row: number): T
+}
+
+interface StructureModel {
+  obj?: {
+    data: {
+      entities?: {
+        subtype: Column<string>
+        getEntityIndex(id: string): number
+      }
+      sourceData?: { data: unknown }
+      sequence: {
+        sequences: readonly {
+          entityId: string
+          sequence: {
+            code: {
+              toArray(): ArrayLike<string>
+            }
+            seqId: {
+              toArray(): ArrayLike<number>
+            }
+          }
+        }[]
+      }
+      atomicHierarchy?: {
+        chains: {
+          label_entity_id: Column<string>
+          auth_asym_id: Column<string>
+        }
+        residues?: {
+          label_seq_id: Column<number>
+          auth_seq_id: Column<number>
+        }
+        residueAtomSegments?: { offsets: ArrayLike<number>; count: number }
+        chainAtomSegments?: { index: ArrayLike<number> }
+      }
+    }
+  }
+}
+
+/** Observed residues' label_seq_id -> auth_seq_id, per entity. The first chain
+ * carrying an entity wins, so a homodimer's copies agree. */
+function authSeqIdsByEntity(model: StructureModel) {
+  const hierarchy = model.obj?.data.atomicHierarchy
+  const byEntity = new Map<string, Map<number, number>>()
+  const { residues, residueAtomSegments, chainAtomSegments, chains } =
+    hierarchy ?? {}
+  if (!residues || !residueAtomSegments || !chainAtomSegments || !chains) {
+    return undefined
+  }
+  for (let residue = 0; residue < residueAtomSegments.count; residue++) {
+    const atom = residueAtomSegments.offsets[residue]!
+    const entityId = chains.label_entity_id.value(
+      chainAtomSegments.index[atom]!,
+    )
+    let ids = byEntity.get(entityId)
+    if (!ids) {
+      ids = new Map()
+      byEntity.set(entityId, ids)
+    }
+    const labelSeqId = residues.label_seq_id.value(residue)
+    if (!ids.has(labelSeqId)) {
+      ids.set(labelSeqId, residues.auth_seq_id.value(residue))
+    }
+  }
+  return byEntity
+}
+
+/**
+ * Author numbering for every SEQRES position, observed or not. A residue with
+ * no atoms has no auth_seq_id of its own, so it takes the offset of the nearest
+ * observed residue before it (after it, at an unobserved N-terminus): a
+ * disordered loop keeps counting the way the paper does. With nothing observed
+ * the label numbering stands.
+ */
+export function fillAuthSeqIds(
+  seqIds: number[],
+  observed: Map<number, number> | undefined,
+) {
+  const out: number[] = []
+  let offset: number | undefined
+  const firstObserved = seqIds.find(id => observed?.has(id))
+  if (firstObserved !== undefined) {
+    offset = observed!.get(firstObserved)! - firstObserved
+  }
+  for (const id of seqIds) {
+    const auth = observed?.get(id)
+    if (auth !== undefined) {
+      offset = auth - id
+    }
+    out.push(id + (offset ?? 0))
+  }
+  return out
+}
+
+/** The number a residue is called by: author numbering when the file carries
+ * it, else molstar's label_seq_id, which is the author numbering already for a
+ * SEQRES-less PDB and 1..N for everything else. */
+export function residueNumber(entity: Entity | undefined, pos: number) {
+  return entity?.authSeqIds?.[pos] ?? entity?.seqIds[pos] ?? pos + 1
+}
+
+/**
+ * The 0-based half-open position range covering an inclusive range of author
+ * residue numbers, the form a paper or a spec names a site by ("R248",
+ * "residues 102-292"). Undefined when no residue of the entity carries a number
+ * in the range, so a typo selects nothing rather than something else.
+ */
+export function residueRangeToPositions(
+  entity: Entity | undefined,
+  range: { start: number; end: number },
+) {
+  if (!entity) {
+    return undefined
+  }
+  let first: number | undefined
+  let last: number | undefined
+  for (let pos = 0; pos < entity.seq.length; pos++) {
+    const n = residueNumber(entity, pos)
+    if (n >= range.start && n <= range.end) {
+      first ??= pos
+      last = pos
+    }
+  }
+  return first === undefined || last === undefined
+    ? undefined
+    : { start: first, end: last + 1 }
+}
+
+function chainsByEntity(model: StructureModel) {
+  const chains = model.obj?.data.atomicHierarchy?.chains
+  const byEntity = new Map<string, string[]>()
+  if (chains) {
+    for (let i = 0; i < chains.label_entity_id.rowCount; i++) {
+      const entityId = chains.label_entity_id.value(i)
+      const chain = chains.auth_asym_id.value(i)
+      const list = byEntity.get(entityId) ?? []
+      if (!list.includes(chain)) {
+        list.push(chain)
+      }
+      byEntity.set(entityId, list)
+    }
+  }
+  return byEntity
+}
+
+// mmCIF entity_poly.type values for nucleic-acid polymers. Molstar derives the
+// subtype from residue components when a file (PDB format) carries no
+// entity_poly, so the flag is available for either format.
+const NUCLEIC_ACID_SUBTYPES = new Set([
+  'polydeoxyribonucleotide',
+  'polyribonucleotide',
+  'polydeoxyribonucleotide/polyribonucleotide hybrid',
+  'peptide nucleic acid',
+])
+
+function isNucleicAcid(model: StructureModel, entityId: string) {
+  const entities = model.obj?.data.entities
+  if (!entities) {
+    return false
+  }
+  const index = entities.getEntityIndex(entityId)
+  return index >= 0 && NUCLEIC_ACID_SUBTYPES.has(entities.subtype.value(index))
+}
+
+/** The slice of molstar's MmcifFormat data read here; other formats have no
+ * `db` */
+interface MmcifSourceData {
+  db?: {
+    entity_poly?: {
+      entity_id: Column<string>
+      pdbx_seq_one_letter_code_can: Column<string>
+    }
+  }
+}
+
+function canonicalSequencesByEntity(model: StructureModel) {
+  const source = model.obj?.data.sourceData?.data as MmcifSourceData | undefined
+  const entityPoly = source?.db?.entity_poly
+  const byEntity = new Map<string, string>()
+  if (entityPoly) {
+    for (let i = 0; i < entityPoly.entity_id.rowCount; i++) {
+      byEntity.set(
+        entityPoly.entity_id.value(i),
+        entityPoly.pdbx_seq_one_letter_code_can.value(i).replaceAll(/\s/g, ''),
+      )
+    }
+  }
+  return byEntity
+}
+
+/**
+ * One letter per position, so `seq[pos]` and `seqIds[pos]` name the same
+ * residue. Molstar's `label` column is not that: it spells a residue with no
+ * one-letter code by its component id (MSE, TPO, ACE) and an alternate site as
+ * "(S|P)", which shifted every later position. `code` writes X for those; the
+ * mmCIF canonical sequence then supplies the parent residue (MSE is M) when it
+ * has one letter per position, which a chromophore spelled "TYG" does not.
+ */
+export function oneLetterSequence(
+  codes: ArrayLike<string>,
+  canonical: string | undefined,
+) {
+  const letters = Array.from(codes)
+  return letters
+    .map((c, i) =>
+      c === 'X' && canonical?.length === letters.length ? canonical[i]! : c,
+    )
+    .join('')
+}
+
+export function extractEntities(model: StructureModel): Entity[] | undefined {
+  const chains = chainsByEntity(model)
+  const authIds = authSeqIdsByEntity(model)
+  const canonical = canonicalSequencesByEntity(model)
+  return model.obj?.data.sequence.sequences.map(s => {
+    const seqIds = Array.from(s.sequence.seqId.toArray())
+    return {
+      entityId: s.entityId,
+      seq: oneLetterSequence(
+        s.sequence.code.toArray(),
+        canonical.get(s.entityId),
+      ),
+      seqIds,
+      chains: chains.get(s.entityId) ?? [],
+      ...(isNucleicAcid(model, s.entityId) ? { nucleicAcid: true } : {}),
+      ...(authIds
+        ? { authSeqIds: fillAuthSeqIds(seqIds, authIds.get(s.entityId)) }
+        : {}),
+    }
+  })
+}
+
+/** A user-facing name for an entity: its chains when known, else its id. */
+export function entityLabel(entity: Entity) {
+  const chains =
+    entity.chains.length > 0
+      ? `Chain ${entity.chains.join('/')}`
+      : `Entity ${entity.entityId}`
+  return `${chains} (${entity.seq.length} ${entity.nucleicAcid ? 'nt' : 'aa'})`
+}
+
+/** The protein chains' sequences, for the launch dialog's isoform matching,
+ * which has no use for a DNA strand that happens to align. */
+export function extractStructureSequences(
+  model: StructureModel,
+): string[] | undefined {
+  return extractEntities(model)
+    ?.filter(e => !e.nucleicAcid)
+    .map(e => e.seq)
+}
+
+/**
+ * The molstar `label_seq_id`s for a set of 0-based structure positions. Unknown
+ * positions are dropped rather than guessed, so an out-of-range position paints
+ * nothing instead of painting something wrong.
+ */
+export function toLabelSeqIds(
+  entity: Entity | undefined,
+  positions: Iterable<number>,
+): number[] {
+  if (!entity) {
+    return []
+  }
+  const out: number[] = []
+  for (const pos of positions) {
+    const id = entity.seqIds[pos]
+    if (id !== undefined) {
+      out.push(id)
+    }
+  }
+  return out
+}
+
+/** As toLabelSeqIds, for a half-open [start, end) structure-position range. */
+export function rangeToLabelSeqIds(
+  entity: Entity | undefined,
+  range: { start: number; end: number } | undefined,
+): number[] {
+  if (!entity || !range) {
+    return []
+  }
+  const start = Math.max(0, range.start)
+  const end = Math.min(entity.seqIds.length, range.end)
+  return end > start ? entity.seqIds.slice(start, end) : []
+}
+
+/** Reverse of `seqIds`: molstar's label_seq_id -> 0-based structure position. */
+export function makeLabelSeqIdIndex(entity: Entity | undefined) {
+  const index = new Map<number, number>()
+  entity?.seqIds.forEach((id, pos) => {
+    // first wins: duplicate ids (micro-heterogeneity) collapse to one residue
+    if (!index.has(id)) {
+      index.set(id, pos)
+    }
+  })
+  return index
+}

package/src/fetchUtils.ts

@@ -0,0 +1,110 @@
+function hostOf(url: string) {
+  try {
+    return new URL(url).host
+  } catch {
+    return url
+  }
+}
+
+const MAX_DETAIL = 200
+
+function firstLine(body: string) {
+  const line = body.split('\n', 1)[0]?.trim() ?? ''
+  return line.length > MAX_DETAIL ? `${line.slice(0, MAX_DETAIL)}…` : line
+}
+
+/**
+ * The error a failed response deserves: status and host, plus at most the first
+ * line of the body. A whole body is an HTML error page or a megabyte of JSON,
+ * and pasting it into the dialog buries the one line that says what went wrong.
+ */
+export async function httpError(response: Response, url: string) {
+  const detail = firstLine(await response.text().catch(() => ''))
+  const status = `HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''} from ${hostOf(url)}`
+  return new Error(detail ? `${status}: ${detail}` : status)
+}
+
+/**
+ * `fetch` rejects with a bare `TypeError: Failed to fetch` for a DNS failure,
+ * an offline browser and a refused cross-origin request alike, naming neither
+ * the host nor the cause. Anything else — an abort, most notably — passes
+ * through untouched.
+ */
+export function networkError(url: string, cause: unknown) {
+  return cause instanceof TypeError
+    ? new Error(
+        `Could not reach ${hostOf(url)}. Check your network connection; the server may also be refusing cross-origin requests from this page.`,
+        { cause },
+      )
+    : cause
+}
+
+/**
+ * Request options plus the `fetch` to make the request with. Every network
+ * function here takes them, so a caller can hand in a host's instrumented
+ * fetch, a test double, or nothing at all and get `globalThis.fetch`. Resolved
+ * per call rather than captured at import, so a page that installs its fetch
+ * late is still honored.
+ */
+export interface FetchOptions extends RequestInit {
+  fetch?: typeof globalThis.fetch
+}
+
+export async function rawfetch(url: string, args?: FetchOptions) {
+  const { fetch: f = globalThis.fetch, ...init } = args ?? {}
+  try {
+    return await f(url, init)
+  } catch (e) {
+    throw networkError(url, e)
+  }
+}
+
+export async function myfetch(url: string, args?: FetchOptions) {
+  const response = await rawfetch(url, args)
+
+  if (!response.ok) {
+    throw await httpError(response, url)
+  }
+
+  return response
+}
+
+export async function jsonfetch<T = unknown>(
+  url: string,
+  args?: FetchOptions,
+): Promise<T> {
+  // The caller names the shape it expects; `Response.json` promises `any`, and
+  // narrowing it here rather than at the return keeps the body free of casts.
+  const response: { json: () => Promise<T> } = await myfetch(url, args)
+  return response.json()
+}
+
+/**
+ * An AbortSignal's reason as a real Error. `signal.reason` is `any` — usually a
+ * DOMException, but a caller can abort with anything at all — and throwing a
+ * non-Error loses the stack and breaks `instanceof Error` checks in the UI's
+ * error rendering. Normalize at every throw site.
+ */
+export function abortError(signal: AbortSignal) {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error('Aborted', { cause: signal.reason })
+}
+
+export function timeout(time: number, signal?: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal))
+    } else {
+      const id = setTimeout(resolve, time)
+      signal?.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(id)
+          reject(abortError(signal))
+        },
+        { once: true },
+      )
+    }
+  })
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+// Alignment
+export * from './types.ts'
+export * from './mappings.ts'
+export * from './pairwiseAlignment.ts'
+export * from './alignmentQuality.ts'
+
+// Coordinates
+export * from './coordinates.ts'
+export * from './invertMap.ts'
+export * from './stripStopCodon.ts'
+
+// Chain choice
+export * from './chooseMappedEntity.ts'
+export * from './extractStructureSequences.ts'
+export * from './extractPerResidueConfidence.ts'
+export * from './isoformRanking.ts'
+
+// SIFTS
+export * from './pdbUniProtMapping.ts'
+export * from './siftsNumbering.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'
+
+// Urls and formats
+export * from './structureUrls.ts'
+export * from './structureFormat.ts'
+export * from './caCoordsToPdb.ts'
+export * from './fetchUtils.ts'

package/src/invertMap.ts

@@ -0,0 +1,4 @@
+/** Swap keys and values of a numeric map, for reading a position map backwards. */
+export function invertMap(arg: Record<number, number>): Record<number, number> {
+  return Object.fromEntries(Object.entries(arg).map(([a, b]) => [b, +a]))
+}

package/src/isoformRanking.ts

@@ -0,0 +1,139 @@
+import { stripStopCodon } from './stripStopCodon.ts'
+import {
+  alignTranscriptToEntity,
+  chooseMappedEntity,
+} from './chooseMappedEntity.ts'
+
+/** A transcript isoform, named by whatever id the caller ranks by. `seq` is its
+ * translation, absent when none could be computed. */
+export interface Isoform {
+  id: string
+  seq?: string
+}
+
+export interface RankedIsoform {
+  id: string
+  length: number
+  /** identical residues against the structure, for an isoform that does not
+   * match it exactly; undefined with no structure to compare to */
+  identical?: number
+  /** that alignment's score, which is what ranks non-matching isoforms */
+  score?: number
+}
+
+export interface ClassifiedIsoforms {
+  // protein matches the structure residues, longest first
+  matches: RankedIsoform[]
+  // has a protein sequence but doesn't match the structure, best-aligning first
+  nonMatches: RankedIsoform[]
+  // ids of the isoforms no protein sequence could be computed for
+  noData: string[]
+}
+
+// The picker re-ranks on every render and each non-exact isoform costs an
+// O(len²) alignment, so results are cached by sequence pair: a titin-sized
+// isoform against a long chain is a second of main-thread work each time.
+const alignmentCache = new Map<string, { identical: number; score: number }>()
+const ALIGNMENT_CACHE_LIMIT = 200
+
+function alignToStructure(isoform: string, structure: string) {
+  const key = `${isoform}\n${structure}`
+  let result = alignmentCache.get(key)
+  if (result === undefined) {
+    const scored = alignTranscriptToEntity(isoform, structure, 'smith_waterman')
+    result = { identical: scored?.matches ?? 0, score: scored?.score ?? 0 }
+    if (alignmentCache.size >= ALIGNMENT_CACHE_LIMIT) {
+      alignmentCache.clear()
+    }
+    alignmentCache.set(key, result)
+  }
+  return result
+}
+
+/**
+ * The single rule for ranking transcript isoforms against a structure, shared
+ * by a picker UI and an auto-selection. An isoform whose translation is the
+ * structure's sequence wins outright. Among the rest, the best alignment score
+ * comes first, then the most identical residues, then length.
+ *
+ * The score has to lead: an isoform carrying an exon the structure lacks
+ * aligns every structure residue too, across a gap, so it ties on identical
+ * residues with the isoform the structure was made from (1MH1 against Rac1
+ * and Rac1b).
+ */
+export function classifyIsoforms({
+  isoforms,
+  structureSequence,
+}: {
+  isoforms: readonly Isoform[]
+  structureSequence?: string
+}): ClassifiedIsoforms {
+  const matches: RankedIsoform[] = []
+  const nonMatches: RankedIsoform[] = []
+  const noData: string[] = []
+  const structure = structureSequence
+    ? stripStopCodon(structureSequence)
+    : undefined
+  for (const { id, seq } of isoforms) {
+    if (seq === undefined) {
+      noData.push(id)
+    } else if (structure && stripStopCodon(seq) === structure) {
+      matches.push({ id, length: seq.length })
+    } else {
+      nonMatches.push({
+        id,
+        length: seq.length,
+        ...(structure ? alignToStructure(seq, structure) : {}),
+      })
+    }
+  }
+  const byLengthDesc = (a: RankedIsoform, b: RankedIsoform) =>
+    b.length - a.length
+  const byAlignmentThenLength = (a: RankedIsoform, b: RankedIsoform) =>
+    (b.score ?? 0) - (a.score ?? 0) ||
+    (b.identical ?? 0) - (a.identical ?? 0) ||
+    byLengthDesc(a, b)
+  return {
+    matches: matches.toSorted(byLengthDesc),
+    nonMatches: nonMatches.toSorted(byAlignmentThenLength),
+    noData,
+  }
+}
+
+/** The id of the isoform to open, by the ranking above. */
+export function selectBestTranscript(args: {
+  isoforms: readonly Isoform[]
+  structureSequence?: string
+}) {
+  const { matches, nonMatches } = classifyIsoforms(args)
+  return (matches[0] ?? nonMatches[0])?.id
+}
+
+/**
+ * Which of a structure's protein chains isoforms are compared against: one some
+ * isoform translates to exactly, else the chain `chooseMappedEntity` would map
+ * the longest isoform to, never simply the first (CDK2, on 1H26).
+ * `structureSequences` must hold protein chains only.
+ */
+export function pickStructureSequence(
+  structureSequences: string[] | undefined,
+  isoforms: readonly Isoform[] | undefined,
+): string | undefined {
+  const translations = (isoforms ?? []).flatMap(({ seq }) =>
+    seq === undefined ? [] : [stripStopCodon(seq)],
+  )
+  const translated = new Set(translations)
+  const exact = structureSequences?.find(s => translated.has(stripStopCodon(s)))
+  const longest = translations.reduce<string | undefined>(
+    (a, b) => (a !== undefined && a.length >= b.length ? a : b),
+    undefined,
+  )
+  const aligned =
+    structureSequences && longest
+      ? chooseMappedEntity(longest, structureSequences, 'smith_waterman')
+      : undefined
+  return (
+    exact ??
+    (aligned ? structureSequences?.[aligned.index] : structureSequences?.[0])
+  )
+}