app/kb/registry/primer.mjs

Functions

Imports

It imports app/kb/registry/references.generated.mjs, app/kb/registry/tm.mjs. Imported by app/components/procedure-primers.tsx, app/kb/registry/catalog.mjs, app/kb/registry/host.server.ts, app/kb/registry/kinds.mjs, app/kb/registry/search-inputs.mjs, app/kb/registry/strain.mjs.

Source

1// The primer kind of the lab registry (docs/REGISTRY.md). A primer record states what the lab's protocols state about one
2// oligo (its sequence as stored, its direction, the set it works in and what that set targets) and what the literature says
3// about it, as read: the paper that prints it, that paper's own name for it, the sequence the paper prints, the product size
4// the paper states, and the reference sequence the primer is placed on.
5//
6// Anything not stored is COMPUTED and so cannot drift: its length, GC content, Tm and reverse complement come from the
7// sequence (tm.mjs, primers.mjs); its position, strand and mismatches on the reference, and a pair's product, come from the
8// reference by tested code (align.mjs); whether the stored sequence matches the printed one is a comparison, not a field; and
9// the protocols that use it are found from the protocols, which name their primers by id.
10//
11// A fact nobody could read is written "MISSING: <why>" with the reason (paywalled, not stated), never filled from memory or
12// inferred. A sequence that DIFFERS from the one a paper prints is shown as differing on its page and listed by
13// check:content; it is never corrected silently, and the decision to change it is the seat's.
14
15import { REFERENCES } from "./references.generated.mjs";
16import { primerTmRounded } from "./tm.mjs";
17
18/** An upper-case IUPAC nucleotide sequence, as the protocols write one. */
19const SEQUENCE = /^[ACGTRYSWKMBDHVN]+$/;
20const PRIMER_MIN_LENGTH = 10;
21const PRIMER_MAX_LENGTH = 80;
22const DIRECTIONS = /** @type {const} */ (["forward", "reverse", "probe"]);
23/** A product as a paper states it: a size in base pairs, "about" when the paper says so. */
24const PRODUCT = /^(?:about )?[1-9][0-9]{1,4} bp$/;
25const DOI = /^10\.[0-9]{4,9}\/[^\s]+$/;
26const LINE = /^[^\r\n]+$/;
27
28/** @param {unknown} value @param {number} max */
29const oneLine = (value, max) =>
30  typeof value === "string" && LINE.test(value) && value === value.trim() && value.length <= max ? null : `is one line of at most ${max} characters`;
31
32/** @param {unknown} value */
33const sequenceCheck = (value) =>
34  typeof value !== "string" || !SEQUENCE.test(value)
35    ? "is an upper-case IUPAC nucleotide sequence, written 5' to 3'"
36    : value.length < PRIMER_MIN_LENGTH || value.length > PRIMER_MAX_LENGTH
37      ? `is ${PRIMER_MIN_LENGTH} to ${PRIMER_MAX_LENGTH} bases`
38      : null;
39
40/** @type {import("./kinds.mjs").KindSpec} */
41export const PRIMER = {
42  singular: "primer",
43  plural: "primers",
44  fields: {
45    sequence: { required: true, check: sequenceCheck },
46    direction: {
47      required: true,
48      check: (value) => (DIRECTIONS.includes(/** @type {any} */ (value)) ? null : `is ${DIRECTIONS.join(", ")} or MISSING`),
49    },
50    target: { required: true, check: (value) => oneLine(value, 120) },
51    set: { check: (value) => oneLine(value, 120) },
52    // The reference the primer is placed on: a file in data/references (docs/REGISTRY.md), named by its GenBank id.
53    reference: {
54      check: (value) =>
55        typeof value === "string" && Object.hasOwn(REFERENCES, value)
56          ? null
57          : `is the id of a reference in data/references: ${Object.keys(REFERENCES).join(", ")}`,
58    },
59    // The literature, as read. Each is the paper's own words or MISSING with the reason it could not be read.
60    published_in: { required: true, check: (value) => oneLine(value, 200) },
61    published_doi: { check: (value) => (typeof value === "string" && DOI.test(value) ? null : "is a DOI, such as 10.1371/journal.pone.0099678") },
62    published_url: { check: (value) => (typeof value === "string" && /^https:\/\/[^\s]+$/.test(value) ? null : "is an https address") },
63    published_name: { required: true, check: (value) => oneLine(value, 120) },
64    published_sequence: { required: true, check: sequenceCheck },
65    // The product size the paper states for the pair, on the forward primer only: a size is a pair's, and it is shown beside the
66    // computed one, never in its place.
67    published_product: {
68      check: (value) => (typeof value === "string" && PRODUCT.test(value) ? null : 'is a size as the paper states it, such as "710 bp" or "about 710 bp"'),
69    },
70  },
71  /**
72   * What only the whole set can say: a sequence is stored once (two records cannot hold it), a set holds at most one forward and
73   * one reverse primer, a published product is stated on the forward primer alone, and a pair shares one reference, because a
74   * pair's product is computed on one sequence.
75   */
76  setErrors(items) {
77    /** @type {string[]} */
78    const errors = [];
79    /** @type {Map<string, string>} */
80    const sequences = new Map();
81    /** @type {Map<string, { forward: string[], reverse: string[], references: Set<string> }>} */
82    const sets = new Map();
83    for (const { id, fields } of items) {
84      const sequence = String(fields.sequence);
85      const other = sequences.get(sequence);
86      if (!sequence.startsWith("MISSING")) {
87        if (other !== undefined) errors.push(`primer/${id} and primer/${other} hold the same sequence; a sequence is stored once`);
88        else sequences.set(sequence, id);
89      }
90      const set = typeof fields.set === "string" ? fields.set : null;
91      if (set !== null) {
92        const entry = sets.get(set) ?? { forward: [], reverse: [], references: new Set() };
93        if (fields.direction === "forward") entry.forward.push(id);
94        if (fields.direction === "reverse") entry.reverse.push(id);
95        if (typeof fields.reference === "string" && !fields.reference.startsWith("MISSING")) entry.references.add(fields.reference);
96        sets.set(set, entry);
97      }
98      const product = fields.published_product;
99      if (typeof product === "string" && !product.startsWith("MISSING") && fields.direction !== "forward") {
100        errors.push(`primer/${id} states a published product, but a product is a pair's and is stated on its forward primer`);
101      }
102    }
103    for (const [set, { forward, reverse, references }] of sets) {
104      if (forward.length > 1) errors.push(`the set "${set}" has ${forward.length} forward primers (${forward.join(", ")}); a set has one`);
105      if (reverse.length > 1) errors.push(`the set "${set}" has ${reverse.length} reverse primers (${reverse.join(", ")}); a set has one`);
106      if (references.size > 1) errors.push(`the set "${set}" names ${references.size} references (${[...references].join(", ")}); a pair is placed on one`);
107    }
108    return errors;
109  },
110};
111
112/**
113 * What a primer's page and rows derive from its sequence alone: its length, GC content and Tm, and null where the sequence is
114 * not one the model applies to (a gap, or an ambiguity code).
115 *
116 * @param {string} sequence
117 */
118export function primerFacts(sequence) {
119  if (!/^[ACGT]+$/.test(sequence)) return { length: /^[A-Z]+$/.test(sequence) ? sequence.length : null, gcPercent: null, tm: null };
120  const gc = [...sequence].filter((base) => base === "G" || base === "C").length;
121  return { length: sequence.length, gcPercent: Math.round((gc / sequence.length) * 1000) / 10, tm: primerTmRounded(sequence) };
122}
123
124/** A field as text: a recorded gap (MISSING: why) and an absent value are both nothing to show. @param {unknown} value */
125export function stated(value) {
126  return typeof value === "string" && value !== "" && !value.startsWith("MISSING") ? value : null;
127}
128
129/** The reason a field is missing, or null when it is stated or absent. @param {unknown} value */
130export function missingReason(value) {
131  return typeof value === "string" && value.startsWith("MISSING:") ? value.replace(/^MISSING:\s*/, "") : null;
132}
133
134/**
135 * A primer as a protocol carries it (`StoredPrimer` in app/kb/procedures/render.mjs): the registry's stated facts, none
136 * computed. The protocol's record holds these so its page, sheet, twin and frozen versions print one sequence, and a pair's
137 * product is computed from them where it is shown.
138 *
139 * @param {import("./kinds.mjs").RegistryItem} item
140 * @returns {import("../procedures/render.mjs").StoredPrimer}
141 */
142export function storedPrimer(item) {
143  const f = /** @type {Record<string, unknown>} */ (item.fields);
144  return {
145    id: item.id,
146    name: item.name,
147    status: item.status,
148    set: stated(f.set),
149    direction: stated(f.direction),
150    sequence: stated(f.sequence),
151    reference: stated(f.reference),
152    // The paper that prints it, for a protocol's Key Resources Table; null where the registry records a gap.
153    publishedIn: stated(f.published_in),
154  };
155}