@motionscript/molecule 0.0.0-stage → 0.1.0-alpha.0

package/src/protein/parse.ts

@@ -0,0 +1,427 @@
+/**
+ * Reads a coordinate file into a {@link ProteinStructure}.
+ *
+ * Two formats, because the Protein Data Bank serves two and which one an entry
+ * has is not the author's choice: the legacy **PDB** format numbers atoms in
+ * five columns and names chains in one, so an entry that outgrew either — a
+ * ribosome, a capsid — exists only as **mmCIF**. Refusing the second would mean
+ * refusing exactly the structures most worth looking at.
+ *
+ * Both are read the same way: pull out an atom list and whatever secondary
+ * structure the file annotates, then hand both to `deriveStructure`, which does
+ * the geometry. {@link parseStructure} sniffs which is which, so a caller
+ * holding a downloaded file never has to.
+ *
+ * **The first model only.** An NMR ensemble is twenty superposed conformations
+ * of the same molecule; drawing all of them at once produces a blur, and
+ * choosing between them is a question this node does not ask. The first is the
+ * conventional representative.
+ */
+
+import { elementOf, residueKind } from "./chemistry"
+import {
+  deriveStructure,
+  EMPTY_STRUCTURE,
+  type ProteinAtom,
+  type ProteinStructure,
+  type SecondarySpan,
+} from "./structure"
+
+/**
+ * Reads a coordinate file, detecting its format from the contents.
+ *
+ * `id` labels the result — an accession, or the asset's name. Anything that
+ * can't be read at all comes back as {@link EMPTY_STRUCTURE} rather than
+ * throwing: this runs against a file someone just uploaded or an accession
+ * someone is halfway through typing, and both of those are ordinary states
+ * rather than errors. An empty structure draws nothing, which is the honest
+ * picture of a file with no atoms in it.
+ */
+export function parseStructure(text: string, id = ""): ProteinStructure {
+  if (typeof text !== "string" || text.trim() === "") {
+    return { ...EMPTY_STRUCTURE, id }
+  }
+  return isMmcif(text) ? parseMmcif(text, id) : parsePdb(text, id)
+}
+
+/**
+ * Whether a file is mmCIF.
+ *
+ * The `data_` block header is mmCIF's first line and appears in no PDB file, so
+ * it decides on its own — but only over the first stretch, since `data_` is also
+ * an ordinary substring that could turn up in a PDB `REMARK`. The category
+ * prefix is the belt-and-braces check for a fragment handed over without its
+ * header.
+ */
+function isMmcif(text: string): boolean {
+  const head = text.slice(0, 4096)
+  return /^\s*data_/.test(head) || head.includes("_atom_site.")
+}
+
+// --- PDB -------------------------------------------------------------------
+
+/**
+ * Reads the legacy PDB format, which is **fixed-column**: every field is at a
+ * known offset and the whitespace between them is padding rather than a
+ * separator. Splitting on spaces is the classic way to get this wrong — a
+ * residue number that runs into its insertion code, or a `-` sign that eats the
+ * gap between two coordinates, and the record silently comes apart.
+ *
+ * Columns, 1-based as the specification numbers them:
+ *
+ *     7–11  serial     13–16 name      18–20 resName   22 chainID
+ *     23–26 resSeq     31–38 x         39–46 y         47–54 z
+ *     77–78 element
+ */
+function parsePdb(text: string, id: string): ProteinStructure {
+  const atoms: ProteinAtom[] = []
+  const spans: SecondarySpan[] = []
+  let title = ""
+
+  for (const line of text.split("\n")) {
+    const record = line.slice(0, 6).trim()
+
+    // Everything after the first `ENDMDL` is another conformation of what we
+    // already have. Stopping at it rather than filtering by model number also
+    // ends the read early on a large ensemble.
+    if (record === "ENDMDL") break
+
+    if (record === "ATOM" || record === "HETATM") {
+      const atom = parsePdbAtom(line, record === "HETATM")
+      if (atom) atoms.push(atom)
+      continue
+    }
+
+    if (record === "TITLE") {
+      // A long title is continued across several records, with the continuation
+      // number in columns 9–10 and the text always from column 11.
+      title = `${title} ${line.slice(10).trim()}`.trim()
+      continue
+    }
+
+    // The two annotation records. Their first-residue fields sit at *different*
+    // offsets from each other — a genuine wart of the format rather than a
+    // mistake here — while their last-residue fields agree.
+    if (record === "HELIX") {
+      const span = pdbSpan(line, 19, 21, "helix")
+      if (span) spans.push(span)
+      continue
+    }
+    if (record === "SHEET") {
+      const span = pdbSpan(line, 21, 22, "sheet")
+      if (span) spans.push(span)
+    }
+  }
+
+  return deriveStructure(id, title, atoms, spans)
+}
+
+/** One `ATOM`/`HETATM` record, or `null` when its coordinates don't read. */
+function parsePdbAtom(line: string, hetero: boolean): ProteinAtom | null {
+  // Truncated before the coordinates. Worth checking outright: a short slice of
+  // a fixed-column record reads as the empty string, and `Number("")` is 0
+  // rather than `NaN` — so without this a mangled line becomes an atom sitting
+  // at the origin, which is far harder to notice than a missing one.
+  if (line.length < 54) return null
+
+  // An alternate location: the same atom modelled twice because the side chain
+  // is disordered. Keeping both would double the sticks through that residue,
+  // so take the first (blank or `A`), which is the convention.
+  const altLoc = line.slice(16, 17).trim()
+  if (altLoc !== "" && altLoc !== "A") return null
+
+  const x = Number(line.slice(30, 38))
+  const y = Number(line.slice(38, 46))
+  const z = Number(line.slice(46, 54))
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
+    return null
+  }
+
+  const name = line.slice(12, 16).trim()
+  const residue = line.slice(17, 20).trim()
+  const kind = residueKind(residue)
+
+  return {
+    serial: Number(line.slice(6, 11)) || 0,
+    name,
+    element: elementOf(line.slice(76, 78), name, kind),
+    residue,
+    residueSeq: Number(line.slice(22, 26)) || 0,
+    // A file with a single unnamed chain leaves the column blank; calling that
+    // `A` keeps "group by chain" from producing one group named nothing.
+    chain: line.slice(21, 22).trim() || "A",
+    x,
+    y,
+    z,
+    hetero,
+    kind,
+  }
+}
+
+/** Where the last residue's number sits on both `HELIX` and `SHEET` — columns 34–37. */
+const PDB_SPAN_END_AT = 33
+
+/**
+ * One `HELIX`/`SHEET` record as a residue span.
+ *
+ * The first-residue offsets differ between the two records, so they are passed
+ * in rather than hard-coded: a helix names its chain in column 20 and its first
+ * residue in 22–25, a sheet names its chain in 22 and its first residue in
+ * 23–26. Their *last* residue is in the same place in both, which is the one
+ * thing they agree on.
+ */
+function pdbSpan(
+  line: string,
+  chainAt: number,
+  startAt: number,
+  kind: SecondarySpan["kind"]
+): SecondarySpan | null {
+  const chain = line.slice(chainAt, chainAt + 1).trim() || "A"
+  // Read as text first: a blank fixed-column field slices to `""`, and
+  // `Number("")` is 0, so a `Number.isFinite` check alone would accept a record
+  // that states nothing as a span over residue 0.
+  const startText = line.slice(startAt, startAt + 4).trim()
+  const endText = line.slice(PDB_SPAN_END_AT, PDB_SPAN_END_AT + 4).trim()
+  if (startText === "" || endText === "") return null
+
+  const start = Number(startText)
+  const end = Number(endText)
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null
+  return { chain, start, end, kind }
+}
+
+// --- mmCIF -----------------------------------------------------------------
+
+/**
+ * Reads mmCIF, which is a tagged format rather than a positional one: values are
+ * whitespace-separated and their meaning comes from the column headers declared
+ * above them, so the reader has to learn the layout before it can read a row.
+ *
+ * Only three categories are consulted — the atoms, and the two that annotate
+ * secondary structure. mmCIF carries dozens more, and every one this doesn't
+ * read is one this can't be broken by.
+ */
+function parseMmcif(text: string, id: string): ProteinStructure {
+  const lines = text.split("\n")
+  const atoms = mmcifAtoms(lines)
+  const spans = [
+    ...mmcifSpans(lines, "_struct_conf", "helix"),
+    ...mmcifSpans(lines, "_struct_sheet_range", "sheet"),
+  ]
+  return deriveStructure(id, mmcifTitle(lines), atoms, spans)
+}
+
+/** The atoms of the first model in an `_atom_site` loop. */
+function mmcifAtoms(lines: string[]): ProteinAtom[] {
+  const atoms: ProteinAtom[] = []
+  let model: string | null = null
+
+  for (const row of mmcifRows(lines, "_atom_site")) {
+    // `auth_*` is the numbering the literature uses and the one a PDB file would
+    // have carried; `label_*` is the internal, re-derived scheme. Preferring
+    // auth means a residue number quoted in a paper matches what is drawn, and
+    // falling back keeps a file that omits it readable.
+    const chain = row("auth_asym_id") || row("label_asym_id") || "A"
+    const residue = row("auth_comp_id") || row("label_comp_id")
+    const name = row("auth_atom_id") || row("label_atom_id")
+
+    const thisModel = row("pdbx_PDB_model_num")
+    if (model === null) model = thisModel
+    else if (thisModel !== model) break
+
+    const altLoc = row("label_alt_id")
+    if (altLoc !== "" && altLoc !== "." && altLoc !== "?" && altLoc !== "A") {
+      continue
+    }
+
+    const x = Number(row("Cartn_x"))
+    const y = Number(row("Cartn_y"))
+    const z = Number(row("Cartn_z"))
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
+      continue
+    }
+
+    const kind = residueKind(residue)
+    atoms.push({
+      serial: Number(row("id")) || 0,
+      name,
+      element: elementOf(row("type_symbol"), name, kind),
+      residue,
+      residueSeq: Number(row("auth_seq_id") || row("label_seq_id")) || 0,
+      chain,
+      x,
+      y,
+      z,
+      hetero: row("group_PDB") === "HETATM",
+      kind,
+    })
+  }
+
+  return atoms
+}
+
+/** The residue spans of one annotation category. */
+function mmcifSpans(
+  lines: string[],
+  category: string,
+  kind: SecondarySpan["kind"]
+): SecondarySpan[] {
+  const spans: SecondarySpan[] = []
+
+  for (const row of mmcifRows(lines, category)) {
+    // `_struct_conf` covers turns and bends as well as helices, all under one
+    // category and told apart by this tag. A sheet range has no such tag, so an
+    // absent one passes.
+    const type = row("conf_type_id")
+    if (type !== "" && !type.startsWith("HELX")) continue
+
+    const chain = row("beg_auth_asym_id") || row("beg_label_asym_id") || "A"
+    const start = Number(row("beg_auth_seq_id") || row("beg_label_seq_id"))
+    const end = Number(row("end_auth_seq_id") || row("end_label_seq_id"))
+    if (!Number.isFinite(start) || !Number.isFinite(end)) continue
+    spans.push({ chain, start, end, kind })
+  }
+
+  return spans
+}
+
+/** The entry's title, from the `_struct.title` item. */
+function mmcifTitle(lines: string[]): string {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (!line.startsWith("_struct.title")) continue
+    const inline = line.slice("_struct.title".length).trim()
+    // A value too long for the line is carried on the next one, or in a
+    // semicolon-delimited block below it; the inline form covers the rest.
+    if (inline !== "") return unquote(inline)
+    const next = lines[i + 1]?.trim() ?? ""
+    return unquote(next.startsWith(";") ? next.slice(1) : next)
+  }
+  return ""
+}
+
+/**
+ * Walks the rows of one mmCIF category, yielding a field reader for each.
+ *
+ * The reader is a closure over the current row rather than an object, so
+ * nothing allocates a record per atom — this runs over hundreds of thousands of
+ * rows on a large entry, and the caller only ever wants a handful of the fields.
+ *
+ * Handles both forms a category takes: a `loop_` with a header block and many
+ * rows, and the flat `_category.field value` form mmCIF uses when there is
+ * exactly one row.
+ */
+function* mmcifRows(
+  lines: string[],
+  category: string
+): Generator<(field: string) => string> {
+  const prefix = `${category}.`
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!.trim()
+
+    // The flat, single-row form: consecutive `_category.field value` lines.
+    if (line.startsWith(prefix)) {
+      const single = new Map<string, string>()
+      while (i < lines.length) {
+        const item = lines[i]!.trim()
+        if (!item.startsWith(prefix)) break
+        const gap = item.search(/\s/)
+        if (gap === -1) {
+          // A field whose value is on the following line.
+          single.set(item.slice(prefix.length), unquote(lines[++i]?.trim() ?? ""))
+        } else {
+          single.set(
+            item.slice(prefix.length, gap),
+            unquote(item.slice(gap).trim())
+          )
+        }
+        i++
+      }
+      yield (field) => single.get(field) ?? ""
+      return
+    }
+
+    if (line !== "loop_") continue
+
+    // The header block: every `_category.field` line, in the order the values
+    // will arrive in.
+    const columns = new Map<string, number>()
+    let cursor = i + 1
+    while (cursor < lines.length) {
+      const header = lines[cursor]!.trim()
+      if (!header.startsWith("_")) break
+      if (header.startsWith(prefix)) {
+        columns.set(header.slice(prefix.length), columns.size)
+      }
+      cursor++
+    }
+    // A `loop_` for some other category. Its rows carry no leading underscore
+    // and aren't `loop_`, so the outer scan walks past them harmlessly.
+    if (columns.size === 0) continue
+
+    for (; cursor < lines.length; cursor++) {
+      const row = lines[cursor]!
+      const trimmed = row.trim()
+      // A loop ends at the next block, the next loop, or a blank line.
+      if (trimmed === "" || trimmed === "#" || trimmed.startsWith("_")) break
+      if (trimmed === "loop_" || trimmed.startsWith("data_")) break
+
+      const values = splitCifRow(trimmed)
+      yield (field) => {
+        const index = columns.get(field)
+        if (index === undefined) return ""
+        const value = values[index] ?? ""
+        return value === "." || value === "?" ? "" : value
+      }
+    }
+    return
+  }
+}
+
+/**
+ * Splits one mmCIF row into values, respecting quotes.
+ *
+ * Quoting is not decoration here: a chain identifier can be `'A'`, and a residue
+ * name can contain a space that a plain `split` would turn into two columns and
+ * shift every field after it by one.
+ */
+function splitCifRow(row: string): string[] {
+  const values: string[] = []
+  let i = 0
+
+  while (i < row.length) {
+    const char = row[i]!
+    if (char === " " || char === "\t") {
+      i++
+      continue
+    }
+    if (char === "'" || char === '"') {
+      const end = row.indexOf(char, i + 1)
+      if (end === -1) {
+        values.push(row.slice(i + 1))
+        break
+      }
+      values.push(row.slice(i + 1, end))
+      i = end + 1
+      continue
+    }
+    let end = i
+    while (end < row.length && row[end] !== " " && row[end] !== "\t") end++
+    values.push(row.slice(i, end))
+    i = end
+  }
+
+  return values
+}
+
+/** Strips the quotes mmCIF wraps a value in, and the null placeholders. */
+function unquote(value: string): string {
+  const text = value.trim()
+  if (text === "." || text === "?") return ""
+  const first = text[0]
+  if ((first === "'" || first === '"') && text.endsWith(first) && text.length > 1) {
+    return text.slice(1, -1)
+  }
+  return text
+}