@biolibs/bionet-tools 0.0.0-stage → 0.1.0
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.
- package/README.md +68 -2
- package/dist/digest-tool.d.ts +30 -0
- package/dist/digest-tool.d.ts.map +1 -0
- package/dist/digest-tool.js +83 -0
- package/dist/digest-tool.js.map +1 -0
- package/dist/digest.d.ts +94 -0
- package/dist/digest.d.ts.map +1 -0
- package/dist/digest.js +115 -0
- package/dist/digest.js.map +1 -0
- package/dist/index.d.ts +25 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +25 -0
- package/dist/index.js.map +1 -0
- package/dist/pcr-tool.d.ts +18 -0
- package/dist/pcr-tool.d.ts.map +1 -0
- package/dist/pcr-tool.js +72 -0
- package/dist/pcr-tool.js.map +1 -0
- package/dist/pcr.d.ts +59 -0
- package/dist/pcr.d.ts.map +1 -0
- package/dist/pcr.js +79 -0
- package/dist/pcr.js.map +1 -0
- package/dist/run.d.ts +158 -0
- package/dist/run.d.ts.map +1 -0
- package/dist/run.js +139 -0
- package/dist/run.js.map +1 -0
- package/dist/tools.d.ts +23 -0
- package/dist/tools.d.ts.map +1 -0
- package/dist/tools.js +44 -0
- package/dist/tools.js.map +1 -0
- package/package.json +60 -4
- package/src/digest-tool.tsx +198 -0
- package/src/digest.ts +136 -0
- package/src/index.ts +24 -0
- package/src/pcr-tool.tsx +159 -0
- package/src/pcr.ts +87 -0
- package/src/run.ts +227 -0
- package/src/tools.tsx +63 -0
- package/tools.css +22 -0
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A check digest from the freezer, with the gel it should give.
|
|
5
|
+
*
|
|
6
|
+
* Like the PCR tool it holds only what has been chosen. The pieces and the gel come from
|
|
7
|
+
* `planDigest`, and recording is one thing asked of the lab.
|
|
8
|
+
*/
|
|
9
|
+
import { useMemo, useState } from "react";
|
|
10
|
+
import type { Band } from "@biolibs/gel";
|
|
11
|
+
import { GELS, LADDERS } from "@biolibs/gel";
|
|
12
|
+
import { useAct, useLab } from "@biolibs/bionet-react";
|
|
13
|
+
import { cutters, enzymeNamed } from "./digest.js";
|
|
14
|
+
import { digestRun, digestTubes } from "./run.js";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* A gel, drawn: a ladder in one lane and the digest in the next.
|
|
18
|
+
*
|
|
19
|
+
* @param props - `ladder` and `bands` are what `planDigest` gave; `name` is what the sample is called.
|
|
20
|
+
*/
|
|
21
|
+
export function Gel({ ladder, bands, name }: { ladder: readonly Band[]; bands: readonly Band[]; name: string }) {
|
|
22
|
+
const [top, height] = [26, 250];
|
|
23
|
+
const lane = (x: number, drawn: readonly Band[], tone: string, labelled: "left" | "right"): React.ReactNode => drawn.map((band, at) => {
|
|
24
|
+
const y = top + 10 + band.position * (height - 24);
|
|
25
|
+
return (
|
|
26
|
+
<g key={`${x} ${at}`}>
|
|
27
|
+
<rect x={x} y={y - 1.6} width={54} height={3.2} rx={1.2} fill={tone} opacity={0.3 + 0.7 * band.intensity} />
|
|
28
|
+
<text x={labelled === "left" ? x - 6 : x + 60} y={y + 3.5} textAnchor={labelled === "left" ? "end" : "start"} className={labelled === "left" ? "mark" : "size"}>
|
|
29
|
+
{band.sizes.length > 1 ? `${band.sizes.join(" + ")}` : band.size}{band.unresolved ? " *" : ""}
|
|
30
|
+
</text>
|
|
31
|
+
</g>
|
|
32
|
+
);
|
|
33
|
+
});
|
|
34
|
+
return (
|
|
35
|
+
<svg className="gel" viewBox="0 0 330 290" role="img" aria-label={`A gel: a ladder beside ${name}, cut into pieces of ${bands.flatMap((band) => band.sizes).join(", ")} base pairs`}>
|
|
36
|
+
<rect x={52} y={top} width={176} height={height} rx={6} className="slab" />
|
|
37
|
+
<text x={89} y={16} textAnchor="middle" className="lane">ladder</text>
|
|
38
|
+
<text x={177} y={16} textAnchor="middle" className="lane">{name.length > 16 ? `${name.slice(0, 15)}…` : name}</text>
|
|
39
|
+
<rect x={62} y={top + 4} width={54} height={4} className="well" />
|
|
40
|
+
<rect x={150} y={top + 4} width={54} height={4} className="well" />
|
|
41
|
+
{lane(62, ladder, "var(--bionet-dim)", "left")}
|
|
42
|
+
{lane(150, bands, "var(--bionet-held)", "right")}
|
|
43
|
+
</svg>
|
|
44
|
+
);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Cut a tube's molecule in silico, see the gel it should give, and record whether the real gel matched.
|
|
49
|
+
*
|
|
50
|
+
* Choose a tube and one or more enzymes. The enzymes usually on a shelf that cut it are offered,
|
|
51
|
+
* the ones that cut fewest times first, and any other can be named. The pieces are listed and drawn
|
|
52
|
+
* as a gel beside a ladder. Recording takes what was used from the tube and notes whether the gel
|
|
53
|
+
* showed what was expected; nothing is made.
|
|
54
|
+
*
|
|
55
|
+
* @param props - `instrument` is the gel station it is run at, if the lab has one; `onDone` adds a
|
|
56
|
+
* way to leave.
|
|
57
|
+
*/
|
|
58
|
+
export function DigestTool({ instrument = null, onDone }: { instrument?: { id: string; name: string } | null; onDone?: () => void }) {
|
|
59
|
+
const lab = useLab()?.lab;
|
|
60
|
+
const act = useAct();
|
|
61
|
+
const [tube, setTube] = useState("");
|
|
62
|
+
const [chosen, setChosen] = useState<string[]>([]);
|
|
63
|
+
const [other, setOther] = useState("");
|
|
64
|
+
const [unknown, setUnknown] = useState<string | null>(null);
|
|
65
|
+
const [used, setUsed] = useState("1");
|
|
66
|
+
const [gel, setGel] = useState("1.0");
|
|
67
|
+
const [ladder, setLadder] = useState("1kb");
|
|
68
|
+
const [note, setNote] = useState("");
|
|
69
|
+
const [busy, setBusy] = useState(false);
|
|
70
|
+
const [said, setSaid] = useState<string | null>(null);
|
|
71
|
+
|
|
72
|
+
const tubes = useMemo(() => (lab === null || lab === undefined ? [] : digestTubes(lab)), [lab]);
|
|
73
|
+
const part = tubes.find((one) => one.item === tube)?.part;
|
|
74
|
+
const offered = useMemo(() => (part === undefined ? [] : cutters(part)), [part]);
|
|
75
|
+
const run = useMemo(() => (lab === null || lab === undefined ? null : digestRun(lab, {
|
|
76
|
+
tube, enzymes: chosen, gel, ladder, instrument: instrument?.id ?? null, note, ...(used.trim() === "" ? {} : { used: Number(used) }),
|
|
77
|
+
})), [lab, tube, chosen, gel, ladder, instrument, note, used]);
|
|
78
|
+
if (lab === null || lab === undefined || run === null) return null;
|
|
79
|
+
|
|
80
|
+
const toggle = (name: string): void => { setChosen(chosen.includes(name) ? chosen.filter((one) => one !== name) : [...chosen, name]); setSaid(null); };
|
|
81
|
+
const record = async (what: Record<string, unknown> | null, done: string): Promise<void> => {
|
|
82
|
+
if (what === null) return;
|
|
83
|
+
setBusy(true);
|
|
84
|
+
const answer = await act("recordRun", what);
|
|
85
|
+
setBusy(false);
|
|
86
|
+
if (answer.ok) { setSaid(done); setNote(""); }
|
|
87
|
+
};
|
|
88
|
+
const here = lab.runs.filter((one) => one.kind === "digest" && (instrument === null || one.instrument === instrument.id)).slice(-5).reverse();
|
|
89
|
+
const partName = (item: string | undefined): string => lab.parts.find((one) => one.checksum === lab.items.find((each) => each.item === item)?.part)?.name ?? "a tube";
|
|
90
|
+
|
|
91
|
+
return (
|
|
92
|
+
<div className="pcr digest">
|
|
93
|
+
<section className="card">
|
|
94
|
+
<div className="toolhead">
|
|
95
|
+
<div>
|
|
96
|
+
<h2>Digest and gel{instrument === null ? "" : ` · ${instrument.name}`}</h2>
|
|
97
|
+
<p className="dim small">Choose a tube and the enzymes to cut it with. The pieces are worked out from its sequence, and drawn as the gel they should give.</p>
|
|
98
|
+
</div>
|
|
99
|
+
{onDone !== undefined && <button type="button" className="quiet" onClick={onDone}>Back to the lab</button>}
|
|
100
|
+
</div>
|
|
101
|
+
{tubes.length === 0 ? <p className="empty">There are no tubes to digest. Add a part and a tube of it on the Freezer tab.</p> : (
|
|
102
|
+
<fieldset disabled={busy} className="choose">
|
|
103
|
+
<div className="tube">
|
|
104
|
+
<label>Tube
|
|
105
|
+
<select value={tube} onChange={(event) => { setTube(event.target.value); setChosen([]); setSaid(null); }} aria-label="Tube">
|
|
106
|
+
<option value="">Choose a tube…</option>
|
|
107
|
+
{tubes.map((one) => <option key={one.item} value={one.item}>{one.label}</option>)}
|
|
108
|
+
</select>
|
|
109
|
+
</label>
|
|
110
|
+
<label className="used">used<input type="number" min={0} step={1} value={used} onChange={(event) => setUsed(event.target.value)} aria-label="Amount used" /></label>
|
|
111
|
+
{part !== undefined && <p className="dim small">{part.length} bp{part.circular ? " · circular" : " · linear"}</p>}
|
|
112
|
+
</div>
|
|
113
|
+
{part !== undefined && (
|
|
114
|
+
<div>
|
|
115
|
+
<p className="label">Enzymes{offered.length === 0 ? " · none of the usual ones cut this" : ""}</p>
|
|
116
|
+
<div className="enzymes">
|
|
117
|
+
{offered.map((one) => (
|
|
118
|
+
<label key={one.name} className="check" title={`${one.site} · cuts ${one.positions.length === 1 ? "once" : `${one.positions.length} times`}`}>
|
|
119
|
+
<input type="checkbox" checked={chosen.includes(one.name)} onChange={() => toggle(one.name)} /> {one.name} <span className="dim small">×{one.positions.length}</span>
|
|
120
|
+
</label>
|
|
121
|
+
))}
|
|
122
|
+
{chosen.filter((name) => !offered.some((one) => one.name === name)).map((name) => (
|
|
123
|
+
<label key={name} className="check"><input type="checkbox" checked onChange={() => toggle(name)} /> {name}</label>
|
|
124
|
+
))}
|
|
125
|
+
</div>
|
|
126
|
+
<form className="row tight" onSubmit={(event) => {
|
|
127
|
+
event.preventDefault();
|
|
128
|
+
const name = enzymeNamed(other);
|
|
129
|
+
setUnknown(name === null && other.trim() !== "" ? other.trim() : null);
|
|
130
|
+
if (name !== null && !chosen.includes(name)) setChosen([...chosen, name]);
|
|
131
|
+
if (name !== null) setOther("");
|
|
132
|
+
}}>
|
|
133
|
+
<input value={other} onChange={(event) => setOther(event.target.value)} placeholder="Another enzyme, by name" aria-label="Another enzyme" maxLength={40} spellCheck={false} />
|
|
134
|
+
<button type="submit" className="quiet">Add</button>
|
|
135
|
+
</form>
|
|
136
|
+
{unknown !== null && <p className="trouble small" role="status">There is no enzyme called {unknown} here.</p>}
|
|
137
|
+
</div>
|
|
138
|
+
)}
|
|
139
|
+
</fieldset>
|
|
140
|
+
)}
|
|
141
|
+
</section>
|
|
142
|
+
|
|
143
|
+
{run.plan !== null && chosen.length > 0 && (
|
|
144
|
+
<section className="card">
|
|
145
|
+
<h2>What it gives</h2>
|
|
146
|
+
{run.plan.problem !== null ? <p className="trouble" role="status">{run.plan.problem}</p> : (
|
|
147
|
+
<div className="result">
|
|
148
|
+
<Gel ladder={run.plan.ladder} bands={run.plan.bands} name={part?.name ?? "digest"} />
|
|
149
|
+
<div>
|
|
150
|
+
<p><strong>{run.plan.fragments.length} {run.plan.fragments.length === 1 ? "piece" : "pieces"}</strong> <span className="dim">{run.plan.fragments.join(", ")} bp</span></p>
|
|
151
|
+
<table>
|
|
152
|
+
<thead><tr><th>Enzyme</th><th>Site</th><th>Cuts after base</th></tr></thead>
|
|
153
|
+
<tbody>{run.plan.cutters.map((one) => <tr key={one.name}><td>{one.name}</td><td><code>{one.site}</code></td><td>{one.positions.length === 0 ? <span className="dim">does not cut</span> : one.positions.join(", ")}</td></tr>)}</tbody>
|
|
154
|
+
</table>
|
|
155
|
+
<div className="row tight">
|
|
156
|
+
<label>Gel<select value={gel} onChange={(event) => setGel(event.target.value)}>{GELS.map((one) => <option key={one.id} value={one.id}>{one.percent}% agarose</option>)}</select></label>
|
|
157
|
+
<label>Ladder<select value={ladder} onChange={(event) => setLadder(event.target.value)}>{LADDERS.map((one) => <option key={one.id} value={one.id}>{one.name}</option>)}</select></label>
|
|
158
|
+
</div>
|
|
159
|
+
{run.plan.bands.some((band) => band.unresolved) && <p className="dim small">* outside what this gel separates. Try another concentration.</p>}
|
|
160
|
+
{run.plan.bands.some((band) => band.sizes.length > 1) && <p className="dim small">Pieces too close in size to tell apart run as one band.</p>}
|
|
161
|
+
</div>
|
|
162
|
+
</div>
|
|
163
|
+
)}
|
|
164
|
+
{run.plan.problem === null && (
|
|
165
|
+
<fieldset disabled={busy} className="stack">
|
|
166
|
+
<label>Note<input value={note} onChange={(event) => setNote(event.target.value)} placeholder="Anything worth remembering about this gel" maxLength={2000} /></label>
|
|
167
|
+
<div className="row">
|
|
168
|
+
<button type="button" onClick={() => void record(run.matched, "Recorded: the gel showed what was expected.")}>The gel matched</button>
|
|
169
|
+
<button type="button" className="quiet" onClick={() => void record(run.differed, "Recorded: the gel did not show what was expected.")}>The gel did not match</button>
|
|
170
|
+
</div>
|
|
171
|
+
</fieldset>
|
|
172
|
+
)}
|
|
173
|
+
{said !== null && <p className="small" role="status">{said}</p>}
|
|
174
|
+
</section>
|
|
175
|
+
)}
|
|
176
|
+
|
|
177
|
+
{here.length > 0 && (
|
|
178
|
+
<section className="card">
|
|
179
|
+
<h2>Recent digests{instrument === null ? "" : " here"}</h2>
|
|
180
|
+
<table>
|
|
181
|
+
<thead><tr><th>Tube</th><th>Enzymes</th><th>Expected</th><th>Gel</th><th>Note</th></tr></thead>
|
|
182
|
+
<tbody>
|
|
183
|
+
{here.map((one) => (
|
|
184
|
+
<tr key={one.run}>
|
|
185
|
+
<td>{partName(one.inputs[0]?.item)}</td>
|
|
186
|
+
<td>{String(one.settings["enzymes"] ?? "").replace(/\+/g, " + ")}</td>
|
|
187
|
+
<td className="dim">{String(one.settings["expected"] ?? "")}</td>
|
|
188
|
+
<td>{one.outcome === "worked" ? "matched" : <span className="badge">did not match</span>}</td>
|
|
189
|
+
<td className="dim">{one.note ?? ""}</td>
|
|
190
|
+
</tr>
|
|
191
|
+
))}
|
|
192
|
+
</tbody>
|
|
193
|
+
</table>
|
|
194
|
+
</section>
|
|
195
|
+
)}
|
|
196
|
+
</div>
|
|
197
|
+
);
|
|
198
|
+
}
|
package/src/digest.ts
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A restriction digest, and the gel it would give, worked out before either is run.
|
|
3
|
+
*
|
|
4
|
+
* Given a molecule and some enzymes this says where they cut, how long the pieces are, and where
|
|
5
|
+
* each piece would run on a gel beside a ladder. Like `pcr.ts` it knows sequences and nothing of
|
|
6
|
+
* the lab.
|
|
7
|
+
*/
|
|
8
|
+
import { bandsOf, fragmentSizes, gelById, ladderBands, ladderById, type Band } from "@biolibs/gel";
|
|
9
|
+
import { enzymes } from "@biolibs/restriction";
|
|
10
|
+
import { Seq } from "@biolibs/seq";
|
|
11
|
+
|
|
12
|
+
/** The enzymes offered first: the ones most often on a lab's shelf. Any other may be named. */
|
|
13
|
+
export const COMMON_ENZYMES: readonly string[] = [
|
|
14
|
+
"EcoRI", "BamHI", "HindIII", "XhoI", "NotI", "XbaI", "SpeI", "PstI", "NcoI", "NdeI", "KpnI", "SacI",
|
|
15
|
+
"SalI", "EcoRV", "SmaI", "BglII", "NheI", "AgeI", "ApaI", "ClaI", "MluI", "BsaI", "BsmBI", "DpnI",
|
|
16
|
+
];
|
|
17
|
+
|
|
18
|
+
/** The gel a digest is run on unless somebody says otherwise: 1% agarose. */
|
|
19
|
+
export const USUAL_GEL = "1.0";
|
|
20
|
+
|
|
21
|
+
/** The ladder run beside it unless somebody says otherwise. */
|
|
22
|
+
export const USUAL_LADDER = "1kb";
|
|
23
|
+
|
|
24
|
+
/** One enzyme and where it cuts a molecule. */
|
|
25
|
+
export interface Cutter {
|
|
26
|
+
/** The enzyme's name. */
|
|
27
|
+
name: string;
|
|
28
|
+
/** The sequence it recognises. */
|
|
29
|
+
site: string;
|
|
30
|
+
/** Where it cuts, counted from the start of the molecule, in order. */
|
|
31
|
+
positions: number[];
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** What a digest would give. */
|
|
35
|
+
export interface DigestPlan {
|
|
36
|
+
/** Each enzyme asked for that is a real one, and where it cuts. */
|
|
37
|
+
cutters: Cutter[];
|
|
38
|
+
/** How long each piece is, longest first. */
|
|
39
|
+
fragments: number[];
|
|
40
|
+
/** The bands the pieces would show. */
|
|
41
|
+
bands: Band[];
|
|
42
|
+
/** The bands of the ladder beside them. */
|
|
43
|
+
ladder: Band[];
|
|
44
|
+
/** The gel and the ladder it was worked out for. */
|
|
45
|
+
gel: string;
|
|
46
|
+
ladderName: string;
|
|
47
|
+
/** Why there is nothing to look at, said for a person, or `null` if there is. */
|
|
48
|
+
problem: string | null;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
const clean = (text: string): string => text.replace(/\s+/g, "").toUpperCase();
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Find an enzyme whatever case its name was typed in.
|
|
55
|
+
*
|
|
56
|
+
* @param name - Something like `ecori`.
|
|
57
|
+
* @returns Its name as it is written, or `null` if there is no such enzyme.
|
|
58
|
+
*/
|
|
59
|
+
export function enzymeNamed(name: string): string | null {
|
|
60
|
+
const typed = name.trim();
|
|
61
|
+
if (typed === "") return null;
|
|
62
|
+
if (Object.hasOwn(enzymes, typed)) return typed;
|
|
63
|
+
const lower = typed.toLowerCase();
|
|
64
|
+
return Object.keys(enzymes).find((one) => one.toLowerCase() === lower) ?? null;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Where one enzyme cuts a molecule.
|
|
69
|
+
*
|
|
70
|
+
* @param part - The molecule.
|
|
71
|
+
* @param name - The enzyme, by its name as written.
|
|
72
|
+
* @returns The enzyme and its cuts, or `null` if there is no such enzyme or the molecule is not a sequence.
|
|
73
|
+
*/
|
|
74
|
+
export function cutsOf(part: { sequence: string; circular: boolean }, name: string): Cutter | null {
|
|
75
|
+
const enzyme = Object.hasOwn(enzymes, name) ? enzymes[name] : undefined;
|
|
76
|
+
if (enzyme === undefined) return null;
|
|
77
|
+
const bases = clean(part.sequence);
|
|
78
|
+
try {
|
|
79
|
+
// The engine counts from 1 and gives the base after the cut.
|
|
80
|
+
const found = enzyme.search(new Seq(bases), !part.circular).map((at) => (at - 1 + bases.length) % bases.length);
|
|
81
|
+
return { name, site: String(enzyme.site), positions: [...new Set(found)].sort((a, b) => a - b) };
|
|
82
|
+
} catch {
|
|
83
|
+
return null;
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* The enzymes, of those usually on a shelf, that cut a molecule.
|
|
89
|
+
*
|
|
90
|
+
* @param part - The molecule.
|
|
91
|
+
* @param names - The enzymes to try.
|
|
92
|
+
* @returns Those that cut it, the ones that cut fewest times first, since one or two cuts is what a
|
|
93
|
+
* check digest wants.
|
|
94
|
+
*/
|
|
95
|
+
export function cutters(part: { sequence: string; circular: boolean }, names: readonly string[] = COMMON_ENZYMES): Cutter[] {
|
|
96
|
+
return names.map((name) => cutsOf(part, name)).filter((one): one is Cutter => one !== null && one.positions.length > 0)
|
|
97
|
+
.sort((a, b) => a.positions.length - b.positions.length || a.name.localeCompare(b.name));
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Work out a digest and the gel it would give.
|
|
102
|
+
*
|
|
103
|
+
* @param part - The molecule.
|
|
104
|
+
* @param names - The enzymes, by name.
|
|
105
|
+
* @param options - `gel` is the agarose concentration's ID and `ladder` the ladder's, from `@biolibs/gel`.
|
|
106
|
+
* @returns The cuts, the pieces, the bands, and what is wrong if there is nothing to look at.
|
|
107
|
+
*
|
|
108
|
+
* @example
|
|
109
|
+
* ```ts
|
|
110
|
+
* import { planDigest } from "@biolibs/bionet-tools";
|
|
111
|
+
*
|
|
112
|
+
* const plan = planDigest({ sequence: "AAAAAAAAAAGAATTCAAAAAAAAAAAAAAAAAAAAGGATCCAAAAAAAAAA", circular: true }, ["EcoRI", "BamHI"]);
|
|
113
|
+
* plan.fragments; // [ 26, 26 ]
|
|
114
|
+
* plan.problem; // null
|
|
115
|
+
* ```
|
|
116
|
+
*/
|
|
117
|
+
export function planDigest(part: { sequence: string; circular: boolean }, names: readonly string[],
|
|
118
|
+
options: { gel?: string; ladder?: string } = {}): DigestPlan {
|
|
119
|
+
let gel = gelById(USUAL_GEL);
|
|
120
|
+
let ladder = ladderById(USUAL_LADDER);
|
|
121
|
+
try { gel = gelById(options.gel ?? USUAL_GEL); } catch { /* an unknown gel is run as the usual one */ }
|
|
122
|
+
try { ladder = ladderById(options.ladder ?? USUAL_LADDER); } catch { /* and an unknown ladder likewise */ }
|
|
123
|
+
const length = clean(part.sequence).length;
|
|
124
|
+
const found = [...new Set(names)].map((name) => cutsOf(part, name)).filter((one): one is Cutter => one !== null);
|
|
125
|
+
const empty = { cutters: found, fragments: [], bands: [], ladder: ladderBands(ladder.sizes, gel), gel: gel.id, ladderName: ladder.name };
|
|
126
|
+
if (names.length === 0) return { ...empty, problem: "Choose at least one enzyme." };
|
|
127
|
+
if (found.length === 0) return { ...empty, problem: "None of those is an enzyme this knows." };
|
|
128
|
+
const cuts = [...new Set(found.flatMap((one) => one.positions))];
|
|
129
|
+
if (cuts.length === 0) return { ...empty, problem: `${found.map((one) => one.name).join(" and ")} ${found.length === 1 ? "does" : "do"} not cut this.` };
|
|
130
|
+
try {
|
|
131
|
+
const fragments = fragmentSizes(length, part.circular ? "circular" : "linear", cuts).sort((a, b) => b - a);
|
|
132
|
+
return { ...empty, fragments, bands: bandsOf(fragments, gel), problem: null };
|
|
133
|
+
} catch {
|
|
134
|
+
return { ...empty, problem: "That could not be cut into pieces." };
|
|
135
|
+
}
|
|
136
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @packageDocumentation
|
|
3
|
+
* `@biolibs/bionet-tools`: the tools a lab uses at the bench, tied to its freezer.
|
|
4
|
+
*
|
|
5
|
+
* A tool here works on the tubes a lab holds and records what was done with them. Running a PCR is
|
|
6
|
+
* choosing a template and two primers from the freezer, seeing what they would make, and recording
|
|
7
|
+
* the run: the template and primers drop by what was used, and the product is a new tube that knows
|
|
8
|
+
* which run made it.
|
|
9
|
+
*
|
|
10
|
+
* - `pcr.ts` — what a PCR would make, worked out from sequences alone
|
|
11
|
+
* - `digest.ts` — where enzymes cut, the pieces, and the gel they would give
|
|
12
|
+
* - `run.ts` — a PCR as a lab does one: which tubes, and what to record
|
|
13
|
+
* - `pcr-tool.tsx`, `digest-tool.tsx` — the tools
|
|
14
|
+
* - `tools.tsx` — getting to one: from an instrument, or from a list of them all
|
|
15
|
+
*
|
|
16
|
+
* The tools are drawn with the styles of `@biolibs/bionet-panels` and belong inside its `LabWindow`.
|
|
17
|
+
* Import `@biolibs/bionet-tools/tools.css` once.
|
|
18
|
+
*/
|
|
19
|
+
export * from "./pcr.js";
|
|
20
|
+
export * from "./digest.js";
|
|
21
|
+
export * from "./run.js";
|
|
22
|
+
export * from "./pcr-tool.js";
|
|
23
|
+
export * from "./digest-tool.js";
|
|
24
|
+
export * from "./tools.js";
|
package/src/pcr-tool.tsx
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Running a PCR from the freezer.
|
|
5
|
+
*
|
|
6
|
+
* It holds only what has been chosen. The tubes come from the lab, what the PCR would make comes
|
|
7
|
+
* from `planPcr`, and recording it is one thing asked of the lab. It is drawn with the panels'
|
|
8
|
+
* styles, so it belongs inside a `LabWindow`.
|
|
9
|
+
*/
|
|
10
|
+
import { useMemo, useState } from "react";
|
|
11
|
+
import { useAct, useLab } from "@biolibs/bionet-react";
|
|
12
|
+
import { primerTm } from "./pcr.js";
|
|
13
|
+
import { pcrRun, pcrTubes, type TubeChoice } from "./run.js";
|
|
14
|
+
|
|
15
|
+
const whole = (text: string): number | undefined => (text.trim() === "" ? undefined : Number(text));
|
|
16
|
+
|
|
17
|
+
function Tube({ label, name, choices, value, onChange, used, onUsed }: {
|
|
18
|
+
label: string; name: string; choices: TubeChoice[]; value: string; onChange: (item: string) => void; used: string; onUsed: (amount: string) => void;
|
|
19
|
+
}) {
|
|
20
|
+
const chosen = choices.find((one) => one.item === value);
|
|
21
|
+
const tm = chosen !== undefined && name !== "template" ? primerTm(chosen.part.sequence) : null;
|
|
22
|
+
return (
|
|
23
|
+
<div className="tube">
|
|
24
|
+
<label>{label}
|
|
25
|
+
<select value={value} onChange={(event) => onChange(event.target.value)} aria-label={label}>
|
|
26
|
+
<option value="">Choose a tube…</option>
|
|
27
|
+
{choices.map((one) => <option key={one.item} value={one.item}>{one.label}</option>)}
|
|
28
|
+
</select>
|
|
29
|
+
</label>
|
|
30
|
+
<label className="used">used<input type="number" min={0} step={1} value={used} onChange={(event) => onUsed(event.target.value)} aria-label={`${label}, amount used`} /></label>
|
|
31
|
+
{chosen !== undefined && (
|
|
32
|
+
<p className="dim small">{chosen.part.length} {chosen.part.length === 1 ? "base" : "bases"}{chosen.part.circular ? " · circular" : ""}{tm === null ? "" : ` · about ${Math.round(tm)} °C`}</p>
|
|
33
|
+
)}
|
|
34
|
+
</div>
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Run a PCR in silico from tubes the lab holds, and record it.
|
|
40
|
+
*
|
|
41
|
+
* Choose a template and two primers. If they make one product it is shown, and the run can be
|
|
42
|
+
* recorded: each tube drops by what was used and the product becomes a new tube. A run that gave
|
|
43
|
+
* nothing at the bench can be recorded too, since the tubes were used all the same.
|
|
44
|
+
*
|
|
45
|
+
* @param props - `instrument` is the thermocycler it is run on, if the lab has one; `onDone` adds a
|
|
46
|
+
* way to leave.
|
|
47
|
+
*/
|
|
48
|
+
export function PcrTool({ instrument = null, onDone }: { instrument?: { id: string; name: string } | null; onDone?: () => void }) {
|
|
49
|
+
const lab = useLab()?.lab;
|
|
50
|
+
const act = useAct();
|
|
51
|
+
const [template, setTemplate] = useState("");
|
|
52
|
+
const [forward, setForward] = useState("");
|
|
53
|
+
const [reverse, setReverse] = useState("");
|
|
54
|
+
const [used, setUsed] = useState({ template: "1", forward: "1", reverse: "1" });
|
|
55
|
+
const [least, setLeast] = useState("18");
|
|
56
|
+
const [name, setName] = useState("");
|
|
57
|
+
const [amount, setAmount] = useState("50");
|
|
58
|
+
const [unit, setUnit] = useState("µL");
|
|
59
|
+
const [note, setNote] = useState("");
|
|
60
|
+
const [busy, setBusy] = useState(false);
|
|
61
|
+
const [said, setSaid] = useState<string | null>(null);
|
|
62
|
+
|
|
63
|
+
const tubes = useMemo(() => (lab === null || lab === undefined ? { templates: [], primers: [] } : pcrTubes(lab)), [lab]);
|
|
64
|
+
const run = useMemo(() => (lab === null || lab === undefined ? null : pcrRun(lab, {
|
|
65
|
+
template, forward, reverse, instrument: instrument?.id ?? null, name, note,
|
|
66
|
+
used: { template: whole(used.template), forward: whole(used.forward), reverse: whole(used.reverse) },
|
|
67
|
+
annealAtLeast: whole(least), amount: whole(amount), unit: unit.trim() === "" ? null : unit.trim(),
|
|
68
|
+
} as Parameters<typeof pcrRun>[1])), [lab, template, forward, reverse, instrument, name, note, used, least, amount, unit]);
|
|
69
|
+
if (lab === null || lab === undefined || run === null) return null;
|
|
70
|
+
|
|
71
|
+
const record = async (what: Record<string, unknown> | null, done: string): Promise<void> => {
|
|
72
|
+
if (what === null) return;
|
|
73
|
+
setBusy(true);
|
|
74
|
+
const answer = await act("recordRun", what);
|
|
75
|
+
setBusy(false);
|
|
76
|
+
if (!answer.ok) return;
|
|
77
|
+
setSaid(done);
|
|
78
|
+
setName("");
|
|
79
|
+
setNote("");
|
|
80
|
+
};
|
|
81
|
+
const product = run.plan !== null && run.plan.problem === null ? run.plan.products[0]! : null;
|
|
82
|
+
const here = lab.runs.filter((one) => one.kind === "pcr" && (instrument === null || one.instrument === instrument.id)).slice(-5).reverse();
|
|
83
|
+
const partName = (checksum: string): string => lab.parts.find((part) => part.checksum === checksum)?.name ?? "a part";
|
|
84
|
+
|
|
85
|
+
return (
|
|
86
|
+
<div className="pcr">
|
|
87
|
+
<section className="card">
|
|
88
|
+
<div className="toolhead">
|
|
89
|
+
<div>
|
|
90
|
+
<h2>PCR{instrument === null ? "" : ` · ${instrument.name}`}</h2>
|
|
91
|
+
<p className="dim small">Choose tubes from the freezer. The product is worked out from their sequences, and recording the run takes what was used from each.</p>
|
|
92
|
+
</div>
|
|
93
|
+
{onDone !== undefined && <button type="button" className="quiet" onClick={onDone}>Back to the lab</button>}
|
|
94
|
+
</div>
|
|
95
|
+
{tubes.templates.length === 0 ? <p className="empty">There are no tubes to run a PCR from. Add a part and a tube of it on the Freezer tab.</p> : (
|
|
96
|
+
<fieldset disabled={busy} className="choose">
|
|
97
|
+
<Tube label="Template" name="template" choices={tubes.templates} value={template} onChange={(item) => { setTemplate(item); setSaid(null); }}
|
|
98
|
+
used={used.template} onUsed={(value) => setUsed({ ...used, template: value })} />
|
|
99
|
+
<Tube label="Forward primer" name="forward" choices={tubes.primers} value={forward} onChange={(item) => { setForward(item); setSaid(null); }}
|
|
100
|
+
used={used.forward} onUsed={(value) => setUsed({ ...used, forward: value })} />
|
|
101
|
+
<Tube label="Reverse primer" name="reverse" choices={tubes.primers} value={reverse} onChange={(item) => { setReverse(item); setSaid(null); }}
|
|
102
|
+
used={used.reverse} onUsed={(value) => setUsed({ ...used, reverse: value })} />
|
|
103
|
+
<label className="least">Bases at each primer's 3′ end that must bind
|
|
104
|
+
<input type="number" min={8} max={60} step={1} value={least} onChange={(event) => setLeast(event.target.value)} />
|
|
105
|
+
</label>
|
|
106
|
+
</fieldset>
|
|
107
|
+
)}
|
|
108
|
+
</section>
|
|
109
|
+
|
|
110
|
+
{run.plan !== null && (
|
|
111
|
+
<section className="card">
|
|
112
|
+
<h2>What it makes</h2>
|
|
113
|
+
{product === null ? <p className="trouble" role="status">{run.plan.problem}</p> : (
|
|
114
|
+
<>
|
|
115
|
+
<p><strong>{product.length} bp</strong> <span className="dim">linear</span></p>
|
|
116
|
+
<code className="wrap">{product.length <= 120 ? product.sequence : `${product.sequence.slice(0, 60)} … ${product.sequence.slice(-60)}`}</code>
|
|
117
|
+
</>
|
|
118
|
+
)}
|
|
119
|
+
<fieldset disabled={busy} className="stack">
|
|
120
|
+
{product !== null && (
|
|
121
|
+
<div className="row tight">
|
|
122
|
+
<label>Call the product<input value={name} onChange={(event) => setName(event.target.value)} placeholder={run.name} maxLength={200} /></label>
|
|
123
|
+
<label>Amount<input type="number" min={0} step={1} value={amount} onChange={(event) => setAmount(event.target.value)} className="num" /></label>
|
|
124
|
+
<label>Unit<input value={unit} onChange={(event) => setUnit(event.target.value)} maxLength={20} className="num" /></label>
|
|
125
|
+
</div>
|
|
126
|
+
)}
|
|
127
|
+
<label>Note<input value={note} onChange={(event) => setNote(event.target.value)} placeholder="Anything worth remembering about this run" maxLength={2000} /></label>
|
|
128
|
+
<div className="row">
|
|
129
|
+
{product !== null && <button type="button" onClick={() => void record(run.worked, `Recorded. There is a new tube of ${run.name}, not yet put anywhere.`)}>Record the run</button>}
|
|
130
|
+
<button type="button" className="quiet" onClick={() => void record(run.failed, "Recorded as a run that gave nothing. The tubes were used all the same.")}>It was run and gave nothing</button>
|
|
131
|
+
</div>
|
|
132
|
+
</fieldset>
|
|
133
|
+
{said !== null && <p className="small" role="status">{said}</p>}
|
|
134
|
+
</section>
|
|
135
|
+
)}
|
|
136
|
+
|
|
137
|
+
{here.length > 0 && (
|
|
138
|
+
<section className="card">
|
|
139
|
+
<h2>Recent runs{instrument === null ? "" : " here"}</h2>
|
|
140
|
+
<table>
|
|
141
|
+
<thead><tr><th>Template</th><th>Made</th><th>Note</th></tr></thead>
|
|
142
|
+
<tbody>
|
|
143
|
+
{here.map((one) => {
|
|
144
|
+
const from = lab.items.find((item) => item.item === one.inputs.find((input) => input.role === "template")?.item);
|
|
145
|
+
return (
|
|
146
|
+
<tr key={one.run}>
|
|
147
|
+
<td>{from === undefined ? "a tube" : partName(from.part)}</td>
|
|
148
|
+
<td>{one.outcome === "worked" ? one.outputs.map((made) => partName(made.part)).join(", ") : <span className="badge">gave nothing</span>}</td>
|
|
149
|
+
<td className="dim">{one.note ?? ""}</td>
|
|
150
|
+
</tr>
|
|
151
|
+
);
|
|
152
|
+
})}
|
|
153
|
+
</tbody>
|
|
154
|
+
</table>
|
|
155
|
+
</section>
|
|
156
|
+
)}
|
|
157
|
+
</div>
|
|
158
|
+
);
|
|
159
|
+
}
|
package/src/pcr.ts
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A PCR, worked out before it is run.
|
|
3
|
+
*
|
|
4
|
+
* Given a template and two primers this says what would come out, using the same engine the cloning
|
|
5
|
+
* plans use. It decides nothing about the lab: it takes sequences and returns sequences, so the same
|
|
6
|
+
* answer can be shown in a window, checked in a test, or worked out again by somebody who was sent
|
|
7
|
+
* the run.
|
|
8
|
+
*/
|
|
9
|
+
import { Primer, pcrAssembly } from "@biolibs/assembly2";
|
|
10
|
+
import { Dseqrecord } from "@biolibs/dseqrecord";
|
|
11
|
+
import { tmWallace } from "@biolibs/seqtools";
|
|
12
|
+
|
|
13
|
+
/** How many bases at a primer's 3′ end have to bind, unless somebody says otherwise. */
|
|
14
|
+
export const ANNEAL_AT_LEAST = 18;
|
|
15
|
+
|
|
16
|
+
/** The longest a part can be and still be offered first as a primer. */
|
|
17
|
+
export const LONGEST_PRIMER = 60;
|
|
18
|
+
|
|
19
|
+
/** What a PCR would make. */
|
|
20
|
+
export interface PcrPlan {
|
|
21
|
+
/** Every product the primers would make from the template, shortest first. */
|
|
22
|
+
products: { sequence: string; length: number }[];
|
|
23
|
+
/** Why there is not exactly one product, said for a person, or `null` if there is. */
|
|
24
|
+
problem: string | null;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Whether a part is short enough to be a primer.
|
|
29
|
+
*
|
|
30
|
+
* @param part - Its length and whether it is a circle.
|
|
31
|
+
* @returns Whether to offer it as a primer first. Anything may still be chosen.
|
|
32
|
+
*/
|
|
33
|
+
export function looksLikePrimer(part: { length: number; circular: boolean }): boolean {
|
|
34
|
+
return !part.circular && part.length <= LONGEST_PRIMER;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* A primer's melting temperature by the Wallace rule: 2 °C for each A or T, 4 °C for each G or C.
|
|
39
|
+
*
|
|
40
|
+
* It is the rough figure written on a tube, good for seeing that two primers are near each other.
|
|
41
|
+
*
|
|
42
|
+
* @param sequence - The primer.
|
|
43
|
+
* @returns Degrees Celsius, or `null` if that is not a sequence.
|
|
44
|
+
*/
|
|
45
|
+
export function primerTm(sequence: string): number | null {
|
|
46
|
+
try { return tmWallace(sequence.replace(/\s+/g, "")); } catch { return null; }
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Work out what a PCR would make.
|
|
51
|
+
*
|
|
52
|
+
* @param template - What is being copied.
|
|
53
|
+
* @param forward - One primer.
|
|
54
|
+
* @param reverse - The other.
|
|
55
|
+
* @param options - `annealAtLeast` is how many bases at each primer's 3′ end must bind.
|
|
56
|
+
* @returns The products, and what is wrong if there is not exactly one.
|
|
57
|
+
*
|
|
58
|
+
* @example
|
|
59
|
+
* ```ts
|
|
60
|
+
* import { planPcr } from "@biolibs/bionet-tools";
|
|
61
|
+
*
|
|
62
|
+
* const template = "GGATCACAGTCTACACTGCTCACTCCAACCCCGGCCCCTGAGTCCGAGGAGAGGGTGCTTCAGAGTATGTATACC";
|
|
63
|
+
* const plan = planPcr({ sequence: template, circular: false }, "GGATCACAGTCTACACTG", "GGTATACATACTCTGAAG");
|
|
64
|
+
* plan.problem; // null
|
|
65
|
+
* plan.products[0].length; // 75
|
|
66
|
+
* ```
|
|
67
|
+
*/
|
|
68
|
+
export function planPcr(template: { sequence: string; circular: boolean }, forward: string, reverse: string,
|
|
69
|
+
options: { annealAtLeast?: number } = {}): PcrPlan {
|
|
70
|
+
const least = options.annealAtLeast ?? ANNEAL_AT_LEAST;
|
|
71
|
+
const clean = (text: string): string => text.replace(/\s+/g, "");
|
|
72
|
+
// The engine finds the primers whichever of them binds the upper strand, so the order they are
|
|
73
|
+
// given in does not matter.
|
|
74
|
+
let products: { sequence: string; length: number }[] = [];
|
|
75
|
+
try {
|
|
76
|
+
products = pcrAssembly(new Dseqrecord(clean(template.sequence), template.circular, undefined, "1", "template"),
|
|
77
|
+
new Primer(clean(forward), "2", "forward"), new Primer(clean(reverse), "3", "reverse"), false, least)
|
|
78
|
+
.map((product) => ({ sequence: String(product.seq), length: product.length }));
|
|
79
|
+
} catch {
|
|
80
|
+
products = [];
|
|
81
|
+
}
|
|
82
|
+
products.sort((a, b) => a.length - b.length);
|
|
83
|
+
const problem = products.length === 1 ? null
|
|
84
|
+
: products.length === 0 ? `These primers do not both bind this template with ${least} bases at their 3′ ends.`
|
|
85
|
+
: `These primers make ${products.length} different products from this template. A run records one.`;
|
|
86
|
+
return { products, problem };
|
|
87
|
+
}
|