app/kb/registry/align.mjs

Functions

Imports

It imports app/kb/registry/reference.mjs, app/kb/registry/references.generated.mjs, app/lib/primers.mjs. Imported by app/components/lab.tsx, app/components/procedure-primers.tsx, app/kb/procedures/render.mjs, app/kb/registry/catalog.mjs.

Source

1// Placing a primer on a reference, and the product a pair makes there (docs/REGISTRY.md): COMPUTED by the primer code in
2// app/lib/primers.mjs (findSites, amplicons), whose tests hold it to hand-worked cases, and never copied from a paper or a
3// database. A primer is looked for exactly first, then with one mismatch more at a time up to MAX_MISMATCHES, and the first
4// level that finds it is the answer, with its mismatches reported. A primer that binds only with a mismatch is therefore
5// shown with the mismatch, never silently absorbed, and a primer that binds nowhere within the limit has no placement.
6//
7// Coordinates are the accession's own: a slice of a chromosome (`NC_052532.1:76902320-76906237`) is reported on the
8// chromosome, so a reader can check a position against the record at NCBI.
9
10import { amplicons, findSites } from "../../lib/primers.mjs";
11import { accessionPosition } from "./reference.mjs";
12import { REFERENCES } from "./references.generated.mjs";
13
14/** The most mismatches a primer may have against a reference and still be placed. A primer is 16 to 30 bases. */
15export const MAX_MISMATCHES = 4;
16/** A product longer than this is not a PCR product here; the registry's references are short or the primers sit close. */
17const MAX_PRODUCT = 5000;
18
19/**
20 * @typedef {import("./reference.mjs").Reference} Reference
21 * @typedef {{
22 *   strand: "+" | "-",
23 *   start: number,
24 *   end: number,
25 *   mismatches: number,
26 *   mismatchPositions: number[],
27 * }} Placed
28 * A site in the accession's own coordinates; `mismatchPositions` are 1-based from the primer's 5' end.
29 *
30 * @typedef {{ reference: { id: string, accession: string, description: string }, sites: Placed[], mismatches: number }} Placement
31 * @typedef {{
32 *   length: number,
33 *   start: number,
34 *   end: number,
35 *   forward: Placed,
36 *   reverse: Placed,
37 * }} Product
38 */
39
40/** The reference an id names, or null. @param {string} id @param {Record<string, Reference>} [references] */
41function referenceFor(id, references = /** @type {any} */ (REFERENCES)) {
42  const found = references[id];
43  return found ? parseReferenceShape(found) : null;
44}
45
46/** The generated module's entries are already parsed; this keeps the type and refuses a malformed one. @param {any} entry @returns {Reference} */
47function parseReferenceShape(entry) {
48  if (typeof entry?.sequence !== "string" || typeof entry?.id !== "string") throw new Error("a reference in references.generated.mjs is malformed");
49  return entry;
50}
51
52/** @param {Reference} reference @param {import("../../lib/primers.mjs").Site} site @returns {Placed} */
53function placed(reference, site) {
54  return {
55    strand: site.strand,
56    start: accessionPosition(reference, site.start),
57    end: accessionPosition(reference, site.end),
58    mismatches: site.mismatches,
59    mismatchPositions: site.mismatchPositions,
60  };
61}
62
63/**
64 * Where a primer binds a reference: every site at the fewest mismatches that finds one.
65 *
66 * @param {string} sequence the primer, 5' to 3', A, C, G and T only
67 * @param {string} referenceId
68 * @param {Record<string, Reference>} [references]
69 * @returns {Placement | null} null when the reference is unknown or the primer binds nowhere within MAX_MISMATCHES
70 */
71export function placePrimer(sequence, referenceId, references = /** @type {any} */ (REFERENCES)) {
72  const reference = referenceFor(referenceId, references);
73  if (!reference || !/^[ACGT]+$/.test(sequence)) return null;
74  for (let mismatches = 0; mismatches <= MAX_MISMATCHES; mismatches += 1) {
75    const sites = findSites(reference.sequence, sequence, { maxMismatches: mismatches }).filter((s) => s.mismatches === mismatches);
76    if (sites.length > 0) {
77      return {
78        reference: { id: reference.id, accession: reference.accession, description: reference.description },
79        sites: sites.map((site) => placed(reference, site)),
80        mismatches,
81      };
82    }
83  }
84  return null;
85}
86
87/**
88 * The products a forward and a reverse primer make on a reference, each at the fewest mismatches either needs, shortest
89 * first. A pair that makes none, or whose primers do not both place, has no product.
90 *
91 * @param {string} forward
92 * @param {string} reverse
93 * @param {string} referenceId
94 * @param {Record<string, Reference>} [references]
95 * @returns {{ reference: Placement["reference"], products: Product[] } | null}
96 */
97export function pairProducts(forward, reverse, referenceId, references = /** @type {any} */ (REFERENCES)) {
98  const reference = referenceFor(referenceId, references);
99  const f = placePrimer(forward, referenceId, references);
100  const r = placePrimer(reverse, referenceId, references);
101  if (!reference || !f || !r) return null;
102  const level = Math.max(f.mismatches, r.mismatches);
103  const found = amplicons(reference.sequence, forward, reverse, { maxMismatches: level, maxLength: MAX_PRODUCT })
104    // Only the sites each primer was placed at: a product that used a worse site than the best is not the pair's.
105    .filter((p) => p.forward.mismatches === f.mismatches && p.reverse.mismatches === r.mismatches)
106    .map((p) => ({
107      length: p.length,
108      start: accessionPosition(reference, p.start),
109      end: accessionPosition(reference, p.end),
110      forward: placed(reference, p.forward),
111      reverse: placed(reference, p.reverse),
112    }))
113    .sort((a, b) => a.length - b.length || a.start - b.start);
114  return found.length === 0 ? null : { reference: f.reference, products: found };
115}
116
117
118/**
119 * The products a protocol's primers make, computed, for the primer table of a page, sheet or twin: each set that holds one
120 * forward and one reverse primer on one reference gives its pair's products, keyed by the id of both primers. A row with no
121 * mate, no reference or no placement has no entry.
122 *
123 * @param {Array<{ id: string, set: string | null, direction: string | null, sequence: string | null, reference: string | null }>} rows
124 * @returns {Map<string, { reference: Placement["reference"], products: Product[] }>}
125 */
126export function productsForRows(rows) {
127  /** @type {Map<string, { reference: Placement["reference"], products: Product[] }>} */
128  const out = new Map();
129  const sets = new Set(rows.flatMap((row) => (row.set ? [row.set] : [])));
130  for (const set of sets) {
131    const inSet = rows.filter((row) => row.set === set);
132    const forward = inSet.find((row) => row.direction === "forward");
133    const reverse = inSet.find((row) => row.direction === "reverse");
134    if (!forward?.sequence || !reverse?.sequence || !forward.reference || forward.reference !== reverse.reference) continue;
135    const pair = pairProducts(forward.sequence, reverse.sequence, forward.reference);
136    if (pair) {
137      out.set(forward.id, pair);
138      out.set(reverse.id, pair);
139    }
140  }
141  return out;
142}