app/kb/procedures/key-resources.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/components/procedure-materials.tsx, app/components/procedure.tsx, app/kb/procedures/render.mjs.

Source

1// A protocol's Key Resources Table (docs/KNOWLEDGE-BASE.md, step 6), in the shape Cell Press's STAR Methods ask for:
2// each resource with its source and identifier, grouped by type. Computed from the record, never stored or typed: the
3// strains, reagents, primers and equipment a protocol names are the lab registry's, baked into the record when it is
4// compiled, so the table, the page's own tables and the twin print the same facts. A fact the registry records as a gap
5// reads "Not recorded", and an identifier a resource does not have reads "N/A", as STAR tables write it.
6
7const NOT_RECORDED = "Not recorded";
8const NONE = "N/A";
9
10/**
11 * @typedef {{ resource: string, sequence?: string, href: string | null, source: string, identifier: string }} KeyResource
12 * @typedef {{ id: string, heading: string, rows: KeyResource[] }} KeyResourceGroup
13 */
14
15/**
16 * The table's groups, in STAR's order, each holding at least one row; empty for a record that is not a protocol or names
17 * nothing from the registry.
18 *
19 * @param {import("./render.mjs").ProcedureRecord} record
20 * @returns {KeyResourceGroup[]}
21 */
22export function keyResources(record) {
23  if (record.profile !== "protocol") return [];
24
25  const strains = record.hostStrains.map((s) => ({
26    resource: s.name,
27    href: s.path,
28    source: s.collection ?? NOT_RECORDED,
29    // The registry stores the collection and its number apart ("ATCC", "700084"); a table names the deposit with both.
30    identifier: s.collectionNumber ? [s.collection, s.collectionNumber].filter(Boolean).join(" ") : NONE,
31  }));
32
33  // A reagent once, however many materials name it, in the order the protocol first names it.
34  const seen = new Set();
35  const chemicals = [];
36  for (const m of record.materials) {
37    const r = m.reagent;
38    if (!r || seen.has(r.id)) continue;
39    seen.add(r.id);
40    chemicals.push({
41      resource: r.name,
42      href: null,
43      source: r.preparedInLab ? "Prepared in the lab" : (r.supplier ?? NOT_RECORDED),
44      identifier: r.preparedInLab ? NONE : r.catalogNumber ? `Cat# ${r.catalogNumber}` : NOT_RECORDED,
45    });
46  }
47
48  // A primer's sequence, 5′ to 3′, is a part of the row, as STAR tables give it, kept apart from its name so the page can set
49  // it in monospace and let it break anywhere.
50  const oligos = record.primers.map((p) => ({
51    resource: p.name,
52    ...(p.sequence ? { sequence: `5′-${p.sequence}-3′` } : {}),
53    href: `/research/lab/primers/${p.id}`,
54    source: p.publishedIn ?? NOT_RECORDED,
55    identifier: NONE,
56  }));
57
58  const other = record.equipment.flatMap((e) =>
59    e.item ? [{ resource: e.item.name, href: null, source: e.item.manufacturer ?? NOT_RECORDED, identifier: NONE }] : [],
60  );
61
62  return [
63    { id: "strains", heading: "Bacterial and virus strains", rows: strains },
64    { id: "chemicals", heading: "Chemicals, peptides, and recombinant proteins", rows: chemicals },
65    { id: "oligonucleotides", heading: "Oligonucleotides", rows: oligos },
66    { id: "other", heading: "Other", rows: other },
67  ].filter((group) => group.rows.length > 0);
68}
69
70/** A cell's text for a markdown table: pipes escaped, so a citation with one cannot split the row. @param {string} text */
71const cell = (text) => text.replace(/\|/g, "\\|");
72
73/**
74 * The table as the twin prints it: one markdown table, each group a bold row above its resources.
75 *
76 * @param {KeyResourceGroup[]} groups
77 * @returns {string[]} lines, ending with a blank one; none when there is nothing to list
78 */
79export function keyResourcesMarkdown(groups) {
80  if (groups.length === 0) return [];
81  const out = ["## Key resources", "", "| Reagent or resource | Source | Identifier |", "| --- | --- | --- |"];
82  for (const group of groups) {
83    out.push(`| **${cell(group.heading)}** | | |`);
84    for (const row of group.rows) {
85      const name = row.href ? `[${cell(row.resource)}](${row.href})` : cell(row.resource);
86      const sequence = row.sequence ? `: \`${row.sequence}\`` : "";
87      out.push(`| ${name}${sequence} | ${cell(row.source)} | ${cell(row.identifier)} |`);
88    }
89  }
90  out.push("");
91  return out;
92}