p2s_mapper 1.0.0

package/src/structureSources.ts

@@ -0,0 +1,101 @@
+// 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
+// residue mapping.
+
+import { rawfetch } from './fetchUtils.ts'
+
+import type { FetchOptions } from './fetchUtils.ts'
+
+export interface ExperimentalStructure {
+  pdbId: string
+  method: string
+  /** Å; absent for NMR and some EM entries */
+  resolution?: number
+  /** 1-based inclusive UniProt residues the entry covers */
+  start: number
+  end: number
+  /** fraction of the UniProt sequence the entry covers, 0..1 */
+  coverage: number
+}
+
+export function beaconsSummaryUrl(uniprotId: string) {
+  return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json?provider=pdbe`
+}
+
+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
+}
+
+/**
+ * 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.
+ */
+export function parseExperimentalStructures(
+  json: unknown,
+): ExperimentalStructure[] {
+  const structures = isRecord(json) ? json.structures : undefined
+  if (!Array.isArray(structures)) {
+    return []
+  }
+  return structures
+    .flatMap(entry => {
+      const s = isRecord(entry) ? entry.summary : undefined
+      if (!isRecord(s)) {
+        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
+        ? [
+            {
+              pdbId: s.model_identifier.toLowerCase(),
+              method:
+                typeof s.experimental_method === 'string'
+                  ? s.experimental_method
+                  : 'experimental',
+              resolution: finiteNumber(s.resolution),
+              start,
+              end,
+              coverage,
+            },
+          ]
+        : []
+    })
+    .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. */
+export async function fetchExperimentalStructures(
+  uniprotId: string,
+  opts?: FetchOptions,
+): Promise<ExperimentalStructure[]> {
+  const res = await rawfetch(beaconsSummaryUrl(uniprotId), opts).catch(
+    () => undefined,
+  )
+  return res?.ok ? parseExperimentalStructures(await res.json()) : []
+}

package/src/structureUrls.ts

@@ -0,0 +1,171 @@
+// 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: string) {
+  return `https://rest.uniprot.org/uniprotkb/${uniprotId}.gff`
+}
+
+export function uniprotFastaUrl(uniprotId: string) {
+  return `https://rest.uniprot.org/uniprotkb/${uniprotId}.fasta`
+}
+
+export function uniprotEntryUrl(uniprotId: string) {
+  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: string,
+  version = ALPHAFOLD_VERSION,
+) {
+  return `https://alphafold.ebi.ac.uk/files/AF-${uniprotId}-F1-model_${version}.cif`
+}
+
+export function getPdbStructureUrl(pdbId: string) {
+  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,
+}: {
+  url?: string
+  data?: string
+  uniprotId?: string
+  pdbId?: string
+}) {
+  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: string) {
+  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: string) {
+  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: string) {
+  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: string, db: string) {
+  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: string) {
+  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,
+}: {
+  url?: string
+  data?: string
+  uniprotId?: string
+}) {
+  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
+}

package/src/types.ts

@@ -0,0 +1,30 @@
+export type AlignmentAlgorithm = 'needleman_wunsch' | 'smith_waterman'
+
+export const ALIGNMENT_ALGORITHMS = {
+  NEEDLEMAN_WUNSCH: 'needleman_wunsch',
+  SMITH_WATERMAN: 'smith_waterman',
+} as const
+
+export const DEFAULT_ALIGNMENT_ALGORITHM: AlignmentAlgorithm = 'smith_waterman'
+
+export const ALIGNMENT_ALGORITHM_VALUES: AlignmentAlgorithm[] = [
+  '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: string): AlignmentAlgorithm {
+  return (
+    ALIGNMENT_ALGORITHM_VALUES.find(v => v === value) ??
+    DEFAULT_ALIGNMENT_ALGORITHM
+  )
+}
+
+export const ALIGNMENT_ALGORITHM_LABELS: Record<AlignmentAlgorithm, string> = {
+  needleman_wunsch: 'Needleman-Wunsch',
+  smith_waterman: 'Smith-Waterman',
+}

package/src/uniProtSearch.ts

@@ -0,0 +1,212 @@
+import { jsonfetch } from './fetchUtils.ts'
+import {
+  buildUniProtXrefQuery,
+  isRecognizedDatabaseId,
+  stripTrailingVersion,
+} from './dbIds.ts'
+
+import type { FetchOptions } from './fetchUtils.ts'
+
+interface UniProtApiResult {
+  results: {
+    entryType: string
+    primaryAccession: string
+    uniProtkbId?: string
+    genes?: {
+      geneName?: {
+        value: string
+      }
+    }[]
+    organism?: {
+      taxonId: number
+      scientificName?: string
+      commonName?: string
+    }
+    proteinDescription?: {
+      recommendedName?: {
+        fullName?: {
+          value: string
+        }
+      }
+    }
+  }[]
+}
+
+export interface UniProtEntry {
+  accession: string
+  id?: string
+  geneName?: string
+  organismName?: string
+  proteinName?: string
+  isReviewed: boolean
+}
+
+const UNIPROT_FIELDS =
+  'accession,id,gene_names,organism_name,protein_name,reviewed'
+
+function mapApiResultToEntry(
+  result: UniProtApiResult['results'][0],
+): UniProtEntry {
+  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: string,
+  size: number,
+  opts?: FetchOptions,
+): Promise<UniProtEntry[]> {
+  const url = `https://rest.uniprot.org/uniprotkb/search?query=${encodeURIComponent(query)}&fields=${UNIPROT_FIELDS}&size=${size}`
+  const data = await jsonfetch<UniProtApiResult>(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: string, organismId?: number) {
+  return [
+    `gene_exact:"${geneName.replaceAll('"', '\\"')}"`,
+    organismId ? `organism_id:${organismId}` : undefined,
+    'reviewed:true',
+  ]
+    .filter(s => s !== undefined)
+    .join(' AND ')
+}
+
+interface SearchAttempt {
+  entries: UniProtEntry[]
+  error: unknown
+}
+
+async function searchByXref(
+  id: string,
+  opts?: FetchOptions,
+): Promise<SearchAttempt> {
+  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: string,
+  organismId: number | undefined,
+  opts?: FetchOptions,
+): Promise<SearchAttempt> {
+  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: UniProtEntry[]) {
+  const seen = new Set<string>()
+  const result: UniProtEntry[] = []
+  for (const entry of entries) {
+    if (!seen.has(entry.accession)) {
+      seen.add(entry.accession)
+      result.push(entry)
+    }
+  }
+  return result
+}
+
+export interface UniProtSearchResult {
+  entries: UniProtEntry[]
+  attemptedCount: number
+  failedCount: number
+}
+
+export async 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> {
+  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,
+  }
+}