@biolibs/bionet-tools 0.1.9 → 0.1.10

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/src/modify.ts ADDED
@@ -0,0 +1,350 @@
1
+ /**
2
+ * Which residues of a protein would be phosphorylated, and whether the host would do it.
3
+ *
4
+ * This exists because of the gap between a band and a protein. The induction tool can tell a lab it
5
+ * will get a 24 kDa band; it cannot tell the lab that the band will be the right mass and the wrong
6
+ * thing. For casein that is the whole question. Casein builds a micelle — which is what makes it
7
+ * behave like cheese rather than like dissolved protein — by binding calcium through clusters of
8
+ * phosphorylated serines. A casein that was made but not phosphorylated weighs almost the same,
9
+ * runs almost in the same place, and will not do the job.
10
+ *
11
+ * So two separate things are worked out here, and they are kept separate because one is arithmetic
12
+ * and the other is not.
13
+ *
14
+ * - **Which residues carry the motif.** This is a rule over the sequence and nothing more. The
15
+ * secretory-pathway kinase that phosphorylates milk proteins recognises Ser-x-Glu, and once a
16
+ * serine is phosphorylated it acts like a glutamate for the one two residues before it, so the
17
+ * sites march backwards along a cluster. That hierarchy is why casein's serines come in runs.
18
+ * {@link phosphoSites} applies it, says which round each site was found in, and shows the working.
19
+ * - **Whether the host has the enzyme.** This is not arithmetic, and nothing here pretends it is.
20
+ * {@link hostPhosphorylation} says what is generally held about the usual expression hosts, how
21
+ * firmly, and says plainly that it is a claim to check — which the lab's own literature tools can
22
+ * now do.
23
+ *
24
+ * A motif is a prediction. Where a curated record exists, as it does for the caseins in UniProt,
25
+ * {@link comparedWithKnown} says which predictions it confirms and which it does not, and that
26
+ * comparison is worth far more than either on its own.
27
+ */
28
+ import type { Working } from "./pcr-working.js";
29
+
30
+ /** One rule for recognising a site. */
31
+ export interface PhosphoMotif {
32
+ /** What to call it. */
33
+ name: string;
34
+ /** The kinase family that uses it. */
35
+ kinase: string;
36
+ /** The rule, written as people write it. */
37
+ pattern: string;
38
+ /** Which residues it can act on. */
39
+ acts: string;
40
+ /** What it is for, in a sentence. */
41
+ about: string;
42
+ }
43
+
44
+ /**
45
+ * The rules applied, in the order they are applied.
46
+ *
47
+ * Only two, and deliberately only two. These are the acidophilic motifs — the ones that read a
48
+ * negative charge two or three residues along — and they are the ones that matter for a secreted
49
+ * milk protein. A kinase whose rule is a structure rather than a few residues cannot be found by
50
+ * looking at a sequence, and nothing here claims otherwise.
51
+ */
52
+ export const PHOSPHO_MOTIFS: readonly PhosphoMotif[] = [
53
+ {
54
+ name: "S-x-E", kinase: "secretory-pathway casein kinase (FAM20C family)", pattern: "S-x-[E/D]", acts: "S",
55
+ about: "The kinase that phosphorylates milk and other secreted proteins, inside the Golgi, as they are on their way out. It reads a negative charge two residues along.",
56
+ },
57
+ {
58
+ name: "S/T-x-x-E", kinase: "casein kinase II (CK2)", pattern: "[S/T]-x-x-[E/D]", acts: "ST",
59
+ about: "A kinase found in essentially every eukaryote, in the cytoplasm and the nucleus rather than the secretory pathway. Named after casein because casein is what it was first shown to work on, not because casein is what it does in a cell.",
60
+ },
61
+ ];
62
+
63
+ /** One residue that would be phosphorylated, and why. */
64
+ export interface PhosphoSite {
65
+ /** Where it is, counting from 1. */
66
+ at: number;
67
+ /** The residue, as a letter. */
68
+ residue: string;
69
+ /** The rule that found it, by name. */
70
+ by: string;
71
+ /** The kinase family that rule belongs to. */
72
+ kinase: string;
73
+ /** The residues either side of it, as they are written. */
74
+ context: string;
75
+ /**
76
+ * Which round found it. Round 1 is the motif read off the sequence as it stands. A later round is
77
+ * a site that only became one because a site found in the round before gave it the charge it
78
+ * needed — which is how a cluster of phosphoserines builds backwards along a chain.
79
+ */
80
+ round: number;
81
+ /** What made it a site, said for a person. */
82
+ because: string;
83
+ /**
84
+ * Any other rule that also matches this residue.
85
+ *
86
+ * A serine can carry more than one motif, and which one is reported first depends only on the
87
+ * order the rules are tried in. Saying "this is a CK2 site" when it is equally the secretory
88
+ * kinase's would be an accident of that order presented as a finding, so the others are listed.
89
+ */
90
+ alsoBy: { name: string; kinase: string; because: string }[];
91
+ }
92
+
93
+ /** What was worked out about a protein. */
94
+ export interface Phosphorylation {
95
+ /** The sites, in order along the chain. */
96
+ sites: PhosphoSite[];
97
+ /** How many rounds found something. A further round, which found nothing, is what ended it. */
98
+ rounds: number;
99
+ /** Why there is nothing to say, or `null` if there is. */
100
+ problem: string | null;
101
+ }
102
+
103
+ const ACID = new Set(["E", "D"]);
104
+
105
+ /**
106
+ * The residues of a protein that carry a phosphorylation motif.
107
+ *
108
+ * The rules are applied in rounds. In the first, each is read off the sequence as it stands. In
109
+ * each round after, a serine whose +2 residue is a site found already counts too, because a
110
+ * phosphoserine carries the negative charge the kinase was reading for. That is repeated until a
111
+ * round finds nothing, which is what builds the runs of phosphoserines a casein has.
112
+ *
113
+ * @param protein - The amino acids, in one letter each.
114
+ * @param options - `motifs` are the rules to apply, {@link PHOSPHO_MOTIFS} if not given; `prime`
115
+ * turns off the later rounds, leaving only what the bare sequence says.
116
+ * @returns The sites, and how many rounds it took.
117
+ *
118
+ * @example
119
+ * ```ts
120
+ * import { phosphoSites } from "@biolibs/bionet-tools";
121
+ *
122
+ * const found = phosphoSites(casein.sequence);
123
+ * found.sites.filter((one) => one.round > 1); // the ones a neighbour made possible
124
+ * ```
125
+ */
126
+ export function phosphoSites(protein: string, options: { motifs?: readonly PhosphoMotif[]; prime?: boolean } = {}): Phosphorylation {
127
+ const chain = protein.replace(/\s+/g, "").toUpperCase();
128
+ if (chain === "") return { sites: [], rounds: 0, problem: "There is no protein here to look at." };
129
+ if (!/^[ACDEFGHIKLMNPQRSTVWY]+$/.test(chain)) return { sites: [], rounds: 0, problem: "That is written in letters that are not the twenty standard amino acids." };
130
+ const motifs = options.motifs ?? PHOSPHO_MOTIFS;
131
+ const found = new Map<number, PhosphoSite>();
132
+ const context = (at: number): string => chain.slice(Math.max(0, at - 4), at + 3);
133
+
134
+ let round = 0;
135
+ for (;;) {
136
+ round += 1;
137
+ const fresh: PhosphoSite[] = [];
138
+ for (let at = 1; at <= chain.length; at += 1) {
139
+ const residue = chain[at - 1]!;
140
+ /** Every rule that matches this residue as things stand, in the order the rules are given. */
141
+ const matching: { name: string; kinase: string; because: string }[] = [];
142
+ for (const motif of motifs) {
143
+ if (!motif.acts.includes(residue)) continue;
144
+ const reach = motif.name === "S-x-E" ? 2 : 3;
145
+ const charged = chain[at - 1 + reach];
146
+ if (charged === undefined) continue;
147
+ if (ACID.has(charged)) {
148
+ matching.push({ name: motif.name, kinase: motif.kinase, because: `${residue}${at} with ${charged} ${reach} residues along: ${motif.pattern}` });
149
+ continue;
150
+ }
151
+ // A serine that is already a site carries the charge the kinase was reading for, so the one
152
+ // before it becomes a site in the next round. That is what builds a run of them backwards.
153
+ if (options.prime !== false && charged === "S" && found.has(at + reach)) {
154
+ matching.push({ name: motif.name, kinase: motif.kinase,
155
+ because: `${residue}${at} with the phosphoserine at ${at + reach} ${reach} residues along, which carries the negative charge a glutamate would` });
156
+ }
157
+ }
158
+ if (matching.length === 0) continue;
159
+ const already = found.get(at);
160
+ if (already !== undefined) {
161
+ // A rule that only matched once a neighbour was found is still a rule that matches, so it
162
+ // joins the site it belongs to rather than being lost or restarting the round count.
163
+ for (const one of matching) {
164
+ if (one.name !== already.by && !already.alsoBy.some((other) => other.name === one.name)) already.alsoBy.push(one);
165
+ }
166
+ continue;
167
+ }
168
+ const [best, ...rest] = matching as [typeof matching[number], ...typeof matching];
169
+ fresh.push({ at, residue, by: best.name, kinase: best.kinase, context: context(at), round, because: best.because, alsoBy: rest });
170
+ }
171
+ for (const one of fresh) found.set(one.at, one);
172
+ // A round that adds nothing is the end, and is not counted: what is reported is how many
173
+ // rounds found something, which is what says how deep the hierarchy went.
174
+ if (fresh.length === 0) { round -= 1; break; }
175
+ if (options.prime === false) break;
176
+ if (round > chain.length) break;
177
+ }
178
+ return { sites: [...found.values()].sort((a, b) => a.at - b.at), rounds: Math.max(round, 1), problem: null };
179
+ }
180
+
181
+ /** How a predicted set of sites stands against a curated one. */
182
+ export interface Compared {
183
+ /** Sites that were predicted and are recorded: the ones to trust. */
184
+ confirmed: number[];
185
+ /** Sites that are recorded and were not predicted: the rule missed them. */
186
+ missed: number[];
187
+ /** Sites that were predicted and are not recorded: they may be wrong, or merely unstudied. */
188
+ onlyPredicted: number[];
189
+ /** What fraction of the recorded sites the rule found. */
190
+ caught: number;
191
+ }
192
+
193
+ /**
194
+ * How a prediction stands against what somebody has actually recorded.
195
+ *
196
+ * This is the honest way to use a motif. A rule over a sequence says what could be phosphorylated;
197
+ * a curated record says what somebody saw. Where both exist, how well they agree is the measure of
198
+ * whether to believe the rule anywhere else — on a variant, say, or on a gene that has been
199
+ * rewritten in another host's codons.
200
+ *
201
+ * @param predicted - Where the rule said, counting from 1.
202
+ * @param known - Where a record says, counting from 1 on the same sequence.
203
+ * @returns What agrees, what was missed, and what is predicted alone.
204
+ *
205
+ * @example
206
+ * ```ts
207
+ * import { comparedWithKnown, phosphoSites } from "@biolibs/bionet-tools";
208
+ *
209
+ * const found = phosphoSites(casein.sequence);
210
+ * comparedWithKnown(found.sites.map((one) => one.at), [30, 32, 33, 34, 50]).caught; // 1
211
+ * ```
212
+ */
213
+ export function comparedWithKnown(predicted: readonly number[], known: readonly number[]): Compared {
214
+ const said = new Set(predicted);
215
+ const recorded = new Set(known);
216
+ const confirmed = [...recorded].filter((one) => said.has(one)).sort((a, b) => a - b);
217
+ return {
218
+ confirmed,
219
+ missed: [...recorded].filter((one) => !said.has(one)).sort((a, b) => a - b),
220
+ onlyPredicted: [...said].filter((one) => !recorded.has(one)).sort((a, b) => a - b),
221
+ caught: recorded.size === 0 ? 0 : confirmed.length / recorded.size,
222
+ };
223
+ }
224
+
225
+ /** What is held about whether a host phosphorylates a secreted protein this way. */
226
+ export interface HostKinases {
227
+ /** The organism, as it would be written. */
228
+ host: string;
229
+ /** Whether it is held to have the secretory-pathway kinase, and whether it has CK2. */
230
+ secretoryKinase: "yes" | "no" | "not known";
231
+ casein2: boolean;
232
+ /** What is held, in a sentence or two. */
233
+ says: string;
234
+ /** How firmly: something long settled, something reported, or something to go and check. */
235
+ standing: "well established" | "reported" | "check";
236
+ }
237
+
238
+ /**
239
+ * What is generally held about the usual expression hosts.
240
+ *
241
+ * Everything here is a claim about biology and not something computed, which is why it carries a
242
+ * `standing` and why the answer tells a reader to check it. It rots: a homologue nobody had found
243
+ * when this was written may have been found since, and a host engineered to carry the kinase is now
244
+ * a thing people build. What it is for is to stop a lab discovering at the end of a month that the
245
+ * protein it made was never going to be phosphorylated — and then to point at the literature, which
246
+ * the lab's own tools can now read.
247
+ */
248
+ export const HOST_KINASES: readonly HostKinases[] = [
249
+ {
250
+ host: "Escherichia coli", secretoryKinase: "no", casein2: false, standing: "well established",
251
+ says: "A bacterium has no secretory pathway of this kind and no kinase in it. Casein made in E. coli is reported unphosphorylated, and that is the usual reason a group that wanted micelles moved away from it.",
252
+ },
253
+ {
254
+ host: "Bacillus subtilis", secretoryKinase: "no", casein2: false, standing: "well established",
255
+ says: "As for E. coli: it secretes well, which is why people use it, but not through a compartment that phosphorylates what passes through.",
256
+ },
257
+ {
258
+ host: "Saccharomyces cerevisiae", secretoryKinase: "not known", casein2: true, standing: "reported",
259
+ says: "Budding yeast has casein kinase I and II homologues, but no homologue of the secretory-pathway kinase has been identified. Phosphorylation of casein expressed in yeast is reported, and reported as partial and uneven between sites rather than as the full pattern.",
260
+ },
261
+ {
262
+ host: "Komagataella phaffii", secretoryKinase: "not known", casein2: true, standing: "reported",
263
+ says: "The yeast formerly called Pichia pastoris, and the usual choice for a secreted protein because it secretes a great deal of it. The same holds as for budding yeast: the kinase of the secretory pathway has not been identified in it.",
264
+ },
265
+ {
266
+ host: "Nicotiana benthamiana", secretoryKinase: "not known", casein2: true, standing: "reported",
267
+ says: "Plants have CK2 and a secretory pathway, and phosphorylated casein has been reported from plant expression. How complete the pattern is varies by report.",
268
+ },
269
+ {
270
+ host: "Cricetulus griseus", secretoryKinase: "yes", casein2: true, standing: "well established",
271
+ says: "CHO cells are mammalian and have the secretory-pathway kinase, so they phosphorylate a milk protein as a mammal does. They are slow and expensive, which is why nobody makes cheese protein in them.",
272
+ },
273
+ ];
274
+
275
+ /**
276
+ * What is held about one host.
277
+ *
278
+ * @param host - What it is, as the lab writes it. Matched loosely, so `Pichia pastoris GS115` finds
279
+ * the entry for the species under its current name.
280
+ * @returns What is held, or `null` for a host nothing here knows about, which is not the same as a
281
+ * host that does not do it.
282
+ *
283
+ * @example
284
+ * ```ts
285
+ * import { hostPhosphorylation } from "@biolibs/bionet-tools";
286
+ *
287
+ * hostPhosphorylation("Saccharomyces cerevisiae W303")?.secretoryKinase; // "not known"
288
+ * ```
289
+ */
290
+ export function hostPhosphorylation(host: string): HostKinases | null {
291
+ const asked = host.trim().toLowerCase();
292
+ if (asked === "") return null;
293
+ // The old names are what a lab's own records are most likely to say.
294
+ const also: Readonly<Record<string, string>> = {
295
+ "pichia pastoris": "komagataella phaffii", "pichia": "komagataella phaffii",
296
+ "e. coli": "escherichia coli", "b. subtilis": "bacillus subtilis",
297
+ "s. cerevisiae": "saccharomyces cerevisiae", "cho": "cricetulus griseus", "tobacco": "nicotiana benthamiana",
298
+ };
299
+ for (const [old, now] of Object.entries(also)) {
300
+ if (asked.includes(old)) return HOST_KINASES.find((one) => one.host.toLowerCase() === now) ?? null;
301
+ }
302
+ return HOST_KINASES.find((one) => asked.includes(one.host.toLowerCase())
303
+ || asked.includes(one.host.split(" ")[0]!.toLowerCase())) ?? null;
304
+ }
305
+
306
+ /**
307
+ * The working behind what was found: the rule, the rounds, and what it rests on.
308
+ *
309
+ * @param found - What {@link phosphoSites} gave.
310
+ * @param host - What is held about the host, if a host was named.
311
+ * @returns The workings, in the order to read them.
312
+ */
313
+ export function phosphoWorking(found: Phosphorylation, host: HostKinases | null = null): Working[] {
314
+ if (found.problem !== null) return [];
315
+ const byRound = new Map<number, PhosphoSite[]>();
316
+ for (const one of found.sites) byRound.set(one.round, [...(byRound.get(one.round) ?? []), one]);
317
+ const out: Working[] = [{
318
+ of: "the sites the sequence carries",
319
+ comes: `${found.sites.length} ${found.sites.length === 1 ? "residue" : "residues"}`,
320
+ kind: "estimate",
321
+ steps: [
322
+ ...PHOSPHO_MOTIFS.map((one) => `${one.name}: ${one.pattern}, which is ${one.kinase}.`),
323
+ ...[...byRound.entries()].sort(([a], [b]) => a - b).map(([round, sites]) => {
324
+ const named = sites.map((one) => `${one.residue}${one.at}`).join(", ");
325
+ if (round === 1) return `Round 1 reads the sequence as it stands: ${named}.`;
326
+ return sites.length === 1
327
+ ? `Round ${round} adds ${named}, which only became a site because the one two residues along was found in the round before.`
328
+ : `Round ${round} adds ${named}, each of which only became a site because the one two residues along was found in the round before.`;
329
+ }),
330
+ found.rounds === 1
331
+ ? "One round found anything; the next found nothing more."
332
+ : `${found.rounds} rounds found something, and the next found nothing more, which is how far back along the chain the cluster builds.`,
333
+ ],
334
+ rests: "A motif says a residue could be phosphorylated, not that it is. It is a rule over a few residues, and the kinases it stands for are not the only ones there are; a kinase that reads a shape rather than a sequence cannot be found this way at all. Where somebody has recorded the real sites, compare against those and believe the comparison rather than the rule.",
335
+ }];
336
+ if (host !== null) {
337
+ out.push({
338
+ of: `whether ${host.host} would do it`,
339
+ comes: host.secretoryKinase === "yes" ? "it has the kinase" : host.secretoryKinase === "no" ? "it has no such kinase" : "not known to have the kinase",
340
+ kind: "estimate",
341
+ steps: [
342
+ host.says,
343
+ host.casein2 ? "It does have CK2, so a site that is CK2's may still be phosphorylated." : "It has no CK2 either.",
344
+ "This is not worked out from anything. It is what is generally held, and it is what to check in the literature before spending a month on it.",
345
+ ],
346
+ rests: `Held as ${host.standing}. A host engineered to carry the kinase is a thing people now build, and a homologue nobody had found when this was written may have been found since. Search the literature for this host and this protein rather than taking this for the answer.`,
347
+ });
348
+ }
349
+ return out;
350
+ }
package/src/protein.ts CHANGED
@@ -193,7 +193,9 @@ export function proteinWorking(made: Translated, facts: ProteinFacts | null): Wo
193
193
  steps: [
194
194
  `the weight is the amino acids added up, less a water for each bond: ${count(Math.round(facts.weight))} Da`,
195
195
  `the isoelectric point is where its charges cancel: pH ${facts.isoelectric.toFixed(2)}`,
196
- `it absorbs at 280 nm with ${count(facts.extinction.reduced)} M⁻¹cm⁻¹, which is how a concentration is read off`,
196
+ facts.extinction.reduced > 0
197
+ ? `it absorbs at 280 nm with ${count(facts.extinction.reduced)} M⁻¹cm⁻¹, which is how a concentration is read off`
198
+ : "it has no tryptophan, tyrosine or cystine, so it does not absorb at 280 nm and a concentration cannot be read there",
197
199
  `the instability index is ${facts.instability.toFixed(1)}; over 40 is reckoned unstable in a tube`,
198
200
  `${Math.round(facts.structure.helix * 100)}% helix, ${Math.round(facts.structure.turn * 100)}% turn, ${Math.round(facts.structure.sheet * 100)}% sheet`,
199
201
  ],
package/src/run.ts CHANGED
@@ -386,10 +386,10 @@ export function ligationRun(lab: ToolLab, choice: LigationChoice): LigationRun {
386
386
  }
387
387
 
388
388
  /** The tools there are. */
389
- export type ToolName = "pcr" | "digest" | "ligation";
389
+ export type ToolName = "pcr" | "digest" | "ligation" | "induction";
390
390
 
391
391
  /** The model of instrument each tool is used at. */
392
- export const TOOL_AT: Readonly<Record<ToolName, string>> = { pcr: "thermocycler", digest: "gel-station", ligation: "heat-block" };
392
+ export const TOOL_AT: Readonly<Record<ToolName, string>> = { pcr: "thermocycler", digest: "gel-station", ligation: "heat-block", induction: "shaking-incubator" };
393
393
 
394
394
  /**
395
395
  * Which tool an instrument opens.
package/src/tools.tsx CHANGED
@@ -4,6 +4,7 @@
4
4
  import { useState, type ReactNode } from "react";
5
5
  import { useLab } from "@biolibs/bionet-react";
6
6
  import { DigestTool } from "./digest-tool.js";
7
+ import { InductionTool } from "./induce-bench.js";
7
8
  import { PcrTool } from "./pcr-tool.js";
8
9
  import { instrumentFor, toolFor, type ToolName } from "./run.js";
9
10
  import { LigationTool } from "./ligate-bench.js";
@@ -17,12 +18,13 @@ import { SequencesTool } from "./sequences-tool.js";
17
18
  export type DeskTool = "sequences" | "primers" | "codons" | "assembly" | "verify";
18
19
 
19
20
  /** What each tool is called. */
20
- export const TOOL_NAMES: Readonly<Record<ToolName, string>> = { pcr: "PCR", digest: "Digest and gel", ligation: "Ligation" };
21
+ export const TOOL_NAMES: Readonly<Record<ToolName, string>> = { pcr: "PCR", digest: "Digest and gel", ligation: "Ligation", induction: "Induction" };
21
22
 
22
23
  function Tool({ tool, instrument, onDone }: { tool: ToolName; instrument: { id: string; name: string } | null; onDone?: (() => void) | undefined }) {
23
24
  const more = onDone === undefined ? {} : { onDone };
24
25
  return tool === "pcr" ? <PcrTool instrument={instrument} {...more} />
25
26
  : tool === "ligation" ? <LigationTool instrument={instrument} {...more} />
27
+ : tool === "induction" ? <InductionTool instrument={instrument} {...more} />
26
28
  : <DigestTool instrument={instrument} {...more} />;
27
29
  }
28
30
 
@@ -42,7 +44,7 @@ export function InstrumentTool({ place, onDone }: { place: string; onDone?: () =
42
44
  <div className="toolhead">
43
45
  <div>
44
46
  <h2>{found?.name ?? "This place"}</h2>
45
- <p className="dim">There is no tool for this yet. A thermocycler opens PCR, and a gel station opens digest and gel.</p>
47
+ <p className="dim">There is no tool for this yet. A thermocycler opens PCR, a gel station opens digest and gel, and a shaking incubator opens induction.</p>
46
48
  </div>
47
49
  {onDone !== undefined && <button type="button" className="quiet" onClick={onDone}>Back to the lab</button>}
48
50
  </div>