@biolibs/gel 0.0.0-stage → 1.0.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/src/index.ts ADDED
@@ -0,0 +1,31 @@
1
+ /**
2
+ * @packageDocumentation
3
+ * `@biolibs/gel`: a virtual agarose gel — where DNA fragments of a given size would run, and which of them a gel
4
+ * would tell apart.
5
+ *
6
+ * There is no Biopython counterpart; this is the data behind the gel photograph that tools such as SnapGene and
7
+ * Benchling draw beside a digest. Migration follows the standard log-linear approximation over the range a gel
8
+ * resolves, described in `bands.ts`. The figures are conventional working values for agarose in TAE, enough to show
9
+ * which fragments would be distinguishable, not measurements of a particular rig.
10
+ *
11
+ * - `gels.ts`: `GelType`, `GELS`, `gelById` — agarose concentrations and their resolving ranges
12
+ * - `ladders.ts`: `Ladder`, `LADDERS`, `ladderById` — size markers
13
+ * - `bands.ts`: `bandPosition`, `resolves`, `Band`, `bandsOf`, `ladderBands` — fragment sizes to visible bands
14
+ * - `fragments.ts`: `Topology`, `fragmentSizes` — cut positions to fragment lengths
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * import { bandsOf, fragmentSizes, gelById } from "@biolibs/gel";
19
+ *
20
+ * const gel = gelById("1.0");
21
+ * const sizes = fragmentSizes(2686, "circular", [395, 1230]); // pUC19 cut twice
22
+ * for (const band of bandsOf(sizes, gel)) {
23
+ * console.log(`${band.size} bp at ${(band.position * 100).toFixed(0)}% down the gel`);
24
+ * }
25
+ * ```
26
+ */
27
+
28
+ export * from "./gels.js";
29
+ export * from "./ladders.js";
30
+ export * from "./bands.js";
31
+ export * from "./fragments.js";
package/src/ladders.ts ADDED
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Size markers (ladders) run alongside a sample so band sizes can be read off.
3
+ *
4
+ * The two ladders here are the generic 1 kb and 100 bp sets sold by every supplier. Their band sizes are the
5
+ * nominal ones printed on the tube.
6
+ */
7
+
8
+ import { ValueError } from "@biolibs/core";
9
+
10
+ /** A set of marker bands of known size. */
11
+ export interface Ladder {
12
+ /** Short identifier, e.g. `"1kb"`. */
13
+ id: string;
14
+ /** Display name. */
15
+ name: string;
16
+ /** Band sizes in base pairs, largest first. */
17
+ sizes: readonly number[];
18
+ }
19
+
20
+ /**
21
+ * The generic 1 kb and 100 bp ladders.
22
+ *
23
+ * @example
24
+ * ```ts
25
+ * LADDERS[0]!.sizes[0]; // 10000
26
+ * ```
27
+ */
28
+ export const LADDERS: readonly Ladder[] = [
29
+ { id: "1kb", name: "1 kb ladder", sizes: [10000, 8000, 6000, 5000, 4000, 3000, 2000, 1500, 1000, 500] },
30
+ { id: "100bp", name: "100 bp ladder", sizes: [1500, 1000, 900, 800, 700, 600, 500, 400, 300, 200, 100] },
31
+ ];
32
+
33
+ /**
34
+ * Look a ladder up by its {@link Ladder.id}.
35
+ *
36
+ * @param id - An id from {@link LADDERS}, e.g. `"100bp"`.
37
+ * @returns The matching ladder.
38
+ * @throws {@link ValueError} if no ladder has that id.
39
+ */
40
+ export function ladderById(id: string): Ladder {
41
+ const ladder = LADDERS.find((l) => l.id === id);
42
+ if (!ladder) throw new ValueError(`unknown ladder '${id}'; known ladders are ${LADDERS.map((l) => l.id).join(", ")}`);
43
+ return ladder;
44
+ }