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

package/src/protein/structure.ts

@@ -0,0 +1,491 @@
+/**
+ * What a parsed molecule *is*, and the three things derived from it that no
+ * coordinate file states outright: which atoms are bonded, which curve each
+ * chain traces, and how big the whole thing is.
+ *
+ * The shape here is the seam between the parser (`parse.ts`) and the node
+ * (`protein.ts`), and it is deliberately flat and numeric: parallel arrays of
+ * plain numbers rather than a graph of objects. A mid-sized structure is tens of
+ * thousands of atoms, the node rebuilds its command list every frame, and an
+ * object per atom would put a few hundred thousand allocations between the
+ * scrubber and the picture.
+ *
+ * Parsing happens **once, ahead of the build** — the same arrangement a chart's
+ * CSV gets (see `SceneAsset.rows`), and for the same reason: `buildScene` is
+ * synchronous, so anything that has to be read off a network or a file has to
+ * already be here by the time it runs.
+ */
+
+import { covalentRadius, traceAtomName, type ResidueKind } from "./chemistry"
+
+/** One atom, as the file gave it. Coordinates are in Ångströms. */
+export interface ProteinAtom {
+  /** The file's own serial number, kept so `CONECT` records can be resolved. */
+  serial: number
+  /** The atom's name within its residue — `CA`, `OG1`, `FE`. */
+  name: string
+  /** The element symbol, upper-cased. Derived when the file omits it. */
+  element: string
+  /** The residue's three-letter code — `ALA`, `HOH`, `HEM`. */
+  residue: string
+  /** The residue's number within its chain, as the file numbers it. */
+  residueSeq: number
+  /** The chain the residue belongs to — `A`, `B`, … */
+  chain: string
+  x: number
+  y: number
+  z: number
+  /** Whether the file filed this under `HETATM` — a ligand, an ion, a water. */
+  hetero: boolean
+  /** What the residue is, resolved once here so nothing downstream re-derives it. */
+  kind: ResidueKind
+}
+
+/**
+ * What a stretch of backbone is doing, which is the one property of a protein
+ * that a picture of it is usually *about*.
+ *
+ * Taken from the file's own `HELIX`/`SHEET` annotations rather than computed:
+ * assigning secondary structure from coordinates alone is DSSP, which is a
+ * hydrogen-bond model and a paper of its own. A file that annotates none draws
+ * as an even tube, which is the honest picture of "nobody said".
+ */
+export type SecondaryStructure = "helix" | "sheet" | "coil"
+
+/** One residue's place on a chain's backbone curve. */
+export interface TracePoint {
+  x: number
+  y: number
+  z: number
+  /** What this residue is part of, for the ribbon's shape and its colouring. */
+  secondary: SecondaryStructure
+  /**
+   * The residue's position along **this trace**, 0-based. Against the trace's
+   * own length this is what a spectrum colouring needs: N terminus to C
+   * terminus, per chain, independent of how long the others are.
+   */
+  index: number
+  /**
+   * The residue's number as the file gives it, which is what ties a trace point
+   * back to the atoms of the same residue.
+   *
+   * Both are needed and neither substitutes for the other: {@link index} is
+   * dense and ordered, so it is what a spectrum is computed against, while this
+   * is sparse and arbitrary — files skip numbers, start at 17, and number
+   * insertions — so it is what a *lookup* has to be keyed on.
+   */
+  residueSeq: number
+  /**
+   * Which way this residue's ribbon faces — the unit vector its **wide**
+   * direction is swept along.
+   *
+   * A tube needs a point and nothing else; a cartoon ribbon needs to know which
+   * way round it is, and that is not something a curve through α-carbons can
+   * answer. The residue's own carbonyl does: CA→O is roughly perpendicular to
+   * the chain and turns with the fold, so sweeping the ribbon's width along it
+   * is what makes a helix read as a twisted band and a strand as a flat one.
+   * This is the same vector every molecular viewer builds its cartoon frame
+   * from.
+   *
+   * `null` when the file has no carbonyl for the residue — a Cα-only model, a
+   * nucleotide, the last residue of a truncated chain — and the ribbon builder
+   * falls back to the curve's own binormal there. See `ribbonFrames`.
+   *
+   * Not orthogonalized here: it is a *direction*, and the frame that has to be
+   * square is built against the tangent, which only exists once the neighbours
+   * are known.
+   */
+  normal: { x: number; y: number; z: number } | null
+}
+
+/** One polymer chain: its identity and the curve its backbone follows. */
+export interface ProteinChain {
+  /** The chain identifier the file uses — `A`, `B`, … */
+  id: string
+  /** The α-carbon (or phosphorus) trace, in residue order. */
+  trace: TracePoint[]
+}
+
+/**
+ * A parsed molecule.
+ *
+ * Bonds and chains are *derived* (see {@link deriveStructure}) rather than read,
+ * because coordinate files mostly don't state them: `CONECT` records cover the
+ * ligands and little else, and the chain break between two residues is implied
+ * by their distance.
+ */
+export interface ProteinStructure {
+  /** The accession or filename this came from, for labelling. */
+  id: string
+  /** The file's `TITLE`, when it has one. */
+  title: string
+  atoms: ProteinAtom[]
+  /** Bonded pairs, as indices into {@link atoms}. */
+  bonds: ProteinBond[]
+  chains: ProteinChain[]
+  /** The centroid of every atom — what the node translates to the origin. */
+  center: { x: number; y: number; z: number }
+  /** Distance from {@link center} to the furthest atom, in Ångströms. */
+  radius: number
+}
+
+/** One bond, as a pair of indices into {@link ProteinStructure.atoms}. */
+export interface ProteinBond {
+  a: number
+  b: number
+}
+
+/** An empty molecule — what an unresolved or unparseable source draws as. */
+export const EMPTY_STRUCTURE: ProteinStructure = {
+  id: "",
+  title: "",
+  atoms: [],
+  bonds: [],
+  chains: [],
+  center: { x: 0, y: 0, z: 0 },
+  radius: 1,
+}
+
+/**
+ * A secondary-structure span as the file states it: a run of residue numbers on
+ * one chain. Collected by the parser, applied to the traces here.
+ */
+export interface SecondarySpan {
+  chain: string
+  start: number
+  end: number
+  kind: Exclude<SecondaryStructure, "coil">
+}
+
+/**
+ * Completes a parsed atom list into a {@link ProteinStructure}: infers the
+ * bonds, walks out each chain's backbone, and measures the whole thing.
+ *
+ * Split from the parsers because both formats reach the same place — an atom
+ * list and a set of annotated spans — and everything past that point is
+ * geometry rather than syntax.
+ */
+export function deriveStructure(
+  id: string,
+  title: string,
+  atoms: ProteinAtom[],
+  spans: SecondarySpan[]
+): ProteinStructure {
+  if (atoms.length === 0) return { ...EMPTY_STRUCTURE, id, title }
+
+  return {
+    id,
+    title,
+    atoms,
+    bonds: inferBonds(atoms),
+    chains: traceChains(atoms, spans),
+    ...measure(atoms),
+  }
+}
+
+// --- Bonds -----------------------------------------------------------------
+
+/**
+ * How much further apart than the sum of their covalent radii two atoms may sit
+ * and still count as bonded, in Ångströms.
+ *
+ * The conventional tolerance. It has to be generous enough to survive a
+ * moderate-resolution structure's coordinate error and mean enough not to bond
+ * a residue to the one packed against it — 0.45 Å is where every viewer has
+ * settled, and the gap between a real bond (~1.5 Å) and the closest non-bonded
+ * contact (~2.8 Å) is wide enough that the exact number rarely decides anything.
+ */
+const BOND_TOLERANCE = 0.45
+
+/**
+ * The shortest separation treated as a bond. Two atoms closer than this are
+ * alternate conformations of the same one, or a duplicate record — bonding them
+ * would draw a stick of no length and a mesh with no orientation.
+ */
+const MIN_BOND_LENGTH = 0.4
+
+/**
+ * The furthest two atoms can be bonded, which sets the neighbour grid's cell
+ * size: the largest pair of covalent radii here (potassium's, twice) plus the
+ * tolerance.
+ */
+const MAX_BOND_LENGTH = 2.5
+
+/**
+ * Infers bonds by distance, over a uniform grid.
+ *
+ * The grid is what makes this affordable. Bonding is a nearest-neighbour
+ * question and the naïve form is every atom against every other — 20,000 atoms
+ * is 200 million comparisons, which is a visible freeze on the frame someone
+ * picks a structure. Bucketed at the maximum bond length, each atom only looks
+ * at the 27 cells around it, and since the cells are that size no bond can span
+ * further, so nothing is missed. The work becomes linear in the atom count.
+ *
+ * Waters are skipped outright: they are a single oxygen with nothing to bond to
+ * (their hydrogens are almost never in the file), so every comparison against
+ * one is wasted, and there can be more of them than there are protein atoms.
+ */
+export function inferBonds(atoms: ProteinAtom[]): ProteinBond[] {
+  const bonds: ProteinBond[] = []
+  const cells = new Map<string, number[]>()
+  const radii = new Float32Array(atoms.length)
+
+  for (let i = 0; i < atoms.length; i++) {
+    const atom = atoms[i]!
+    if (atom.kind === "water") continue
+    radii[i] = covalentRadius(atom.element)
+    const key = cellKey(atom.x, atom.y, atom.z)
+    const bucket = cells.get(key)
+    if (bucket) bucket.push(i)
+    else cells.set(key, [i])
+  }
+
+  for (const [key, bucket] of cells) {
+    const [cx, cy, cz] = key.split(",").map(Number) as [number, number, number]
+
+    for (let dx = -1; dx <= 1; dx++) {
+      for (let dy = -1; dy <= 1; dy++) {
+        for (let dz = -1; dz <= 1; dz++) {
+          const neighbours = cells.get(`${cx + dx},${cy + dy},${cz + dz}`)
+          if (!neighbours) continue
+
+          for (const i of bucket) {
+            for (const j of neighbours) {
+              // Each unordered pair is reached from both cells, so keep only one
+              // ordering. This also excludes an atom against itself.
+              if (j <= i) continue
+              const a = atoms[i]!
+              const b = atoms[j]!
+              const limit = radii[i]! + radii[j]! + BOND_TOLERANCE
+              const dxx = a.x - b.x
+              const dyy = a.y - b.y
+              const dzz = a.z - b.z
+              const squared = dxx * dxx + dyy * dyy + dzz * dzz
+              if (squared > limit * limit) continue
+              if (squared < MIN_BOND_LENGTH * MIN_BOND_LENGTH) continue
+              bonds.push({ a: i, b: j })
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return bonds
+}
+
+/** The grid cell a coordinate falls in, as a map key. */
+function cellKey(x: number, y: number, z: number): string {
+  const cx = Math.floor(x / MAX_BOND_LENGTH)
+  const cy = Math.floor(y / MAX_BOND_LENGTH)
+  const cz = Math.floor(z / MAX_BOND_LENGTH)
+  return `${cx},${cy},${cz}`
+}
+
+// --- Chains ----------------------------------------------------------------
+
+/**
+ * How far apart two consecutive α-carbons may sit and still be the same chain,
+ * in Ångströms.
+ *
+ * Consecutive α-carbons are 3.8 Å apart — the distance is fixed by the peptide
+ * bond's geometry, not by what the protein is doing — so a larger gap is a
+ * *chain break*: a disordered loop the crystallographer could not resolve, which
+ * the file records by simply skipping those residues. Drawing through one would
+ * run a ribbon across the middle of the molecule between two ends that are not
+ * joined. Nucleotide phosphorus atoms sit further apart (~6 Å), which is why the
+ * threshold is well above 3.8 rather than snug against it.
+ */
+const CHAIN_BREAK_DISTANCE = 7.5
+
+/**
+ * The backbone curve of every chain, in residue order, with each residue's
+ * secondary structure attached.
+ *
+ * A chain break starts a **new trace** rather than being drawn through — see
+ * {@link CHAIN_BREAK_DISTANCE} — so one chain identifier can produce several
+ * entries. That is the right unit downstream anyway: each entry is one
+ * continuous curve, which is exactly what a tube is swept along.
+ */
+export function traceChains(
+  atoms: ProteinAtom[],
+  spans: SecondarySpan[]
+): ProteinChain[] {
+  const assign = secondaryLookup(spans)
+  // Built ahead of the walk rather than during it, because the carbonyl comes
+  // *after* the α-carbon in a residue's records and the trace point is written
+  // as the α-carbon is reached. One pass over the atoms costs nothing beside
+  // the bond inference already running over them.
+  const carbonyls = carbonylDirections(atoms)
+  const chains: ProteinChain[] = []
+
+  let current: ProteinChain | null = null
+  let previous: ProteinAtom | null = null
+
+  for (const atom of atoms) {
+    if (atom.name !== traceAtomName(atom.kind)) continue
+
+    const broken =
+      previous !== null &&
+      (previous.chain !== atom.chain ||
+        distance(previous, atom) > CHAIN_BREAK_DISTANCE)
+
+    if (current === null || broken) {
+      current = { id: atom.chain, trace: [] }
+      chains.push(current)
+    }
+
+    current.trace.push({
+      x: atom.x,
+      y: atom.y,
+      z: atom.z,
+      secondary: assign(atom.chain, atom.residueSeq),
+      index: current.trace.length,
+      residueSeq: atom.residueSeq,
+      normal: carbonyls.get(residueKey(atom)) ?? null,
+    })
+    previous = atom
+  }
+
+  // A single point is not a curve — nothing can be swept along it and no
+  // direction can be taken from it — so a lone resolved residue is dropped
+  // rather than left for the tube builder to divide by zero over.
+  return chains.filter((chain) => chain.trace.length > 1)
+}
+
+/**
+ * Builds the residue → secondary-structure lookup.
+ *
+ * A map per chain of residue number to kind, rather than a scan of the span list
+ * per residue: a large structure has thousands of residues and hundreds of
+ * spans, and the product of the two is the sort of quiet quadratic that only
+ * shows up on the file somebody actually cares about.
+ */
+function secondaryLookup(
+  spans: SecondarySpan[]
+): (chain: string, residue: number) => SecondaryStructure {
+  const byChain = new Map<string, Map<number, SecondaryStructure>>()
+
+  for (const span of spans) {
+    let residues = byChain.get(span.chain)
+    if (!residues) {
+      residues = new Map()
+      byChain.set(span.chain, residues)
+    }
+    // A malformed span (end before start, or one covering the whole file) would
+    // otherwise fill the map with junk; the loop simply doesn't run backwards.
+    for (let seq = span.start; seq <= span.end; seq++) {
+      residues.set(seq, span.kind)
+    }
+  }
+
+  return (chain, residue) => byChain.get(chain)?.get(residue) ?? "coil"
+}
+
+/** A residue's identity across the whole file — its chain and its number. */
+function residueKey(atom: ProteinAtom): string {
+  return `${atom.chain}:${atom.residueSeq}`
+}
+
+/**
+ * The unit CA→O vector of every amino-acid residue that has both atoms.
+ *
+ * This is the one piece of chemistry a *cartoon* needs and a tube does not. A
+ * ribbon has a width, so it has a side, and nothing about a curve through
+ * α-carbons says which way round it should be: sweep a flat band along that
+ * curve with an arbitrary frame and a helix comes out as a twisted ribbon in
+ * the wrong plane, its face turning at random rather than with the fold.
+ *
+ * The carbonyl is what every molecular viewer resolves that with. It points
+ * roughly across the chain, it is what hydrogen-bonds a helix to itself and a
+ * strand to its neighbour, and so it turns *with* the structure — which makes a
+ * band swept along it lie the way the fold does.
+ *
+ * Amino acids only. A nucleotide's ribbon has no equivalent (its trace atom is
+ * the phosphorus and its "width" is the base pair), and a residue whose file
+ * gives no `O` — a Cα-only model, a truncated terminus — simply has no entry;
+ * both fall back to the curve's own binormal in the ribbon builder.
+ */
+function carbonylDirections(
+  atoms: ProteinAtom[]
+): Map<string, { x: number; y: number; z: number }> {
+  const alpha = new Map<string, ProteinAtom>()
+  const oxygen = new Map<string, ProteinAtom>()
+
+  for (const atom of atoms) {
+    if (atom.kind !== "amino") continue
+    // The first record of each name wins, which is what picks conformation A
+    // out of a residue the file gives two of: alternates are written in order
+    // and the ribbon needs one frame, not an average of two.
+    if (atom.name === "CA") {
+      if (!alpha.has(residueKey(atom))) alpha.set(residueKey(atom), atom)
+    } else if (atom.name === "O") {
+      if (!oxygen.has(residueKey(atom))) oxygen.set(residueKey(atom), atom)
+    }
+  }
+
+  const directions = new Map<string, { x: number; y: number; z: number }>()
+  for (const [key, ca] of alpha) {
+    const o = oxygen.get(key)
+    if (!o) continue
+    const x = o.x - ca.x
+    const y = o.y - ca.y
+    const z = o.z - ca.z
+    const length = Math.hypot(x, y, z)
+    // A zero-length carbonyl is a duplicated record rather than a direction.
+    if (length < 1e-6) continue
+    directions.set(key, { x: x / length, y: y / length, z: z / length })
+  }
+  return directions
+}
+
+/** Straight-line distance between two atoms, in Ångströms. */
+function distance(a: ProteinAtom, b: ProteinAtom): number {
+  return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z)
+}
+
+// --- Bounds ----------------------------------------------------------------
+
+/**
+ * The molecule's centroid and the radius of the sphere about it that holds every
+ * atom.
+ *
+ * The centroid rather than the centre of the bounding box: a structure with one
+ * long tail — a coiled-coil, a nucleic acid strand hanging off a complex —
+ * has a box whose centre is nowhere near the mass of it, and the camera would
+ * frame the empty half.
+ *
+ * The radius is floored above zero so a single-atom file (or one whose
+ * coordinates are all identical) still gives the camera a distance to work from
+ * rather than parking it inside the atom.
+ */
+function measure(atoms: ProteinAtom[]): {
+  center: { x: number; y: number; z: number }
+  radius: number
+} {
+  let sx = 0
+  let sy = 0
+  let sz = 0
+  for (const atom of atoms) {
+    sx += atom.x
+    sy += atom.y
+    sz += atom.z
+  }
+  const center = {
+    x: sx / atoms.length,
+    y: sy / atoms.length,
+    z: sz / atoms.length,
+  }
+
+  let radius = 0
+  for (const atom of atoms) {
+    const d = Math.hypot(
+      atom.x - center.x,
+      atom.y - center.y,
+      atom.z - center.z
+    )
+    if (d > radius) radius = d
+  }
+
+  return { center, radius: Math.max(radius, 1) }
+}

package/README.md

@@ -1,4 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.