linked-rolls 0.71.0 → 0.73.0

package/lib/filiation/systems.js

@@ -0,0 +1,39 @@
+/** Which reproducing system a version of the stemma is coded for, and which systems a roll was re-cut into. */
+import { procedures } from "../model/procedures.js";
+import { trackerBars } from "../systems/index.js";
+const TRANSFER = /\/umstanzung\/(.+)-to-(.+)$/;
+/**
+ * By system, the systems a roll of it was re-cut for, as the procedures
+ * of the vocabulary name them: a red roll was re-punched for the
+ * Licensee system and for the green one, and never the other way round.
+ * @category Filiation
+ */
+export const transfersOf = () => {
+    const transfers = new Map();
+    for (const procedure of procedures) {
+        const match = TRANSFER.exec(procedure.id ?? "");
+        if (!match)
+            continue;
+        const [from, to] = [match[1], match[2]];
+        transfers.set(from, new Set([...(transfers.get(from) ?? []), to]));
+    }
+    return transfers;
+};
+/** Whether a version of the one system can stand above a version of the other: the same system, or one re-cut from it. */
+export const leadsTo = (transfers, from, to) => from === to || (transfers.get(from)?.has(to) ?? false);
+/**
+ * The system of a lost version above versions of the given systems: the
+ * one they share, or else the one they were all re-cut from. A lost
+ * state above a red and a Licensee version is red, since a Licensee
+ * version is never re-cut into red. Where no system leads to all of
+ * them, nothing.
+ * @category Filiation
+ */
+export const systemAbove = (transfers, systems) => {
+    if (systems.size === 1)
+        return [...systems][0];
+    const candidates = new Set([...systems, ...transfers.keys()]);
+    return [...candidates].sort().find(candidate => [...systems].every(system => leadsTo(transfers, candidate, system)));
+};
+/** The bar of a system the library knows, by its identifier. */
+export const barNamed = (id) => trackerBars.find(bar => bar.id === id);

package/lib/filiation/texts.d.ts

@@ -0,0 +1,54 @@
+/** Which copies carry the same text, and so one version between them. */
+import { PresenceMatrix } from "./presence.js";
+/**
+ * Copies taken to carry one text: copies of one system, punched from one
+ * master, that differ in no more readings than a transcription and the
+ * wear of a copy explain.
+ * @category Filiation
+ */
+export interface SharedText {
+    /** The copies, in the order the proposal was given them. */
+    copies: string[];
+    /** The most readings any two of them differ in, where both can tell. */
+    differences: number;
+    /** Whether the edition says so: the copies carry one version at first hand there. */
+    stated: boolean;
+}
+/**
+ * Two copies of one system the proposal keeps apart, and how many
+ * readings they differ in, for the closest pairs: what was near being
+ * taken for one text.
+ * @category Filiation
+ */
+export interface KeptApart {
+    copies: [string, string];
+    differences: number;
+}
+/**
+ * How many readings two copies of one system may differ in and still be
+ * taken to carry the same text, where nothing else is said. A version
+ * can differ from the one it derives from by a handful of edits: WM 225's
+ * L2 differs from R4 in seven readings. Copies punched from one master,
+ * transcribed with care, differ in fewer.
+ * @category Filiation
+ */
+export declare const defaultSameText = 3;
+/** In how many readings the two copies differ where both can tell: one has it, the other lacks it. */
+export declare const differencesBetween: (matrix: PresenceMatrix, one: string, other: string) => number;
+/**
+ * The copies in groups that carry the same text.
+ *
+ * Copies of different systems never carry one text, since a version is a
+ * reading in one system's words. Copies the edition gives one version at
+ * first hand stay together (`stated`). Beyond that, the two groups whose
+ * copies differ least are joined first, as long as every copy of the one
+ * differs from every copy of the other in no more than `within` readings
+ * where both can tell, so that a chain of small differences never joins
+ * copies far apart. Ties go to the order the copies were given in.
+ * `within` below zero joins only what the edition states.
+ * @category Filiation
+ */
+export declare const sharedTexts: (matrix: PresenceMatrix, systems: readonly string[], within: number, stated?: readonly (readonly string[])[]) => {
+    texts: SharedText[];
+    apart: KeptApart[];
+};

package/lib/filiation/texts.js

@@ -0,0 +1,96 @@
+/**
+ * How many readings two copies of one system may differ in and still be
+ * taken to carry the same text, where nothing else is said. A version
+ * can differ from the one it derives from by a handful of edits: WM 225's
+ * L2 differs from R4 in seven readings. Copies punched from one master,
+ * transcribed with care, differ in fewer.
+ * @category Filiation
+ */
+export const defaultSameText = 3;
+/** In how many readings the two copies differ where both can tell: one has it, the other lacks it. */
+export const differencesBetween = (matrix, one, other) => {
+    let count = 0;
+    for (const presence of Object.values(matrix.presence)) {
+        const a = presence[one];
+        const b = presence[other];
+        if ((a === 'present' && b === 'absent') || (a === 'absent' && b === 'present'))
+            count++;
+    }
+    return count;
+};
+/**
+ * The copies in groups that carry the same text.
+ *
+ * Copies of different systems never carry one text, since a version is a
+ * reading in one system's words. Copies the edition gives one version at
+ * first hand stay together (`stated`). Beyond that, the two groups whose
+ * copies differ least are joined first, as long as every copy of the one
+ * differs from every copy of the other in no more than `within` readings
+ * where both can tell, so that a chain of small differences never joins
+ * copies far apart. Ties go to the order the copies were given in.
+ * `within` below zero joins only what the edition states.
+ * @category Filiation
+ */
+export const sharedTexts = (matrix, systems, within, stated = []) => {
+    const copies = matrix.copies;
+    const index = new Map(copies.map((copy, i) => [copy, i]));
+    const distance = copies.map((one, i) => copies.map((other, j) => i === j ? 0 : j < i ? NaN : differencesBetween(matrix, one, other)));
+    const between = (i, j) => i < j ? distance[i][j] : distance[j][i];
+    const groupOf = copies.map((_, i) => i);
+    const members = new Map(copies.map((_, i) => [i, [i]]));
+    const statedGroups = new Set();
+    const join = (a, b) => {
+        const [keep, drop] = a < b ? [a, b] : [b, a];
+        for (const i of members.get(drop))
+            groupOf[i] = keep;
+        members.set(keep, [...members.get(keep), ...members.get(drop)].sort((x, y) => x - y));
+        members.delete(drop);
+    };
+    for (const group of stated) {
+        const known = group.map(copy => index.get(copy)).filter((i) => i !== undefined);
+        for (const i of known.slice(1)) {
+            if (systems[i] !== systems[known[0]] || groupOf[i] === groupOf[known[0]])
+                continue;
+            join(groupOf[i], groupOf[known[0]]);
+        }
+        if (known.length > 1)
+            statedGroups.add(groupOf[known[0]]);
+    }
+    const pairs = [];
+    for (let i = 0; i < copies.length; i++) {
+        for (let j = i + 1; j < copies.length; j++) {
+            if (systems[i] === systems[j])
+                pairs.push({ i, j, d: between(i, j) });
+        }
+    }
+    pairs.sort((a, b) => a.d - b.d || a.i - b.i || a.j - b.j);
+    if (within >= 0) {
+        for (const { i, j, d } of pairs) {
+            if (d > within)
+                break;
+            const a = groupOf[i];
+            const b = groupOf[j];
+            if (a === b)
+                continue;
+            const close = members.get(a).every(x => members.get(b).every(y => between(x, y) <= within));
+            if (!close)
+                continue;
+            const wasStated = statedGroups.has(a) || statedGroups.has(b);
+            join(a, b);
+            if (wasStated)
+                statedGroups.add(Math.min(a, b));
+        }
+    }
+    const texts = [...members.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([group, list]) => ({
+        copies: list.map(i => copies[i]),
+        differences: Math.max(0, ...list.flatMap(x => list.filter(y => y > x).map(y => between(x, y)))),
+        stated: statedGroups.has(group)
+    }));
+    const apart = pairs
+        .filter(({ i, j }) => groupOf[i] !== groupOf[j])
+        .slice(0, 5)
+        .map(({ i, j, d }) => ({ copies: [copies[i], copies[j]], differences: d }));
+    return { texts, apart };
+};

package/lib/filiation/trees.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Every stemma a handful of copies can stand in: rooted trees whose
+ * nodes are versions, a copy carrying any of them, a lost one above
+ * any two or more.
+ */
+/**
+ * A node of a stemma: the copy carrying it at first hand, by its number,
+ * or none for a lost state, and the nodes derived from it.
+ */
+export interface StemmaNode {
+    readonly copy?: number;
+    readonly children: readonly StemmaNode[];
+}
+/**
+ * Every stemma of n copies: 3 for two copies, 91,984 for six. They are
+ * produced one by one, so that only the leaf trees, far fewer, are held.
+ */
+export declare function stemmataOf(n: number): Generator<StemmaNode>;
+/** How many stemmata the exhaustive search scores, at most. */
+export declare const MAX_COPIES = 7;

package/lib/filiation/trees.js

@@ -0,0 +1,69 @@
+/**
+ * Every stemma a handful of copies can stand in: rooted trees whose
+ * nodes are versions, a copy carrying any of them, a lost one above
+ * any two or more.
+ */
+const leaf = (copy) => ({ copy, children: [] });
+/** Every way to add the copy to the tree: as a further child of a lost node, or on an edge, above any subtree. */
+function* insertions(tree, copy) {
+    yield { children: [tree, leaf(copy)] };
+    if (tree.children.length === 0)
+        return;
+    yield { ...tree, children: [...tree.children, leaf(copy)] };
+    for (let i = 0; i < tree.children.length; i++) {
+        for (const child of insertions(tree.children[i], copy)) {
+            yield { ...tree, children: [...tree.children.slice(0, i), child, ...tree.children.slice(i + 1)] };
+        }
+    }
+}
+/** The trees whose leaves are the copies 0 to n − 1 and whose inner nodes are all lost, each once. */
+const leafTrees = (n) => {
+    if (n === 1)
+        return [leaf(0)];
+    let trees = [{ children: [leaf(0), leaf(1)] }];
+    for (let copy = 2; copy < n; copy++) {
+        trees = trees.flatMap(tree => [...insertions(tree, copy)]);
+    }
+    return trees;
+};
+const product = (lists) => lists.reduce((combos, list) => combos.flatMap(combo => list.map(item => [...combo, item])), [[]]);
+/**
+ * The tree with as many of its copies moved up as it allows: at each
+ * lost node, at most one copy among its leaf children may come to carry
+ * it instead, making that copy's text the ancestor of the others'.
+ * Every stemma arises from exactly one leaf tree in exactly one way.
+ */
+function* promotions(tree) {
+    if (tree.children.length === 0) {
+        yield tree;
+        return;
+    }
+    const options = tree.children.map(child => [...promotions(child)]);
+    const leaves = tree.children.flatMap((child, index) => child.children.length === 0 ? [index] : []);
+    for (const combo of product(options)) {
+        yield { children: combo };
+        for (const index of leaves) {
+            yield { copy: tree.children[index].copy, children: combo.filter((_, i) => i !== index) };
+        }
+    }
+}
+const cache = new Map();
+/**
+ * Every stemma of n copies: 3 for two copies, 91,984 for six. They are
+ * produced one by one, so that only the leaf trees, far fewer, are held.
+ */
+export function* stemmataOf(n) {
+    let trees = cache.get(n);
+    if (!trees) {
+        trees = leafTrees(n);
+        cache.set(n, trees);
+    }
+    if (n === 1) {
+        yield trees[0];
+        return;
+    }
+    for (const tree of trees)
+        yield* promotions(tree);
+}
+/** How many stemmata the exhaustive search scores, at most. */
+export const MAX_COPIES = 7;

package/lib/index.d.ts

@@ -76,6 +76,7 @@ export { validate, type ValidateEdition } from './validate.js';
 export * from './analysis/constraints.js';
 export * from './collation/substitution.js';
 export * from './io/context.js';
+export * from './filiation/index.js';
 export * from './analysis/sigla.js';
 export * from './model/notes.js';
 export { asJsonLd } from './io/asJsonLd.js';

package/lib/index.js

@@ -39,6 +39,7 @@ export { validate } from './validate.js';
 export * from './analysis/constraints.js';
 export * from './collation/substitution.js';
 export * from './io/context.js';
+export * from './filiation/index.js';
 export * from './analysis/sigla.js';
 export * from './model/notes.js';
 export { asJsonLd } from './io/asJsonLd.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.71.0",
+  "version": "0.73.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {