app/lib/phage-tools.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/components/phage-tool.tsx, app/enhance/tools.ts, app/kb/form.server.ts, app/kb/procedures/library.mjs, app/kb/procedures/render.mjs, app/kb/procedures/validate.mjs, app/lib/pages/invariants.mjs, app/routes/content-page.tsx.

Source

1/**
2 * The phage lab calculators at /research/tools: titer, serial dilution, webbed plate, MOI, efficiency of
3 * plating and lysate volume. One pure module,
4 * imported by the server-rendered calculator (app/components/phage-tool.tsx), which renders the worked
5 * example with script off, and by the browser module that recomputes on input (app/enhance/tools.ts).
6 * test/phage-tools.test.mjs holds it against hand arithmetic and the numbers on the FAQ and the
7 * isolation protocol, and holds each page's worked example to what this module prints.
8 *
9 * Every lab default here names the page that states it (`source`), and the page shows that source.
10 * Volumes are in µl and titers in pfu/ml throughout, as on the FAQ.
11 */
12
13/** @typedef {{ href: string, label: string }} Source */
14
15/**
16 * @typedef {object} ToolField
17 * @property {string} name the query parameter and the input's name
18 * @property {string} label
19 * @property {string} [unit]
20 * @property {string} value the value the page opens with
21 * @property {string} [hint]
22 * @property {Source} [source] set when `value` is a lab default rather than the worked example's number
23 */
24
25/** @typedef {{ text: string, sup?: false } | { text: string, sup: true }} TextPart */
26
27/**
28 * @typedef {object} ToolSection
29 * @property {string} heading
30 * @property {string[]} steps the arithmetic, one line each, in the order it is done
31 * @property {string} [result] the answer, set apart from the steps
32 * @property {string[]} [notes] cautions from the lab's pages, shown after the steps
33 */
34
35/** @typedef {{ ok: true, sections: ToolSection[] } | { ok: false, error: string }} ToolResult */
36
37const FAQ = "/teaching/virus-isolation/faq";
38const PROTOCOL = "/research/protocols/phage-isolation";
39
40/** @type {Record<string, Source>} */
41const SOURCES = {
42  fullPlate: { href: `${PROTOCOL}#full-plate-titer`, label: "Phage Isolation and Purification Protocol: full plate titer" },
43  spot: { href: `${PROTOCOL}#spot-titer`, label: "Phage Isolation and Purification Protocol: spot titer" },
44  tenfold: { href: FAQ, label: "Lab Calculations and Common Questions: 10-fold serial dilution" },
45  volumeLimit: { href: `${PROTOCOL}#the-bracketing-shortcut`, label: "Phage Isolation and Purification Protocol: volume limit" },
46  yields: { href: `${PROTOCOL}#yields`, label: "Phage Isolation and Purification Protocol: yields" },
47};
48
49/** The lab's numbers, each with its page. Nothing here is a value no page states. */
50export const LAB = {
51  /** Full plate titer: 10 µl of each dilution with 250 µl host. */
52  ulPlated: 10,
53  /** Spot titer: the Guide's Protocol 6.4, 3 µl spots, as the lab runs it. */
54  ulSpot: 3,
55  /** A 10-fold step: 10 µl phage + 90 µl phage buffer. */
56  transferUl: 10,
57  /** No more lysate than 10% of the 250 µl of host, or the cells lyse. */
58  maxLysateUl: 25,
59  /** Each plate flooded with 8 ml of phage buffer returns about 5 to 7 ml. */
60  floodMl: 8,
61  yieldLowMl: 5,
62  yieldHighMl: 7,
63  /** Plan about 6 webbed plates for 10 ml to archive plus 10 ml for DNA extraction. */
64  plates: 6,
65};
66
67/* ---------------------------------------------------------------- numbers */
68
69/**
70 * A number as the bench writes it: `1.1e10`, `1.1 x 10^10`, `1.1×10^10`, `11,100` or `10^-3`.
71 * Returns NaN for anything else, including an empty field, so the caller names the field.
72 *
73 * @param {unknown} raw
74 */
75export function parseNumber(raw) {
76  const text = String(raw ?? "")
77    .trim()
78    .replace(/[\s,]/g, "")
79    .replace(/[×xX*]/g, "x")
80    .replace(/−/g, "-");
81  if (text === "") return Number.NaN;
82  const sci = /^([+-]?\d*\.?\d+)x10\^([+-]?\d+)$/.exec(text);
83  if (sci) return Number(sci[1]) * 10 ** Number(sci[2]);
84  const power = /^10\^([+-]?\d+)$/.exec(text);
85  if (power) return 10 ** Number(power[1]);
86  if (!/^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i.test(text)) return Number.NaN;
87  return Number(text);
88}
89
90/** @param {number} value @param {number} digits */
91function roundSig(value, digits) {
92  if (value === 0 || !Number.isFinite(value)) return value;
93  return Number(value.toPrecision(digits));
94}
95
96/** Trailing zeros off a fixed-point string: 1.50 to 1.5, 2.00 to 2. @param {string} text */
97function trim(text) {
98  return text.includes(".") ? text.replace(/0+$/, "").replace(/\.$/, "") : text;
99}
100
101/**
102 * Three significant figures, never more than the value has. Plain with thousands separators from 0.01
103 * up to a million, and `a x 10^n` outside that, the way the FAQ writes titers.
104 *
105 * @param {number} value
106 */
107export function formatNumber(value) {
108  if (!Number.isFinite(value)) return String(value);
109  if (value === 0) return "0";
110  const rounded = roundSig(value, 3);
111  const abs = Math.abs(rounded);
112  if (abs >= 0.01 && abs < 1e6) {
113    const [whole = "", fraction] = trim(String(rounded)).split(".");
114    const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
115    return fraction ? `${grouped}.${fraction}` : grouped;
116  }
117  return formatScientific(rounded);
118}
119
120/** Always `a x 10^n`, three significant figures: 1.11 x 10^10, 1 x 10^-3. @param {number} value */
121export function formatScientific(value) {
122  if (value === 0) return "0";
123  const [mantissa = "", exponent] = roundSig(value, 3).toExponential(2).split("e");
124  return `${trim(mantissa)} x 10^${Number(exponent)}`;
125}
126
127/** `10^-6`, and `undiluted` for 10^0. @param {number} n */
128function formatDilution(n) {
129  return n === 0 ? "undiluted" : `10^-${n}`;
130}
131
132/**
133 * A line split into plain runs and superscripts, so both renderers show `10^6` as 10 with a raised 6
134 * and neither parses markup.
135 *
136 * @param {string} line
137 * @returns {TextPart[]}
138 */
139export function textParts(line) {
140  /** @type {TextPart[]} */
141  const parts = [];
142  let last = 0;
143  for (const match of line.matchAll(/10\^(-?\d+)/g)) {
144    const at = match.index ?? 0;
145    parts.push({ text: `${line.slice(last, at)}10` });
146    parts.push({ text: (match[1] ?? "").replace("-", "−"), sup: true });
147    last = at + match[0].length;
148  }
149  parts.push({ text: line.slice(last) });
150  return parts.filter((part) => part.text !== "");
151}
152
153/**
154 * A value the arithmetic guarantees, checked anyway: an index past the end is a bug here, not input.
155 *
156 * @template T
157 * @param {T | undefined} value
158 * @returns {T}
159 */
160function must(value) {
161  if (value === undefined) throw new Error("phage-tools: a planned step is missing.");
162  return value;
163}
164
165const WORDS = ["zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten"];
166/** @param {number} n */
167function count(n) {
168  return WORDS[n] ?? String(n);
169}
170
171/* ---------------------------------------------------------------- titer */
172
173/**
174 * titer (pfu/ml) = plaques counted / µl plated x 1,000 µl/ml x dilution factor, the FAQ's formula.
175 * A spot titer is the same with the spot volume.
176 *
177 * @param {{ plaques: number, volumeUl: number, dilutionExponent: number }} input
178 */
179export function titer({ plaques, volumeUl, dilutionExponent }) {
180  const perUl = plaques / volumeUl;
181  const perMlDiluted = perUl * 1000;
182  const pfuPerMl = perMlDiluted * 10 ** dilutionExponent;
183  return { perUl, perMlDiluted, pfuPerMl };
184}
185
186/**
187 * A plaque count, the volume plated and the dilution's exponent, read and checked. Shared by the titer
188 * calculator and the EOP-from-counts calculator, so both refuse the same inputs in the same words.
189 * `where` names the plate in the message ("" for one plate, " on the test host" for EOP).
190 *
191 * @param {unknown} rawPlaques @param {unknown} rawVolume @param {unknown} rawDilution @param {string} [where]
192 * @returns {{ ok: true, plaques: number, volumeUl: number, n: number } | { ok: false, error: string }}
193 */
194function readCount(rawPlaques, rawVolume, rawDilution, where = "") {
195  const plaques = parseNumber(rawPlaques);
196  const volumeUl = parseNumber(rawVolume);
197  const rawN = parseNumber(rawDilution);
198  if (!Number.isFinite(plaques) || plaques < 0 || !Number.isInteger(plaques)) {
199    return { ok: false, error: `Enter the plaques counted${where} as a whole number, 0 or more.` };
200  }
201  if (!Number.isFinite(volumeUl) || volumeUl <= 0) {
202    return { ok: false, error: `Enter the volume plated or spotted${where}, in µl, greater than 0.` };
203  }
204  // A dilution is never more than 1, so 6 and -6 both mean 10^-6.
205  const n = Math.abs(rawN);
206  if (!Number.isFinite(rawN) || !Number.isInteger(n) || n > 20) {
207    return { ok: false, error: `Enter the dilution's exponent${where} as a whole number from 0 to 20: 6 for 10^-6, 0 if undiluted.` };
208  }
209  return { ok: true, plaques, volumeUl, n };
210}
211
212/** @param {Record<string, string | undefined>} values @returns {ToolResult} */
213function runTiter(values) {
214  const read = readCount(values.plaques, values.volume, values.dilution);
215  if (!read.ok) return read;
216  const { plaques, volumeUl, n } = read;
217  const { perUl, perMlDiluted, pfuPerMl } = titer({ plaques, volumeUl, dilutionExponent: n });
218  const of = n === 0 ? "in the undiluted lysate" : `in the ${formatDilution(n)} dilution`;
219  const steps = [
220    `Plaques per µl: ${formatNumber(plaques)} / ${formatNumber(volumeUl)} µl = ${formatNumber(perUl)} pfu/µl.`,
221    `Per ml: ${formatNumber(perUl)} x 1,000 = ${formatNumber(perMlDiluted)} pfu/ml ${of}.`,
222  ];
223  if (n > 0) {
224    steps.push(`Undo the dilution: ${formatNumber(perMlDiluted)} x 10^${n} = ${formatScientific(pfuPerMl)} pfu/ml.`);
225  }
226  /** @type {string[]} */
227  const notes = [];
228  if (plaques === 0) {
229    notes.push("No plaques: the titer is below what this plate can measure. Count a less dilute plate.");
230  } else {
231    const log = Math.log10(perUl);
232    const exponent = Math.floor(log + 3 + n + 1e-9);
233    steps.push(
234      `Check the exponent: log10(${formatNumber(perUl)}) + 3 + ${n} = ${log.toFixed(2)} + 3 + ${n} = ${(log + 3 + n).toFixed(2)}, so the titer is in the 10^${exponent} range.`,
235    );
236  }
237  return {
238    ok: true,
239    sections: [{ heading: "Titer", steps, result: `${formatScientific(pfuPerMl)} pfu/ml`, notes }],
240  };
241}
242
243/* ---------------------------------------------------------------- dilution */
244
245/**
246 * @typedef {object} DilutionStep
247 * @property {number} tube 1-based
248 * @property {number} transferUl from the tube before (tube 1 takes from the lysate)
249 * @property {number} bufferUl
250 * @property {number} fold this step's own dilution
251 * @property {number} cumulativeFold from the lysate to this tube
252 * @property {number} pfuPerMl in this tube
253 */
254
255/**
256 * The tubes that take a lysate from `startPfuPerMl` down to `targetPfuPerMl`: as many 10-fold steps as
257 * fit (transfer + 9 x transfer of buffer), then one smaller step for whatever is left over when the
258 * total is not a power of ten. Volumes are rounded to 0.1 µl and the tube concentrations are computed
259 * from the rounded volumes, so they are what the tubes will hold. When `neededUl` is set, the last tube
260 * holds at least that much, and each tube before it at least what the next one takes.
261 *
262 * @param {{ startPfuPerMl: number, targetPfuPerMl: number, transferUl?: number, neededUl?: number }} input
263 */
264export function planDilution({ startPfuPerMl, targetPfuPerMl, transferUl = LAB.transferUl, neededUl = 0 }) {
265  const totalFold = startPfuPerMl / targetPfuPerMl;
266  const tenfold = Math.floor(Math.log10(totalFold) + 1e-9);
267  const remainder = totalFold / 10 ** tenfold;
268  /** @type {number[]} */
269  const folds = Array.from({ length: tenfold }, () => 10);
270  // A remainder within 1% of 1 is a power of ten that floating point missed by a hair.
271  if (remainder > 1.01) folds.push(remainder);
272
273  const round = (/** @type {number} */ v) => Math.round(v * 10) / 10;
274  // From the last tube back: each tube must hold what the next one takes, and the last what is needed.
275  /** @type {number[]} */
276  const totals = Array.from({ length: folds.length }, () => 0);
277  // Filled from the end, so each tube's total is known before the tube that supplies it.
278  let required = neededUl;
279  for (let i = folds.length - 1; i >= 0; i -= 1) {
280    const fold = must(folds[i]);
281    // Never a volume under 1 µl: a 1.05-fold step at 10 µl would need 0.5 µl of buffer.
282    const smallest = Math.max(fold, fold / (fold - 1));
283    const total = Math.max(transferUl * fold, smallest, required);
284    totals[i] = total;
285    required = total / fold;
286  }
287
288  /** @type {DilutionStep[]} */
289  const steps = [];
290  let cumulativeFold = 1;
291  folds.forEach((fold, i) => {
292    const total = must(totals[i]);
293    const transfer = round(total / fold);
294    const buffer = round(total - total / fold);
295    const actualFold = (transfer + buffer) / transfer;
296    cumulativeFold *= actualFold;
297    steps.push({
298      tube: i + 1,
299      transferUl: transfer,
300      bufferUl: buffer,
301      fold: actualFold,
302      cumulativeFold,
303      pfuPerMl: startPfuPerMl / cumulativeFold,
304    });
305  });
306  return { totalFold, tenfold, remainder, steps, finalPfuPerMl: startPfuPerMl / cumulativeFold };
307}
308
309/** @param {DilutionStep} step @param {number} tenfoldCount */
310function stepLine(step, tenfoldCount) {
311  const from = step.tube === 1 ? "lysate" : `tube ${step.tube - 1}`;
312  const label = step.tube <= tenfoldCount ? formatDilution(step.tube) : `1/${formatNumber(step.cumulativeFold)}`;
313  return `Tube ${step.tube}: ${formatNumber(step.transferUl)} µl ${from} + ${formatNumber(step.bufferUl)} µl phage buffer = ${label}, ${formatScientific(step.pfuPerMl)} pfu/ml.`;
314}
315
316/**
317 * The steps shared by the dilution and webbed-plate calculators: the fold, how it splits, the tubes.
318 *
319 * @param {ReturnType<typeof planDilution>} plan
320 * @param {number} startPfuPerMl
321 * @param {number} targetPfuPerMl
322 */
323function planLines(plan, startPfuPerMl, targetPfuPerMl) {
324  const lines = [
325    `Total dilution: ${formatScientific(startPfuPerMl)} / ${formatScientific(targetPfuPerMl)} = ${formatNumber(plan.totalFold)}-fold.`,
326  ];
327  const split =
328    plan.steps.length === plan.tenfold
329      ? `That is 10^${plan.tenfold}: ${count(plan.tenfold)} 10-fold steps.`
330      : plan.tenfold === 0
331        ? `That is less than 10-fold: one ${formatNumber(plan.remainder)}-fold step.`
332        : `That is 10^${plan.tenfold} x ${formatNumber(plan.remainder)}: ${count(plan.tenfold)} 10-fold ${plan.tenfold === 1 ? "step" : "steps"}, then one ${formatNumber(plan.remainder)}-fold step.`;
333  lines.push(split);
334  for (const step of plan.steps) lines.push(stepLine(step, plan.tenfold));
335  return lines;
336}
337
338/** @param {Record<string, string | undefined>} values @returns {ToolResult} */
339function runDilution(values) {
340  const start = parseNumber(values.start);
341  const target = parseNumber(values.target);
342  const transfer = parseNumber(values.transfer);
343  const needed = values.needed === undefined || String(values.needed).trim() === "" ? 0 : parseNumber(values.needed);
344  if (!Number.isFinite(start) || start <= 0) return { ok: false, error: "Enter the starting titer in pfu/ml, greater than 0." };
345  if (!Number.isFinite(target) || target <= 0) return { ok: false, error: "Enter the target concentration in pfu/ml, greater than 0." };
346  if (target >= start) return { ok: false, error: "The target is not below the starting titer, so there is nothing to dilute." };
347  if (start / target > 1e20) return { ok: false, error: "That is more than 20 10-fold steps. Check the exponents." };
348  if (!Number.isFinite(transfer) || transfer <= 0) return { ok: false, error: "Enter the volume carried into each tube, in µl, greater than 0." };
349  if (!Number.isFinite(needed) || needed < 0) return { ok: false, error: "Enter the volume needed from the last tube in µl, or leave it empty." };
350  const plan = planDilution({ startPfuPerMl: start, targetPfuPerMl: target, transferUl: transfer, neededUl: needed });
351  const steps = planLines(plan, start, target);
352  const last = must(plan.steps.at(-1));
353  const lastVolume = last.transferUl + last.bufferUl;
354  if (needed > 0) steps.push(`The last tube holds ${formatNumber(lastVolume)} µl, enough for the ${formatNumber(needed)} µl needed.`);
355  /** @type {string[]} */
356  const notes = [];
357  if (plan.steps.some((step) => step.transferUl < 1 || step.bufferUl < 1)) {
358    notes.push("A volume is under 1 µl. Raise the volume carried into each tube so every volume can be pipetted.");
359  }
360  return {
361    ok: true,
362    sections: [
363      {
364        heading: "Dilution series",
365        steps,
366        result: `${plan.steps.length} ${plan.steps.length === 1 ? "tube" : "tubes"}, ending at ${formatScientific(plan.finalPfuPerMl)} pfu/ml`,
367        notes,
368      },
369    ],
370  };
371}
372
373/* ---------------------------------------------------------------- webbed plate */
374
375/**
376 * µl of lysate per plate = pfu wanted per plate / titer (pfu/ml) x 1,000 µl/ml, the FAQ's formula.
377 *
378 * @param {{ titerPfuPerMl: number, pfuPerPlate: number }} input
379 */
380export function lysatePerPlate({ titerPfuPerMl, pfuPerPlate }) {
381  return (pfuPerPlate / titerPfuPerMl) * 1000;
382}
383
384/**
385 * Lysate back from flooding: plates x the lab's 5 to 7 ml per plate.
386 *
387 * @param {{ plates: number, lowMl?: number, highMl?: number }} input
388 */
389export function floodYield({ plates, lowMl = LAB.yieldLowMl, highMl = LAB.yieldHighMl }) {
390  return { lowMl: plates * lowMl, highMl: plates * highMl };
391}
392
393/**
394 * Plates to flood for a lysate volume: ml wanted / 5 to 7 ml per plate, rounded up. Fewest plates at
395 * the high yield, most at the low one.
396 *
397 * @param {{ mlWanted: number, lowMl?: number, highMl?: number }} input
398 */
399export function platesForLysate({ mlWanted, lowMl = LAB.yieldLowMl, highMl = LAB.yieldHighMl }) {
400  return { fewest: Math.ceil(mlWanted / highMl - 1e-9), most: Math.ceil(mlWanted / lowMl - 1e-9) };
401}
402
403/** @param {Record<string, string | undefined>} values @returns {ToolResult} */
404function runWebbedPlate(values) {
405  const titerValue = parseNumber(values.titer);
406  const pfu = parseNumber(values.pfu);
407  const volume = parseNumber(values.volume);
408  const plates = parseNumber(values.plates);
409  if (!Number.isFinite(titerValue) || titerValue <= 0) return { ok: false, error: "Enter the lysate's titer in pfu/ml, greater than 0." };
410  if (!Number.isFinite(pfu) || pfu <= 0) return { ok: false, error: "Enter the pfu wanted on each plate, greater than 0." };
411  if (!Number.isFinite(volume) || volume <= 0) return { ok: false, error: "Enter the volume plated on each plate, in µl, greater than 0." };
412  if (!Number.isFinite(plates) || plates < 1 || !Number.isInteger(plates) || plates > 100) {
413    return { ok: false, error: "Enter the number of plates as a whole number from 1 to 100." };
414  }
415  const lysateUl = lysatePerPlate({ titerPfuPerMl: titerValue, pfuPerPlate: pfu });
416  const neededUl = plates * volume;
417  const plate = [
418    `Lysate per plate: ${formatNumber(pfu)} / ${formatScientific(titerValue)} pfu/ml x 1,000 µl/ml = ${formatNumber(lysateUl)} µl.`,
419  ];
420  /** @type {string[]} */
421  const notes = [];
422  let result;
423  const targetPfuPerMl = (pfu / volume) * 1000;
424  if (targetPfuPerMl >= titerValue) {
425    plate.push(`That is more than ${formatNumber(volume)} µl, so plate undiluted lysate: ${formatNumber(lysateUl)} µl on each plate, ${formatNumber(lysateUl * plates)} µl for ${plates} plates.`);
426    result = `${formatNumber(lysateUl)} µl of undiluted lysate per plate`;
427    if (lysateUl > LAB.maxLysateUl) {
428      notes.push(`${formatNumber(lysateUl)} µl is over the lab's limit of ${LAB.maxLysateUl} µl on 250 µl of host (10% of the cell volume), which lyses the cells. Plate ${LAB.maxLysateUl} µl, or use a lysate with a higher titer.`);
429    }
430  } else {
431    plate.push(`To plate that in ${formatNumber(volume)} µl, the tube must hold ${formatNumber(pfu)} pfu / ${formatNumber(volume)} µl x 1,000 = ${formatScientific(targetPfuPerMl)} pfu/ml.`);
432    const plan = planDilution({ startPfuPerMl: titerValue, targetPfuPerMl, transferUl: LAB.transferUl, neededUl });
433    plate.push(...planLines(plan, titerValue, targetPfuPerMl));
434    plate.push(`Enough of the last tube: ${plates} plates x ${formatNumber(volume)} µl = ${formatNumber(neededUl)} µl.`);
435    const last = must(plan.steps.at(-1));
436    result = `${formatNumber(volume)} µl of tube ${last.tube} (${formatNumber(volume * (last.pfuPerMl / 1000))} pfu) on each of ${plates} plates`;
437  }
438  const { lowMl, highMl } = floodYield({ plates });
439  const flood = [
440    `Flooded with ${LAB.floodMl} ml of phage buffer each, a plate returns about ${LAB.yieldLowMl} to ${LAB.yieldHighMl} ml.`,
441    `${plates} plates x ${LAB.yieldLowMl} to ${LAB.yieldHighMl} ml = ${formatNumber(lowMl)} to ${formatNumber(highMl)} ml of lysate.`,
442  ];
443  return {
444    ok: true,
445    sections: [
446      { heading: "Webbed plates", steps: plate, result, notes },
447      {
448        heading: "Lysate from flooding",
449        steps: flood,
450        result: `About ${formatNumber(lowMl)} to ${formatNumber(highMl)} ml`,
451        notes: ["Dry or aged plates return less; one returned only 3.5 ml of an 8 ml flood."],
452      },
453    ],
454  };
455}
456
457/** @param {Record<string, string | undefined>} values @returns {ToolResult} */
458function runFlood(values) {
459  const ml = parseNumber(values.ml);
460  if (!Number.isFinite(ml) || ml <= 0 || ml > 10000) return { ok: false, error: "Enter the lysate wanted in ml, greater than 0." };
461  const { fewest, most } = platesForLysate({ mlWanted: ml });
462  const range = fewest === most ? `${most}` : `${fewest} to ${most}`;
463  return {
464    ok: true,
465    sections: [
466      {
467        heading: "Plates to flood",
468        steps: [
469          `At ${LAB.yieldHighMl} ml per plate: ${formatNumber(ml)} / ${LAB.yieldHighMl} = ${formatNumber(ml / LAB.yieldHighMl)}, so ${fewest} ${fewest === 1 ? "plate" : "plates"}.`,
470          `At ${LAB.yieldLowMl} ml per plate: ${formatNumber(ml)} / ${LAB.yieldLowMl} = ${formatNumber(ml / LAB.yieldLowMl)}, so ${most} ${most === 1 ? "plate" : "plates"}.`,
471        ],
472        result: `${range} webbed plates`,
473        notes: ["Pour a plate or two more than this: some plates do not web or yield less."],
474      },
475    ],
476  };
477}
478
479/* ---------------------------------------------------------------- MOI */
480
481/**
482 * MOI = pfu added / cells, with pfu = titer (pfu/ml) x µl added / 1,000 µl/ml and cells = cells/ml x µl
483 * of culture / 1,000 µl/ml. `infected` is the share of cells that receive at least one phage when phages
484 * land at random (Poisson): 1 - exp(-MOI). The site gives no OD-to-cells conversion, so cells are counted.
485 *
486 * @param {{ titerPfuPerMl: number, phageUl: number, cellsPerMl: number, hostUl: number }} input
487 */
488export function moi({ titerPfuPerMl, phageUl, cellsPerMl, hostUl }) {
489  const pfu = (titerPfuPerMl * phageUl) / 1000;
490  const cells = (cellsPerMl * hostUl) / 1000;
491  const ratio = pfu / cells;
492  return { pfu, cells, moi: ratio, infected: -Math.expm1(-ratio) };
493}
494
495/** @param {Record<string, string | undefined>} values @returns {ToolResult} */
496function runMoi(values) {
497  const titerValue = parseNumber(values.titer);
498  const phageUl = parseNumber(values.phage);
499  const cellsPerMl = parseNumber(values.cells);
500  const hostUl = parseNumber(values.host);
501  if (!Number.isFinite(titerValue) || titerValue <= 0) return { ok: false, error: "Enter the phage titer in pfu/ml, greater than 0." };
502  if (!Number.isFinite(phageUl) || phageUl <= 0) return { ok: false, error: "Enter the volume of phage added, in µl, greater than 0." };
503  if (!Number.isFinite(cellsPerMl) || cellsPerMl <= 0) return { ok: false, error: "Enter the host cells per ml, greater than 0." };
504  if (!Number.isFinite(hostUl) || hostUl <= 0) return { ok: false, error: "Enter the volume of host culture, in µl, greater than 0." };
505  const result = moi({ titerPfuPerMl: titerValue, phageUl, cellsPerMl, hostUl });
506  return {
507    ok: true,
508    sections: [
509      {
510        heading: "MOI",
511        steps: [
512          `pfu added: ${formatScientific(titerValue)} pfu/ml x ${formatNumber(phageUl)} µl / 1,000 µl/ml = ${formatNumber(result.pfu)} pfu.`,
513          `Cells: ${formatScientific(cellsPerMl)} cells/ml x ${formatNumber(hostUl)} µl / 1,000 µl/ml = ${formatNumber(result.cells)} cells.`,
514          `MOI: ${formatNumber(result.pfu)} pfu / ${formatNumber(result.cells)} cells = ${formatNumber(result.moi)}.`,
515          `Cells that get at least one phage: 1 - exp(-${formatNumber(result.moi)}) = ${formatNumber(result.infected)}, about ${formatNumber(result.infected * 100)}%.`,
516        ],
517        result: `${formatNumber(result.moi)} pfu per cell`,
518        notes: [
519          "The last step assumes phages meet cells at random and every pfu adsorbs. Slow or incomplete adsorption infects fewer cells than it says.",
520        ],
521      },
522    ],
523  };
524}
525
526/* ---------------------------------------------------------------- EOP */
527
528/**
529 * EOP = titer on the test host / titer on the reference host.
530 *
531 * @param {{ testPfuPerMl: number, referencePfuPerMl: number }} input
532 */
533export function eop({ testPfuPerMl, referencePfuPerMl }) {
534  return testPfuPerMl / referencePfuPerMl;
535}
536
537/**
538 * The EOP steps shared by both EOP calculators. `boundPfuPerMl`, when the test host had no plaques, is
539 * the titer one plaque on that plate would have meant, so the note can say how low the EOP is.
540 *
541 * @param {number} test @param {number} reference @param {number} [boundPfuPerMl]
542 */
543function eopSection(test, reference, boundPfuPerMl) {
544  const ratio = eop({ testPfuPerMl: test, referencePfuPerMl: reference });
545  /** @type {string[]} */
546  const notes = [];
547  if (test === 0) {
548    const bound = boundPfuPerMl === undefined ? "" : ` It is below ${formatNumber(eop({ testPfuPerMl: boundPfuPerMl, referencePfuPerMl: reference }))}, what one plaque on that plate would give.`;
549    notes.push(`No plaques on the test host: the phage did not plate at this dilution, which is not the same as an EOP of exactly 0.${bound} Plate a less dilute sample to measure it.`);
550  }
551  return {
552    heading: "Efficiency of plating",
553    steps: [
554      `EOP: ${formatScientific(test)} pfu/ml on the test host / ${formatScientific(reference)} pfu/ml on the reference host = ${formatNumber(ratio)}.`,
555      `As a percentage of the reference titer: ${formatNumber(ratio)} x 100 = ${formatNumber(ratio * 100)}%.`,
556    ],
557    result: `${formatNumber(ratio)} (${formatNumber(ratio * 100)}% of the reference titer)`,
558    notes,
559  };
560}
561
562/** @param {Record<string, string | undefined>} values @returns {ToolResult} */
563function runEop(values) {
564  const test = parseNumber(values.test);
565  const reference = parseNumber(values.reference);
566  if (!Number.isFinite(test) || test < 0) return { ok: false, error: "Enter the titer on the test host in pfu/ml, 0 or more." };
567  if (!Number.isFinite(reference) || reference <= 0) return { ok: false, error: "Enter the titer on the reference host in pfu/ml, greater than 0." };
568  return { ok: true, sections: [eopSection(test, reference)] };
569}
570
571/** One host's titer line for the EOP-from-counts steps. @param {string} host @param {{ plaques: number, volumeUl: number, n: number }} count @param {number} pfuPerMl */
572function countLine(host, { plaques, volumeUl, n }, pfuPerMl) {
573  const undo = n === 0 ? "" : ` x 10^${n}`;
574  return `Titer on the ${host}: ${formatNumber(plaques)} / ${formatNumber(volumeUl)} µl x 1,000${undo} = ${formatScientific(pfuPerMl)} pfu/ml.`;
575}
576
577/** @param {Record<string, string | undefined>} values @returns {ToolResult} */
578function runEopCounts(values) {
579  const test = readCount(values.testPlaques, values.testVolume, values.testDilution, " on the test host");
580  if (!test.ok) return test;
581  const reference = readCount(values.refPlaques, values.refVolume, values.refDilution, " on the reference host");
582  if (!reference.ok) return reference;
583  if (reference.plaques === 0) {
584    return { ok: false, error: "No plaques on the reference host, so there is no titer to divide by. Count a less dilute plate." };
585  }
586  const testTiter = titer({ plaques: test.plaques, volumeUl: test.volumeUl, dilutionExponent: test.n }).pfuPerMl;
587  const refTiter = titer({ plaques: reference.plaques, volumeUl: reference.volumeUl, dilutionExponent: reference.n }).pfuPerMl;
588  const bound = titer({ plaques: 1, volumeUl: test.volumeUl, dilutionExponent: test.n }).pfuPerMl;
589  const section = eopSection(testTiter, refTiter, bound);
590  return {
591    ok: true,
592    sections: [
593      {
594        ...section,
595        steps: [countLine("test host", test, testTiter), countLine("reference host", reference, refTiter), ...section.steps],
596      },
597    ],
598  };
599}
600
601/* ---------------------------------------------------------------- lysate volume */
602
603/**
604 * Lysate for a run of plates: (pfu per plate x plates) / titer (pfu/ml) x 1,000 µl/ml, the webbed
605 * plate formula for all the plates at once.
606 *
607 * @param {{ titerPfuPerMl: number, pfuPerPlate: number, plates: number }} input
608 */
609export function lysateForPlates({ titerPfuPerMl, pfuPerPlate, plates }) {
610  const totalPfu = pfuPerPlate * plates;
611  const totalUl = lysatePerPlate({ titerPfuPerMl, pfuPerPlate: totalPfu });
612  return { totalPfu, totalUl, perPlateUl: totalUl / plates };
613}
614
615/** @param {Record<string, string | undefined>} values @returns {ToolResult} */
616function runLysateVolume(values) {
617  const titerValue = parseNumber(values.titer);
618  const pfu = parseNumber(values.pfu);
619  const plates = parseNumber(values.plates);
620  const volume = parseNumber(values.volume);
621  if (!Number.isFinite(titerValue) || titerValue <= 0) return { ok: false, error: "Enter the lysate's titer in pfu/ml, greater than 0." };
622  if (!Number.isFinite(pfu) || pfu <= 0) return { ok: false, error: "Enter the pfu wanted on each plate, greater than 0." };
623  if (!Number.isFinite(plates) || plates < 1 || !Number.isInteger(plates) || plates > 100) {
624    return { ok: false, error: "Enter the number of plates as a whole number from 1 to 100." };
625  }
626  if (!Number.isFinite(volume) || volume <= 0) return { ok: false, error: "Enter the volume plated on each plate, in µl, greater than 0." };
627  const { totalPfu, totalUl, perPlateUl } = lysateForPlates({ titerPfuPerMl: titerValue, pfuPerPlate: pfu, plates });
628  const steps = [
629    `pfu for all plates: ${formatNumber(pfu)} x ${plates} = ${formatNumber(totalPfu)} pfu.`,
630    `Lysate for all plates: ${formatNumber(totalPfu)} / ${formatScientific(titerValue)} pfu/ml x 1,000 µl/ml = ${formatNumber(totalUl)} µl.`,
631    `Per plate: ${formatNumber(totalUl)} µl / ${plates} = ${formatNumber(perPlateUl)} µl.`,
632  ];
633  /** @type {string[]} */
634  const notes = [];
635  let result;
636  if (perPlateUl >= volume * (1 - 1e-9)) {
637    steps.push(`That is at least the ${formatNumber(volume)} µl plated per plate, so plate the lysate undiluted: ${formatNumber(perPlateUl)} µl on each plate.`);
638    result = `${formatNumber(totalUl)} µl of undiluted lysate, ${formatNumber(perPlateUl)} µl on each of ${plates} plates`;
639    if (perPlateUl > LAB.maxLysateUl) {
640      notes.push(`${formatNumber(perPlateUl)} µl is over the lab's limit of ${LAB.maxLysateUl} µl on 250 µl of host (10% of the cell volume), which lyses the cells. Use a lysate with a higher titer.`);
641    }
642  } else {
643    const mixUl = plates * volume;
644    if (totalUl >= 1) {
645      steps.push(
646        `To plate ${formatNumber(volume)} µl on each: ${plates} plates x ${formatNumber(volume)} µl = ${formatNumber(mixUl)} µl, so mix ${formatNumber(totalUl)} µl lysate + ${formatNumber(mixUl - totalUl)} µl phage buffer.`,
647      );
648      result = `${formatNumber(totalUl)} µl of lysate in ${formatNumber(mixUl)} µl, ${formatNumber(volume)} µl on each of ${plates} plates`;
649    } else {
650      steps.push(`${formatNumber(totalUl)} µl is under 1 µl, too little to pipette, so dilute the lysate first and plate ${formatNumber(volume)} µl of the last tube on each plate.`);
651      result = `${formatNumber(totalUl)} µl of lysate for ${plates} plates, made by dilution`;
652      notes.push("The webbed plate calculator plans the dilution tubes for these numbers.");
653    }
654  }
655  return { ok: true, sections: [{ heading: "Lysate needed", steps, result, notes }] };
656}
657
658/* ---------------------------------------------------------------- registry */
659
660/**
661 * @typedef {object} ToolDefinition
662 * @property {string} path the page it is on
663 * @property {string} title the form's accessible name
664 * @property {ToolField[]} fields
665 * @property {(values: Record<string, string | undefined>) => ToolResult} run
666 */
667
668/** @type {Record<string, ToolDefinition>} */
669export const TOOLS = {
670  titer: {
671    path: "/research/tools/titer",
672    title: "Titer calculator",
673    fields: [
674      { name: "plaques", label: "Plaques counted", value: "111", hint: "On one plate, or in one spot." },
675      {
676        name: "volume",
677        label: "Volume plated or spotted",
678        unit: "µl",
679        value: String(LAB.ulPlated),
680        hint: `The lab plates ${LAB.ulPlated} µl for a full plate titer and spots ${LAB.ulSpot} µl for a spot titer; enter 10 for a 10 µl spot.`,
681        source: SOURCES.fullPlate,
682      },
683      { name: "dilution", label: "Dilution, 10 to the minus", value: "6", hint: "6 for the 10^-6 tube, 0 if undiluted." },
684    ],
685    run: runTiter,
686  },
687  dilution: {
688    path: "/research/tools/dilution",
689    title: "Serial dilution planner",
690    fields: [
691      { name: "start", label: "Starting titer", unit: "pfu/ml", value: "1.11e10", hint: "1.11e10 or 1.11 x 10^10." },
692      { name: "target", label: "Target concentration", unit: "pfu/ml", value: "1.11e6" },
693      {
694        name: "transfer",
695        label: "Volume carried into each tube",
696        unit: "µl",
697        value: String(LAB.transferUl),
698        hint: "Each 10-fold tube gets 9 times this of phage buffer: 10 µl + 90 µl.",
699        source: SOURCES.tenfold,
700      },
701      { name: "needed", label: "Volume needed from the last tube (optional)", unit: "µl", value: "", hint: "Plates x µl per plate. Earlier tubes are scaled up to supply it." },
702    ],
703    run: runDilution,
704  },
705  "webbed-plate": {
706    path: "/research/tools/webbed-plate",
707    title: "Webbed plate calculator",
708    fields: [
709      { name: "titer", label: "Lysate titer", unit: "pfu/ml", value: "1.11e10", hint: "1.11e10 or 1.11 x 10^10." },
710      { name: "pfu", label: "pfu wanted per plate", value: "11100", hint: "What webs depends on plaque size; see the notes below." },
711      { name: "volume", label: "Volume plated per plate", unit: "µl", value: String(LAB.ulPlated), source: SOURCES.fullPlate },
712      { name: "plates", label: "Plates to pour", value: String(LAB.plates), source: SOURCES.yields },
713    ],
714    run: runWebbedPlate,
715  },
716  flood: {
717    path: "/research/tools/webbed-plate",
718    title: "Plates for a lysate volume",
719    fields: [{ name: "ml", label: "Lysate wanted", unit: "ml", value: "20", hint: "10 ml to archive plus 10 ml for DNA extraction is 20 ml." }],
720    run: runFlood,
721  },
722  moi: {
723    path: "/research/tools/moi",
724    title: "MOI calculator",
725    fields: [
726      { name: "titer", label: "Phage titer", unit: "pfu/ml", value: "1e9", hint: "1e9 or 1 x 10^9." },
727      { name: "phage", label: "Phage volume added", unit: "µl", value: String(LAB.ulPlated), source: SOURCES.fullPlate },
728      {
729        name: "cells",
730        label: "Host cells",
731        unit: "cells/ml",
732        value: "1e8",
733        hint: "Counted, not read off an OD: the site gives no OD-to-cells factor for the lab's hosts. 1e8 is only the worked example's number.",
734      },
735      { name: "host", label: "Host culture volume", unit: "µl", value: "250", source: SOURCES.fullPlate },
736    ],
737    run: runMoi,
738  },
739  eop: {
740    path: "/research/tools/eop",
741    title: "EOP from titers",
742    fields: [
743      { name: "test", label: "Titer on the test host", unit: "pfu/ml", value: "2e8", hint: "2e8 or 2 x 10^8." },
744      { name: "reference", label: "Titer on the reference host", unit: "pfu/ml", value: "1e10", hint: "Usually the host the phage was isolated on." },
745    ],
746    run: runEop,
747  },
748  "eop-counts": {
749    path: "/research/tools/eop",
750    title: "EOP from plaque counts",
751    fields: [
752      { name: "testPlaques", label: "Plaques on the test host", value: "20" },
753      { name: "testVolume", label: "Volume plated on the test host", unit: "µl", value: String(LAB.ulPlated), source: SOURCES.fullPlate },
754      { name: "testDilution", label: "Test host dilution, 10 to the minus", value: "5", hint: "5 for the 10^-5 tube, 0 if undiluted." },
755      { name: "refPlaques", label: "Plaques on the reference host", value: "100" },
756      { name: "refVolume", label: "Volume plated on the reference host", unit: "µl", value: String(LAB.ulPlated), source: SOURCES.fullPlate },
757      { name: "refDilution", label: "Reference host dilution, 10 to the minus", value: "6", hint: "6 for the 10^-6 tube, 0 if undiluted." },
758    ],
759    run: runEopCounts,
760  },
761  "lysate-volume": {
762    path: "/research/tools/lysate-volume",
763    title: "Lysate volume planner",
764    fields: [
765      { name: "titer", label: "Lysate titer", unit: "pfu/ml", value: "1e7", hint: "1e7 or 1 x 10^7." },
766      { name: "pfu", label: "pfu wanted per plate", value: "10000", hint: "What webs depends on plaque size and host; see the notes below." },
767      { name: "plates", label: "Plates to pour", value: String(LAB.plates), source: SOURCES.yields },
768      { name: "volume", label: "Volume plated per plate", unit: "µl", value: String(LAB.ulPlated), source: SOURCES.fullPlate },
769    ],
770    run: runLysateVolume,
771  },
772};
773
774/** The calculators on a page, in page order. @param {string} path */
775export function toolsOnPage(path) {
776  return Object.keys(TOOLS).filter((id) => TOOLS[id]?.path === path);
777}
778
779/**
780 * A tool's values: the query string's where it has them, the field's opening value where not.
781 *
782 * @param {string} id
783 * @param {URLSearchParams} [params]
784 * @returns {Record<string, string>}
785 */
786export function toolValues(id, params) {
787  const tool = TOOLS[id];
788  if (!tool) throw new Error(`No calculator named ${id}.`);
789  /** @type {Record<string, string>} */
790  const values = {};
791  for (const field of tool.fields) {
792    const given = params?.get(field.name);
793    values[field.name] = given === null || given === undefined ? field.value : given.slice(0, 40);
794  }
795  return values;
796}
797
798/** @param {string} id @param {Record<string, string | undefined>} values @returns {ToolResult} */
799export function runTool(id, values) {
800  const tool = TOOLS[id];
801  if (!tool) throw new Error(`No calculator named ${id}.`);
802  return tool.run(values);
803}
804
805/* ---------------------------------------------------------------- view */
806
807/**
808 * @typedef {{ tag: "div" | "h3" | "ol" | "li" | "p" | "strong" | "sup", className?: string, children: Array<ViewNode | string> }} ViewNode
809 */
810
811/** @param {string} line @returns {Array<ViewNode | string>} */
812function lineNodes(line) {
813  return textParts(line).map((part) => (part.sup ? { tag: "sup", children: [part.text] } : part.text));
814}
815
816/**
817 * What a result looks like, as plain nodes, so the server component and the browser module build the
818 * same markup from one description and neither parses HTML. `summary` is the one line per section the
819 * status region announces; `detail` is the worked steps under it.
820 *
821 * @param {ToolResult} result
822 * @returns {{ summary: Array<ViewNode | string>, detail: ViewNode[] }}
823 */
824export function resultView(result) {
825  if (!result.ok) {
826    return { summary: [{ tag: "p", className: "phage-tool-error", children: [result.error] }], detail: [] };
827  }
828  const summary = result.sections
829    .filter((section) => section.result)
830    .map((section) => ({
831      tag: /** @type {const} */ ("p"),
832      className: "phage-tool-answer",
833      children: [`${section.heading}: `, { tag: /** @type {const} */ ("strong"), children: lineNodes(section.result ?? "") }],
834    }));
835  const detail = result.sections.map((section) => ({
836    tag: /** @type {const} */ ("div"),
837    className: "phage-tool-section",
838    children: [
839      { tag: /** @type {const} */ ("h3"), children: [section.heading] },
840      {
841        tag: /** @type {const} */ ("ol"),
842        className: "phage-tool-steps",
843        children: section.steps.map((step) => ({ tag: /** @type {const} */ ("li"), children: lineNodes(step) })),
844      },
845      ...(section.notes ?? []).map((note) => ({
846        tag: /** @type {const} */ ("p"),
847        className: "phage-tool-note",
848        children: lineNodes(note),
849      })),
850    ],
851  }));
852  return { summary, detail };
853}