@biolibs/bionet-tools 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +104 -2
  2. package/dist/digest-tool.d.ts +30 -0
  3. package/dist/digest-tool.d.ts.map +1 -0
  4. package/dist/digest-tool.js +84 -0
  5. package/dist/digest-tool.js.map +1 -0
  6. package/dist/digest.d.ts +94 -0
  7. package/dist/digest.d.ts.map +1 -0
  8. package/dist/digest.js +115 -0
  9. package/dist/digest.js.map +1 -0
  10. package/dist/index.d.ts +29 -0
  11. package/dist/index.d.ts.map +1 -0
  12. package/dist/index.js +29 -0
  13. package/dist/index.js.map +1 -0
  14. package/dist/pcr-bench.d.ts +94 -0
  15. package/dist/pcr-bench.d.ts.map +1 -0
  16. package/dist/pcr-bench.js +187 -0
  17. package/dist/pcr-bench.js.map +1 -0
  18. package/dist/pcr-scene.d.ts +247 -0
  19. package/dist/pcr-scene.d.ts.map +1 -0
  20. package/dist/pcr-scene.js +287 -0
  21. package/dist/pcr-scene.js.map +1 -0
  22. package/dist/pcr-tool.d.ts +18 -0
  23. package/dist/pcr-tool.d.ts.map +1 -0
  24. package/dist/pcr-tool.js +73 -0
  25. package/dist/pcr-tool.js.map +1 -0
  26. package/dist/pcr.d.ts +59 -0
  27. package/dist/pcr.d.ts.map +1 -0
  28. package/dist/pcr.js +79 -0
  29. package/dist/pcr.js.map +1 -0
  30. package/dist/run.d.ts +161 -0
  31. package/dist/run.d.ts.map +1 -0
  32. package/dist/run.js +143 -0
  33. package/dist/run.js.map +1 -0
  34. package/dist/tools.d.ts +27 -0
  35. package/dist/tools.d.ts.map +1 -0
  36. package/dist/tools.js +45 -0
  37. package/dist/tools.js.map +1 -0
  38. package/package.json +61 -4
  39. package/src/digest-tool.tsx +199 -0
  40. package/src/digest.ts +136 -0
  41. package/src/index.ts +28 -0
  42. package/src/pcr-bench.tsx +350 -0
  43. package/src/pcr-scene.ts +408 -0
  44. package/src/pcr-tool.tsx +160 -0
  45. package/src/pcr.ts +87 -0
  46. package/src/run.ts +234 -0
  47. package/src/tools.tsx +64 -0
  48. package/tools.css +50 -0
package/src/run.ts ADDED
@@ -0,0 +1,234 @@
1
+ /**
2
+ * A PCR as a lab does one: from tubes in its freezer to a record of the run.
3
+ *
4
+ * `pcr.ts` knows sequences. This knows the lab: which tubes could be the template and which the
5
+ * primers, and what to ask the lab to record once somebody has chosen. It is plain data in and plain
6
+ * data out, so the window that uses it decides nothing.
7
+ */
8
+ import type { ItemState, PartState, PlaceState } from "@biolibs/bionet";
9
+ import { amountOf, whereWords } from "@biolibs/bionet-panels";
10
+ import { planDigest, type DigestPlan } from "./digest.js";
11
+ import { ANNEAL_AT_LEAST, looksLikePrimer, planPcr, type PcrPlan } from "./pcr.js";
12
+ import type { PcrProgramme } from "./pcr-scene.js";
13
+
14
+ /** As much of a lab as a tool reads. */
15
+ export interface ToolLab {
16
+ parts: readonly PartState[];
17
+ items: readonly ItemState[];
18
+ places: readonly PlaceState[];
19
+ }
20
+
21
+ /** One tube that could be chosen. */
22
+ export interface TubeChoice {
23
+ /** The tube. */
24
+ item: string;
25
+ /** What it is a tube of. */
26
+ part: PartState;
27
+ /** How to say it in a list: what it is, how much is left, where it is. */
28
+ label: string;
29
+ }
30
+
31
+ /**
32
+ * The tubes a PCR could be run from.
33
+ *
34
+ * Tubes that are retired or empty are left out. Short linear parts are offered as primers and the
35
+ * rest as templates; if a lab has nothing short, everything is offered as a primer, since the lab
36
+ * knows better than a length does.
37
+ *
38
+ * @param lab - The lab.
39
+ * @returns The tubes to offer as a template, and as a primer.
40
+ */
41
+ export function pcrTubes(lab: ToolLab): { templates: TubeChoice[]; primers: TubeChoice[] } {
42
+ const all: TubeChoice[] = [];
43
+ for (const item of lab.items) {
44
+ const part = lab.parts.find((one) => one.checksum === item.part);
45
+ if (part === undefined || item.retired || item.amount <= 0) continue;
46
+ all.push({ item: item.item, part, label: `${part.name} · ${amountOf(item)} · ${whereWords(item, lab.places)}` });
47
+ }
48
+ const short = all.filter((one) => looksLikePrimer(one.part));
49
+ const long = all.filter((one) => !looksLikePrimer(one.part));
50
+ return { templates: long.length > 0 ? [...long, ...short] : all, primers: short.length > 0 ? short : all };
51
+ }
52
+
53
+ /** What somebody has chosen for a PCR. */
54
+ export interface PcrChoice {
55
+ /** The tube of template, and the tubes of each primer. */
56
+ template: string;
57
+ forward: string;
58
+ reverse: string;
59
+ /** How much of each was used, in each tube's own unit. Whole numbers. */
60
+ used?: { template?: number; forward?: number; reverse?: number };
61
+ /** How many bases at each primer's 3′ end must bind. */
62
+ annealAtLeast?: number;
63
+ /** The thermocycler it was run on, if the lab has one. */
64
+ instrument?: string | null;
65
+ /** What to call the product, how much of it there is, and in what unit. */
66
+ name?: string;
67
+ amount?: number;
68
+ unit?: string | null;
69
+ /** Anything worth saying about the run. */
70
+ note?: string | null;
71
+ /** The programme the machine was set to, to be kept with the run. */
72
+ programme?: PcrProgramme;
73
+ }
74
+
75
+ /** A PCR as chosen: what it would make, and what to ask the lab to record. */
76
+ export interface PcrRun {
77
+ /** What the PCR would make, or `null` if a tube that was chosen is not one the lab has. */
78
+ plan: PcrPlan | null;
79
+ /** What the product would be called. */
80
+ name: string;
81
+ /** What to hand to the lab's `recordRun` if it worked. `null` while there is not exactly one product. */
82
+ worked: Record<string, unknown> | null;
83
+ /** What to hand to the lab's `recordRun` if it was run and gave nothing. `null` if a tube is missing. */
84
+ failed: Record<string, unknown> | null;
85
+ }
86
+
87
+ /**
88
+ * Work a choice of tubes out into a run.
89
+ *
90
+ * @param lab - The lab.
91
+ * @param choice - The tubes, how much of each, and what to call the product.
92
+ * @returns What it would make, and what to record either way.
93
+ *
94
+ * @example
95
+ * ```ts
96
+ * import { pcrRun, pcrTubes } from "@biolibs/bionet-tools";
97
+ *
98
+ * const { templates, primers } = pcrTubes(lab);
99
+ * const run = pcrRun(lab, { template: templates[0].item, forward: primers[0].item, reverse: primers[1].item });
100
+ * if (run.worked !== null) await act("recordRun", run.worked);
101
+ * ```
102
+ */
103
+ export function pcrRun(lab: ToolLab, choice: PcrChoice): PcrRun {
104
+ const partOf = (id: string): PartState | undefined => {
105
+ const item = lab.items.find((one) => one.item === id);
106
+ return item === undefined ? undefined : lab.parts.find((one) => one.checksum === item.part);
107
+ };
108
+ const [template, forward, reverse] = [partOf(choice.template), partOf(choice.forward), partOf(choice.reverse)];
109
+ const typed = choice.name?.trim() ?? "";
110
+ if (template === undefined || forward === undefined || reverse === undefined) return { plan: null, name: typed, worked: null, failed: null };
111
+ const least = choice.annealAtLeast ?? ANNEAL_AT_LEAST;
112
+ const plan = planPcr(template, forward.sequence, reverse.sequence, { annealAtLeast: least });
113
+ const name = typed !== "" ? typed : `${template.name} × ${forward.name} + ${reverse.name}`.slice(0, 200);
114
+ const whole = (value: number | undefined, usual: number): number => (value === undefined || !Number.isSafeInteger(value) || value < 0 ? usual : value);
115
+ const record = {
116
+ kind: "pcr", instrument: choice.instrument ?? null,
117
+ inputs: [
118
+ { item: choice.template, amount: whole(choice.used?.template, 1), role: "template" },
119
+ { item: choice.forward, amount: whole(choice.used?.forward, 1), role: "forward primer" },
120
+ { item: choice.reverse, amount: whole(choice.used?.reverse, 1), role: "reverse primer" },
121
+ ],
122
+ // What the operator set is part of what was done, and is what somebody repeating the run needs.
123
+ settings: { anneal_at_least: least, ...(choice.programme === undefined ? {} : {
124
+ denature_c: choice.programme.steps[0].celsius, anneal_c: choice.programme.steps[1].celsius, anneal_s: choice.programme.steps[1].seconds,
125
+ extend_c: choice.programme.steps[2].celsius, extend_s: choice.programme.steps[2].seconds, cycles: choice.programme.cycles,
126
+ }) },
127
+ note: choice.note ?? null,
128
+ };
129
+ const product = plan.problem === null ? plan.products[0]! : null;
130
+ return {
131
+ plan, name,
132
+ worked: product === null ? null : {
133
+ ...record, outcome: "worked",
134
+ outputs: [{ sequence: product.sequence, circular: false, name, amount: whole(choice.amount, 50), unit: choice.unit === undefined ? "µL" : choice.unit }],
135
+ },
136
+ failed: { ...record, outcome: "failed", outputs: [] },
137
+ };
138
+ }
139
+
140
+ /**
141
+ * The tubes a digest could be run on: every tube with something in it, the longer molecules first,
142
+ * since those are what is usually checked.
143
+ *
144
+ * @param lab - The lab.
145
+ * @returns The tubes to offer.
146
+ */
147
+ export function digestTubes(lab: ToolLab): TubeChoice[] {
148
+ return pcrTubes(lab).templates;
149
+ }
150
+
151
+ /** What somebody has chosen for a digest. */
152
+ export interface DigestChoice {
153
+ /** The tube being cut. */
154
+ tube: string;
155
+ /** The enzymes, by name. */
156
+ enzymes: readonly string[];
157
+ /** How much of the tube was used, in its own unit. A whole number. */
158
+ used?: number;
159
+ /** The gel's agarose concentration and the ladder beside it, by their IDs in `@biolibs/gel`. */
160
+ gel?: string;
161
+ ladder?: string;
162
+ /** The gel station it was run at, if the lab has one. */
163
+ instrument?: string | null;
164
+ /** Anything worth saying about it. */
165
+ note?: string | null;
166
+ }
167
+
168
+ /** A digest as chosen: what it would give, and what to ask the lab to record. */
169
+ export interface DigestRun {
170
+ /** What the digest would give, or `null` if the tube is not one the lab has. */
171
+ plan: DigestPlan | null;
172
+ /** What to hand to the lab's `recordRun` if the gel matched. `null` while there is nothing to match. */
173
+ matched: Record<string, unknown> | null;
174
+ /** What to hand to it if the gel was run and did not match. `null` likewise. */
175
+ differed: Record<string, unknown> | null;
176
+ }
177
+
178
+ /**
179
+ * Work a choice of tube and enzymes out into a run.
180
+ *
181
+ * A digest here is a check: it uses some of a tube and makes nothing. What is recorded is which
182
+ * enzymes, what pieces were expected, and whether the gel showed them. Keeping a piece as a tube is
183
+ * not offered, because a part cannot yet say what ends it has, and a cut piece is defined by its ends.
184
+ *
185
+ * @param lab - The lab.
186
+ * @param choice - The tube, the enzymes, and how much was used.
187
+ * @returns What it would give, and what to record either way.
188
+ */
189
+ export function digestRun(lab: ToolLab, choice: DigestChoice): DigestRun {
190
+ const item = lab.items.find((one) => one.item === choice.tube);
191
+ const part = item === undefined ? undefined : lab.parts.find((one) => one.checksum === item.part);
192
+ if (part === undefined) return { plan: null, matched: null, differed: null };
193
+ const plan = planDigest(part, choice.enzymes, { ...(choice.gel === undefined ? {} : { gel: choice.gel }), ...(choice.ladder === undefined ? {} : { ladder: choice.ladder }) });
194
+ if (plan.problem !== null) return { plan, matched: null, differed: null };
195
+ const used = choice.used === undefined || !Number.isSafeInteger(choice.used) || choice.used < 0 ? 1 : choice.used;
196
+ const record = {
197
+ kind: "digest", instrument: choice.instrument ?? null,
198
+ inputs: [{ item: choice.tube, amount: used, role: "cut" }],
199
+ outputs: [],
200
+ // Settings are short text, so a digest into very many pieces records as many as fit.
201
+ settings: { enzymes: plan.cutters.map((one) => one.name).join("+").slice(0, 200), expected: plan.fragments.join(",").slice(0, 200), gel: plan.gel },
202
+ note: choice.note ?? null,
203
+ };
204
+ return { plan, matched: { ...record, outcome: "worked" }, differed: { ...record, outcome: "failed" } };
205
+ }
206
+
207
+ /** The tools there are. */
208
+ export type ToolName = "pcr" | "digest";
209
+
210
+ /** The model of instrument each tool is used at. */
211
+ export const TOOL_AT: Readonly<Record<ToolName, string>> = { pcr: "thermocycler", digest: "gel-station" };
212
+
213
+ /**
214
+ * Which tool an instrument opens.
215
+ *
216
+ * @param place - The place, as the lab records it.
217
+ * @returns The tool's name, or `null` if there is none for it yet.
218
+ */
219
+ export function toolFor(place: Pick<PlaceState, "kind" | "fields"> | undefined): ToolName | null {
220
+ if (place?.kind !== "instrument") return null;
221
+ return (Object.keys(TOOL_AT) as ToolName[]).find((tool) => TOOL_AT[tool] === place.fields["model"]) ?? null;
222
+ }
223
+
224
+ /**
225
+ * The instrument a tool would be used at, if the lab has placed one.
226
+ *
227
+ * @param lab - The lab.
228
+ * @param tool - The tool.
229
+ * @returns The first such instrument still in use, or `null`.
230
+ */
231
+ export function instrumentFor(lab: Pick<ToolLab, "places">, tool: ToolName): { id: string; name: string } | null {
232
+ const found = lab.places.find((place) => !place.retired && toolFor(place) === tool);
233
+ return found === undefined ? null : { id: found.place, name: found.name };
234
+ }
package/src/tools.tsx ADDED
@@ -0,0 +1,64 @@
1
+ "use client";
2
+
3
+ /** Getting to a tool: from the instrument it is used at, or from a list of them all. */
4
+ import { useState, type ReactNode } from "react";
5
+ import { useLab } from "@biolibs/bionet-react";
6
+ import { DigestTool } from "./digest-tool.js";
7
+ import { PcrTool } from "./pcr-tool.js";
8
+ import { instrumentFor, toolFor, type ToolName } from "./run.js";
9
+
10
+ /** What each tool is called. */
11
+ export const TOOL_NAMES: Readonly<Record<ToolName, string>> = { pcr: "PCR", digest: "Digest and gel" };
12
+
13
+ function Tool({ tool, instrument, onDone }: { tool: ToolName; instrument: { id: string; name: string } | null; onDone?: (() => void) | undefined }) {
14
+ const more = onDone === undefined ? {} : { onDone };
15
+ return tool === "pcr" ? <PcrTool instrument={instrument} {...more} /> : <DigestTool instrument={instrument} {...more} />;
16
+ }
17
+
18
+ /**
19
+ * The tool an instrument opens.
20
+ *
21
+ * @param props - `place` is the instrument's ID; `onDone` adds a way to leave.
22
+ */
23
+ export function InstrumentTool({ place, onDone }: { place: string; onDone?: () => void }) {
24
+ const lab = useLab()?.lab;
25
+ if (lab === null || lab === undefined) return null;
26
+ const found = lab.places.find((one) => one.place === place);
27
+ const tool = toolFor(found);
28
+ if (tool !== null) return <Tool tool={tool} instrument={{ id: place, name: found!.name }} onDone={onDone} />;
29
+ return (
30
+ <section className="card">
31
+ <div className="toolhead">
32
+ <div>
33
+ <h2>{found?.name ?? "This place"}</h2>
34
+ <p className="dim">There is no tool for this yet. A thermocycler opens PCR, and a gel station opens digest and gel.</p>
35
+ </div>
36
+ {onDone !== undefined && <button type="button" className="quiet" onClick={onDone}>Back to the lab</button>}
37
+ </div>
38
+ </section>
39
+ );
40
+ }
41
+
42
+ /**
43
+ * Every tool, for a lab that has not drawn its room, or for getting to one without walking there.
44
+ *
45
+ * A run is still recorded as done at the instrument for that tool, if the lab has placed one.
46
+ *
47
+ * @param props - `tool` is which to open on; `views` lets a host show a tool its own way, such as
48
+ * at its instrument in a scene, in place of the plain form.
49
+ */
50
+ export function Tools({ tool: first = "pcr", views = {} }: { tool?: ToolName; views?: Partial<Record<ToolName, ReactNode>> }) {
51
+ const lab = useLab()?.lab;
52
+ const [tool, setTool] = useState<ToolName>(first);
53
+ if (lab === null || lab === undefined) return null;
54
+ return (
55
+ <div className="tools">
56
+ <div className="row tight pick" role="tablist" aria-label="Tools">
57
+ {(Object.keys(TOOL_NAMES) as ToolName[]).map((one) => (
58
+ <button key={one} type="button" role="tab" aria-selected={one === tool} className={one === tool ? "" : "quiet"} onClick={() => setTool(one)}>{TOOL_NAMES[one]}</button>
59
+ ))}
60
+ </div>
61
+ {views[tool] ?? <Tool key={tool} tool={tool} instrument={instrumentFor(lab, tool)} />}
62
+ </div>
63
+ );
64
+ }
package/tools.css ADDED
@@ -0,0 +1,50 @@
1
+ /* The tools are drawn with the panels' styles, inside a .bionet window. These are the few of their own. */
2
+ .bionet .pcr { display: grid; gap: 1rem }
3
+ .bionet .toolhead { display: flex; justify-content: space-between; align-items: flex-start; gap: 1rem }
4
+ .bionet .pcr fieldset { border: 0; margin: 0; padding: 0 }
5
+ .bionet .pcr .choose { display: grid; gap: .8rem; margin-top: .8rem }
6
+ .bionet .pcr .tube { display: grid; grid-template-columns: 1fr 6rem; gap: .2rem .7rem; align-items: end }
7
+ .bionet .pcr .tube p { grid-column: 1 / -1; margin: 0 }
8
+ .bionet .pcr .tube select { width: 100% }
9
+ .bionet .pcr .least input { max-width: 6rem }
10
+ .bionet .pcr code.wrap { display: block; margin: .4rem 0 .9rem; word-break: break-all }
11
+ .bionet .tools { display: grid; gap: 1rem }
12
+ .bionet .tools .pick { flex-wrap: wrap }
13
+ .bionet .digest .enzymes { display: flex; flex-wrap: wrap; gap: .3rem 1.1rem; margin: .3rem 0 .7rem }
14
+ .bionet .digest .label { margin: 0; color: var(--bionet-dim) }
15
+ .bionet .digest .result { display: grid; grid-template-columns: minmax(15rem, 20rem) 1fr; gap: 1.4rem; align-items: start; margin-bottom: 1rem }
16
+ @media (max-width: 760px) { .bionet .digest .result { grid-template-columns: 1fr } }
17
+ .bionet .gel { width: 100%; height: auto }
18
+ .bionet .gel .slab { fill: var(--bionet-field, var(--bionet-ground)); stroke: var(--bionet-rule) }
19
+ .bionet .gel .well { fill: var(--bionet-rule) }
20
+ .bionet .gel text { font-size: 9.5px; fill: var(--bionet-dim) }
21
+ .bionet .gel text.size { fill: var(--bionet-ink); font-weight: 600 }
22
+ .bionet .gel text.lane { font-size: 10.5px }
23
+ /* Beside an instrument's scene. */
24
+ .bionet.benchpanel { display: grid; gap: .8rem; font-size: .92rem }
25
+ .bionet.benchpanel .card { padding: .9rem 1rem }
26
+ .bionet.benchpanel fieldset { border: 0; margin: 0; padding: 0 }
27
+ .bionet.benchpanel select { width: 100% }
28
+ .bionet.benchpanel .voice { margin: .9rem 0 .15rem; font-size: .68rem; letter-spacing: .09em; text-transform: uppercase; color: var(--bionet-dim) }
29
+ .bionet.benchpanel .voice + p, .bionet.benchpanel .voice + ul { margin-top: 0 }
30
+ .bionet.benchpanel .programme { display: grid; gap: .45rem }
31
+ .bionet.benchpanel .programme label { display: flex; align-items: center; gap: .5rem }
32
+ .bionet.benchpanel .programme input { width: 5.5rem }
33
+ .bionet.benchpanel .checks { margin: 0; padding-left: 1.1rem; display: grid; gap: .3rem; font-size: .86rem }
34
+ .bionet.benchpanel .checks .stop { color: var(--bionet-attention) }
35
+ .bionet.benchpanel .checks .look { color: var(--bionet-held) }
36
+ .bionet.benchpanel .good { color: var(--bionet-good) }
37
+ .bionet.benchpanel .pick { margin-bottom: .4rem; flex-wrap: wrap; align-items: center }
38
+ .bionet.benchpanel code.wrap { display: block; margin: .3rem 0 .6rem; word-break: break-all; font-size: .78rem }
39
+ .bionet.benchpanel .trace { display: block; width: 100%; max-width: 20rem; height: auto; margin: .2rem 0 .3rem }
40
+ .bionet.benchpanel .trace .line { stroke: var(--bionet-dim); stroke-width: 2; stroke-linejoin: round }
41
+ .bionet.benchpanel .trace .now { fill: var(--bionet-found); opacity: .16 }
42
+ .bionet.benchpanel .trace text { font-size: 9px; fill: var(--bionet-dim) }
43
+ .bionet.benchpanel .trace text.on { fill: var(--bionet-found); font-weight: 600 }
44
+ .bionet.benchpanel .bars { display: grid; gap: .3rem; margin: .2rem 0 .5rem }
45
+ .bionet.benchpanel .bar { display: grid; grid-template-columns: 4.6rem 1fr 6.2rem; align-items: center; gap: .5rem; font-size: .82rem }
46
+ .bionet.benchpanel .bar .track { height: .55rem; border-radius: 999px; background: color-mix(in srgb, var(--bionet-rule) 60%, transparent); overflow: hidden }
47
+ .bionet.benchpanel .bar .fill { display: block; height: 100%; border-radius: 999px; transition: width .2s linear }
48
+ .bionet.benchpanel .bar .fill.template { background: var(--bionet-dim) } .bionet.benchpanel .bar .fill.long { background: var(--bionet-theirs) }
49
+ .bionet.benchpanel .bar .fill.product { background: var(--bionet-held) }
50
+ .bionet.benchpanel .bar .count { text-align: right; font-variant-numeric: tabular-nums }